@financedistrict/medusa-plugin-agentic-commerce 0.1.0

package/.medusa/server/src/workflows/steps/setup-payment.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupPaymentStep = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const utils_1 = require("@medusajs/framework/utils");
+const core_flows_1 = require("@medusajs/medusa/core-flows");
+exports.setupPaymentStep = (0, workflows_sdk_1.createStep)("setup-payment", async (input, { container }) => {
+    const query = container.resolve(utils_1.ContainerRegistrationKeys.QUERY);
+    // Check if cart already has a payment collection
+    const { data: [cart] } = await query.graph({
+        entity: "cart",
+        fields: [
+            "id",
+            "payment_collection.id",
+            "payment_collection.payment_sessions.*",
+        ],
+        filters: { id: input.cart_id },
+    });
+    let paymentCollectionId = cart?.payment_collection?.id;
+    // Create payment collection if none exists
+    if (!paymentCollectionId) {
+        await (0, core_flows_1.createPaymentCollectionForCartWorkflow)(container).run({
+            input: { cart_id: input.cart_id },
+        });
+        // Re-fetch to get the payment collection ID
+        const { data: [updatedCart] } = await query.graph({
+            entity: "cart",
+            fields: ["id", "payment_collection.id"],
+            filters: { id: input.cart_id },
+        });
+        paymentCollectionId = updatedCart?.payment_collection?.id;
+        if (!paymentCollectionId) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "Failed to create payment collection for cart");
+        }
+    }
+    // Check if there's already an active payment session
+    const existingSessions = cart?.payment_collection?.payment_sessions || [];
+    const hasActiveSession = existingSessions.some((s) => s.status === "pending" || s.status === "authorized");
+    if (!hasActiveSession) {
+        // Create payment session with the configured provider
+        const sessionData = {};
+        // Pass EIP-3009 authorization to the payment provider
+        // The provider receives this in its initiatePayment() and stores it in session data,
+        // then receives it again in authorizePayment() during cart completion
+        if (input.payment_data?.eip3009_authorization) {
+            sessionData.eip3009_authorization = input.payment_data.eip3009_authorization;
+            if (input.payment_data.x402_version) {
+                sessionData.x402_version = input.payment_data.x402_version;
+            }
+        }
+        // Legacy: pass flat token for backwards compatibility
+        if (input.payment_data?.token && !input.payment_data?.eip3009_authorization) {
+            sessionData.shared_payment_token = input.payment_data.token;
+        }
+        await (0, core_flows_1.createPaymentSessionsWorkflow)(container).run({
+            input: {
+                payment_collection_id: paymentCollectionId,
+                provider_id: input.payment_provider_id,
+                data: sessionData,
+                context: {},
+            },
+        });
+    }
+    return new workflows_sdk_1.StepResponse({
+        cart_id: input.cart_id,
+        payment_collection_id: paymentCollectionId,
+    }, 
+    // Compensation data — used for cleanup on workflow failure
+    {
+        cart_id: input.cart_id,
+        payment_collection_id: paymentCollectionId,
+    });
+}, 
+// Compensation: refresh payment collection on failure
+async (compensationData, { container }) => {
+    if (!compensationData?.cart_id)
+        return;
+    try {
+        const { refreshPaymentCollectionForCartWorkflow } = await import("@medusajs/medusa/core-flows");
+        await refreshPaymentCollectionForCartWorkflow(container).run({
+            input: { cart_id: compensationData.cart_id },
+        });
+    }
+    catch {
+        // Best effort cleanup — don't throw from compensation
+    }
+});
+//# sourceMappingURL=setup-payment.js.map

package/.medusa/server/src/workflows/steps/setup-payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-payment.js","sourceRoot":"","sources":["../../../../../src/workflows/steps/setup-payment.ts"],"names":[],"mappings":"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"}

package/.medusa/server/src/workflows/steps/validate-checkout-prerequisites.d.ts

@@ -0,0 +1,9 @@
+type ValidateInput = {
+    cart_id: string;
+};
+export declare const validateCheckoutPrerequisitesStep: import("@medusajs/framework/workflows-sdk").StepFunction<ValidateInput, {
+    cart_id: string;
+    validated: boolean;
+}>;
+export {};
+//# sourceMappingURL=validate-checkout-prerequisites.d.ts.map

package/.medusa/server/src/workflows/steps/validate-checkout-prerequisites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-checkout-prerequisites.d.ts","sourceRoot":"","sources":["../../../../../src/workflows/steps/validate-checkout-prerequisites.ts"],"names":[],"mappings":"AAIA,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,iCAAiC;;;EAuD7C,CAAA"}

package/.medusa/server/src/workflows/steps/validate-checkout-prerequisites.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCheckoutPrerequisitesStep = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const utils_1 = require("@medusajs/framework/utils");
+const cart_fields_1 = require("../../lib/cart-fields");
+exports.validateCheckoutPrerequisitesStep = (0, workflows_sdk_1.createStep)("validate-checkout-prerequisites", async ({ cart_id }, { container }) => {
+    const query = container.resolve(utils_1.ContainerRegistrationKeys.QUERY);
+    const { data: [cart] } = await query.graph({
+        entity: "cart",
+        fields: cart_fields_1.CART_VALIDATION_FIELDS,
+        filters: { id: cart_id },
+    });
+    if (!cart) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_FOUND, `Cart ${cart_id} not found`);
+    }
+    if (cart.metadata?.checkout_session_canceled) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, "Checkout session has been cancelled");
+    }
+    if (cart.completed_at) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.DUPLICATE_ERROR, "Checkout session has already been completed");
+    }
+    if (!cart.items || cart.items.length === 0) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Cart is empty — add items before completing checkout");
+    }
+    if (!cart.email) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Email is required to complete checkout");
+    }
+    if (!cart.shipping_address?.id) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Shipping address is required to complete checkout");
+    }
+    return new workflows_sdk_1.StepResponse({ cart_id, validated: true });
+});
+//# sourceMappingURL=validate-checkout-prerequisites.js.map

package/.medusa/server/src/workflows/steps/validate-checkout-prerequisites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-checkout-prerequisites.js","sourceRoot":"","sources":["../../../../../src/workflows/steps/validate-checkout-prerequisites.ts"],"names":[],"mappings":";;;AAAA,qEAA4E;AAC5E,qDAAkF;AAClF,uDAA8D;AAMjD,QAAA,iCAAiC,GAAG,IAAA,0BAAU,EACzD,iCAAiC,EACjC,KAAK,EAAE,EAAE,OAAO,EAAiB,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;IAClD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,iCAAyB,CAAC,KAAK,CAAC,CAAA;IAEhE,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC;QACzC,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,oCAAsB;QAC9B,OAAO,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE;KACzB,CAAC,CAAA;IAEF,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,SAAS,EAC3B,QAAQ,OAAO,YAAY,CAC5B,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,EAAE,yBAAyB,EAAE,CAAC;QAC7C,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,WAAW,EAC7B,qCAAqC,CACtC,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,eAAe,EACjC,6CAA6C,CAC9C,CAAA;IACH,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,YAAY,EAC9B,sDAAsD,CACvD,CAAA;IACH,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,YAAY,EAC9B,wCAAwC,CACzC,CAAA;IACH,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,mBAAW,CACnB,mBAAW,CAAC,KAAK,CAAC,YAAY,EAC9B,mDAAmD,CACpD,CAAA;IACH,CAAC;IAED,OAAO,IAAI,4BAAY,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AACvD,CAAC,CACF,CAAA"}

package/.medusa/server/src/workflows/update-checkout-session.d.ts

@@ -0,0 +1,22 @@
+type ItemUpdate = {
+    variant_id?: string;
+    line_item_id?: string;
+    quantity: number;
+};
+type UpdateCheckoutSessionInput = {
+    cart_id: string;
+    items?: ItemUpdate[];
+    email?: string;
+    shipping_address?: Record<string, unknown>;
+    fulfillment_address?: Record<string, unknown>;
+    buyer?: {
+        email?: string;
+        name?: string;
+    };
+    fulfillment_option_id?: string;
+};
+declare const updateCheckoutSessionWorkflow: import("@medusajs/framework/workflows-sdk").ReturnWorkflow<UpdateCheckoutSessionInput, {
+    cart_id: string;
+}, []>;
+export default updateCheckoutSessionWorkflow;
+//# sourceMappingURL=update-checkout-session.d.ts.map

package/.medusa/server/src/workflows/update-checkout-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checkout-session.d.ts","sourceRoot":"","sources":["../../../../src/workflows/update-checkout-session.ts"],"names":[],"mappings":"AAeA,KAAK,UAAU,GAAG;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,KAAK,0BAA0B,GAAG;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,UAAU,EAAE,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,QAAA,MAAM,6BAA6B;;MAwHlC,CAAA;AAED,eAAe,6BAA6B,CAAA"}

package/.medusa/server/src/workflows/update-checkout-session.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const core_flows_1 = require("@medusajs/medusa/core-flows");
+const updateCheckoutSessionWorkflow = (0, workflows_sdk_1.createWorkflow)("update-checkout-session", (input) => {
+    // Step 1: Update cart properties (email, shipping address)
+    const hasCartUpdates = (0, workflows_sdk_1.transform)(input, (input) => {
+        const email = input.buyer?.email || input.email;
+        const address = input.fulfillment_address || input.shipping_address;
+        return !!(email || address);
+    });
+    (0, workflows_sdk_1.when)(hasCartUpdates, (v) => v).then(() => {
+        const updateData = (0, workflows_sdk_1.transform)(input, (input) => {
+            const data = { id: input.cart_id };
+            const email = input.buyer?.email || input.email;
+            const address = input.fulfillment_address || input.shipping_address;
+            if (email)
+                data.email = email;
+            if (address)
+                data.shipping_address = address;
+            return data;
+        });
+        core_flows_1.updateCartWorkflow.runAsStep({ input: updateData });
+    });
+    // Step 2a: Add new items (items with variant_id and no line_item_id)
+    const itemActions = (0, workflows_sdk_1.transform)(input, (input) => {
+        const items = input.items || [];
+        return {
+            toAdd: items.filter((i) => i.variant_id && !i.line_item_id && i.quantity > 0),
+            toUpdate: items.filter((i) => i.line_item_id && i.quantity > 0),
+            toRemove: items.filter((i) => i.line_item_id && i.quantity === 0),
+        };
+    });
+    (0, workflows_sdk_1.when)(itemActions, (a) => a.toAdd.length > 0).then(() => {
+        core_flows_1.addToCartWorkflow.runAsStep({
+            input: (0, workflows_sdk_1.transform)({ input, itemActions }, ({ input, itemActions }) => ({
+                cart_id: input.cart_id,
+                items: itemActions.toAdd.map((i) => ({
+                    variant_id: i.variant_id,
+                    quantity: i.quantity,
+                })),
+            })),
+        });
+    });
+    // Step 2b: Update existing item quantities
+    (0, workflows_sdk_1.when)(itemActions, (a) => a.toUpdate.length > 0).then(() => {
+        // updateLineItemInCartWorkflow handles one item at a time
+        // For multiple updates, we process the first one here
+        // (Medusa v2 workflows don't support dynamic loops — for MVP this handles the common case)
+        const firstUpdate = (0, workflows_sdk_1.transform)({ input, itemActions }, ({ input, itemActions }) => ({
+            cart_id: input.cart_id,
+            item_id: itemActions.toUpdate[0].line_item_id,
+            update: { quantity: itemActions.toUpdate[0].quantity },
+        }));
+        core_flows_1.updateLineItemInCartWorkflow.runAsStep({ input: firstUpdate });
+    });
+    // Step 2c: Remove items (quantity = 0)
+    (0, workflows_sdk_1.when)(itemActions, (a) => a.toRemove.length > 0).then(() => {
+        core_flows_1.deleteLineItemsWorkflow.runAsStep({
+            input: (0, workflows_sdk_1.transform)({ input, itemActions }, ({ input, itemActions }) => ({
+                cart_id: input.cart_id,
+                ids: itemActions.toRemove.map((i) => i.line_item_id),
+            })),
+        });
+    });
+    // Step 3: If address was changed and no explicit fulfillment option, auto-select shipping
+    const shouldAutoSelectShipping = (0, workflows_sdk_1.transform)(input, (input) => {
+        const addressChanged = !!(input.fulfillment_address || input.shipping_address);
+        const noExplicitOption = !input.fulfillment_option_id;
+        return addressChanged && noExplicitOption;
+    });
+    const shippingOptions = (0, workflows_sdk_1.when)(shouldAutoSelectShipping, (v) => !!v).then(() => {
+        return core_flows_1.listShippingOptionsForCartWorkflow.runAsStep({
+            input: (0, workflows_sdk_1.transform)(input, (input) => ({
+                cart_id: input.cart_id,
+                is_return: false,
+            })),
+        });
+    });
+    const cheapestOptionId = (0, workflows_sdk_1.transform)({ shouldAutoSelectShipping, shippingOptions }, ({ shouldAutoSelectShipping, shippingOptions }) => {
+        if (!shouldAutoSelectShipping || !shippingOptions || !Array.isArray(shippingOptions) || shippingOptions.length === 0)
+            return null;
+        const sorted = [...shippingOptions].sort((a, b) => (a.amount ?? 0) - (b.amount ?? 0));
+        return sorted[0]?.id || null;
+    });
+    // Resolve the final shipping option: explicit choice wins, otherwise auto-select cheapest
+    const shippingOptionToApply = (0, workflows_sdk_1.transform)({ input, cheapestOptionId }, ({ input, cheapestOptionId }) => {
+        if (input.fulfillment_option_id)
+            return input.fulfillment_option_id;
+        return cheapestOptionId;
+    });
+    (0, workflows_sdk_1.when)(shippingOptionToApply, (id) => !!id).then(() => {
+        core_flows_1.addShippingMethodToCartWorkflow.runAsStep({
+            input: (0, workflows_sdk_1.transform)({ input, shippingOptionToApply }, ({ input, shippingOptionToApply }) => ({
+                cart_id: input.cart_id,
+                options: [{ id: shippingOptionToApply }],
+            })),
+        });
+    });
+    return new workflows_sdk_1.WorkflowResponse((0, workflows_sdk_1.transform)(input, (input) => ({ cart_id: input.cart_id })));
+});
+exports.default = updateCheckoutSessionWorkflow;
+//# sourceMappingURL=update-checkout-session.js.map

package/.medusa/server/src/workflows/update-checkout-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checkout-session.js","sourceRoot":"","sources":["../../../../src/workflows/update-checkout-session.ts"],"names":[],"mappings":";;AAAA,qEAK0C;AAC1C,4DAOoC;AAkBpC,MAAM,6BAA6B,GAAG,IAAA,8BAAc,EAClD,yBAAyB,EACzB,CAAC,KAAiC,EAAE,EAAE;IACpC,2DAA2D;IAC3D,MAAM,cAAc,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;QAChD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,KAAK,IAAI,KAAK,CAAC,KAAK,CAAA;QAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,gBAAgB,CAAA;QACnE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;IAEF,IAAA,oBAAI,EAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACvC,MAAM,UAAU,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;YAC5C,MAAM,IAAI,GAA4B,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;YAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,KAAK,IAAI,KAAK,CAAC,KAAK,CAAA;YAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,gBAAgB,CAAA;YACnE,IAAI,KAAK;gBAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;YAC7B,IAAI,OAAO;gBAAE,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAA;YAC5C,OAAO,IAAI,CAAA;QACb,CAAC,CAAC,CAAA;QACF,+BAAkB,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAiB,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAC,CAAA;IAEF,qEAAqE;IACrE,MAAM,WAAW,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAA;QAC/B,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;YAC7E,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;YAC/D,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC;SAClE,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,IAAA,oBAAI,EAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACrD,8BAAiB,CAAC,SAAS,CAAC;YAC1B,KAAK,EAAE,IAAA,yBAAS,EAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;gBACpE,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACnC,UAAU,EAAE,CAAC,CAAC,UAAW;oBACzB,QAAQ,EAAE,CAAC,CAAC,QAAQ;iBACrB,CAAC,CAAC;aACJ,CAAC,CAAC;SACJ,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,2CAA2C;IAC3C,IAAA,oBAAI,EAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACxD,0DAA0D;QAC1D,sDAAsD;QACtD,2FAA2F;QAC3F,MAAM,WAAW,GAAG,IAAA,yBAAS,EAC3B,EAAE,KAAK,EAAE,WAAW,EAAE,EACtB,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;YAC3B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAa;YAC9C,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;SACvD,CAAC,CACH,CAAA;QACD,yCAA4B,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAA;IAChE,CAAC,CAAC,CAAA;IAEF,uCAAuC;IACvC,IAAA,oBAAI,EAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACxD,oCAAuB,CAAC,SAAS,CAAC;YAChC,KAAK,EAAE,IAAA,yBAAS,EAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;gBACpE,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAa,CAAC;aACtD,CAAC,CAAC;SACJ,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,0FAA0F;IAC1F,MAAM,wBAAwB,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;QAC1D,MAAM,cAAc,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAA;QAC9E,MAAM,gBAAgB,GAAG,CAAC,KAAK,CAAC,qBAAqB,CAAA;QACrD,OAAO,cAAc,IAAI,gBAAgB,CAAA;IAC3C,CAAC,CAAC,CAAA;IAEF,MAAM,eAAe,GAAG,IAAA,oBAAI,EAAC,wBAAwB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QAC3E,OAAO,+CAAkC,CAAC,SAAS,CAAC;YAClD,KAAK,EAAE,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAClC,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;SACJ,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,MAAM,gBAAgB,GAAG,IAAA,yBAAS,EAChC,EAAE,wBAAwB,EAAE,eAAe,EAAE,EAC7C,CAAC,EAAE,wBAAwB,EAAE,eAAe,EAAE,EAAE,EAAE;QAChD,IAAI,CAAC,wBAAwB,IAAI,CAAC,eAAe,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACjI,MAAM,MAAM,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAA;QAC/F,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,IAAI,CAAA;IAC9B,CAAC,CACF,CAAA;IAED,0FAA0F;IAC1F,MAAM,qBAAqB,GAAG,IAAA,yBAAS,EACrC,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAC3B,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,EAAE;QAC9B,IAAI,KAAK,CAAC,qBAAqB;YAAE,OAAO,KAAK,CAAC,qBAAqB,CAAA;QACnE,OAAO,gBAAgB,CAAA;IACzB,CAAC,CACF,CAAA;IAED,IAAA,oBAAI,EAAC,qBAAqB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QAClD,4CAA+B,CAAC,SAAS,CAAC;YACxC,KAAK,EAAE,IAAA,yBAAS,EACd,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAChC,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC,CAAC;gBACrC,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,qBAAqB,EAAE,CAAC;aACzC,CAAC,CACH;SACF,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,OAAO,IAAI,gCAAgB,CACzB,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAC1D,CAAA;AACH,CAAC,CACF,CAAA;AAED,kBAAe,6BAA6B,CAAA"}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Finance District OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+<h1 align="center">@financedistrict/medusa-plugin-agentic-commerce</h1>
+
+<p align="center">
+  Turn any Medusa v2 store into an AI-native storefront.<br />
+  Adds <strong>UCP</strong> and <strong>ACP</strong> protocol endpoints so AI agents can discover products, check out, pay, and track orders — all through standard HTTP APIs.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &middot;
+  <a href="#protocols">Protocols</a> &middot;
+  <a href="#api-reference">API Reference</a> &middot;
+  <a href="#payment-handlers">Payment Handlers</a> &middot;
+  <a href="#configuration">Configuration</a>
+</p>
+
+---
+
+## Why
+
+AI agents are becoming a real commerce channel. They need machine-readable APIs to browse catalogs, fill carts, handle payments, and confirm orders — without scraping HTML or reverse-engineering checkout flows.
+
+This plugin gives your Medusa store a **standards-compliant agent API** in minutes. No custom code, no frontend changes. And the **pluggable payment handler adapter system** means any payment method — stablecoins, cards, wallets — can be added without modifying the core plugin.
+
+## What You Get
+
+| Feature | Description |
+|---------|-------------|
+| **Dual protocol support** | Both UCP and ACP endpoints from a single plugin |
+| **Product discovery** | Full-text search and direct lookup for agents to browse your catalog |
+| **Checkout sessions** | Create, update, complete, and cancel — with idempotency built in |
+| **Pluggable payments** | Bring your own payment handler via the adapter interface |
+| **Order tracking** | Agents can retrieve order status and details |
+| **Webhook notifications** | Automatic agent callbacks on order placement |
+| **Protocol discovery** | `/.well-known/ucp` and `/.well-known/acp.json` for automatic capability detection |
+| **Product feed sync** | Scheduled job to push your catalog to agent platforms |
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @financedistrict/medusa-plugin-agentic-commerce
+```
+
+### 2. Configure `medusa-config.ts`
+
+```typescript
+import { defineConfig } from "@medusajs/framework/utils"
+
+export default defineConfig({
+  // Register the plugin for route/workflow/subscriber auto-discovery
+  plugins: [
+    {
+      resolve: "@financedistrict/medusa-plugin-agentic-commerce",
+      options: {},
+    },
+  ],
+  modules: [
+    // Register the core service module with your configuration
+    {
+      key: "agenticCommerce",
+      resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
+      options: {
+        api_key: process.env.AGENTIC_COMMERCE_API_KEY,
+        signatureKey: process.env.AGENTIC_COMMERCE_SIGNATURE_KEY,
+        storefront_url: process.env.STOREFRONT_URL || "https://your-store.com",
+        store_name: "Your Store Name",
+        store_description: "What your store sells",
+        // Reference payment handler adapter module keys (see Payment Handlers)
+        payment_handler_adapters: ["prismPaymentHandler"],
+      },
+    },
+  ],
+})
+```
+
+### 3. Set Environment Variables
+
+```bash
+# Required
+AGENTIC_COMMERCE_API_KEY=your-secret-api-key
+
+# Optional
+AGENTIC_COMMERCE_SIGNATURE_KEY=your-hmac-secret
+STOREFRONT_URL=https://your-store.com
+AGENTIC_STORE_NAME="Your Store"
+AGENTIC_STORE_DESCRIPTION="Premium widgets for humans and agents"
+```
+
+### 4. Start Your Store
+
+```bash
+npx medusa develop
+```
+
+Your agent APIs are now live:
+
+```bash
+# Discovery
+curl http://localhost:9000/.well-known/ucp
+curl http://localhost:9000/.well-known/acp.json
+
+# Search products (UCP)
+curl -X POST http://localhost:9000/ucp/catalog/search \
+  -H "UCP-Agent: my-agent/1.0" \
+  -H "Request-Id: $(uuidgen)" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "t-shirt", "limit": 10}'
+```
+
+## Protocols
+
+### UCP (Unified Commerce Protocol)
+
+UCP is designed for **agent-to-merchant** interactions. It uses a shopping-cart model where agents manage carts directly.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/ucp` | GET | Protocol discovery and capabilities |
+| `/ucp/catalog/search` | POST | Full-text product search |
+| `/ucp/catalog/lookup` | POST | Direct product lookup by ID or handle |
+| `/ucp/carts` | POST | Create a new cart |
+| `/ucp/carts/:id` | GET | Retrieve cart |
+| `/ucp/carts/:id` | PUT | Update cart (add/remove items, set address) |
+| `/ucp/checkout-sessions` | POST | Create checkout session from cart |
+| `/ucp/checkout-sessions/:id` | GET | Retrieve checkout session |
+| `/ucp/checkout-sessions/:id` | PUT | Update checkout session |
+| `/ucp/checkout-sessions/:id/complete` | POST | Complete checkout and place order |
+| `/ucp/checkout-sessions/:id/cancel` | POST | Cancel checkout session |
+| `/ucp/orders/:id` | GET | Retrieve order details |
+
+**Required headers:** `UCP-Agent`, `Request-Id`
+
+### ACP (Agent Commerce Protocol)
+
+ACP is designed for **platform-to-merchant** interactions. It uses a session-based model where the platform manages the checkout flow.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/acp.json` | GET | Protocol discovery and capabilities |
+| `/acp/checkout_sessions` | POST | Create checkout session |
+| `/acp/checkout_sessions/:id` | GET | Retrieve checkout session |
+| `/acp/checkout_sessions/:id` | POST | Update checkout session |
+| `/acp/checkout_sessions/:id/complete` | POST | Complete checkout |
+| `/acp/checkout_sessions/:id/cancel` | POST | Cancel checkout session |
+| `/acp/orders/:id` | GET | Retrieve order |
+| `/acp/product-feed` | GET | Retrieve product feed |
+
+**Required headers:** `Authorization: Bearer <api_key>`, `API-Version`
+
+## Payment Handlers
+
+Payment is handled through a **pluggable adapter system**. Each adapter implements the `PaymentHandlerAdapter` interface and registers as a Medusa module.
+
+### Using the Prism Payment Handler
+
+For x402 stablecoin payments (USDC, FDUSD, etc.), use the companion package:
+
+```bash
+npm install @financedistrict/medusa-plugin-prism-payment
+```
+
+See [@financedistrict/medusa-plugin-prism-payment](../prism-payment/README.md) for setup instructions.
+
+### Building a Custom Payment Handler
+
+Implement the `PaymentHandlerAdapter` interface:
+
+```typescript
+import type {
+  PaymentHandlerAdapter,
+  CheckoutPrepareInput,
+} from "@financedistrict/medusa-plugin-agentic-commerce"
+
+export default class MyPaymentAdapter implements PaymentHandlerAdapter {
+  readonly id = "my_payment_handler"
+  readonly name = "My Payment"
+
+  // Discovery — what to advertise in .well-known endpoints
+  async getUcpDiscoveryHandlers(): Promise<Record<string, unknown[]>> {
+    return {
+      "com.example.my_payment": [{
+        id: "my-handler",
+        version: "1.0.0",
+      }],
+    }
+  }
+
+  async getAcpDiscoveryHandlers(): Promise<unknown[]> {
+    return [{
+      id: "com.example.my_payment",
+      name: "My Payment",
+      version: "1.0.0",
+      psp: "my-psp",
+      requires_delegate_payment: false,
+      instrument_schemas: [/* ... */],
+    }]
+  }
+
+  // Checkout preparation — called when a checkout session is created
+  async prepareCheckoutPayment(input: CheckoutPrepareInput) {
+    // Call your payment gateway, return config for the agent
+    return { id: "my-handler", version: "1.0.0", config: { /* ... */ } }
+  }
+
+  // Response formatting — include payment config in checkout responses
+  getUcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
+    return { /* ... */ }
+  }
+
+  getAcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
+    return [/* ... */]
+  }
+}
+```
+
+Register it as a Medusa module and reference it in `payment_handler_adapters`:
+
+```typescript
+// medusa-config.ts
+modules: [
+  {
+    key: "myPaymentHandler",
+    resolve: "./src/modules/my-payment-handler",
+    options: { /* ... */ },
+  },
+  {
+    key: "agenticCommerce",
+    resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
+    options: {
+      payment_handler_adapters: ["myPaymentHandler"],
+      // ...
+    },
+  },
+]
+```
+
+## Architecture
+
+```
+medusa-config.ts
+  |
+  +-- plugins: [@financedistrict/medusa-plugin-agentic-commerce]
+  |     Routes, workflows, subscribers, jobs auto-discovered
+  |
+  +-- modules:
+        +-- agenticCommerce (core service)
+        |     Config, auth, formatting, payment registry
+        |
+        +-- prismPaymentHandler (optional adapter)
+              Discovery, checkout-prepare, response formatting
+```
+
+### How Adapter Resolution Works
+
+Medusa v2 modules have isolated DI containers. The plugin resolves payment handler adapters from the **request-scoped container** (`req.scope`) via middleware — not from the module's constructor. This ensures all modules are registered and accessible at request time.
+
+```
+Request → resolvePaymentAdapters middleware → route handler
+              |
+              +-- req.scope.resolve("prismPaymentHandler")
+              +-- agenticCommerceService.resolveAdapters(req.scope)
+```
+
+## Workflows
+
+The plugin provides four reusable workflows that orchestrate the checkout process:
+
+| Workflow | Description |
+|----------|-------------|
+| `createCheckoutSessionWorkflow` | Validates cart, resolves region, prepares payment |
+| `updateCheckoutSessionWorkflow` | Handles item/address changes, re-prepares payment |
+| `completeCheckoutSessionWorkflow` | Completes payment, creates order |
+| `cancelCheckoutSessionWorkflow` | Cancels session and releases resources |
+
+Import them in your custom code:
+
+```typescript
+import {
+  createCheckoutSessionWorkflow,
+  completeCheckoutSessionWorkflow,
+} from "@financedistrict/medusa-plugin-agentic-commerce/workflows"
+```
+
+## Configuration
+
+### Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | `string` | `""` | API key for ACP Bearer token authentication |
+| `signatureKey` | `string` | `""` | HMAC-SHA256 key for request signing |
+| `storefront_url` | `string` | `"http://localhost:8000"` | Public URL of your storefront |
+| `store_name` | `string` | `"My Store"` | Store name in protocol responses |
+| `store_description` | `string` | `""` | Store description for discovery |
+| `payment_provider_id` | `string` | `"pp_system_default"` | Medusa payment provider ID |
+| `payment_handler_adapters` | `string[]` | `[]` | Module keys of payment handler adapters |
+| `ucp_version` | `string` | `"2026-01-11"` | UCP protocol version to advertise |
+| `acp_version` | `string` | `"2026-01-30"` | ACP protocol version to advertise |
+
+### Environment Variables
+
+| Variable | Maps to |
+|----------|---------|
+| `AGENTIC_COMMERCE_API_KEY` | `api_key` |
+| `AGENTIC_COMMERCE_SIGNATURE_KEY` | `signatureKey` |
+| `STOREFRONT_URL` | `storefront_url` |
+| `AGENTIC_STORE_NAME` | `store_name` |
+| `AGENTIC_STORE_DESCRIPTION` | `store_description` |
+| `AGENTIC_PAYMENT_PROVIDER` | `payment_provider_id` |
+
+## Exported Utilities
+
+```typescript
+import {
+  // Service & module
+  AgenticCommerceService,
+  AgenticCommerceModule,
+  AGENTIC_COMMERCE_MODULE,
+
+  // Payment adapter interface
+  PaymentHandlerAdapter,      // type
+  CheckoutPrepareInput,       // type
+  PaymentHandlerRegistry,
+
+  // Error formatting
+  formatAcpError,
+  formatUcpError,
+
+  // Address translation
+  medusaToAcpAddress,
+  acpAddressToMedusa,
+  medusaToUcpAddress,
+  ucpAddressToMedusa,
+
+  // Status mapping
+  resolveAcpStatus,
+  resolveUcpStatus,
+} from "@financedistrict/medusa-plugin-agentic-commerce"
+```
+
+## Requirements
+
+- **Medusa v2** (2.x)
+- **Node.js** 20+
+- **PostgreSQL** (standard Medusa requirement)
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  Built by <a href="https://fd.xyz">Finance District</a>
+</p>