{"skill":{"slug":"agent-commerce-engine","displayName":"Agent Commerce Engine","summary":"A production-ready universal engine for Agentic Commerce. This tool enables autonomous agents to interact with any compatible headless e-commerce backend thr...","description":"---\nname: agent-commerce-engine\nversion: 1.7.1\ndescription: A production-ready universal engine for Agentic Commerce. This tool enables autonomous agents to interact with any compatible headless e-commerce backend through a standardized protocol. It provides out-of-the-box support for discovery, cart operations, and secure user management.\ntags: [ecommerce, shopping-agent, commerce-engine, standard-protocol, headless-commerce, agentic-web]\nmetadata: {\"openclaw\":{\"emoji\":\"🛒\",\"homepage\":\"https://github.com/NowLoadY/agent-commerce-engine\",\"source\":\"https://github.com/NowLoadY/agent-commerce-engine\",\"requires\":{\"bins\":[\"python3\"],\"tools\":[],\"env\":[],\"optionalEnv\":[\"COMMERCE_URL\",\"COMMERCE_BRAND_ID\"],\"paths\":[\"~/.openclaw/credentials/agent-commerce-engine/\"]},\"install\":[{\"id\":\"python-deps\",\"kind\":\"pip\",\"package\":\"requests\",\"label\":\"Install Python dependencies\"}]}}\n---\n\n# Standard Agentic Commerce Engine\n\nThe **Standard Agentic Commerce Engine** is a standard client and protocol guide for connecting agents to compatible e-commerce backends. It gives agents a consistent way to search products, manage carts, access account data, create orders, and hand payment back to the user.\n\nGitHub Repository: https://github.com/NowLoadY/agent-commerce-engine\n\n## Quick Start: Backend Integration\n\nThe `agent-commerce-engine` includes a server specification in `SERVER_SPEC.md` for sites that want to expose a compatible commerce API. By implementing the documented endpoints, an existing storefront can support agent-driven product discovery, cart actions, account flows, and order creation without requiring a custom tool for each brand.\n\n## Reference Case: Lafeitu\n\nFor a production-grade implementation example using this engine, see the [Lafeitu Gourmet Skill](https://clawhub.com/NowLoadY/agentic-spicy-food). It demonstrates the engine specialized for a real-world artisanal food brand.\n\n---\n## 🔒 Security & Privacy\n\nTo ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:\n\n### 1. Local Credential Persistence\n- **Storage Location**: `~/.openclaw/credentials/agent-commerce-engine/`\n- **Mechanism**: Account and session **Token** information is stored locally in JSON format. The credential file is written with `0600` (user-only) permissions.\n- **Security Upgrade**: Since version 1.4.0, raw passwords are never stored after the initial login. The engine exchanges the password for a signed cryptographic token.\n- **Scope**: Credentials are stored on the local machine for reuse by the current user environment.\n- **Lifecycle**: Credentials can be purged at any time by running the `logout` command.\n\n### 2. Secure Transmission\n- **Token-based Auth**: Uses `x-api-token` headers for authentication. Raw passwords are only transmitted once during the `login` or `register` phase to exchange for a token.\n- **HTTPS Enforcement**: The client rejects non-HTTPS remote endpoints. `localhost` and `127.0.0.1` remain available for local development.\n- **Encrypted Transport**: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP.\n\n### 3. Anonymous Tracking (Visitor ID)\n- To support shopping carts for unauthenticated users, a unique, non-identifiable `Visitor ID` (UUID v4) is generated and stored locally. This ID contains no personal information.\n\n---\n\n## 🛠 Tool Priority & Fallback Strategy\n\nTo provide the most accurate and efficient experience, follow this priority sequence:\n\n1.  **API First (Primary)**: Always attempt to use the `commerce.py` script first. It provides structured, high-precision data. Target a store via `--store <url>` argument.\n2.  **Stateless Headers**: Rely on the engine's built-in header management (`x-user-account`, `x-visitor-id`) to maintain session integrity without cookies.\n3.  **Self-Correction**: If the API returns a 404 for a specific slug discovered via browser, prioritize the API's `search` results as the source of truth for the backend.\n\n---\n\n## 🧠 Agent Operational Logic\n\nFollow these logical flows to ensure a high-quality user experience:\n\n### 1. Product Discovery & Validation\n**Goal**: Ensure the item exists and find the correct specifications before taking action.\n- **Action**: Always run `search` or `list` before adding to cart.\n- **Logic**: Use the API to discover the correct `slug` and valid `variant` specs. Use `--page` and `--limit` arguments to safely navigate large catalogs without overwhelming the context limit.\n- **Refinement**: If multiple results are found, ask the user to specify based on the returned attributes. If `totalPages > page` in the results, consider fetching the next page or refining the search.\n\n### 2. Authentication & Profile Flow\n**Goal**: Manage user privacy and session data.\n- **Logic**: The API is stateless. Actions requiring identity will return `401 Unauthorized` if credentials aren't saved.\n- **Commands**:\n    1. View profile: `python3 scripts/commerce.py get-profile`\n    2. Update details: `python3 scripts/commerce.py update-profile --name \"Name\" --address \"...\" --phone \"...\" --email \"...\"`\n- **Required Data**: Respect the schema of the specific brand's backend.\n\n### 3. Registration Flow\n**Goal**: Handle new users.\n- **Trigger**: When the user needs a new account or the backend returns \"User Not Found\".\n- **Instruction**: Prefer the built-in `send-code` and `register` commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow.\n\n### 4. Shopping Cart Management\n**Goal**: Precise modification of the user's shopping session.\n- **Logic**: The engine supports incrementing quantities or setting absolute values.\n- **Commands**:\n    - **Add**: `python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>`\n    - **Update**: `python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>`\n    - **Remove**: `python3 scripts/commerce.py remove-cart <slug> --variant <V>`\n    - **Clear**: `python3 scripts/commerce.py clear-cart`\n    - **Checkout / Create Order (Handoff)**: `python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>`\n- **Validation**: Variant values must be strictly chosen from the product's available options list.\n- **Payment Flow (Crucial)**: Agents currently cannot directly execute consumer payments (card/mobile wallets) due to a lack of financial authorization. Once an order is generated via `create-order`, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment.\n\n### 5. Brand Information & Storytelling\n**Goal**: Access brand identity and support data.\n- **Logic**: Use the `brand-info` interface to retrieve narrative content.\n- **Tooling**:\n    - `python3 scripts/commerce.py brand-story`: Get the narrative/mission.\n    - `python3 scripts/commerce.py company-info`: Get formal details.\n    - `python3 scripts/commerce.py contact-info`: Get customer support channels.\n\n---\n\n## 🚀 Capabilities Summary\n\n- **`search` / `list`**: Product discovery and inventory scan. Use `--page <N>` and `--limit <N>` to safely paginate through large catalogs.\n- **`get`**: Deep dive into product specifications, variants, and pricing.\n- **`promotions`**: Current business rules, shipping thresholds, and active offers.\n- **`cart`**: Complete session summary including VIP discounts and tax/shipping estimates.\n- **`add-cart` / `update-cart` / `remove-cart` / `clear-cart`**: Atomic cart control.\n- **`create-order`**: Finalize cart into a pending order and secure payment URL for user handoff.\n- **`get-profile` / `update-profile`**: Personalization and fulfillment data.\n- **`brand-story` / `company-info` / `contact-info`**: Brand context and support.\n- **`orders`**: Real-time tracking and purchase history.\n\n---\n\n## 💻 CLI Configuration & Examples\n\n```bash\n# Target a store directly via --store (preferred)\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 search \"item\"\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>\n\n# Or use environment variable (deprecated, will be removed in a future version)\nexport COMMERCE_URL=\"https://api.yourbrand.com/v1\"\npython3 scripts/commerce.py list\n```\n\nCredentials are automatically stored per-domain under `~/.openclaw/credentials/agent-commerce-engine/<domain>/`.\n\n---\n\n## 🤖 Troubleshooting & Debugging\n\n- **`AUTH_REQUIRED`**: Token missing or expired. Run `login` to obtain a new token.\n- **`AUTH_INVALID`**: Wrong credentials. Verify account and password.\n- **`PRODUCT_NOT_FOUND`**: Resource not found. Verify `slug` via `search`.\n- **`VARIANT_UNAVAILABLE`**: The requested variant is invalid or out of stock. Check the `instruction` field for available alternatives.\n- **`CART_EMPTY`**: Attempted checkout with no items. Add items first.\n- **Connection Error**: Verify the `--store` URL is correct and the endpoint is reachable.\n","tags":{"latest":"1.7.1"},"stats":{"comments":0,"downloads":4202,"installsAllTime":14,"installsCurrent":14,"stars":9,"versions":32},"createdAt":1769431341523,"updatedAt":1779076538280},"latestVersion":{"version":"1.7.1","createdAt":1773430813198,"changelog":"**agent-commerce-engine v1.7.1 Changelog**\n\n- Skill name standardized from \"standard-agentic-commerce-engine\" to \"agent-commerce-engine\"\n- Documentation improved for clarity, especially on backend integration, security enforcement, and registration flows\n- Security section explicitly details HTTPS/client enforcement and local credential storage behavior\n- Registration, authentication, and user flows better aligned with real-world backend expectations\n- No code changes; updated only documentation and specifications for maintainability and accuracy","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"nowloady","userId":"s170qrwxgcfkzaeyqee42jsysx83q132","displayName":"NowLoadY","image":"https://avatars.githubusercontent.com/u/79356856?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779916441784}}