Agentic commerce

npm install @financedistrict/medusa-plugin-agentic-commerce

1import { defineConfig } from "@medusajs/framework/utils"
2
3export default defineConfig({
4  // Register the plugin for route/workflow/subscriber auto-discovery
5  plugins: [
6    {
7      resolve: "@financedistrict/medusa-plugin-agentic-commerce",
8      options: {},
9    },
10  ],
11  modules: [
12    // Register the core service module with your configuration
13    {
14      key: "agenticCommerce",
15      resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
16      options: {
17        api_key: process.env.AGENTIC_COMMERCE_API_KEY,
18        signatureKey: process.env.AGENTIC_COMMERCE_SIGNATURE_KEY,
19        storefront_url: process.env.STOREFRONT_URL || "https://your-store.com",
20        store_name: "Your Store Name",
21        store_description: "What your store sells",
22        // Reference payment handler adapter module keys (see Payment Handlers)
23        payment_handler_adapters: ["prismPaymentHandler"],
24      },
25    },
26  ],
27})

1# Required
2AGENTIC_COMMERCE_API_KEY=your-secret-api-key
3
4# Optional
5AGENTIC_COMMERCE_SIGNATURE_KEY=your-hmac-secret
6STOREFRONT_URL=https://your-store.com
7AGENTIC_STORE_NAME="Your Store"
8AGENTIC_STORE_DESCRIPTION="Premium widgets for humans and agents"

npx medusa develop

1# Discovery
2curl http://localhost:9000/.well-known/ucp
3curl http://localhost:9000/.well-known/acp.json
4
5# Search products (UCP)
6curl -X POST http://localhost:9000/ucp/catalog/search \
7  -H "UCP-Agent: my-agent/1.0" \
8  -H "Request-Id: $(uuidgen)" \
9  -H "Content-Type: application/json" \
10  -d '{"query": "t-shirt", "limit": 10}'

npm install @financedistrict/medusa-plugin-prism-payment

1import type {
2  PaymentHandlerAdapter,
3  CheckoutPrepareInput,
4} from "@financedistrict/medusa-plugin-agentic-commerce"
5
6export default class MyPaymentAdapter implements PaymentHandlerAdapter {
7  readonly id = "my_payment_handler"
8  readonly name = "My Payment"
9
10  // Discovery — what to advertise in .well-known endpoints
11  async getUcpDiscoveryHandlers(): Promise<Record<string, unknown[]>> {
12    return {
13      "com.example.my_payment": [{
14        id: "my-handler",
15        version: "1.0.0",
16      }],
17    }
18  }
19
20  async getAcpDiscoveryHandlers(): Promise<unknown[]> {
21    return [{
22      id: "com.example.my_payment",
23      name: "My Payment",
24      version: "1.0.0",
25      psp: "my-psp",
26      requires_delegate_payment: false,
27      instrument_schemas: [/* ... */],
28    }]
29  }
30
31  // Checkout preparation — called when a checkout session is created
32  async prepareCheckoutPayment(input: CheckoutPrepareInput) {
33    // Call your payment gateway, return config for the agent
34    return { id: "my-handler", version: "1.0.0", config: { /* ... */ } }
35  }
36
37  // Response formatting — include payment config in checkout responses
38  getUcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
39    return { /* ... */ }
40  }
41
42  getAcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
43    return [/* ... */]
44  }
45}

1// medusa-config.ts
2modules: [
3  {
4    key: "myPaymentHandler",
5    resolve: "./src/modules/my-payment-handler",
6    options: { /* ... */ },
7  },
8  {
9    key: "agenticCommerce",
10    resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
11    options: {
12      payment_handler_adapters: ["myPaymentHandler"],
13      // ...
14    },
15  },
16]

1medusa-config.ts
2  |
3  +-- plugins: [@financedistrict/medusa-plugin-agentic-commerce]
4  |     Routes, workflows, subscribers, jobs auto-discovered
5  |
6  +-- modules:
7        +-- agenticCommerce (core service)
8        |     Config, auth, formatting, payment registry
9        |
10        +-- prismPaymentHandler (optional adapter)
11              Discovery, checkout-prepare, response formatting

1Request → resolvePaymentAdapters middleware → route handler
2              |
3              +-- req.scope.resolve("prismPaymentHandler")
4              +-- agenticCommerceService.resolveAdapters(req.scope)

1import {
2  createCheckoutSessionWorkflow,
3  completeCheckoutSessionWorkflow,
4} from "@financedistrict/medusa-plugin-agentic-commerce/workflows"

1import {
2  // Service & module
3  AgenticCommerceService,
4  AgenticCommerceModule,
5  AGENTIC_COMMERCE_MODULE,
6
7  // Payment adapter interface
8  PaymentHandlerAdapter,      // type
9  CheckoutPrepareInput,       // type
10  PaymentHandlerRegistry,
11
12  // Error formatting
13  formatAcpError,
14  formatUcpError,
15
16  // Address translation
17  medusaToAcpAddress,
18  acpAddressToMedusa,
19  medusaToUcpAddress,
20  ucpAddressToMedusa,
21
22  // Status mapping
23  resolveAcpStatus,
24  resolveUcpStatus,
25} from "@financedistrict/medusa-plugin-agentic-commerce"