@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/crossmint-adapt.js

@@ -0,0 +1,68 @@
+import { hexToBytes } from "./receipt.js";
+import { MEMO_PROGRAM_ID } from "./constants.js";
+import { CROSSMINT_CONNECTOR, CROSSMINT_CONNECTOR_LABEL, MAX_CROSSMINT_MEMO_BYTES, crossmintPaymentTerms, deriveCrossmintPaymentReferences, parseCrossmintOrder, } from "./crossmint-order.js";
+/** Terms plus the references the receipt PDA is derived from. */
+export async function crossmintTermsToPrepareFields(terms) {
+    const references = await deriveCrossmintPaymentReferences(terms.orderId);
+    return {
+        connector: CROSSMINT_CONNECTOR,
+        connectorLabel: CROSSMINT_CONNECTOR_LABEL,
+        orderId: terms.orderId,
+        mint: terms.mint,
+        recipient: terms.recipient,
+        amount: terms.amount,
+        tokenProgram: terms.tokenProgram,
+        ...references,
+    };
+}
+export function crossmintFieldsToPreparePaymentInput(mandate, fields) {
+    return {
+        mandate,
+        invoiceHash: hexToBytes(fields.invoiceHash, "invoiceHash"),
+        paymentId: hexToBytes(fields.paymentId, "paymentId"),
+        signatureReference: hexToBytes(fields.signatureReference, "signatureReference"),
+        mint: fields.mint,
+        recipient: fields.recipient,
+        amount: BigInt(fields.amount),
+        tokenProgram: fields.tokenProgram,
+    };
+}
+/** One call from a raw Crossmint order response to a ChainPay payment input. */
+export async function crossmintOrderToPreparePaymentInput(mandate, order, expected = {}) {
+    const terms = crossmintPaymentTerms(parseCrossmintOrder(order), expected);
+    const fields = await crossmintTermsToPrepareFields(terms);
+    return { terms, fields, input: crossmintFieldsToPreparePaymentInput(mandate, fields) };
+}
+/**
+ * Crossmint's order memo as a top-level SPL Memo instruction with no accounts.
+ *
+ * Crossmint's own preparation has the payer sign the memo. In ChainPay the
+ * approved agent signs and pays fees, never the owner, so the memo names no
+ * signer; the memo program accepts an unsigned memo. The bytes are Crossmint's
+ * memo exactly, because Crossmint matches a payment to its order by this text.
+ */
+export function crossmintMemoInstruction(memo) {
+    const data = new TextEncoder().encode(memo);
+    if (data.length === 0 || data.length > MAX_CROSSMINT_MEMO_BYTES) {
+        throw new Error("Crossmint memo is empty or too long");
+    }
+    return { name: "crossmint_order_memo", programId: MEMO_PROGRAM_ID, keys: [], data };
+}
+/**
+ * The transaction a Crossmint checkout signs: the unchanged mandate payment,
+ * then Crossmint's memo. Nothing else is added and nothing is dropped; a
+ * prepared payment that is not exactly one `execute_payment` is refused.
+ * The receipt PDA and invoice hash are untouched: they come from the order id.
+ */
+export function crossmintPaymentTransaction(prepared, terms) {
+    if (!terms.memo)
+        throw new Error("Crossmint terms carry no checked order memo");
+    if (prepared.instructions.length !== 1 || prepared.instructions[0].name !== "execute_payment") {
+        throw new Error("A Crossmint payment must start from exactly one execute_payment instruction");
+    }
+    return {
+        ...prepared,
+        requiredSigners: [...prepared.requiredSigners],
+        instructions: [prepared.instructions[0], crossmintMemoInstruction(terms.memo)],
+    };
+}

package/dist/crossmint-order.d.ts

@@ -0,0 +1,220 @@
+import type { Address, TokenProgram } from "./types.js";
+export declare const CROSSMINT_CONNECTOR: "crossmint-checkout/1.0";
+export declare const CROSSMINT_CONNECTOR_LABEL = "Crossmint checkout order settled through a ChainPay mandate. Proof is the settled signature and receipt PDA; Crossmint order state is read back from its Orders API.";
+export declare const CROSSMINT_STAGING_BASE_URL = "https://staging.crossmint.com";
+export declare const CROSSMINT_PRODUCTION_BASE_URL = "https://www.crossmint.com";
+export declare const CROSSMINT_ORDERS_PATH = "/api/2022-06-09/orders";
+/** Crossmint advances an order through these phases; only `payment` still owes money. */
+export declare const CROSSMINT_PAYABLE_PHASE: "payment";
+export declare const CROSSMINT_SETTLED_PHASES: readonly ["delivery", "completed"];
+/**
+ * Crossmint's Solana memo is `------BEGIN MEMO------<JWT>------END MEMO------`,
+ * about 300 bytes. The bound keeps the memo plus `execute_payment` well inside
+ * one legacy transaction.
+ */
+export declare const MAX_CROSSMINT_MEMO_BYTES = 512;
+export type CrossmintOrderErrorCode = "malformed" | "order_not_payable" | "terms_unavailable" | "terms_mismatch" | "unsupported_token_program";
+export declare class CrossmintOrderError extends Error {
+    readonly code: CrossmintOrderErrorCode;
+    constructor(code: CrossmintOrderErrorCode, message: string);
+}
+/**
+ * The fields ChainPay reads from a Crossmint order. Everything except the order
+ * id, the phase, and the payment preparation is optional: a field Crossmint
+ * renames or drops must not stop a payment whose terms come from the
+ * transaction Crossmint itself prepared.
+ */
+export type CrossmintOrderSummary = {
+    orderId: string;
+    phase: string;
+    paymentStatus?: string;
+    paymentMethod?: string;
+    currency?: string;
+    quotedTotal?: {
+        amount: string;
+        currency?: string;
+    };
+    lineItemLocators: string[];
+    /**
+     * What each line item delivers and to whom. `lineItemCount` is the raw count
+     * Crossmint returned, so an item ChainPay could not read is never silently
+     * dropped from what the owner reviews.
+     */
+    lineItems: CrossmintLineItem[];
+    lineItemCount: number;
+    serializedTransaction?: string;
+    /**
+     * `payment.preparation.transactionParameters.memo`, byte for byte (never
+     * trimmed). Crossmint pays every order into one shared treasury account, so
+     * this memo is the only thing that ties a payment to this order.
+     */
+    transactionMemo?: string;
+    /** `transactionParameters.amount`, base units, when Crossmint states it. */
+    transactionAmount?: string;
+    payerAddress?: string;
+    preparationChain?: string;
+    quoteExpiresAt?: string;
+    quoteStatus?: string;
+};
+/**
+ * One Crossmint line item as ChainPay reads it. A field that is absent stays
+ * undefined; a field Crossmint states twice with different values is flagged
+ * as a conflict instead of picking one, so checkout can fail closed.
+ */
+export type CrossmintLineItem = {
+    locator?: string;
+    /** `metadata.name`: what the owner is buying, in Crossmint's words. */
+    name?: string;
+    description?: string;
+    imageUrl?: string;
+    /** A metadata field Crossmint stated but ChainPay could not read within bounds. */
+    metadataUnreadable?: true;
+    chain?: string;
+    executionMode?: string;
+    quantity?: number;
+    quantityConflict?: true;
+    /** Wallet that receives the purchased item: Crossmint's `delivery.recipient`. */
+    deliveryRecipient?: string;
+    deliveryRecipientConflict?: true;
+    totalPrice?: {
+        amount: string;
+        currency?: string;
+    };
+};
+/** The material terms of one item, bound into the reviewed approval. */
+export type CrossmintBoundItem = {
+    /** Crossmint's live order responses carry no locator; kept when one is returned. */
+    locator: string | null;
+    name: string | null;
+    description: string | null;
+    imageUrl: string | null;
+    chain: string | null;
+    executionMode: string | null;
+    quantity: number | null;
+    deliveryRecipient: string | null;
+    totalPrice: {
+        amount: string;
+        currency: string | null;
+    } | null;
+};
+export type CrossmintQuoteCheck = "match" | "mismatch" | "unavailable";
+export type CrossmintPaymentTerms = {
+    connector: typeof CROSSMINT_CONNECTOR;
+    connectorLabel: string;
+    orderId: string;
+    phase: string;
+    mint: Address;
+    recipient: Address;
+    amount: string;
+    decimals?: number;
+    tokenProgram: TokenProgram;
+    /**
+     * Crossmint's own prepared transfer is the only authority on what is owed.
+     * ChainPay reads it and never submits it: settlement goes through
+     * `execute_payment` so the mandate and the receipt still apply.
+     */
+    termsSource: "serialized-transaction";
+    quoteCheck: CrossmintQuoteCheck;
+    quotedTotal?: {
+        amount: string;
+        currency?: string;
+    };
+    lineItemLocators: string[];
+    /**
+     * Who receives what, and how many. The payer and the token-transfer recipient
+     * say nothing about where the purchased item goes, so a changed delivery
+     * wallet or quantity must change the reviewed fingerprint too.
+     */
+    items: CrossmintBoundItem[];
+    payerAddress?: string;
+    crossmintSourceTokenAccount?: Address;
+    /**
+     * Crossmint's exact order memo. Checkout carries it as a second top-level
+     * SPL Memo instruction beside `execute_payment`, because the shared treasury
+     * destination cannot tell orders apart. Set only by
+     * `validateCrossmintCheckoutOrder`, after the memo is checked against the
+     * prepared transaction and the order id.
+     */
+    memo?: string;
+};
+export type CrossmintTransferTerms = {
+    mint: Address;
+    recipient: Address;
+    source: Address;
+    amount: string;
+    decimals?: number;
+    tokenProgram: TokenProgram;
+    /**
+     * Strict decoding only: the single SPL Memo instruction's text and the
+     * accounts it names. Every memo account must be a transaction signer.
+     */
+    memo?: {
+        text: string;
+        signers: Address[];
+    };
+};
+export type CrossmintPaymentReferences = {
+    invoiceHash: string;
+    paymentId: string;
+    signatureReference: string;
+};
+/**
+ * Scale a decimal display amount to base units without floating point.
+ * Returns undefined when the string is not a plain decimal number, because a
+ * quote ChainPay cannot read must be reported as unchecked, never as agreeing.
+ */
+export declare function scaleDecimalString(value: string, decimals: number): bigint | undefined;
+/**
+ * Read a Crossmint create-order or get-order response. Accepts the documented
+ * `{ order }` envelope and a bare order object, because the same order shape is
+ * returned by both endpoints.
+ */
+export declare function parseCrossmintOrder(value: unknown): CrossmintOrderSummary;
+/**
+ * Derive what a Crossmint order actually charges from the transaction Crossmint
+ * prepared for its own payer. Exactly one SPL Token or Token-2022 transfer must
+ * be present: an order that moves money in more than one transfer has no single
+ * set of terms a mandate can be checked against.
+ */
+export declare function decodeCrossmintTransferTerms(serializedTransaction: string, expected?: {
+    mint?: Address;
+    tokenProgram?: TokenProgram;
+    strict?: boolean;
+}): CrossmintTransferTerms;
+/**
+ * Check Crossmint's order memo and return it unchanged.
+ *
+ * The memo is `------BEGIN MEMO------<JWT>------END MEMO------`. Its JWT payload
+ * names the order (`orderIdentifier`). ChainPay cannot check the JWT signature,
+ * which is Crossmint's own; it only checks that the memo belongs to this order,
+ * so a memo copied from a different order is refused.
+ */
+export declare function crossmintOrderMemo(memo: string, orderId: string): string;
+/** Narrow, fail-closed staging checkout contract; generic decoding is not checkout authorization. */
+export declare function validateCrossmintCheckoutOrder(order: CrossmintOrderSummary, expected: {
+    orderId: string;
+    owner: Address;
+    source: Address;
+    mint: Address;
+    now?: number;
+}): CrossmintPaymentTerms;
+/**
+ * Turn a Crossmint order into the terms ChainPay will check against a mandate.
+ * A phase that no longer owes money is rejected here rather than at settlement,
+ * so an already-paid order cannot be charged a second time by mistake.
+ */
+export declare function crossmintPaymentTerms(order: CrossmintOrderSummary, expected?: {
+    mint?: Address;
+    tokenProgram?: TokenProgram;
+}): CrossmintPaymentTerms;
+/**
+ * Payment references for a Crossmint order.
+ *
+ * The invoice hash commits to the connector and the order id and nothing else.
+ * The receipt PDA is derived from it, so one Crossmint order can be settled at
+ * most once under a given mandate however its price or recipient later change —
+ * a repriced order cannot become a second charge.
+ */
+export declare function deriveCrossmintPaymentReferences(orderId: string): Promise<CrossmintPaymentReferences>;
+/** Orders API URL for one order id, against the staging or production host. */
+export declare function crossmintOrderUrl(baseUrl: string, orderId: string): string;