Merge pull request #13 from happycog/craft-commerce

Add Commerce, user, and address management CLI tools

Author: elivz

.github/workflows/test.yml

@@ -63,7 +63,7 @@ jobs:
       - name: Install dependencies
         if: steps.composer-cache.outputs.cache-hit != 'true'
         run: |
-          composer require "craftcms/cms:~5.8.8" --prefer-dist --no-progress
+          composer require "craftcms/cms:~5.9" --prefer-dist --no-progress
 
       - name: Copy config files
         run: |

README.md

@@ -24,7 +24,14 @@ By adding this skill to Claude, you transform your Craft CMS site into an AI-acc
 - **Field Layout Management**: Build and modify field layouts programmatically
 - **Draft Support**: Create, update, and apply drafts for content workflows
 - **Asset Management**: Upload, update, and manage assets and volumes
+- **Address Management**: Create, read, update, and delete owner-backed addresses plus manage the global address field layout
+- **User Management**: Create, read, update, and delete users plus inspect the global user field layout
+- **User Group Management**: Manage user groups and permissions on Craft Pro installations
 - **Site Information**: Access multi-site configuration details
+- **Commerce: Products**: Create, read, update, and delete products with variant support
+- **Commerce: Variants**: Manage product variants with pricing, inventory, and dimensions
+- **Commerce: Orders**: Search and manage orders with status updates
+- **Commerce: Stores**: View and configure store settings, checkout behavior, and pricing strategies
 
 ## Installation
 
@@ -253,12 +260,65 @@ All tools from the HTTP API are available via CLI. Common operations include:
 - `assets/delete <id>` - Delete asset
 - `volumes/list` - List asset volumes
 
+### Addresses
+- `addresses/list` - List/search addresses
+- `addresses/get <id>` - Get address by ID
+- `addresses/create` - Create address for an owner or address field
+- `addresses/update <id>` - Update address
+- `addresses/delete <id>` - Delete address
+- `addresses/field-layout` - Get the global address field layout
+
+### Users
+- `users/list` - List/search users
+- `users/get <id>` - Get user by ID
+- `users/create` - Create user
+- `users/permissions` - List available user permissions
+- `users/update <id>` - Update user
+- `users/delete <id>` - Delete user
+- `users/field-layout` - Get the global user field layout
+
+### User Groups
+- `user-groups/list` - List user groups
+- `user-groups/get <id>` - Get user group by ID
+- `user-groups/create` - Create user group
+- `user-groups/update <id>` - Update user group
+- `user-groups/delete <id>` - Delete user group
+
 ### Other
 - `sites/list` - List all sites
 - `field-layouts/create` - Create field layout
 - `field-layouts/get` - Get field layout
 - `field-layouts/update <id>` - Update field layout
 
+### Commerce: Products
+- `products/create` - Create new product
+- `products/get <id>` - Get product by ID
+- `products/search` - Search/filter products
+- `products/update <id>` - Update product
+- `products/delete <id>` - Delete product
+- `product-types/list` - List product types
+- `product-types/get <id>` - Get product type by ID with field layouts
+- `product-types/create` - Create product type
+- `product-types/update <id>` - Update product type
+- `product-types/delete <id>` - Delete product type
+
+### Commerce: Variants
+- `variants/create` - Create variant for a product
+- `variants/get <id>` - Get variant by ID
+- `variants/update <id>` - Update variant
+- `variants/delete <id>` - Delete variant
+
+### Commerce: Orders
+- `orders/get <id>` - Get order by ID
+- `orders/search` - Search/filter orders
+- `orders/update <id>` - Update order status
+- `order-statuses/list` - List order statuses
+
+### Commerce: Stores
+- `stores/list` - List all stores with configuration
+- `stores/get <id>` - Get store by ID
+- `stores/update <id>` - Update store settings
+
 For detailed documentation on each tool, see the [SKILLS documentation](./SKILLS/).
 
 ## Development

SKILLS/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Craft CMS Skills
-description: Complete skill suite for managing Craft CMS content including sections, entry types, fields, entries, drafts, field layouts, and sites.
+description: Complete skill suite for managing Craft CMS content including users, addresses, sections, entry types, fields, entries, drafts, field layouts, sites, and Commerce products, variants, and orders.
 ---
 
 ## Important: Use this plugin, Not YAML Files
@@ -80,5 +80,58 @@ All API endpoints:
 - [delete_asset](delete_asset.md) - `DELETE /api/assets/<id>` - Delete asset and file
 - [get_volumes](get_volumes.md) - `GET /api/volumes` - List asset volumes with IDs/URLs
 
+## Addresses
+- [get_addresses](get_addresses.md) - `GET /api/addresses` - List/search addresses by owner, field, and location
+- [get_address](get_address.md) - `GET /api/addresses/<id>` - Retrieve address details with owner and field context
+- [create_address](create_address.md) - `POST /api/addresses` - Create generic owner-backed addresses for users or custom address fields
+- [update_address](update_address.md) - `PUT /api/addresses/<id>` - Update address attributes and custom fields
+- [delete_address](delete_address.md) - `DELETE /api/addresses/<id>` - Delete address (soft/permanent)
+- [get_address_field_layout](get_address_field_layout.md) - `GET /api/addresses/field-layout` - Retrieve the single global address field layout
+
+## Users
+- [get_users](get_users.md) - `GET /api/users` - List/search users by query, identity fields, status, and optionally group
+- [get_user](get_user.md) - `GET /api/users/<id>` - Retrieve a user by ID, email, or username
+- [create_user](create_user.md) - `POST /api/users` - Create a user with native attributes and custom fields
+- [get_available_permissions](get_available_permissions.md) - `GET /api/users/permissions` - List all known permissions plus custom stored permission names
+- [update_user](update_user.md) - `PUT /api/users/<id>` - Update a user by ID, email, or username
+- [delete_user](delete_user.md) - `DELETE /api/users/<id>` - Delete a user by ID, email, or username
+- [get_user_field_layout](get_user_field_layout.md) - `GET /api/users/field-layout` - Retrieve the single global user field layout
+
+## User Groups
+- [get_user_groups](get_user_groups.md) - `GET /api/user-groups` - List user groups and their permissions
+- [get_user_group](get_user_group.md) - `GET /api/user-groups/<id>` - Retrieve a user group by ID or handle
+- [create_user_group](create_user_group.md) - `POST /api/user-groups` - Create a user group and set permissions
+- [update_user_group](update_user_group.md) - `PUT /api/user-groups/<id>` - Update a user group and its permissions
+- [delete_user_group](delete_user_group.md) - `DELETE /api/user-groups/<id>` - Delete a user group by ID or handle
+
 ## System
 - [health](health.md) - `GET /api/health` - Health check endpoint to verify plugin installation and API availability
+
+## Commerce: Products
+- [create_product](create_product.md) - `POST /api/products` - Create product with type, title, SKU, price, and custom fields
+- [get_product](get_product.md) - `GET /api/products/<id>` - Retrieve product with variants, pricing, and custom fields
+- [get_products](get_products.md) - `GET /api/products/search` - Search/filter products by type/status/query
+- [update_product](update_product.md) - `PUT /api/products/<id>` - Update product attributes and custom fields
+- [delete_product](delete_product.md) - `DELETE /api/products/<id>` - Delete product (soft/permanent)
+- [get_product_types](get_product_types.md) - `GET /api/product-types` - List available Commerce product types
+- [get_product_type](get_product_type.md) - `GET /api/product-types/<id>` - Retrieve product type with field layouts and site settings
+- [create_product_type](create_product_type.md) - `POST /api/product-types` - Create product type with title, variant, layout, and site settings
+- [update_product_type](update_product_type.md) - `PUT /api/product-types/<id>` - Update product type configuration and site settings
+- [delete_product_type](delete_product_type.md) - `DELETE /api/product-types/<id>` - Delete product type with impact analysis and force protection
+
+## Commerce: Variants
+- [create_variant](create_variant.md) - `POST /api/variants` - Add variant to existing product with SKU, price, and attributes
+- [get_variant](get_variant.md) - `GET /api/variants/<id>` - Retrieve variant with pricing, inventory, and dimensions
+- [update_variant](update_variant.md) - `PUT /api/variants/<id>` - Update variant pricing, SKU, stock, and fields
+- [delete_variant](delete_variant.md) - `DELETE /api/variants/<id>` - Delete variant (soft/permanent)
+
+## Commerce: Orders
+- [get_order](get_order.md) - `GET /api/orders/<id>` - Retrieve order with line items, totals, and addresses
+- [search_orders](search_orders.md) - `GET /api/orders/search` - Search/filter orders by email/status/date/payment
+- [update_order](update_order.md) - `PUT /api/orders/<id>` - Update order status or message
+- [get_order_statuses](get_order_statuses.md) - `GET /api/order-statuses` - List all order statuses with IDs/handles/colors
+
+## Commerce: Stores
+- [get_stores](get_stores.md) - `GET /api/stores` - List all stores with checkout/payment/tax configuration
+- [get_store](get_store.md) - `GET /api/stores/<id>` - Retrieve store with full configuration details
+- [update_store](update_store.md) - `PUT /api/stores/<id>` - Update store checkout, payment, and pricing settings

SKILLS/create_address.md

@@ -0,0 +1,35 @@
+# create_address
+
+Create an Address for a generic owner, either directly on an element or inside an `Addresses` custom field.
+
+## Endpoint
+
+`POST /api/addresses`
+
+## Parameters
+
+- `ownerId` (int, required) - Owner element ID
+- `ownerType` (string, required) - Owner element class name
+- `fieldId` (int, optional) - Target `craft\fields\Addresses` field ID
+- `fieldHandle` (string, optional) - Alternative to `fieldId`
+- Native address attributes such as `title`, `countryCode`, `administrativeArea`, `locality`, `postalCode`, `addressLine1`, `addressLine2`, `organization`, `latitude`, `longitude`
+- `fields` (object, optional) - Custom address field values from the global Address field layout
+
+## Returns
+
+Returns the created address with ownership metadata and serialized custom fields.
+
+## Example
+
+```json
+{
+  "ownerId": 12,
+  "ownerType": "craft\\elements\\User",
+  "title": "Home",
+  "countryCode": "US",
+  "addressLine1": "123 Main St",
+  "locality": "Portland",
+  "administrativeArea": "OR",
+  "postalCode": "97205"
+}
+```

SKILLS/create_product.md

@@ -0,0 +1,92 @@
+# create_product
+
+Create a new Commerce product with a default variant.
+
+## Route
+
+`POST /api/products`
+
+## Description
+
+Creates a new Commerce product with the specified product type, title, and default variant (SKU and price). The product is created with a single default variant; use `create_variant` to add additional variants after creation.
+
+## Parameters
+
+### Required Parameters
+
+- **typeId** (integer): The product type ID. Use `get_product_types` to discover available types.
+- **title** (string): Product title.
+- **sku** (string): SKU for the default variant.
+- **price** (float): Price for the default variant.
+
+### Optional Parameters
+
+- **slug** (string, optional): Product slug. Auto-generated from title if not provided.
+- **postDate** (string, optional): Post date in ISO 8601 format. Defaults to now.
+- **expiryDate** (string, optional): Expiry date in ISO 8601 format. Null means no expiry.
+- **enabled** (boolean, optional): Whether the product is enabled. Default: `true`.
+- **fields** (object, optional): Custom field data keyed by field handle.
+
+## Return Value
+
+Returns an object containing:
+
+- **_notes** (string): Confirmation message
+- **productId** (integer): Created product ID
+- **title** (string): Product title
+- **slug** (string): Product slug
+- **status** (string): Product status (live, pending, expired, disabled)
+- **typeId** (integer): Product type ID
+- **typeName** (string): Product type name
+- **defaultSku** (string): Default variant SKU
+- **defaultPrice** (float): Default variant price
+- **url** (string): Craft control panel edit URL
+
+## Example Usage
+
+### Basic Product
+```json
+{
+  "typeId": 1,
+  "title": "Ergonomic Widget",
+  "sku": "WIDGET-001",
+  "price": 29.99
+}
+```
+
+### Product with All Options
+```json
+{
+  "typeId": 1,
+  "title": "Premium Widget",
+  "sku": "WIDGET-PRE-001",
+  "price": 99.99,
+  "slug": "premium-widget",
+  "postDate": "2025-06-01T00:00:00+00:00",
+  "expiryDate": "2025-12-31T23:59:59+00:00",
+  "enabled": true,
+  "fields": {
+    "description": "A premium ergonomic widget."
+  }
+}
+```
+
+### CLI Usage
+```bash
+agent-craft products/create --typeId=1 --title="Ergonomic Widget" --sku="WIDGET-001" --price=29.99
+agent-craft products/create --typeId=1 --title="Premium Widget" --sku="WIDGET-PRE" --price=99.99 --slug="premium-widget" --enabled=false
+```
+
+## Notes
+
+- A default variant is always created with the provided SKU and price
+- Use `get_product_types` to discover available product type IDs
+- Use `create_variant` to add additional variants after creation
+- Throws an error if the product type ID is invalid
+- Requires Craft Commerce to be installed
+
+## See Also
+
+- [get_product_types](get_product_types.md) - Discover available product types
+- [update_product](update_product.md) - Update product attributes
+- [create_variant](create_variant.md) - Add variants to a product