@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/constants.js

@@ -0,0 +1,163 @@
+/**
+ * card_policy program ID on Devnet (contracts.md Changelog, Lane 1 / 1A;
+ * `address` in programs/card_policy/idl/card_policy.json). Every builder and
+ * PDA helper takes an explicit `programId` and falls back to this value.
+ */
+export const CARD_POLICY_PROGRAM_ID = "H3aetJdQXG8EeJSCHZrpQa8iKHBw8e1p9fSPjTUsB93n";
+export function resolveCardPolicyProgramId(programId) {
+    const value = (programId ?? CARD_POLICY_PROGRAM_ID).trim();
+    if (!value) {
+        throw new Error("card_policy program ID is not configured yet. Pass programId explicitly until the program is deployed.");
+    }
+    return value;
+}
+/** MagicBlock Devnet TEE (Private Ephemeral Rollup). Tokens go in the query string; never log the full URL. */
+export const DEVNET_TEE_URL = "https://devnet-tee.magicblock.app";
+export const DEVNET_TEE_WS_URL = "wss://devnet-tee.magicblock.app";
+/** The only validator `delegate_card` accepts on Devnet (contracts.md §1). */
+export const DEVNET_TEE_VALIDATOR = "MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo";
+export const TEE_VALIDATOR_ALLOWLIST = [DEVNET_TEE_VALIDATOR];
+export const DELEGATION_PROGRAM_ID = "DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh";
+export const MAGIC_PROGRAM_ID = "Magic11111111111111111111111111111111111111";
+export const MAGIC_CONTEXT_ID = "MagicContext1111111111111111111111111111111";
+export const PERMISSION_PROGRAM_ID = "ACLseoPoyC3cBqoUtkbjZ4aDrkurZW86v19pXz2XQnp1";
+export const EPHEMERAL_VAULT_ID = "MagicVau1t999999999999999999999999999999999";
+export const CARD_SEEDS = {
+    binding: "card_binding",
+    policy: "card_policy",
+    period: "card_period",
+    reservation: "res",
+    intent: "intent",
+    commitment: "card_commit",
+    /** Per-card replay guard for closed reservations (PER only). */
+    authGuard: "auth_guard",
+    /** Lamport-only base PDA: the `approved_agent` of the owner's repayment mandate. */
+    repayAgent: "repay_agent",
+};
+export const MAX_MERCHANTS = 8;
+export const MAX_MCCS = 16;
+/** owner + authorizer + 4 finance readers. */
+export const MAX_MEMBERS = 6;
+/** $10,000 sandbox cap on any budget (contracts.md §1.3 #6). */
+export const MAX_BUDGET_CENTS = 1000000n;
+export const MIN_PERIOD_SECONDS = 86_400;
+export const MAX_FEE_BPS = 1_000;
+/** A checkout intent may live at most 10 minutes. */
+export const MAX_INTENT_TTL_SECONDS = 600;
+export const CARD_ISSUER = { lithic_sandbox: 1, card_sim: 2 };
+/** EphemeralPermission member flags used by card_policy (MagicBlock permission program). */
+export const PERMISSION_FLAGS = {
+    AUTHORITY: 1,
+    TX_LOGS: 2,
+    TX_BALANCES: 4,
+    TX_MESSAGE: 8,
+};
+/** Anchor instruction discriminators: sha256("global:<name>")[0..8]. */
+export const CARD_POLICY_DISCRIMINATORS = {
+    initCard: Uint8Array.from([163, 228, 150, 17, 250, 36, 156, 20]),
+    delegateCard: Uint8Array.from([143, 76, 125, 25, 4, 123, 254, 155]),
+    initPermission: Uint8Array.from([66, 14, 153, 250, 187, 36, 179, 236]),
+    updatePermission: Uint8Array.from([1, 120, 111, 126, 237, 61, 41, 61]),
+    syncPermission: Uint8Array.from([164, 186, 105, 85, 229, 147, 214, 246]),
+    setPolicy: Uint8Array.from([40, 133, 12, 157, 235, 202, 2, 132]),
+    openCheckoutIntent: Uint8Array.from([139, 180, 113, 38, 119, 108, 36, 224]),
+    cancelCheckoutIntent: Uint8Array.from([175, 152, 6, 182, 211, 206, 160, 167]),
+    closeCheckoutIntent: Uint8Array.from([36, 161, 214, 238, 244, 192, 71, 234]),
+    authorize: Uint8Array.from([173, 193, 102, 210, 219, 137, 113, 120]),
+    adjustReservation: Uint8Array.from([137, 209, 64, 94, 107, 194, 101, 43]),
+    capture: Uint8Array.from([110, 65, 245, 241, 195, 248, 233, 142]),
+    reverse: Uint8Array.from([137, 149, 242, 82, 88, 95, 221, 145]),
+    refund: Uint8Array.from([2, 96, 183, 251, 63, 208, 46, 46]),
+    recordDispute: Uint8Array.from([190, 94, 198, 130, 215, 36, 43, 143]),
+    recordException: Uint8Array.from([221, 204, 254, 53, 116, 13, 197, 105]),
+    resolveException: Uint8Array.from([131, 144, 179, 147, 199, 157, 77, 127]),
+    rollPeriod: Uint8Array.from([30, 184, 166, 42, 251, 204, 47, 107]),
+    freeze: Uint8Array.from([255, 91, 207, 84, 251, 194, 254, 63]),
+    unfreeze: Uint8Array.from([133, 160, 68, 253, 80, 232, 218, 247]),
+    recoveryFreeze: Uint8Array.from([113, 1, 136, 29, 212, 19, 213, 56]),
+    restore: Uint8Array.from([77, 37, 122, 128, 139, 35, 6, 58]),
+    confirmReconciled: Uint8Array.from([116, 7, 34, 18, 87, 241, 4, 233]),
+    checkpoint: Uint8Array.from([213, 200, 19, 204, 240, 143, 184, 252]),
+    writeCommitment: Uint8Array.from([159, 54, 242, 213, 46, 162, 174, 75]),
+    wipeCard: Uint8Array.from([210, 120, 235, 58, 105, 132, 206, 76]),
+    closeCard: Uint8Array.from([142, 206, 170, 182, 227, 204, 185, 115]),
+    recordRepayment: Uint8Array.from([193, 155, 76, 246, 27, 189, 147, 102]),
+    closeReservation: Uint8Array.from([171, 96, 8, 85, 100, 252, 173, 204]),
+    /** Base layer: the card's repay agent pays a statement by ChainPay `execute_payment` CPI. */
+    repayStatement: Uint8Array.from([56, 158, 212, 137, 146, 226, 174, 82]),
+    /** PER: MagicBlock private payment, authorizer-attested (no ChainPay receipt). */
+    recordPrivateRepayment: Uint8Array.from([91, 51, 18, 9, 7, 33, 77, 147]),
+};
+/** Anchor account discriminators: sha256("account:<Name>")[0..8]. */
+export const CARD_ACCOUNT_DISCRIMINATORS = {
+    cardBinding: Uint8Array.from([86, 71, 81, 106, 155, 166, 1, 72]),
+    cardPolicy: Uint8Array.from([196, 159, 33, 83, 231, 156, 65, 71]),
+    cardPeriod: Uint8Array.from([112, 201, 91, 227, 87, 121, 62, 2]),
+    reservation: Uint8Array.from([188, 235, 0, 111, 208, 253, 247, 212]),
+    checkoutIntent: Uint8Array.from([39, 73, 4, 146, 212, 151, 108, 241]),
+    cardCommitment: Uint8Array.from([43, 146, 163, 253, 221, 147, 4, 9]),
+    /** Zero-copy, 8 KB: the last 256 closed reservations' auth ids. */
+    authGuard: Uint8Array.from([53, 204, 86, 193, 155, 169, 182, 150]),
+};
+/** `CardPolicyError` codes (contracts.md §1.4). Append only. */
+export const CARD_POLICY_ERRORS = {
+    6000: "Unauthorized",
+    6001: "ValidatorNotAllowed",
+    6002: "PolicyNotSet",
+    6003: "InvalidPolicy",
+    6004: "CardFrozen",
+    6005: "RecoveryFrozen",
+    6006: "PolicyExpired",
+    6007: "IntentInvalid",
+    6008: "IntentExpired",
+    6009: "IntentStale",
+    6010: "MerchantMismatch",
+    6011: "MerchantNotAllowed",
+    6012: "MccNotAllowed",
+    6013: "CurrencyMismatch",
+    6014: "AmountExceedsIntent",
+    6015: "AmountExceedsMax",
+    6016: "BudgetExceeded",
+    6017: "VelocityExceeded",
+    6018: "RecurringNotAllowed",
+    6019: "DuplicateAuthorization",
+    6020: "DuplicateCapture",
+    6021: "ReservationClosed",
+    6022: "PeriodNotEnded",
+    6023: "DisclosureBlocked",
+    6024: "MemberLimit",
+    6025: "ExceptionsOpen",
+    6026: "NotInRecovery",
+    6027: "StaleCommitment",
+    6028: "OpenReservations",
+    6029: "OutstandingBalance",
+    6030: "MathOverflow",
+    6031: "AuthorizerChangeRequiresFreeze",
+    6032: "DuplicateRepayment",
+    // Appended by card_policy (contracts.md Changelog, Lane 1 / 1A).
+    6033: "MemberNotFound",
+    6034: "PermissionNotInitialized",
+    6035: "InvalidAmount",
+    6036: "NoOpenExceptions",
+    6037: "ReconDigestMismatch",
+    6038: "RepaymentExceedsOutstanding",
+    6039: "InvalidAccount",
+    6040: "PrefundTooLow",
+    6041: "NotWiped",
+    6042: "InvalidEventId",
+    6043: "DuplicateEvent",
+    6044: "EphemeralAccountsOpen",
+    6045: "ReservationNotFinal",
+    6046: "CoSignerRequired",
+    6047: "RefundExceedsCapture",
+    6048: "CaptureLimit",
+    6049: "BudgetBelowCommitted",
+    // Appended for the ChainPay repayment CPI (2026-10-04).
+    6050: "InvalidRepaymentReceipt",
+    6051: "RepaymentRecipientMismatch",
+    6052: "RepaymentExceedsReceipt",
+    6053: "InvalidRepaymentMandate",
+};
+export function cardPolicyErrorName(code) {
+    return CARD_POLICY_ERRORS[code];
+}

package/dist/cards/draft.d.ts

@@ -0,0 +1,57 @@
+export type CardDraft = {
+    v: 1;
+    label: string;
+    budgetCents: string;
+    maxPurchaseCents: string;
+    /** Registered merchant references (Axum resolves each to an acceptor-id hash). */
+    merchants: string[];
+    mccs: number[];
+    periodDays: number;
+    /** ISO time or null for no expiry. */
+    expiresAt: string | null;
+    feeBps: number;
+};
+export type CardDraftInput = {
+    label: unknown;
+    budgetCents: unknown;
+    maxPurchaseCents: unknown;
+    merchants?: unknown;
+    mccs?: unknown;
+    periodDays: unknown;
+    expiresAt?: unknown;
+    feeBps?: unknown;
+};
+/** ChainPay's displayed platform fee when a draft doesn't name one (contracts.md §1.5 example). */
+export declare const DEFAULT_CARD_FEE_BPS = 50;
+export declare const MAX_PERIOD_DAYS = 365;
+/** Validate and normalize an agent-proposed draft. Throws plain-language errors. */
+export declare function normalizeCardDraft(input: CardDraftInput, now?: number): CardDraft;
+/** hex sha256("chainpay-card-draft:v1\n" || canonical draft). The dashboard recomputes it before showing the review. */
+export declare function cardDraftDigest(draft: CardDraft): Promise<string>;
+export declare function cardDraftMaxObligationCents(draft: CardDraft): string;
+/** `${app}/app/cards/new#draft=<base64url(JSON)>`. The fragment never reaches a server. */
+export declare function encodeCardDraftLink(draft: CardDraft, appBaseUrl: string): string;
+export declare function decodeCardDraftFragment(fragment: string, now?: number): CardDraft;
+/** Review link with the draft digest alongside: `…/app/cards/new#draft=…&digest=<hex>`. */
+export declare function encodeCardDraftReviewLink(draft: CardDraft, appBaseUrl: string): Promise<string>;
+export type CardDraftIntake = {
+    status: "matched";
+    draft: CardDraft;
+    digest: string;
+} | {
+    status: "mismatch";
+    digest: string;
+    expected: string;
+} | {
+    status: "missing_digest";
+    digest: string;
+} | {
+    status: "invalid";
+    reason: string;
+};
+/**
+ * Dashboard intake for an agent's review link. The draft is only usable when
+ * the digest in the link equals the digest recomputed here; otherwise the
+ * caller must leave the form empty.
+ */
+export declare function verifyCardDraftFragment(fragment: string, now?: number): Promise<CardDraftIntake>;

package/dist/cards/draft.js

@@ -0,0 +1,131 @@
+import { MAX_BUDGET_CENTS, MAX_FEE_BPS, MAX_MCCS, MAX_MERCHANTS } from "./constants.js";
+import { centsToString, maxObligationCents, parseCents } from "./math.js";
+import { cardMerchantByRef } from "./merchants.js";
+import { redactCardNumbersInInput } from "./redact.js";
+/** ChainPay's displayed platform fee when a draft doesn't name one (contracts.md §1.5 example). */
+export const DEFAULT_CARD_FEE_BPS = 50;
+export const MAX_PERIOD_DAYS = 365;
+const MERCHANT_REF = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** Validate and normalize an agent-proposed draft. Throws plain-language errors. */
+export function normalizeCardDraft(input, now = Date.now()) {
+    if (typeof input.label !== "string" || !input.label.trim() || input.label.trim().length > 40)
+        throw new Error("label must be 1-40 characters");
+    const budget = parseCents(input.budgetCents, "budgetCents");
+    const maxPurchase = parseCents(input.maxPurchaseCents, "maxPurchaseCents");
+    if (budget <= 0n)
+        throw new Error("Budget must be more than $0");
+    if (budget > MAX_BUDGET_CENTS)
+        throw new Error("Budget can't be more than $10,000 in the sandbox");
+    if (maxPurchase <= 0n || maxPurchase > budget)
+        throw new Error("Max purchase must be more than $0 and no more than the budget");
+    const merchants = input.merchants === undefined ? [] : input.merchants;
+    const mccs = input.mccs === undefined ? [] : input.mccs;
+    if (!Array.isArray(merchants) || !merchants.every((ref) => typeof ref === "string" && MERCHANT_REF.test(ref)))
+        throw new Error("merchants must be a list of merchant references");
+    if (!Array.isArray(mccs) || !mccs.every((mcc) => Number.isInteger(mcc) && mcc >= 0 && mcc <= 9_999))
+        throw new Error("mccs must be a list of 4-digit merchant category codes");
+    if (merchants.length === 0 && mccs.length === 0)
+        throw new Error("Pick at least one shop or merchant category");
+    // A shop ChainPay can't check out at would make the owner's review link dead
+    // on arrival, so the draft is never "ready" with one (review F8).
+    const unknown = merchants.filter((ref) => !cardMerchantByRef(ref));
+    if (unknown.length)
+        throw new Error(`${unknown.map((ref) => `"${redactCardNumbersInInput(ref)}"`).join(", ")} ${unknown.length === 1 ? "isn't a shop" : "aren't shops"} ChainPay can check out at`);
+    if (merchants.length > MAX_MERCHANTS)
+        throw new Error(`At most ${MAX_MERCHANTS} shops`);
+    if (mccs.length > MAX_MCCS)
+        throw new Error(`At most ${MAX_MCCS} merchant categories`);
+    if (new Set(merchants).size !== merchants.length)
+        throw new Error("A shop is listed twice");
+    if (new Set(mccs).size !== mccs.length)
+        throw new Error("A merchant category is listed twice");
+    if (!Number.isInteger(input.periodDays) || input.periodDays < 1 || input.periodDays > MAX_PERIOD_DAYS)
+        throw new Error(`periodDays must be a whole number from 1 to ${MAX_PERIOD_DAYS}`);
+    const feeBps = input.feeBps === undefined ? DEFAULT_CARD_FEE_BPS : input.feeBps;
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > MAX_FEE_BPS)
+        throw new Error("feeBps must be a whole number from 0 to 1000");
+    let expiresAt = null;
+    if (input.expiresAt !== undefined && input.expiresAt !== null) {
+        const ms = typeof input.expiresAt === "string" ? Date.parse(input.expiresAt) : Number.NaN;
+        if (Number.isNaN(ms))
+            throw new Error("expiresAt must be an ISO date");
+        if (ms <= now)
+            throw new Error("expiresAt must be in the future");
+        expiresAt = new Date(ms).toISOString();
+    }
+    return {
+        v: 1,
+        label: input.label.trim(),
+        budgetCents: centsToString(budget),
+        maxPurchaseCents: centsToString(maxPurchase),
+        merchants: [...merchants],
+        mccs: [...mccs],
+        periodDays: input.periodDays,
+        expiresAt,
+        feeBps: feeBps,
+    };
+}
+function canonical(draft) {
+    return JSON.stringify([draft.v, draft.label, draft.budgetCents, draft.maxPurchaseCents, draft.merchants, draft.mccs, draft.periodDays, draft.expiresAt, draft.feeBps]);
+}
+/** hex sha256("chainpay-card-draft:v1\n" || canonical draft). The dashboard recomputes it before showing the review. */
+export async function cardDraftDigest(draft) {
+    const bytes = new TextEncoder().encode(`chainpay-card-draft:v1\n${canonical(draft)}`);
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes.slice().buffer));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function cardDraftMaxObligationCents(draft) {
+    return centsToString(maxObligationCents(BigInt(draft.budgetCents), draft.feeBps));
+}
+function toBase64Url(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+    const binary = globalThis.atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+/** `${app}/app/cards/new#draft=<base64url(JSON)>`. The fragment never reaches a server. */
+export function encodeCardDraftLink(draft, appBaseUrl) {
+    const origin = appBaseUrl.trim().replace(/\/+$/, "");
+    if (!/^https?:\/\//.test(origin))
+        throw new Error("App URL must be http(s)");
+    return `${origin}/app/cards/new#draft=${toBase64Url(JSON.stringify(draft))}`;
+}
+export function decodeCardDraftFragment(fragment, now = Date.now()) {
+    const match = fragment.match(/(?:^#?|&)draft=([A-Za-z0-9_-]+)/);
+    if (!match)
+        throw new Error("No card draft in this link");
+    const raw = JSON.parse(fromBase64Url(match[1]));
+    if (raw.v !== 1)
+        throw new Error("Unsupported card draft version");
+    return normalizeCardDraft(raw, now);
+}
+/** Review link with the draft digest alongside: `…/app/cards/new#draft=…&digest=<hex>`. */
+export async function encodeCardDraftReviewLink(draft, appBaseUrl) {
+    return `${encodeCardDraftLink(draft, appBaseUrl)}&digest=${await cardDraftDigest(draft)}`;
+}
+/**
+ * Dashboard intake for an agent's review link. The draft is only usable when
+ * the digest in the link equals the digest recomputed here; otherwise the
+ * caller must leave the form empty.
+ */
+export async function verifyCardDraftFragment(fragment, now = Date.now()) {
+    let draft;
+    try {
+        draft = decodeCardDraftFragment(fragment, now);
+    }
+    catch (error) {
+        return { status: "invalid", reason: error instanceof Error ? error.message : "This link can't be read" };
+    }
+    const digest = await cardDraftDigest(draft);
+    const claimed = fragment.match(/(?:^#?|&)digest=([0-9a-f]{64})(?:&|$)/)?.[1];
+    if (!claimed)
+        return { status: "missing_digest", digest };
+    if (claimed !== digest)
+        return { status: "mismatch", digest, expected: claimed };
+    return { status: "matched", draft, digest };
+}

package/dist/cards/evidence.d.ts

@@ -0,0 +1,69 @@
+export type CardDeclineReason = "frozen" | "merchant_not_allowed" | "over_budget" | "over_max" | "velocity" | "intent_missing" | "internal";
+export type CardMerchantView = {
+    displayName: string;
+    mcc: string;
+};
+export type SplSettlementEvidence = {
+    kind: "spl_settlement";
+    receiptPda: string;
+};
+export type CardAuthorizationEvidence = {
+    kind: "card_authorization";
+    cardId: string;
+    intentId: string;
+    merchant: CardMerchantView;
+    amountCents: string;
+    currency: "USD";
+    reservationState: "reserved" | "declined" | "ambiguous";
+    decision: "approved" | "declined";
+    declineReason?: CardDeclineReason;
+    at: string;
+    private: true;
+};
+export type CardCaptureLifecycle = "captured" | "partially_captured" | "reversed" | "expired" | "late_capture" | "refunded" | "forced_capture";
+export type CardCaptureEvidence = {
+    kind: "card_capture";
+    cardId: string;
+    authId: string;
+    merchant: CardMerchantView;
+    capturedCents: string;
+    reservedCents: string;
+    lifecycle: CardCaptureLifecycle;
+    exception?: "forced_capture" | "over_capture" | "unpaired_capture";
+    commitment?: {
+        seq: string;
+        root: string;
+        slot: string;
+    };
+    private: true;
+};
+export type StatementRepaymentState = "repayment_observed" | "partner_confirmed" | "discharged" | "repayment_mismatch";
+export type StatementRepaymentEvidence = {
+    kind: "statement_repayment";
+    cardId: string;
+    statementId: string;
+    statementDigest: string;
+    totalCents: string;
+    receiptPda: string;
+    repaymentState: StatementRepaymentState;
+    simulatedCredit: true;
+};
+export type CardEvidence = CardAuthorizationEvidence | CardCaptureEvidence | StatementRepaymentEvidence;
+export type ReceiptEvidence = SplSettlementEvidence | CardEvidence;
+export type ReceiptEvidenceKind = ReceiptEvidence["kind"];
+export declare const CARD_EVIDENCE_KINDS: readonly ["card_authorization", "card_capture", "statement_repayment"];
+export declare function isCardEvidence(evidence: ReceiptEvidence): evidence is CardEvidence;
+/** Only `spl_settlement` may use the on-chain settlement layout and wording. */
+export declare function mayRenderAsSplSettlement(evidence: ReceiptEvidence): boolean;
+/** Reservation lifecycle (contracts.md §4.1). `pending` and `ambiguous` are off-chain only. */
+export type CardReservationLifecycle = "pending" | "reserved" | "captured" | "partially_captured" | "reversed" | "expired" | "declined" | "ambiguous";
+/** Statement lifecycle (contracts.md §4.2). Every statement is simulated credit. */
+export type StatementState = "open" | "closed" | "repayment_observed" | "partner_confirmed" | "discharged" | "repayment_mismatch" | "overdue";
+export type AsaResult = "APPROVED" | "CARD_PAUSED" | "UNAUTHORIZED_MERCHANT" | "INSUFFICIENT_FUNDS" | "VELOCITY_EXCEEDED" | "SUSPECTED_FRAUD";
+/** Map a program error code to the ASA decision and the receipt decline reason (contracts.md §3.1). */
+export declare function declineForProgramError(code: number): {
+    asa: AsaResult;
+    reason: CardDeclineReason;
+};
+/** Plain-language decline copy for owners and agents. Never reveals the limit itself. */
+export declare const DECLINE_COPY: Record<CardDeclineReason, string>;

package/dist/cards/evidence.js

@@ -0,0 +1,41 @@
+import { cardPolicyErrorName } from "./constants.js";
+export const CARD_EVIDENCE_KINDS = ["card_authorization", "card_capture", "statement_repayment"];
+export function isCardEvidence(evidence) {
+    return CARD_EVIDENCE_KINDS.includes(evidence.kind);
+}
+/** Only `spl_settlement` may use the on-chain settlement layout and wording. */
+export function mayRenderAsSplSettlement(evidence) {
+    return evidence.kind === "spl_settlement";
+}
+const DECLINES = {
+    CardFrozen: { asa: "CARD_PAUSED", reason: "frozen" },
+    RecoveryFrozen: { asa: "CARD_PAUSED", reason: "frozen" },
+    PolicyExpired: { asa: "CARD_PAUSED", reason: "frozen" },
+    MerchantMismatch: { asa: "UNAUTHORIZED_MERCHANT", reason: "merchant_not_allowed" },
+    MerchantNotAllowed: { asa: "UNAUTHORIZED_MERCHANT", reason: "merchant_not_allowed" },
+    MccNotAllowed: { asa: "UNAUTHORIZED_MERCHANT", reason: "merchant_not_allowed" },
+    CurrencyMismatch: { asa: "UNAUTHORIZED_MERCHANT", reason: "merchant_not_allowed" },
+    RecurringNotAllowed: { asa: "UNAUTHORIZED_MERCHANT", reason: "merchant_not_allowed" },
+    IntentInvalid: { asa: "UNAUTHORIZED_MERCHANT", reason: "intent_missing" },
+    IntentExpired: { asa: "UNAUTHORIZED_MERCHANT", reason: "intent_missing" },
+    IntentStale: { asa: "UNAUTHORIZED_MERCHANT", reason: "intent_missing" },
+    BudgetExceeded: { asa: "INSUFFICIENT_FUNDS", reason: "over_budget" },
+    AmountExceedsIntent: { asa: "INSUFFICIENT_FUNDS", reason: "over_max" },
+    AmountExceedsMax: { asa: "INSUFFICIENT_FUNDS", reason: "over_max" },
+    VelocityExceeded: { asa: "VELOCITY_EXCEEDED", reason: "velocity" },
+};
+/** Map a program error code to the ASA decision and the receipt decline reason (contracts.md §3.1). */
+export function declineForProgramError(code) {
+    const name = cardPolicyErrorName(code);
+    return (name && DECLINES[name]) || { asa: "SUSPECTED_FRAUD", reason: "internal" };
+}
+/** Plain-language decline copy for owners and agents. Never reveals the limit itself. */
+export const DECLINE_COPY = {
+    frozen: "The card is frozen, so the purchase was declined.",
+    merchant_not_allowed: "This shop isn't on the card's list.",
+    over_budget: "This purchase would go over what's left this period.",
+    over_max: "This purchase is bigger than the card allows in one go.",
+    velocity: "The card has hit its number of purchases for this period.",
+    intent_missing: "No matching checkout was opened for this purchase.",
+    internal: "ChainPay couldn't confirm this purchase in time, so it was declined.",
+};

package/dist/cards/hash.d.ts

@@ -0,0 +1,9 @@
+/** sha256("chainpay-merchant:v1\n" || UPPER(trim(acceptor_id))). */
+export declare function merchantIdHash(acceptorId: string): Promise<Uint8Array>;
+/** sha256("chainpay-auth-id:v1\n" || issuer_u8 || lithic_txn_token_utf8). */
+export declare function authIdHash(issuer: number, issuerTransactionToken: string): Promise<Uint8Array>;
+/** sha256("chainpay-card-ref:v1\n" || lithic_card_token_utf8 || ref_salt32). */
+export declare function issuerCardRefHash(issuerCardToken: string, refSalt: Uint8Array): Promise<Uint8Array>;
+/** `cpcap_v1_<base64url(32 random bytes)>` (contracts.md §6). Opaque; carries no card data. */
+export declare const CHECKOUT_CAPABILITY_PATTERN: RegExp;
+export declare function isCheckoutCapability(value: unknown): value is string;

package/dist/cards/hash.js

@@ -0,0 +1,47 @@
+/*
+ * Domain-separated hashes the program and Axum agree on (contracts.md §1.2).
+ * WebCrypto only, so the same code runs in the browser, Node and workers.
+ */
+async function sha256(bytes) {
+    return new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes.slice().buffer));
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+function join(...parts) {
+    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/** sha256("chainpay-merchant:v1\n" || UPPER(trim(acceptor_id))). */
+export async function merchantIdHash(acceptorId) {
+    const normalized = acceptorId.trim().toUpperCase();
+    if (!normalized)
+        throw new Error("merchant acceptor id is required");
+    return sha256(utf8(`chainpay-merchant:v1\n${normalized}`));
+}
+/** sha256("chainpay-auth-id:v1\n" || issuer_u8 || lithic_txn_token_utf8). */
+export async function authIdHash(issuer, issuerTransactionToken) {
+    if (!Number.isInteger(issuer) || issuer < 0 || issuer > 255)
+        throw new Error("issuer must fit in u8");
+    if (!issuerTransactionToken)
+        throw new Error("issuer transaction token is required");
+    return sha256(join(utf8("chainpay-auth-id:v1\n"), Uint8Array.of(issuer), utf8(issuerTransactionToken)));
+}
+/** sha256("chainpay-card-ref:v1\n" || lithic_card_token_utf8 || ref_salt32). */
+export async function issuerCardRefHash(issuerCardToken, refSalt) {
+    if (refSalt.length !== 32)
+        throw new Error("refSalt must be exactly 32 bytes");
+    if (!issuerCardToken)
+        throw new Error("issuer card token is required");
+    return sha256(join(utf8("chainpay-card-ref:v1\n"), utf8(issuerCardToken), refSalt));
+}
+/** `cpcap_v1_<base64url(32 random bytes)>` (contracts.md §6). Opaque; carries no card data. */
+export const CHECKOUT_CAPABILITY_PATTERN = /^cpcap_v1_[A-Za-z0-9_-]{43}$/;
+export function isCheckoutCapability(value) {
+    return typeof value === "string" && CHECKOUT_CAPABILITY_PATTERN.test(value);
+}

package/dist/cards/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./constants.js";
+export * from "./layout.js";
+export * from "./accounts.js";
+export * from "./pda.js";
+export * from "./instructions.js";
+export * from "./math.js";
+export * from "./hash.js";
+export * from "./redact.js";
+export * from "./evidence.js";
+export * from "./api.js";
+export * from "./tee.js";
+export * from "./draft.js";
+export * from "./commitment.js";
+export * from "./merchants.js";

package/dist/cards/index.js

@@ -0,0 +1,14 @@
+export * from "./constants.js";
+export * from "./layout.js";
+export * from "./accounts.js";
+export * from "./pda.js";
+export * from "./instructions.js";
+export * from "./math.js";
+export * from "./hash.js";
+export * from "./redact.js";
+export * from "./evidence.js";
+export * from "./api.js";
+export * from "./tee.js";
+export * from "./draft.js";
+export * from "./commitment.js";
+export * from "./merchants.js";