@genesis-tech/genesispay-seller 0.13.1 → 1.3.0

package/dist/checkout-documents.d.ts

@@ -0,0 +1,99 @@
+import { type ItemTax } from "./item-tax.js";
+import { type GenesisPayRequest } from "./resource.js";
+export type CheckoutDocumentKind = "invoice" | "enhanced_receipt";
+/** The commercial snapshot frozen before the buyer signs the hosted checkout. */
+export type CheckoutDocumentSnapshot = {
+    version: number;
+    seller: {
+        userId: string;
+        legalName: string;
+        email: string | null;
+        addressLine1: string | null;
+        addressLine2: string | null;
+        city: string | null;
+        postalCode: string | null;
+        countryCode: string | null;
+        taxId: string | null;
+        profileVersion?: number;
+        taxRegistration?: CheckoutTaxRegistration;
+    };
+    buyer: {
+        legalName: string;
+        companyName: string | null;
+        addressLine1: string;
+        addressLine2: string | null;
+        city: string;
+        region: string | null;
+        postalCode: string;
+        countryCode: string;
+        taxId: string | null;
+        email: string;
+    };
+    lineItem: {
+        description: string;
+    };
+    lines?: Array<{
+        description: string;
+        quantity: number;
+        unitAmountMinor: string;
+        subtotalMinor: string;
+        discountMinor: string;
+        taxMinor: string;
+        totalMinor: string;
+        taxConfig: ItemTax;
+    }>;
+    invoice: {
+        prefix: string;
+        pricesIncludeTax: true;
+    };
+    tax: {
+        source: "seller_configured" | null;
+        status: "receipt_required" | "calculated";
+        reason: string | null;
+        taxRateBps: number | null;
+        zeroTaxNote: string | null;
+        rounding: "half_up_asset_minor_unit" | null;
+        settingsUpdatedAt: string | null;
+        itemConfig?: ItemTax;
+    };
+};
+export type CheckoutTaxRegistration = {
+    status: "not_registered";
+    reason: string;
+} | {
+    status: "registered";
+    registrations: Array<{
+        type: "vat" | "gst" | "tax_id" | "business_number";
+        countryCode: string;
+        value: string;
+    }>;
+};
+/** A formal invoice or enhanced receipt issued for a hosted human checkout. */
+export type CheckoutDocument = {
+    id: string;
+    publicId: string;
+    kind: CheckoutDocumentKind;
+    /** Present only when the seller's tax configuration supported a formal invoice. */
+    invoiceNumber: string | null;
+    asset: "USDC" | "EURC";
+    chainId: number;
+    subtotalMinor: string;
+    discountMinor: string;
+    taxMinor: string;
+    totalMinor: string;
+    txHash: string | null;
+    confirmedAt: string;
+    issuedAt: string;
+    retainUntil: string;
+    recipientEmail: string;
+    snapshot: CheckoutDocumentSnapshot;
+};
+export interface CheckoutDocumentsResource {
+    /** Lists the latest 100 immutable documents from hosted human checkout. */
+    list(): Promise<CheckoutDocument[]>;
+    /** Retrieves one seller-owned document by its public `doc_…` id. */
+    get(publicId: string): Promise<CheckoutDocument>;
+}
+export declare function createCheckoutDocumentsResource(request: GenesisPayRequest): CheckoutDocumentsResource;
+export declare function toCheckoutDocument(raw: Record<string, unknown>): CheckoutDocument;
+//# sourceMappingURL=checkout-documents.d.ts.map

package/dist/checkout-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-documents.d.ts","sourceRoot":"","sources":["../src/checkout-documents.ts"],"names":[],"mappings":"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"}

package/dist/checkout-documents.js

@@ -0,0 +1,155 @@
+// `genesispay.checkoutDocuments.*` — documents created after hosted human checkout.
+//
+// These are intentionally read-only. They are not the seller-authored invoice
+// lifecycle (`genesispay.invoices.*`): a hosted checkout document is produced
+// only after a confirmed, non-simulated payment and is immutable thereafter.
+import { GenesisPayConfigError } from "./errors.js";
+import { parseItemTax } from "./item-tax.js";
+import { asRecord, oneOf, optionalString, requiredString, toAmountString, toCount, } from "./resource.js";
+export function createCheckoutDocumentsResource(request) {
+    return {
+        list: async () => {
+            const body = await request({
+                path: "/api/v1/checkout-documents",
+                operation: "GET /api/v1/checkout-documents",
+                action: "list hosted checkout documents",
+            });
+            const rows = asRecord(body)?.documents;
+            if (!Array.isArray(rows)) {
+                throw new GenesisPayConfigError(`GenesisPay GET /api/v1/checkout-documents returned no documents array: ${JSON.stringify(body)}`);
+            }
+            return rows
+                .map(asRecord)
+                .filter((row) => Boolean(row?.publicId))
+                .map(toCheckoutDocument);
+        },
+        get: async (publicId) => {
+            const body = await request({
+                path: `/api/v1/checkout-documents/${encodeURIComponent(publicId)}`,
+                operation: "GET /api/v1/checkout-documents/:publicId",
+                notFoundMessage: `Checkout document ${publicId} was not found.`,
+                action: "retrieve a hosted checkout document",
+            });
+            const row = asRecord(asRecord(body)?.document);
+            if (!row) {
+                throw new GenesisPayConfigError(`GenesisPay GET /api/v1/checkout-documents/:publicId returned no document: ${JSON.stringify(body)}`);
+            }
+            return toCheckoutDocument(row);
+        },
+    };
+}
+export function toCheckoutDocument(raw) {
+    return {
+        id: requiredString(raw.id),
+        publicId: requiredString(raw.publicId),
+        kind: oneOf(raw.kind, ["invoice", "enhanced_receipt"], "enhanced_receipt"),
+        invoiceNumber: optionalString(raw.invoiceNumber),
+        asset: oneOf(raw.asset, ["USDC", "EURC"], "USDC"),
+        chainId: toCount(raw.chainId),
+        subtotalMinor: toAmountString(raw.subtotalMinor),
+        discountMinor: toAmountString(raw.discountMinor),
+        taxMinor: toAmountString(raw.taxMinor),
+        totalMinor: toAmountString(raw.totalMinor),
+        txHash: optionalString(raw.txHash),
+        confirmedAt: requiredString(raw.confirmedAt),
+        issuedAt: requiredString(raw.issuedAt),
+        retainUntil: requiredString(raw.retainUntil),
+        recipientEmail: requiredString(raw.recipientEmail),
+        snapshot: toCheckoutDocumentSnapshot(asRecord(raw.snapshot) ?? {}),
+    };
+}
+function toCheckoutDocumentSnapshot(raw) {
+    const seller = asRecord(raw.seller) ?? {};
+    const buyer = asRecord(raw.buyer) ?? {};
+    const lineItem = asRecord(raw.lineItem) ?? {};
+    const invoice = asRecord(raw.invoice) ?? {};
+    const tax = asRecord(raw.tax) ?? {};
+    const v2 = raw.version === 2;
+    return {
+        version: toCount(raw.version),
+        seller: {
+            userId: requiredString(seller.userId),
+            legalName: requiredString(seller.legalName),
+            email: optionalString(seller.email),
+            addressLine1: optionalString(seller.addressLine1),
+            addressLine2: optionalString(seller.addressLine2),
+            city: optionalString(seller.city),
+            postalCode: optionalString(seller.postalCode),
+            countryCode: optionalString(seller.countryCode),
+            taxId: optionalString(seller.taxId),
+            ...(v2 ? { profileVersion: toCount(seller.profileVersion), taxRegistration: parseCheckoutTaxRegistration(seller.taxRegistration) } : {}),
+        },
+        buyer: {
+            legalName: requiredString(buyer.legalName),
+            companyName: optionalString(buyer.companyName),
+            addressLine1: requiredString(buyer.addressLine1),
+            addressLine2: optionalString(buyer.addressLine2),
+            city: requiredString(buyer.city),
+            region: optionalString(buyer.region),
+            postalCode: requiredString(buyer.postalCode),
+            countryCode: requiredString(buyer.countryCode),
+            taxId: optionalString(buyer.taxId),
+            email: requiredString(buyer.email),
+        },
+        lineItem: {
+            description: requiredString(lineItem.description),
+        },
+        ...(v2 ? { lines: parseCheckoutLines(raw.lines) } : {}),
+        invoice: {
+            prefix: requiredString(invoice.prefix),
+            pricesIncludeTax: true,
+        },
+        tax: {
+            source: nullableOneOf(tax.source, ["seller_configured"]),
+            status: oneOf(tax.status, ["receipt_required", "calculated"], "receipt_required"),
+            reason: optionalString(tax.reason),
+            taxRateBps: optionalFiniteNumber(tax.taxRateBps),
+            zeroTaxNote: optionalString(tax.zeroTaxNote),
+            rounding: nullableOneOf(tax.rounding, ["half_up_asset_minor_unit"]),
+            settingsUpdatedAt: optionalString(tax.settingsUpdatedAt),
+            ...(v2 ? { itemConfig: requiredItemTax(tax.itemConfig) } : {}),
+        },
+    };
+}
+function requiredItemTax(raw) {
+    const tax = parseItemTax(raw);
+    if (!tax)
+        throw new GenesisPayConfigError("A v2 document requires explicit item tax.");
+    return tax;
+}
+function parseCheckoutLines(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new GenesisPayConfigError("A v2 document requires line totals.");
+    return raw.map((value) => {
+        const line = asRecord(value) ?? {};
+        return { description: requiredString(line.description), quantity: toCount(line.quantity),
+            unitAmountMinor: toAmountString(line.unitAmountMinor), subtotalMinor: toAmountString(line.subtotalMinor),
+            discountMinor: toAmountString(line.discountMinor), taxMinor: toAmountString(line.taxMinor),
+            totalMinor: toAmountString(line.totalMinor), taxConfig: requiredItemTax(line.taxConfig) };
+    });
+}
+function parseCheckoutTaxRegistration(value) {
+    const tax = asRecord(value);
+    if (tax?.status === "not_registered" && typeof tax.reason === "string")
+        return { status: "not_registered", reason: tax.reason };
+    if (tax?.status !== "registered" || !Array.isArray(tax.registrations) || !tax.registrations.length)
+        throw new GenesisPayConfigError("A v2 document requires the issuer tax declaration.");
+    return { status: "registered", registrations: tax.registrations.map((value) => {
+            const entry = asRecord(value);
+            if (!entry || !["vat", "gst", "tax_id", "business_number"].includes(String(entry.type)) || typeof entry.countryCode !== "string" || typeof entry.value !== "string")
+                throw new GenesisPayConfigError("Invalid issuer tax declaration.");
+            return { type: entry.type, countryCode: entry.countryCode, value: entry.value };
+        }) };
+}
+function nullableOneOf(value, allowed) {
+    return typeof value === "string" && allowed.includes(value)
+        ? value
+        : null;
+}
+function optionalFiniteNumber(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+//# sourceMappingURL=checkout-documents.js.map

package/dist/checkout-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-documents.js","sourceRoot":"","sources":["../src/checkout-documents.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAE7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,YAAY,EAAgB,MAAM,eAAe,CAAC;AAC3D,OAAO,EACL,QAAQ,EACR,KAAK,EACL,cAAc,EACd,cAAc,EACd,cAAc,EACd,OAAO,GAER,MAAM,eAAe,CAAC;AAqFvB,MAAM,UAAU,+BAA+B,CAC7C,OAA0B;IAE1B,OAAO;QACL,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;gBACzB,IAAI,EAAE,4BAA4B;gBAClC,SAAS,EAAE,gCAAgC;gBAC3C,MAAM,EAAE,gCAAgC;aACzC,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;YACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,qBAAqB,CAC7B,0EAA0E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACjG,CAAC;YACJ,CAAC;YACD,OAAO,IAAI;iBACR,GAAG,CAAC,QAAQ,CAAC;iBACb,MAAM,CAAC,CAAC,GAAG,EAAkC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;iBACvE,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC7B,CAAC;QACD,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YACtB,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC;gBACzB,IAAI,EAAE,8BAA8B,kBAAkB,CAAC,QAAQ,CAAC,EAAE;gBAClE,SAAS,EAAE,0CAA0C;gBACrD,eAAe,EAAE,qBAAqB,QAAQ,iBAAiB;gBAC/D,MAAM,EAAE,qCAAqC;aAC9C,CAAC,CAAC;YACH,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC/C,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,qBAAqB,CAC7B,6EAA6E,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACpG,CAAC;YACJ,CAAC;YACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAA4B;IAC7D,OAAO;QACL,EAAE,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC;QACtC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,kBAAkB,CAAU,EAAE,kBAAkB,CAAC;QACnF,aAAa,EAAE,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC;QAChD,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAU,EAAE,MAAM,CAAC;QAC1D,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAC7B,aAAa,EAAE,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC;QAChD,aAAa,EAAE,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC;QAChD,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC;QACtC,UAAU,EAAE,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC;QAC1C,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;QAClC,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC;QAC5C,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC;QACtC,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC;QAC5C,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC;QAClD,QAAQ,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CAAC,GAA4B;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC;IAC7B,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAC7B,MAAM,EAAE;YACN,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC;YACrC,SAAS,EAAE,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC;YAC3C,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC;YACnC,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC;YACjD,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC;YACjD,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC;YACjC,UAAU,EAAE,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC;YAC7C,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC;YAC/C,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC;YACnC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,eAAe,EAAE,4BAA4B,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzI;QACD,KAAK,EAAE;YACL,SAAS,EAAE,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC;YAC1C,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC;YAC9C,YAAY,EAAE,cAAc,CAAC,KAAK,CAAC,YAAY,CAAC;YAChD,YAAY,EAAE,cAAc,CAAC,KAAK,CAAC,YAAY,CAAC;YAChD,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC;YAChC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC;YACpC,UAAU,EAAE,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC;YAC5C,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC;YAC9C,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;YAClC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;SACnC;QACD,QAAQ,EAAE;YACR,WAAW,EAAE,cAAc,CAAC,QAAQ,CAAC,WAAW,CAAC;SAClD;QACD,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE;YACP,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC;YACtC,gBAAgB,EAAE,IAAI;SACvB;QACD,GAAG,EAAE;YACH,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,mBAAmB,CAAU,CAAC;YACjE,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,kBAAkB,EAAE,YAAY,CAAU,EAAE,kBAAkB,CAAC;YAC1F,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;YAClC,UAAU,EAAE,oBAAoB,CAAC,GAAG,CAAC,UAAU,CAAC;YAChD,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC;YAC5C,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,0BAA0B,CAAU,CAAC;YAC5E,iBAAiB,EAAE,cAAc,CAAC,GAAG,CAAC,iBAAiB,CAAC;YACxD,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/D;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAY;IACnC,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,qBAAqB,CAAC,2CAA2C,CAAC,CAAC;IACvF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAC;IACpH,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACvB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,EAAE,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;YACtF,eAAe,EAAE,cAAc,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,aAAa,EAAE,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC;YACxG,aAAa,EAAE,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;YAC1F,UAAU,EAAE,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IAC9F,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAc;IAClD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,GAAG,EAAE,MAAM,KAAK,gBAAgB,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAChI,IAAI,GAAG,EAAE,MAAM,KAAK,YAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM;QAAE,MAAM,IAAI,qBAAqB,CAAC,oDAAoD,CAAC,CAAC;IAC1L,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC9B,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;gBAAE,MAAM,IAAI,qBAAqB,CAAC,iCAAiC,CAAC,CAAC;YACxO,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAoD,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QAClI,CAAC,CAAC,EAAE,CAAC;AACP,CAAC;AAED,SAAS,aAAa,CAAmB,KAAc,EAAE,OAAqB;IAC5E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,OAA6B,CAAC,QAAQ,CAAC,KAAK,CAAC;QAChF,CAAC,CAAE,KAAW;QACd,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/dist/checkout-return.d.ts

@@ -0,0 +1,41 @@
+/** The `returnUrl` query parameter carrying the checkout link's `publicId`. */
+export declare const CHECKOUT_RETURN_LINK_ID_PARAM = "genesispay_link_id";
+/** The `returnUrl` query parameter carrying the checkout status. */
+export declare const CHECKOUT_RETURN_STATUS_PARAM = "genesispay_status";
+/**
+ * The result parameters GenesisPay appends to a merchant's `returnUrl`, as
+ * read back by {@link parseCheckoutReturnHint}.
+ *
+ * **This is a UI hint, not proof of payment.** The values are unsigned and a
+ * payer can open that URL without paying. Use the seller-authenticated strict
+ * `fulfillment.verify` authority path before fulfilment — never these fields.
+ */
+export type CheckoutReturnHint = {
+    /** The checkout link's `publicId` — the value in `genesispay_link_id`. */
+    linkId: string;
+    /** Always `"paid"` — the parser returns nothing else. */
+    status: "paid";
+};
+/**
+ * Reads the return parameters off a `returnUrl`.
+ *
+ * Returns a hint only when the URL carries a non-empty `genesispay_link_id` and
+ * an exact `genesispay_status=paid`. A missing id, any other status, or an
+ * unparseable URL returns `null`. Accepts a string or an already-parsed `URL`.
+ *
+ * Performs **no verification**: it does not check that the link exists, that it
+ * was paid, or that the parameters came from GenesisPay. Call
+ * `fulfillment.verify({ locator: { linkId: hint.linkId }, expected })`
+ * (authenticated with your seller key) before acting on it. A link locator is
+ * suitable only for a single-use link; reusable links require an attempt ID.
+ */
+export declare function parseCheckoutReturnHint(url: string | URL): CheckoutReturnHint | null;
+/**
+ * The payer-facing redirect scheme allowlist for `returnUrl`/`cancelUrl`,
+ * mirroring the server. `https` is always accepted; `http` is accepted only for
+ * the exact loopback hostnames above — a `javascript:`/`data:` value, a remote
+ * `http` host, or a deceptive `localhost.example` name is rejected, because
+ * these values are rendered as links in the payer's browser.
+ */
+export declare function isPayerRedirectUrl(rawUrl: string): boolean;
+//# sourceMappingURL=checkout-return.d.ts.map

package/dist/checkout-return.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-return.d.ts","sourceRoot":"","sources":["../src/checkout-return.ts"],"names":[],"mappings":"AAYA,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,uBAAuB,CAAC;AAElE,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAQhE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,kBAAkB,GAAG,IAAI,CAgBpF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAa1D"}

package/dist/checkout-return.js

@@ -0,0 +1,68 @@
+// The query parameters GenesisPay appends to a merchant's `returnUrl` after a
+// confirmed payment, and the helper that reads them back.
+//
+// These names are part of a cross-side contract: the server's hosted-checkout
+// URL builder (`src/features/payments/checkout-return-url.ts`) writes them and
+// this SDK reads them. A parity test lives on the server side (the only place
+// that can import both) and fails if either side renames one without the other.
+//
+// The parser below performs **no verification**. The parameters are unsigned —
+// anyone who knows a `publicId` can construct that URL without paying — so a
+// hint it returns is a UI convenience, never proof of payment.
+/** The `returnUrl` query parameter carrying the checkout link's `publicId`. */
+export const CHECKOUT_RETURN_LINK_ID_PARAM = "genesispay_link_id";
+/** The `returnUrl` query parameter carrying the checkout status. */
+export const CHECKOUT_RETURN_STATUS_PARAM = "genesispay_status";
+/** The only status the parser accepts — and the only status GenesisPay writes. */
+const PAID_STATUS = "paid";
+/** Hostnames for which `http` is accepted (local development only). */
+const LOCAL_REDIRECT_HOSTNAMES = new Set(["localhost", "127.0.0.1"]);
+/**
+ * Reads the return parameters off a `returnUrl`.
+ *
+ * Returns a hint only when the URL carries a non-empty `genesispay_link_id` and
+ * an exact `genesispay_status=paid`. A missing id, any other status, or an
+ * unparseable URL returns `null`. Accepts a string or an already-parsed `URL`.
+ *
+ * Performs **no verification**: it does not check that the link exists, that it
+ * was paid, or that the parameters came from GenesisPay. Call
+ * `fulfillment.verify({ locator: { linkId: hint.linkId }, expected })`
+ * (authenticated with your seller key) before acting on it. A link locator is
+ * suitable only for a single-use link; reusable links require an attempt ID.
+ */
+export function parseCheckoutReturnHint(url) {
+    let parsed;
+    try {
+        parsed = typeof url === "string" ? new URL(url) : url;
+    }
+    catch {
+        return null;
+    }
+    const linkId = parsed.searchParams.get(CHECKOUT_RETURN_LINK_ID_PARAM);
+    const status = parsed.searchParams.get(CHECKOUT_RETURN_STATUS_PARAM);
+    if (!linkId || status !== PAID_STATUS) {
+        return null;
+    }
+    return { linkId, status: PAID_STATUS };
+}
+/**
+ * The payer-facing redirect scheme allowlist for `returnUrl`/`cancelUrl`,
+ * mirroring the server. `https` is always accepted; `http` is accepted only for
+ * the exact loopback hostnames above — a `javascript:`/`data:` value, a remote
+ * `http` host, or a deceptive `localhost.example` name is rejected, because
+ * these values are rendered as links in the payer's browser.
+ */
+export function isPayerRedirectUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl.trim());
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:") {
+        return true;
+    }
+    return parsed.protocol === "http:" && LOCAL_REDIRECT_HOSTNAMES.has(parsed.hostname);
+}
+//# sourceMappingURL=checkout-return.js.map

package/dist/checkout-return.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-return.js","sourceRoot":"","sources":["../src/checkout-return.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+DAA+D;AAE/D,+EAA+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAElE,oEAAoE;AACpE,MAAM,CAAC,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAEhE,kFAAkF;AAClF,MAAM,WAAW,GAAG,MAAM,CAAC;AAE3B,uEAAuE;AACvE,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAiBrE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAiB;IACvD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAErE,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,wBAAwB,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACtF,CAAC"}