@reactionary/acp 0.10.42 → 0.10.44

package/lib/acp-schemas.js

@@ -1,12 +1,41 @@
+import { CurrencySchema } from "@reactionary/core";
 import * as z from "zod";
+import { ACPDiscountsRequestSchema, ACPRejectedDiscountSchema } from "./acp-discounts.js";
 const ACPItemSchema = z.object({
   id: z.string().min(1),
-  quantity: z.int().min(1)
+  quantity: z.number().positive().optional(),
+  name: z.string().optional(),
+  unit_amount: z.int().optional()
 });
-const ACPBuyerSchema = z.object({
+const ACPCompanyInfoSchema = z.object({
   name: z.string().min(1),
+  tax_id: z.string().optional(),
+  department: z.string().optional(),
+  cost_center: z.string().optional()
+});
+const ACPLoyaltyInfoSchema = z.object({
+  tier: z.string().optional(),
+  points_balance: z.int().optional(),
+  member_since: z.string().optional()
+});
+const ACPTaxExemptionSchema = z.object({
+  certificate_id: z.string().min(1),
+  certificate_type: z.enum(["resale", "exempt_organization", "government"]),
+  exempt_regions: z.array(z.string()).optional(),
+  expires_at: z.string().optional()
+});
+const ACPBuyerSchema = z.object({
+  first_name: z.string().optional(),
+  last_name: z.string().optional(),
+  full_name: z.string().optional(),
   email: z.email(),
-  phone_number: z.string().optional()
+  phone_number: z.string().optional(),
+  customer_id: z.string().optional(),
+  account_type: z.enum(["guest", "registered", "business"]).optional(),
+  authentication_status: z.enum(["authenticated", "guest", "requires_signin"]).optional(),
+  company: ACPCompanyInfoSchema.optional(),
+  loyalty: ACPLoyaltyInfoSchema.optional(),
+  tax_exemption: ACPTaxExemptionSchema.optional()
 });
 const ACPAddressSchema = z.object({
   name: z.string().min(1),
@@ -15,113 +44,254 @@ const ACPAddressSchema = z.object({
   city: z.string().min(1),
   state: z.string().min(1),
   country: z.string().min(1),
-  postal_code: z.string().min(1),
-  phone_number: z.string().optional()
+  postal_code: z.string().min(1)
+});
+const ACPFulfillmentDetailsSchema = z.object({
+  name: z.string().optional(),
+  phone_number: z.string().optional(),
+  email: z.email().optional(),
+  address: ACPAddressSchema.optional()
+});
+const ACPSelectedFulfillmentOptionSchema = z.object({
+  type: z.enum(["shipping", "digital", "pickup", "local_delivery"]),
+  option_id: z.string().min(1),
+  item_ids: z.array(z.string())
+});
+const ACPFlatMetadataSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).refine((metadata) => Object.keys(metadata).length <= 20, { error: "metadata may hold at most 20 keys" }).refine((metadata) => JSON.stringify(metadata).length <= 4096, { error: "metadata may be at most 4KB" });
+const ACPAffiliateAttributionSchema = z.object({
+  provider: z.string().min(1),
+  token: z.string().optional(),
+  publisher_id: z.string().optional(),
+  campaign_id: z.string().optional(),
+  creative_id: z.string().optional(),
+  sub_id: z.string().optional(),
+  source: z.object({
+    type: z.enum(["url", "platform", "unknown"]),
+    url: z.url().optional()
+  }).optional(),
+  issued_at: z.iso.datetime({ offset: true }).optional(),
+  expires_at: z.iso.datetime({ offset: true }).optional(),
+  metadata: ACPFlatMetadataSchema.optional(),
+  touchpoint: z.enum(["first", "last"]).optional()
+}).refine(
+  (attribution) => attribution.token !== void 0 || attribution.publisher_id !== void 0,
+  { error: "token or publisher_id is required", path: ["token"] }
+);
+const ACP_INTERVENTION_TYPES = ["3ds", "biometric", "address_verification"];
+const ACPAgentCapabilitiesSchema = z.object({
+  interventions: z.object({
+    supported: z.array(z.string()).optional(),
+    display_context: z.string().optional(),
+    redirect_context: z.string().optional(),
+    max_redirects: z.int().min(0).optional(),
+    max_interaction_depth: z.int().min(1).optional()
+  }).optional(),
+  extensions: z.array(z.string()).optional()
 });
 const ACPCreateCheckoutSessionRequestSchema = z.object({
+  capabilities: ACPAgentCapabilitiesSchema,
+  locale: z.string().optional(),
+  timezone: z.string().optional(),
+  affiliate_attribution: ACPAffiliateAttributionSchema.optional(),
+  discounts: ACPDiscountsRequestSchema.optional(),
+  /** Deprecated alias of `discounts.codes`. */
+  coupons: z.array(z.string().min(1)).optional(),
   buyer: ACPBuyerSchema.optional(),
-  items: z.array(ACPItemSchema).min(1),
-  fulfillment_address: ACPAddressSchema.optional()
+  line_items: z.array(ACPItemSchema).min(1),
+  currency: z.string().refine(
+    (currency) => CurrencySchema.safeParse(currency.toUpperCase()).success,
+    "Expected an ISO 4217 currency code"
+  ),
+  fulfillment_details: ACPFulfillmentDetailsSchema.optional()
 });
 const ACPUpdateCheckoutSessionRequestSchema = z.object({
   buyer: ACPBuyerSchema.optional(),
-  items: z.array(ACPItemSchema).min(1).optional(),
-  fulfillment_address: ACPAddressSchema.optional(),
-  fulfillment_option_id: z.string().optional()
+  line_items: z.array(ACPItemSchema).min(1).optional(),
+  discounts: ACPDiscountsRequestSchema.optional(),
+  /** Deprecated alias of `discounts.codes`. */
+  coupons: z.array(z.string().min(1)).optional(),
+  // null clears the field; absent leaves it unchanged.
+  fulfillment_details: ACPFulfillmentDetailsSchema.nullable().optional(),
+  selected_fulfillment_options: z.array(ACPSelectedFulfillmentOptionSchema).nullable().optional()
 });
 const ACPPaymentDataSchema = z.object({
-  token: z.string().min(1),
-  provider: z.enum(["stripe", "adyen", "braintree"]),
+  handler_id: z.string().min(1),
+  instrument: z.object({
+    type: z.string().min(1),
+    credential: z.looseObject({
+      type: z.string().min(1),
+      token: z.string().min(1)
+    })
+  }),
   billing_address: ACPAddressSchema.optional()
 });
+const ACPAuthenticationMetadataSchema = z.looseObject({
+  channel: z.looseObject({}).optional(),
+  acquirer_details: z.object({
+    acquirer_bin: z.string().max(11),
+    acquirer_country: z.string().length(2),
+    acquirer_merchant_id: z.string().max(35),
+    merchant_name: z.string().max(40),
+    requestor_id: z.string().max(35).optional()
+  }),
+  directory_server: z.enum(["american_express", "mastercard", "visa"]),
+  flow_preference: z.object({
+    type: z.enum(["challenge", "frictionless"]),
+    challenge: z.object({ type: z.enum(["mandated", "preferred"]).optional() }).optional(),
+    frictionless: z.object({ type: z.enum(["low_risk"]).optional() }).optional()
+  }).optional()
+});
+const ACP_AUTHENTICATED_OUTCOMES = ["authenticated", "attempt_acknowledged", "informational"];
+const ACPAuthenticationResultSchema = z.object({
+  outcome: z.enum([
+    "abandoned",
+    "attempt_acknowledged",
+    "authenticated",
+    "canceled",
+    "denied",
+    "informational",
+    "internal_error",
+    "not_supported",
+    "processing_error",
+    "rejected"
+  ]),
+  outcome_details: z.object({
+    three_ds_cryptogram: z.string(),
+    electronic_commerce_indicator: z.enum(["01", "02", "05", "06", "07"]),
+    transaction_id: z.string(),
+    version: z.string()
+  }).optional()
+}).refine(
+  (result) => result.outcome_details !== void 0 || !ACP_AUTHENTICATED_OUTCOMES.includes(result.outcome),
+  { error: "outcome_details is required for this outcome", path: ["outcome_details"] }
+);
 const ACPCompleteCheckoutSessionRequestSchema = z.object({
   buyer: ACPBuyerSchema.optional(),
-  payment_data: ACPPaymentDataSchema
+  payment_data: ACPPaymentDataSchema,
+  authentication_result: ACPAuthenticationResultSchema.optional(),
+  affiliate_attribution: ACPAffiliateAttributionSchema.optional(),
+  /** The buyer's marketing consent decisions for the offered channels. */
+  marketing_consents: z.array(z.object({ channel: z.string().min(1), opted_in: z.boolean() })).optional()
+});
+const ACPCartCreateRequestSchema = z.object({
+  line_items: z.array(ACPItemSchema).min(1),
+  buyer: ACPBuyerSchema.optional(),
+  locale: z.string().optional()
+});
+const ACPCartUpdateRequestSchema = z.object({
+  line_items: z.array(ACPItemSchema),
+  buyer: ACPBuyerSchema.optional()
+});
+const ACPCartStateSchema = z.looseObject({
+  id: z.string(),
+  cartId: z.string(),
+  sessionId: z.string().optional(),
+  agentId: z.string().optional(),
+  buyer: ACPBuyerSchema.optional(),
+  expiresAt: z.string()
+});
+const ACP_INTENT_TRACE_REASON_CODES = [
+  "price_sensitivity",
+  "shipping_cost",
+  "shipping_speed",
+  "product_fit",
+  "trust_security",
+  "returns_policy",
+  "payment_options",
+  "comparison",
+  "timing_deferred",
+  "other"
+];
+const ACPIntentTraceSchema = z.object({
+  reason_code: z.string().min(1).transform((code) => ACP_INTENT_TRACE_REASON_CODES.includes(code) ? code : "other"),
+  trace_summary: z.string().max(500).optional(),
+  metadata: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+});
+const ACPCancelCheckoutSessionRequestSchema = z.object({
+  intent_trace: ACPIntentTraceSchema.optional()
 });
 const ACPCheckoutSessionStateSchema = z.looseObject({
   id: z.string(),
   // The ACP session owning the backend cart, resumed for later requests.
   sessionId: z.string().optional(),
+  /** The authenticated agent that created the session and may access it. */
+  agentId: z.string().optional(),
   cartId: z.string(),
+  /** BCP 47 locale and IANA timezone requested on creation. */
+  locale: z.string().optional(),
+  timezone: z.string().optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+  /** What the agent declared on creation; capabilities are write-only. */
+  agentCapabilities: ACPAgentCapabilitiesSchema.optional(),
+  /** ISO 4217 currency requested on creation, lower case. */
+  currency: z.string().optional(),
   // Set once completion has created the real reactionary checkout.
   checkoutId: z.string().optional(),
   status: z.enum([
     "not_ready_for_payment",
     "ready_for_payment",
+    "authentication_required",
     "in_progress",
+    "complete_in_progress",
     "completed",
     "canceled"
   ]),
   buyer: ACPBuyerSchema.optional(),
-  fulfillmentAddress: ACPAddressSchema.optional(),
+  /** Affiliate attribution by touchpoint; write-only, never returned. */
+  firstTouchAttribution: z.looseObject({ provider: z.string() }).optional(),
+  lastTouchAttribution: z.looseObject({ provider: z.string() }).optional(),
+  /** Marketing consents submitted on completion, reported with the order. */
+  marketingConsents: z.array(z.looseObject({ channel: z.string(), opted_in: z.boolean() })).optional(),
+  /** Why the agent canceled the session; write-only, never returned. */
+  intentTrace: z.looseObject({
+    reason_code: z.string(),
+    trace_summary: z.string().optional(),
+    metadata: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+  }).optional(),
+  /** Discount codes submitted (discount extension) and those rejected. */
+  discountCodes: z.array(z.string()).optional(),
+  rejectedDiscounts: z.array(ACPRejectedDiscountSchema).optional(),
+  /** The 3DS metadata the session awaits an authentication result for. */
+  authenticationMetadata: ACPAuthenticationMetadataSchema.optional(),
+  fulfillmentDetails: ACPFulfillmentDetailsSchema.optional(),
+  // The backend checkout has one shipping method, so one option is kept.
   fulfillmentOptionId: z.string().optional(),
   orderId: z.string().optional()
 });
-const ACPDescriptionSchema = z.object({
-  plain: z.string().optional(),
-  html: z.string().optional(),
-  markdown: z.string().optional()
-});
-const ACPMediaSchema = z.object({
-  url: z.string(),
-  alt_text: z.string().optional()
-});
-const ACPFeedPriceSchema = z.object({
-  amount: z.int(),
-  currency: z.string().length(3)
-});
-const ACPAvailabilitySchema = z.object({
-  available: z.boolean().optional(),
-  status: z.string().optional()
-});
-const ACPBarcodeSchema = z.object({
-  type: z.string(),
-  value: z.string()
-});
-const ACPVariantOptionSchema = z.object({
-  name: z.string(),
-  value: z.string()
-});
-const ACPFeedVariantSchema = z.object({
+const ACPOrderRecordSchema = z.looseObject({
   id: z.string(),
-  title: z.string(),
-  description: ACPDescriptionSchema.optional(),
-  url: z.string().optional(),
-  barcodes: z.array(ACPBarcodeSchema).optional(),
-  price: ACPFeedPriceSchema.optional(),
-  list_price: ACPFeedPriceSchema.optional(),
-  availability: ACPAvailabilitySchema.optional(),
-  variant_options: z.array(ACPVariantOptionSchema).optional(),
-  media: z.array(ACPMediaSchema).optional()
-});
-const ACPFeedProductSchema = z.object({
-  id: z.string(),
-  title: z.string().optional(),
-  description: ACPDescriptionSchema.optional(),
-  url: z.string().optional(),
-  media: z.array(ACPMediaSchema).optional(),
-  variants: z.array(ACPFeedVariantSchema).min(1)
-});
-const ACPProductFeedResponseSchema = z.object({
-  target_country: z.string().length(2).optional(),
-  products: z.array(ACPFeedProductSchema)
+  checkoutSessionId: z.string(),
+  /** The ACP session that placed the order; backends scope orders to it. */
+  sessionId: z.string().optional(),
+  /** The agent that placed the order, whose webhook receives its events. */
+  agentId: z.string().optional()
 });
 export {
   ACPAddressSchema,
-  ACPAvailabilitySchema,
-  ACPBarcodeSchema,
+  ACPAffiliateAttributionSchema,
+  ACPAgentCapabilitiesSchema,
+  ACPAuthenticationMetadataSchema,
+  ACPAuthenticationResultSchema,
   ACPBuyerSchema,
+  ACPCancelCheckoutSessionRequestSchema,
+  ACPCartCreateRequestSchema,
+  ACPCartStateSchema,
+  ACPCartUpdateRequestSchema,
   ACPCheckoutSessionStateSchema,
+  ACPCompanyInfoSchema,
   ACPCompleteCheckoutSessionRequestSchema,
   ACPCreateCheckoutSessionRequestSchema,
-  ACPDescriptionSchema,
-  ACPFeedPriceSchema,
-  ACPFeedProductSchema,
-  ACPFeedVariantSchema,
+  ACPFulfillmentDetailsSchema,
+  ACPIntentTraceSchema,
   ACPItemSchema,
-  ACPMediaSchema,
+  ACPLoyaltyInfoSchema,
+  ACPOrderRecordSchema,
   ACPPaymentDataSchema,
-  ACPProductFeedResponseSchema,
+  ACPSelectedFulfillmentOptionSchema,
+  ACPTaxExemptionSchema,
   ACPUpdateCheckoutSessionRequestSchema,
-  ACPVariantOptionSchema
+  ACP_AUTHENTICATED_OUTCOMES,
+  ACP_INTENT_TRACE_REASON_CODES,
+  ACP_INTERVENTION_TYPES
 };

package/lib/acp-webhooks.js

@@ -0,0 +1,72 @@
+import { createHmac } from "node:crypto";
+const DEFAULT_RETRY_DELAYS_MS = [500, 2e3, 1e4, 6e4, 3e5];
+const REQUEST_TIMEOUT_MS = 5e3;
+class ACPOrderWebhooks {
+  constructor(options) {
+    this.options = options;
+    this.retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    this.fetchImpl = options.fetch ?? fetch;
+    for (const endpoint of options.endpoints) {
+      if (!endpoint.secret || !this.isAllowedUrl(endpoint.url)) {
+        throw new Error(`ACP webhook endpoint ${endpoint.url} needs an https URL and a secret.`);
+      }
+    }
+  }
+  options;
+  retryDelaysMs;
+  fetchImpl;
+  /** The endpoint for an agent's orders, if any. */
+  getEndpoint(agentId) {
+    return this.options.endpoints.find((endpoint) => agentId !== void 0 && endpoint.agentId === agentId) ?? this.options.endpoints.find((endpoint) => endpoint.agentId === void 0);
+  }
+  /** Sends an event without waiting for it; the order is the full current state. */
+  deliver(endpoint, type, order) {
+    const body = JSON.stringify({ type, data: order });
+    const requestId = `evt_${crypto.randomUUID()}`;
+    void this.attempt(endpoint, body, requestId, 0);
+  }
+  async attempt(endpoint, body, requestId, attempt) {
+    let failure;
+    try {
+      const response = await this.fetchImpl(endpoint.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "request-id": requestId,
+          "merchant-signature": signWebhookPayload(body, endpoint.secret)
+        },
+        body,
+        redirect: "manual",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+      if (response.ok) {
+        return;
+      }
+      failure = `HTTP ${response.status}`;
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error);
+    }
+    const delay = this.retryDelaysMs[attempt];
+    if (delay === void 0) {
+      console.error(`ACP: giving up on webhook ${requestId} to ${endpoint.url} after ${attempt + 1} attempts: ${failure}`);
+      return;
+    }
+    setTimeout(() => void this.attempt(endpoint, body, requestId, attempt + 1), delay).unref();
+  }
+  isAllowedUrl(value) {
+    try {
+      const { protocol } = new URL(value);
+      return protocol === "https:" || protocol === "http:" && Boolean(this.options.allowInsecureUrls);
+    } catch {
+      return false;
+    }
+  }
+}
+function signWebhookPayload(body, secret, timestamp = Math.floor(Date.now() / 1e3)) {
+  const signature = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+  return `t=${timestamp},v1=${signature}`;
+}
+export {
+  ACPOrderWebhooks,
+  signWebhookPayload
+};