@reactionary/acp 0.10.41 → 0.10.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/acp",
-  "version": "0.10.41",
+  "version": "0.10.43",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
@@ -9,8 +9,8 @@
     "url": "git+https://github.com/Solteq/reactionary.git"
   },
   "dependencies": {
-    "@reactionary/core": "0.10.41",
-    "@reactionary/feeds": "0.10.41",
+    "@reactionary/core": "0.10.43",
+    "@reactionary/feeds": "0.10.43",
     "zod": "4.1.9"
   },
   "devDependencies": {

package/src/index.d.ts

@@ -1,2 +1,6 @@
 export * from './lib/acp-schemas.js';
 export * from './lib/reactionary-acp-server.js';
+export * from './lib/acp-payment-handlers.js';
+export { ReactionaryACPFeedPublisher, createACPFeedPublisherFromConfig, type ACPFeedApiConfig, type ACPFeedPublishResult, type ACPFeedPublishingConfig, type ReactionaryACPFeedPublisherOptions, } from '@reactionary/feeds';
+export * from './lib/acp-webhooks.js';
+export * from './lib/acp-discounts.js';

package/src/lib/acp-discounts.d.ts

@@ -0,0 +1,45 @@
+import type { Cart, MonetaryAmount, Result } from '@reactionary/core';
+import * as z from 'zod';
+/** The discount extension, as declared in session `capabilities.extensions`. */
+export declare const ACP_DISCOUNT_EXTENSION: {
+    name: string;
+    extends: string[];
+};
+export declare const ACPDiscountsRequestSchema: z.ZodObject<{
+    codes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ACPRejectedDiscountSchema: z.ZodObject<{
+    code: z.ZodString;
+    reason: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ACPRejectedDiscount = z.infer<typeof ACPRejectedDiscountSchema>;
+/** The cart operations the discount extension needs. */
+export interface ACPDiscountCart {
+    applyCouponCode?(payload: unknown): Promise<Result<Cart>>;
+    removeCouponCode?(payload: unknown): Promise<Result<Cart>>;
+}
+/**
+ * The codes a request submits: `discounts.codes`, else the deprecated
+ * `coupons` alias (discount extension §10.1). Undefined leaves the codes
+ * unchanged; an empty list clears them.
+ */
+export declare function getRequestedDiscountCodes(discounts: z.infer<typeof ACPDiscountsRequestSchema> | undefined, coupons: string[] | undefined): string[] | undefined;
+/**
+ * Applies a submitted code set to the cart with replacement semantics:
+ * codes no longer submitted are removed, new ones applied. Codes match
+ * case-insensitively; a backend that matches exactly is also tried with the
+ * upper-cased code (as in the UCP adapter). The backend does not say why a
+ * code was rejected, so rejections are `discount_code_invalid`.
+ */
+export declare function applyDiscountCodes(cartCapability: ACPDiscountCart, cart: Cart, codes: string[]): Promise<{
+    cart: Cart;
+    rejected: ACPRejectedDiscount[];
+}>;
+/**
+ * The session's `discounts`: submitted codes, the cart's promotions as
+ * applied discounts (code-based and automatic), and rejected codes. A sole
+ * promotion is attributed the whole discount, allocated to the discounted
+ * line items when it is allocated to lines only.
+ */
+export declare function toACPDiscounts(cart: Cart, codes: string[], rejected: ACPRejectedDiscount[], toMinorUnits: (amount: MonetaryAmount) => number): Record<string, unknown>;

package/src/lib/acp-idempotency.d.ts

@@ -0,0 +1,23 @@
+import type { Cache } from '@reactionary/core';
+/** Keys MUST be retained for at least 24 hours (checkout RFC §6.6). */
+export declare const ACP_MIN_IDEMPOTENCY_TTL_SECONDS: number;
+/**
+ * ACP idempotency (checkout RFC §6): every POST carries an Idempotency-Key,
+ * scoped to the authenticated identity and endpoint. A replay of the same
+ * body returns the stored response without re-executing side effects; a
+ * different body is a conflict, and a key still being processed is in
+ * flight. Server errors are never stored, so a retry runs afresh.
+ *
+ * The cache offers no atomic insert, so concurrent requests on one instance
+ * are additionally serialized in memory; across instances the in-flight
+ * marker is best effort.
+ */
+export declare class ACPIdempotency {
+    private readonly cache;
+    private readonly ttlSeconds;
+    /** Fingerprints of the requests in flight on this instance, by cache key. */
+    private readonly inFlight;
+    constructor(cache: Cache, ttlSeconds: number);
+    run(request: Request, scope: string, handle: () => Promise<Response>): Promise<Response>;
+    private put;
+}

package/src/lib/acp-mcp.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The ACP MCP transport binding: the five checkout tools over JSON-RPC 2.0
+ * (Streamable HTTP, JSON responses). Tool calls are dispatched to the REST
+ * handlers: `meta` becomes the protocol headers, `id` the path parameter
+ * and `payload` the request body; the connection's Authorization applies to
+ * every call. Results are the REST response bodies as-is; errors are
+ * JSON-RPC -32000 with the ACP Error in `data`.
+ */
+export declare class ACPMcpEndpoint {
+    private readonly serverInfo;
+    /** Handles a REST request, e.g. the ACP server's own fetch. */
+    private readonly rest;
+    constructor(serverInfo: {
+        name: string;
+        version: string;
+    }, 
+    /** Handles a REST request, e.g. the ACP server's own fetch. */
+    rest: (request: Request) => Promise<Response>);
+    handle(request: Request, restBaseUrl: string): Promise<Response>;
+    private callTool;
+}

package/src/lib/acp-payment-handlers.d.ts

@@ -0,0 +1,64 @@
+import type { PaymentMethod } from '@reactionary/core';
+/**
+ * A payment handler declaration, as advertised in a checkout session's
+ * `capabilities.payment.handlers` (payment handlers RFC §5.1).
+ */
+export interface ACPPaymentHandler {
+    /** Seller-defined handler id, referenced by `payment_data.handler_id`. */
+    id: string;
+    /** Handler specification name in reverse-DNS format, e.g. `dev.acp.tokenized.card`. */
+    name: string;
+    /** Human-readable name for payment UIs, e.g. `Credit Card`. */
+    display_name?: string;
+    /** Handler specification version, `YYYY-MM-DD`. */
+    version: string;
+    spec: string;
+    requires_delegate_payment: boolean;
+    requires_pci_compliance: boolean;
+    /** The seller's payment service provider, e.g. `stripe`. */
+    psp: string;
+    config_schema: string;
+    instrument_schemas: string[];
+    /** Handler-specific configuration; MUST include `merchant_id` and `psp` (RFC §10). */
+    config: ACPPaymentHandlerConfig;
+    /** Suggested display order, lower first. Agents may reorder. */
+    display_order?: number;
+}
+export interface ACPPaymentHandlerConfig {
+    /** The seller's account with the PSP; agents scope delegated tokens to it. */
+    merchant_id: string;
+    psp: string;
+    [key: string]: unknown;
+}
+/**
+ * A payment handler the server advertises, and the backend payment method its
+ * payments are placed with.
+ */
+export interface ACPPaymentHandlerOption {
+    handler: ACPPaymentHandler;
+    /**
+     * The reactionary payment method used for the payment instruction.
+     * Defaults to method `card` with the handler's PSP as name and processor.
+     */
+    paymentMethod?: PaymentMethod['identifier'];
+}
+export interface ACPTokenizedCardHandlerOptions {
+    id?: string;
+    psp: string;
+    merchantId: string;
+    displayName?: string;
+    acceptedBrands?: string[];
+    acceptedFundingTypes?: Array<'credit' | 'debit' | 'prepaid'>;
+    supports3ds?: boolean;
+    displayOrder?: number;
+    paymentMethod?: PaymentMethod['identifier'];
+    /** Additional handler configuration, e.g. `merchant_display_name`. */
+    config?: Record<string, unknown>;
+}
+/**
+ * The reference card handler, `dev.acp.tokenized.card`: delegated payment
+ * tokens (SPTs) minted by the seller's PSP for its merchant account.
+ */
+export declare function createTokenizedCardHandler(options: ACPTokenizedCardHandlerOptions): ACPPaymentHandlerOption;
+/** The backend payment method a handler's payments are placed with. */
+export declare function getHandlerPaymentMethod(option: ACPPaymentHandlerOption): PaymentMethod['identifier'];