@genesis-tech/genesispay-seller 0.13.2 → 1.3.0

package/dist/fulfillment.d.ts

@@ -0,0 +1,152 @@
+import { type FulfillmentAttemptList, type FulfillmentAttemptsQuery } from "./fulfillment-attempts.js";
+export declare const GENESISPAY_API_VERSION: "2026-08-26";
+export declare const GENESISPAY_VERSION_HEADER: "GENESISPAY-Version";
+export declare const GENESISPAY_REQUEST_ID_HEADER: "GENESISPAY-Request-Id";
+export declare const GENESISPAY_PAYMENT_ATTEMPT_ID_HEADER: "GENESISPAY-Payment-Attempt-Id";
+export type ApiVersion = typeof GENESISPAY_API_VERSION;
+export type DeploymentMode = "test" | "live";
+export type SupportedAsset = "USDC" | "EURC";
+export type PaymentChannel = "checkout" | "x402" | "bank_transfer";
+export type DeliveryType = "none" | "url" | "gate";
+export type SettlementStrategy = "dual" | "atomic";
+type EvmAddress = `0x${string}`;
+export interface NetworkContract {
+    mode: DeploymentMode;
+    network: "base";
+    chainId: 8453 | 84532;
+    asset: SupportedAsset;
+    tokenAddress: EvmAddress;
+    minorUnitScale: 6;
+}
+export interface ExpectedDeliveryContract {
+    type: DeliveryType;
+    url: string | null;
+    gate: null | {
+        method: string;
+        resourceUrl: string;
+        fingerprint: string;
+    };
+}
+export interface ExpectedProductContract {
+    kind: "product";
+    productId: string;
+    sku: string | null;
+    grossAmountMinor: bigint;
+    network: NetworkContract;
+    settlementDestination: EvmAddress;
+    delivery: ExpectedDeliveryContract;
+}
+export interface ExpectedPaymentLinkContract {
+    kind: "payment_link";
+    linkId: string;
+    grossAmountMinor: bigint;
+    network: NetworkContract;
+    settlementDestination: EvmAddress;
+}
+export type ExpectedFulfillmentContract = ExpectedProductContract | ExpectedPaymentLinkContract;
+export type FulfillmentLocator = {
+    attemptId: string;
+    linkId?: never;
+    entitlementId?: never;
+} | {
+    linkId: string;
+    attemptId?: never;
+    entitlementId?: never;
+} | {
+    entitlementId: string;
+    attemptId?: never;
+    linkId?: never;
+};
+/**
+ * The fee agreement frozen onto the payment. `record_only` means the payer
+ * never signed a fee leg and the seller leg moved the full gross;
+ * `payer_authorized` means they did, and the seller leg moved gross − amount.
+ */
+export interface FeeTerms {
+    type: "record_only" | "payer_authorized";
+    amountMinor: bigint;
+    treasuryAddress: EvmAddress | null;
+}
+export type FeeCollectionStatus = "not_recorded" | "recorded" | "pending" | "collecting" | "collected" | "failed" | "written_off";
+/**
+ * The fee leg's own outcome, which is separate from — and usually later than —
+ * the seller leg's. Only `collected` with a transaction hash means the platform
+ * fee actually moved; every other status means the seller was paid and the fee
+ * was not (yet) taken. Never derive it from `feeTerms`.
+ */
+export interface FeeCollection {
+    status: FeeCollectionStatus;
+    amountMinor: bigint | null;
+    treasuryAddress: EvmAddress | null;
+    transactionHash: EvmAddress | null;
+    collectedAt: string | null;
+}
+/**
+ * Current delivery capability for a minted entitlement — never payment
+ * authority. A confirmed payment stays confirmed; `valid` goes false when the
+ * entitlement expires or an operator revokes it for fraud. Gate DELIVERY on
+ * this; gate refunds and reconciliation on the payment.
+ */
+export interface EntitlementState {
+    expiresAt: string;
+    revokedAt: string | null;
+    valid: boolean;
+}
+export interface VerifiedPayment {
+    attemptId: string;
+    linkId: string;
+    entitlementId: string | null;
+    entitlement: EntitlementState | null;
+    paymentChannel: PaymentChannel;
+    confirmedAt: string;
+    transactionHash: EvmAddress;
+    grossAmountMinor: bigint;
+    /** What the seller leg moved: gross minus the AUTHORIZED fee, not a collected one. */
+    sellerAmountMinor: bigint;
+    feeTerms: FeeTerms;
+    feeCollection: FeeCollection;
+    settlementDestination: EvmAddress;
+    network: NetworkContract;
+    product: null | {
+        productId: string;
+        sku: string | null;
+        delivery: ExpectedDeliveryContract;
+    };
+}
+export type FulfillmentVerification = {
+    verified: true;
+    requestId: string;
+    apiVersion: ApiVersion;
+    payment: VerifiedPayment;
+} | {
+    verified: false;
+    reason: "not_found" | "not_confirmed" | "simulated" | "entitlement_invalid";
+    requestId: string;
+    apiVersion: ApiVersion;
+};
+export interface FulfillmentResource {
+    /** Seller-scoped recovery candidates, never a verified payment verdict. */
+    listAttempts(input?: FulfillmentAttemptsQuery): Promise<FulfillmentAttemptList>;
+    /**
+     * Retrieves seller-scoped evidence and verifies it against `expected`.
+     * No overload accepts an evidence object: authority always comes from the
+     * authenticated GenesisPay response.
+     */
+    verify(input: {
+        locator: FulfillmentLocator;
+        expected: ExpectedFulfillmentContract;
+    }): Promise<FulfillmentVerification>;
+}
+type CreateFulfillmentResourceOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchFn: typeof fetch;
+    assertPinnedDestination(wallet: unknown, what: string): void;
+};
+export declare function createFulfillmentResource(options: CreateFulfillmentResourceOptions): FulfillmentResource;
+/** Internal shared validation for product gates before any payment negotiation begins. */
+export declare function validateExpectedProductContract(value: unknown): ExpectedProductContract;
+/** Internal shape check after webhook HMAC verification, not authorization. */
+export declare function assertFulfillmentEventEvidence(value: unknown): void;
+export {};
+//# sourceMappingURL=fulfillment.d.ts.map

package/dist/fulfillment.d.ts.map

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