@apiosk/checkout-core 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# `@apiosk/checkout-core`
+
+Shared checkout contract for all Apiosk checkout surfaces.
+
+This package owns the schema and helper layer that the other checkout modules
+should agree on:
+
+- rail metadata
+- normalized checkout config
+- checkout intent payload shape
+- checkout status path helpers
+- webhook event names
+- webhook signature helpers
+
+## Install
+
+After publish:
+
+```bash
+npm install @apiosk/checkout-core
+```
+
+Before publish:
+
+```bash
+npm install ./subs/checkout-core
+```
+
+## What belongs here
+
+`checkout-core` is not a UI package. It should stay framework-neutral and avoid
+React, Vue, DOM, and CSS concerns.
+
+Use it when you need to:
+
+- build a merchant checkout intent payload
+- normalize rail configuration before rendering a button
+- keep webhook naming and signature handling consistent
+- share the same checkout schema between web, React, Vue, and server code
+
+## Quick start
+
+```js
+import {
+  createCheckoutIntentPayload,
+  normalizeCheckoutConfig,
+  selectDefaultRail,
+} from "@apiosk/checkout-core";
+
+const config = normalizeCheckoutConfig({
+  merchantName: "Northstar Marketplace",
+  productName: "Automation bundle",
+  amountLabel: "24.95 EUR",
+  orderReference: "ord_2048",
+  rails: [
+    { id: "credits", status: "live" },
+    { id: "x402", status: "live" },
+    { id: "agent", status: "pilot" },
+  ],
+  callbacks: {
+    successUrl: "https://merchant.example/success",
+    cancelUrl: "https://merchant.example/cancel",
+    webhookUrl: "https://merchant.example/webhooks/apiosk",
+    statusUrl: "https://merchant.example/api/orders/ord_2048",
+  },
+});
+
+const payload = createCheckoutIntentPayload(config);
+const defaultRail = selectDefaultRail(config.rails);
+```
+
+## Normalized config
+
+The normalizer accepts both:
+
+- a flat button-friendly shape like `merchantName`, `productName`, `amountLabel`
+- a structured config with `merchant`, `order`, `appearance`, and `callbacks`
+
+That lets internal dashboard code migrate incrementally while external SDKs use
+the structured version from day one.
+
+## Intent contract
+
+`createCheckoutIntentPayload()` produces the payload shape that the future
+checkout API should accept at:
+
+- `POST /v1/checkout/intents`
+- `GET /v1/checkout/intents/:id`
+
+This package is where that contract should evolve first.
+
+## Webhook helpers
+
+Use `createWebhookSignature()` and `verifyWebhookSignature()` for server-side
+signature handling:
+
+```js
+import { verifyWebhookSignature } from "@apiosk/checkout-core";
+
+const rawBody = '{"event":"checkout.intent.paid"}';
+const signature = request.headers["x-apiosk-signature"];
+
+const isValid = await verifyWebhookSignature(
+  rawBody,
+  signature,
+  process.env.APIOSK_WEBHOOK_SECRET,
+);
+```
+
+Pass the raw request body string whenever possible.

package/index.d.ts

@@ -0,0 +1,172 @@
+export type CheckoutRailId = "credits" | "x402" | "card" | "agent";
+export type CheckoutRailStatus = "live" | "pilot" | "coming-soon";
+export type CheckoutTheme = "light" | "dark" | "system";
+
+export interface CheckoutRailInput {
+  id: CheckoutRailId;
+  title?: string;
+  description?: string;
+  status?: CheckoutRailStatus;
+  badge?: string;
+  launchUrl?: string;
+  checkoutUrl?: string;
+}
+
+export interface CheckoutAmountInput {
+  label?: string;
+  value?: string | number;
+  currency?: string;
+}
+
+export interface CheckoutCallbacks {
+  successUrl?: string;
+  cancelUrl?: string;
+  webhookUrl?: string;
+  statusUrl?: string;
+}
+
+export interface CheckoutAppearance {
+  buttonLabel?: string;
+  theme?: CheckoutTheme;
+}
+
+export interface CheckoutStructuredConfigInput {
+  merchant?: {
+    name?: string;
+    id?: string;
+  };
+  order?: {
+    reference?: string;
+    title?: string;
+    description?: string;
+    amount?: CheckoutAmountInput;
+    amountLabel?: string;
+  };
+  rails?: CheckoutRailInput[];
+  callbacks?: CheckoutCallbacks;
+  trustSignals?: string[];
+  integrationNotes?: string[];
+  appearance?: CheckoutAppearance;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckoutFlatConfigInput {
+  merchantName?: string;
+  merchantId?: string;
+  productName?: string;
+  amountLabel?: string;
+  amountValue?: string | number;
+  currency?: string;
+  orderReference?: string;
+  subtitle?: string;
+  rails?: CheckoutRailInput[];
+  trustSignals?: string[];
+  integrationNotes?: string[];
+  buttonLabel?: string;
+  theme?: CheckoutTheme;
+  callbacks?: CheckoutCallbacks;
+  metadata?: Record<string, unknown>;
+}
+
+export type CheckoutConfigInput = CheckoutStructuredConfigInput | CheckoutFlatConfigInput;
+
+export interface NormalizedCheckoutRail {
+  id: CheckoutRailId;
+  title: string;
+  description: string;
+  status: CheckoutRailStatus;
+  badge?: string;
+  launchUrl?: string;
+}
+
+export interface NormalizedCheckoutConfig {
+  merchant: {
+    name: string;
+    id?: string;
+  };
+  order: {
+    reference: string;
+    title: string;
+    description: string;
+    amount: {
+      label: string;
+      value?: string;
+      currency?: string;
+    };
+  };
+  rails: NormalizedCheckoutRail[];
+  callbacks: CheckoutCallbacks;
+  trustSignals: string[];
+  integrationNotes: string[];
+  appearance: {
+    buttonLabel: string;
+    theme: CheckoutTheme;
+  };
+  metadata: Record<string, unknown>;
+}
+
+export interface CheckoutIntentPayload {
+  merchant_id: string | null;
+  merchant_name: string;
+  order_reference: string;
+  title: string;
+  description: string;
+  amount: {
+    label: string;
+    value: string | null;
+    currency: string | null;
+  };
+  allowed_rails: CheckoutRailId[];
+  callbacks: {
+    success_url: string | null;
+    cancel_url: string | null;
+    webhook_url: string | null;
+    status_url: string | null;
+  };
+  ui: {
+    button_label: string;
+    theme: CheckoutTheme;
+  };
+  trust_signals: string[];
+  integration_notes: string[];
+  metadata: Record<string, unknown>;
+}
+
+export declare const CHECKOUT_CORE_VERSION: string;
+export declare const DEFAULT_WEBHOOK_SIGNATURE_HEADER: string;
+export declare const DEFAULT_WEBHOOK_SIGNATURE_PREFIX: string;
+export declare const DEFAULT_BUTTON_LABEL: string;
+export declare const DEFAULT_CHECKOUT_THEME: CheckoutTheme;
+export declare const DEFAULT_RAIL_ORDER: CheckoutRailId[];
+export declare const CHECKOUT_INTENT_PATH: string;
+export declare const CHECKOUT_INTENT_STATUSES: string[];
+export declare const CHECKOUT_EVENT_TYPES: string[];
+export declare const RAIL_METADATA: Record<CheckoutRailId, {
+  id: CheckoutRailId;
+  title: string;
+  description: string;
+  status: CheckoutRailStatus;
+}>;
+
+export declare function selectDefaultRail(
+  rails: CheckoutRailInput[] | NormalizedCheckoutRail[],
+): CheckoutRailId;
+export declare function normalizeCheckoutConfig(input?: CheckoutConfigInput): NormalizedCheckoutConfig;
+export declare function createCheckoutIntentPayload(input?: CheckoutConfigInput): CheckoutIntentPayload;
+export declare function buildCheckoutIntentPath(): string;
+export declare function buildCheckoutStatusPath(intentId: string): string;
+export declare function resolveRailLaunchTarget(
+  input: CheckoutConfigInput,
+  railId: CheckoutRailId,
+): string | undefined;
+export declare function serializeCheckoutPayload(payload: unknown): string;
+export declare function createWebhookSignature(
+  payload: unknown,
+  secret: string,
+  options?: { prefix?: string },
+): Promise<string>;
+export declare function verifyWebhookSignature(
+  payload: unknown,
+  signature: string,
+  secret: string,
+): Promise<boolean>;

package/index.mjs

@@ -0,0 +1,330 @@
+export const CHECKOUT_CORE_VERSION = "0.1.0";
+export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = "x-apiosk-signature";
+export const DEFAULT_WEBHOOK_SIGNATURE_PREFIX = "sha256";
+export const DEFAULT_BUTTON_LABEL = "Pay with Apiosk";
+export const DEFAULT_CHECKOUT_THEME = "light";
+export const DEFAULT_RAIL_ORDER = ["credits", "x402", "card", "agent"];
+export const CHECKOUT_INTENT_PATH = "/v1/checkout/intents";
+export const CHECKOUT_INTENT_STATUSES = [
+  "draft",
+  "pending",
+  "authorized",
+  "paid",
+  "failed",
+  "expired",
+  "refunded",
+];
+export const CHECKOUT_EVENT_TYPES = [
+  "checkout.intent.created",
+  "checkout.intent.updated",
+  "checkout.intent.authorized",
+  "checkout.intent.paid",
+  "checkout.intent.failed",
+  "checkout.intent.expired",
+  "checkout.intent.refunded",
+];
+export const RAIL_METADATA = Object.freeze({
+  credits: Object.freeze({
+    id: "credits",
+    title: "Apiosk credits",
+    description: "Use a pre-funded Apiosk balance and recover through top-up when needed.",
+    status: "live",
+  }),
+  x402: Object.freeze({
+    id: "x402",
+    title: "x402 wallet",
+    description: "Use proof-based programmable payment from a browser wallet or agent wallet.",
+    status: "live",
+  }),
+  card: Object.freeze({
+    id: "card",
+    title: "Card checkout",
+    description: "Accept familiar fiat checkout where the merchant still needs card coverage.",
+    status: "pilot",
+  }),
+  agent: Object.freeze({
+    id: "agent",
+    title: "Agent budget",
+    description: "Authorize autonomous purchases inside merchant-defined categories and caps.",
+    status: "coming-soon",
+  }),
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function toStringValue(value, fallback = "") {
+  if (value === null || value === undefined) {
+    return fallback;
+  }
+
+  return String(value);
+}
+
+function compactList(values) {
+  return Array.from(
+    new Set(
+      (Array.isArray(values) ? values : [])
+        .map((value) => toStringValue(value).trim())
+        .filter(Boolean),
+    ),
+  );
+}
+
+function normalizeTheme(theme) {
+  if (theme === "dark" || theme === "system") {
+    return theme;
+  }
+
+  return DEFAULT_CHECKOUT_THEME;
+}
+
+function normalizeRail(rawRail) {
+  const source = isPlainObject(rawRail) ? rawRail : {};
+  const id = DEFAULT_RAIL_ORDER.includes(source.id) ? source.id : "credits";
+  const metadata = RAIL_METADATA[id];
+  const status =
+    source.status === "live" || source.status === "pilot" || source.status === "coming-soon"
+      ? source.status
+      : metadata.status;
+
+  return {
+    id,
+    title: toStringValue(source.title, metadata.title).trim() || metadata.title,
+    description:
+      toStringValue(source.description, metadata.description).trim() || metadata.description,
+    status,
+    badge: toStringValue(source.badge).trim() || undefined,
+    launchUrl: toStringValue(source.launchUrl || source.checkoutUrl).trim() || undefined,
+  };
+}
+
+function normalizeAmount(rawAmount, fallbackLabel) {
+  const source = isPlainObject(rawAmount) ? rawAmount : {};
+  const label = toStringValue(source.label, fallbackLabel).trim() || fallbackLabel;
+  const currency = toStringValue(source.currency).trim() || undefined;
+
+  let value = source.value;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    value = String(value);
+  } else if (typeof value === "string" && value.trim()) {
+    value = value.trim();
+  } else {
+    value = undefined;
+  }
+
+  return {
+    label,
+    value,
+    currency,
+  };
+}
+
+function normalizeCallbacks(callbacks) {
+  const source = isPlainObject(callbacks) ? callbacks : {};
+  return {
+    successUrl: toStringValue(source.successUrl).trim() || undefined,
+    cancelUrl: toStringValue(source.cancelUrl).trim() || undefined,
+    webhookUrl: toStringValue(source.webhookUrl).trim() || undefined,
+    statusUrl: toStringValue(source.statusUrl).trim() || undefined,
+  };
+}
+
+function toStructuredConfig(input) {
+  if (isPlainObject(input) && (isPlainObject(input.merchant) || isPlainObject(input.order))) {
+    return input;
+  }
+
+  const source = isPlainObject(input) ? input : {};
+  return {
+    merchant: {
+      name: source.merchantName,
+      id: source.merchantId,
+    },
+    order: {
+      reference: source.orderReference,
+      title: source.productName,
+      description: source.subtitle,
+      amount: {
+        label: source.amountLabel,
+        value: source.amountValue,
+        currency: source.currency,
+      },
+    },
+    rails: source.rails,
+    callbacks: source.callbacks,
+    trustSignals: source.trustSignals,
+    integrationNotes: source.integrationNotes,
+    appearance: {
+      buttonLabel: source.buttonLabel,
+      theme: source.theme,
+    },
+    metadata: source.metadata,
+  };
+}
+
+export function selectDefaultRail(rails) {
+  const normalizedRails = (Array.isArray(rails) ? rails : []).map(normalizeRail);
+  return (
+    normalizedRails.find((rail) => rail.status === "live")?.id ||
+    normalizedRails[0]?.id ||
+    DEFAULT_RAIL_ORDER[0]
+  );
+}
+
+export function normalizeCheckoutConfig(input = {}) {
+  const structured = toStructuredConfig(input);
+  const merchantSource = isPlainObject(structured.merchant) ? structured.merchant : {};
+  const orderSource = isPlainObject(structured.order) ? structured.order : {};
+  const appearanceSource = isPlainObject(structured.appearance) ? structured.appearance : {};
+  const railSource = Array.isArray(structured.rails) ? structured.rails : [];
+  const normalizedRails = DEFAULT_RAIL_ORDER
+    .map((railId) => railSource.find((rail) => rail?.id === railId))
+    .filter(Boolean)
+    .concat(railSource.filter((rail) => rail && !DEFAULT_RAIL_ORDER.includes(rail.id)))
+    .map(normalizeRail);
+  const rails = normalizedRails.length > 0 ? normalizedRails : [normalizeRail({ id: "credits" })];
+  const title = toStringValue(orderSource.title, "Untitled order").trim() || "Untitled order";
+  const description =
+    toStringValue(orderSource.description, "Complete this request through Apiosk checkout.").trim() ||
+    "Complete this request through Apiosk checkout.";
+
+  return {
+    merchant: {
+      name: toStringValue(merchantSource.name, "Apiosk merchant").trim() || "Apiosk merchant",
+      id: toStringValue(merchantSource.id).trim() || undefined,
+    },
+    order: {
+      reference: toStringValue(orderSource.reference, "intent_demo").trim() || "intent_demo",
+      title,
+      description,
+      amount: normalizeAmount(orderSource.amount, toStringValue(orderSource.amountLabel, "")),
+    },
+    rails,
+    callbacks: normalizeCallbacks(structured.callbacks),
+    trustSignals: compactList(structured.trustSignals),
+    integrationNotes: compactList(structured.integrationNotes),
+    appearance: {
+      buttonLabel:
+        toStringValue(appearanceSource.buttonLabel, DEFAULT_BUTTON_LABEL).trim() ||
+        DEFAULT_BUTTON_LABEL,
+      theme: normalizeTheme(appearanceSource.theme),
+    },
+    metadata: isPlainObject(structured.metadata) ? { ...structured.metadata } : {},
+  };
+}
+
+export function createCheckoutIntentPayload(input = {}) {
+  const config = normalizeCheckoutConfig(input);
+
+  return {
+    merchant_id: config.merchant.id || null,
+    merchant_name: config.merchant.name,
+    order_reference: config.order.reference,
+    title: config.order.title,
+    description: config.order.description,
+    amount: {
+      label: config.order.amount.label,
+      value: config.order.amount.value || null,
+      currency: config.order.amount.currency || null,
+    },
+    allowed_rails: config.rails.map((rail) => rail.id),
+    callbacks: {
+      success_url: config.callbacks.successUrl || null,
+      cancel_url: config.callbacks.cancelUrl || null,
+      webhook_url: config.callbacks.webhookUrl || null,
+      status_url: config.callbacks.statusUrl || null,
+    },
+    ui: {
+      button_label: config.appearance.buttonLabel,
+      theme: config.appearance.theme,
+    },
+    trust_signals: config.trustSignals,
+    integration_notes: config.integrationNotes,
+    metadata: config.metadata,
+  };
+}
+
+export function buildCheckoutIntentPath() {
+  return CHECKOUT_INTENT_PATH;
+}
+
+export function buildCheckoutStatusPath(intentId) {
+  return `${CHECKOUT_INTENT_PATH}/${encodeURIComponent(toStringValue(intentId).trim())}`;
+}
+
+export function resolveRailLaunchTarget(input, railId) {
+  const config = normalizeCheckoutConfig(input);
+  const rail = config.rails.find((candidate) => candidate.id === railId);
+  return rail?.launchUrl;
+}
+
+export function serializeCheckoutPayload(payload) {
+  if (typeof payload === "string") {
+    return payload;
+  }
+
+  return JSON.stringify(payload);
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+async function hmacSha256Hex(message, secret) {
+  if (globalThis.crypto?.subtle) {
+    const key = await globalThis.crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+    const signature = await globalThis.crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(message),
+    );
+    return bytesToHex(new Uint8Array(signature));
+  }
+
+  const { createHmac } = await import("node:crypto");
+  return createHmac("sha256", secret).update(message).digest("hex");
+}
+
+function normalizeSignature(signature) {
+  const value = toStringValue(signature).trim();
+  const separatorIndex = value.indexOf("=");
+  return separatorIndex === -1 ? value : value.slice(separatorIndex + 1);
+}
+
+export async function createWebhookSignature(
+  payload,
+  secret,
+  options = {},
+) {
+  const prefix = toStringValue(options.prefix, DEFAULT_WEBHOOK_SIGNATURE_PREFIX).trim();
+  const digest = await hmacSha256Hex(serializeCheckoutPayload(payload), toStringValue(secret));
+  return `${prefix}=${digest}`;
+}
+
+export async function verifyWebhookSignature(payload, signature, secret) {
+  const expected = normalizeSignature(
+    await createWebhookSignature(payload, secret, {
+      prefix: DEFAULT_WEBHOOK_SIGNATURE_PREFIX,
+    }),
+  );
+  const received = normalizeSignature(signature);
+
+  if (expected.length !== received.length) {
+    return false;
+  }
+
+  let mismatch = 0;
+  for (let index = 0; index < expected.length; index += 1) {
+    mismatch |= expected.charCodeAt(index) ^ received.charCodeAt(index);
+  }
+
+  return mismatch === 0;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@apiosk/checkout-core",
+  "version": "0.1.0",
+  "description": "Shared checkout schema, rails, intent payload helpers, and webhook utilities for Apiosk checkout packages",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./index.d.ts",
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    }
+  },
+  "scripts": {
+    "check": "node --check index.mjs"
+  },
+  "keywords": [
+    "apiosk",
+    "checkout",
+    "payments",
+    "x402",
+    "credits"
+  ],
+  "author": "Apiosk",
+  "license": "MIT",
+  "homepage": "https://docs.apiosk.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}