Alrighty, I've fleshed out the product code from Damien's initial build to the following point, and have developed some standards for variable type / naming proposed elsewhere. I'm interested to hear feedback on what's missing in the API and what sorts of tests should be developed to cover the code here. You can view this code in my latest GitHub commit at http://github.com/rszrama/drupalcommerce (and check my other repo for the installation profile).

Product types

The product type object includes...

I've standardized the use of $product_type as the variable name for an entire product type object and $type or 'type' when referring to just the machine-readable type name, i.e. $product_type->type or...

Product types should always be objects, not associative arrays. It was something of a hybrid system (like the comment system in core used to be / maybe still is : ?), so I standardized on objects.

The product type API includes the following functions:

• commerce_product_types() - returns an array of all defined product types.
• commerce_product_type_get_name($type = NULL) - returns the human-readable name given the machine-readable $type; if $type remains NULL, an array is returned of all types / names. Used for tasks like defining menu items / permissions and populating select lists.
• commerce_product_types_reset() - resets the array of product types cached by commerce_product_types().
• commerce_product_type_load($type) - returns the fully loaded product type object for the given type.
• commerce_product_type_to_arg($type) - returns the path argument for a product type... is this used?
• commerce_product_type_save($product_type) - saves a product type, performing an INSERT or UPDATE based on whether or not $product_type->is_new is set.
• commerce_product_type_delete($type) - deletes a product type.
• commerce_product_type_title($product_type) - returns the human-readable product type name given a full product type object (used as a menu item callback).

Products

The product object includes...

The product API includes the following functions:

• commerce_product_load($product_id) - returns a product object loaded by product ID.
• commerce_product_load_by_sku($sku) - returns a product object loaded by SKU.
• commerce_product_load_multiple(...) - loads multiple products through the entity system based on the supplied parameters; the above two functions are really just wrappers for this one.
• commerce_product_save($product) - given a full product object, saves it to the database within a single transaction; performs an INSERT or UPDATE based on the existence of a $product->product_id.
• commerce_product_delete($product_id) - deletes a product by product ID.
• commerce_product_delete_multiple($product_ids) - deletes all the products specified by ID in the $product_ids array; the above function is a wrapper for this one.
• commerce_product_path($product) - currently returns the path to the edit form for a product; used by the entity system.
• commerce_product_autocomplete(...) - returns the autocomplete output for product autocompletes; matches based on SKU or title within a given set of product types.
• commerce_product_match_products(...) - returns an array of product data for products matching the given parameters; used by the autocomplete and other product reference related functions.

Core / contrib integration

Products are handled through Drupal's entity system and are therefore integrated into the fields system. Product data is also exposed to Views in the various includes/views files. A base set of product tokens have been defined in includes/commerce_product.tokens.inc.

The product UI module provides a default View listing out created products with a contextual link to add a product. The View has a local task tab for administering product types and provides the forms necessary to add/edit and delete product types and products. The product reference module provides a Field to refer to products from another entity instance, like a node of a type used for product display. Default formatters for the Field include listing titles and SKUs with or without a link to view the product (which does not exist yet). I'm working locally with a mock-up Add to Cart form formatter.

Current permissions include:

• Administer products
• Administer product types
• Access lists of products (primarily for viewing / referencing)
• Create products
• Product type specific permissions for creating and editing/deleting products (both your own and any)

Current proposals for improvement:

1. The ability to define SKU patterns based on Tokens at the product type level, based on this thread. Problems with the implementation involve checking the validity (i.e. the uniqueness) of the SKU in the product add form's validate stage as opposed to its submission stage. We can't replace the product ID token prior to submission when we actually create the product. However, we can't simply store the pattern as the SKU, because once the SKU has been set we don't want it changing at a later time. I first thought this might not be an issue, since the only Tokens I'd consider allowing would be product ID and product type, which themselves won't change. However, if the concept of SKU is to cover multi-site instances of the same product, we can't presume the product ID will be the same. We need to save the full SKU at the moment the product is created. My proposed solution is to validate based on the next supposed product ID, which even if the product ID ends up being different when the product is actually saved, it will at least still be unique.
2. The addition of initialization functions for creating new products / product types, based on this thread. Defining classes for products and product types, or at least particularly any object that is governed by Drupal's entity system, was ruled out. However, I asked whether or not it would be beneficial to have initialization functions for creating new products / product types and am still interested in feedback. It seems essential to me, but I didn't want to just add it in without anyone else feeling they were beneficial.
3. The code currently doesn't provide any points to hook into processes like loaded, saving, or deleting a product. Should this sort of hook API be built, and do we need to consider adding in alteration hooks?
4. Add a product view and use this in places like the product delete form to show the product that's being deleted.