@vallum/receipts 0.0.0-prerelease → 0.1.0

package/dist/index.d.ts

@@ -24,6 +24,33 @@ export interface EscrowReceipt {
     readonly events: readonly ReceiptEvent[];
     readonly externalPayment?: LinkedReceiptState;
     readonly iotaReceipt?: LinkedReceiptState;
+    readonly escrowSettlement?: EscrowSettlementState;
+}
+export type EscrowSettlementRail = "local" | "iota-testnet" | "iota-mainnet";
+export type EscrowSettlementReleaseMode = "proof" | "acceptance" | "review";
+export interface EscrowSettlementState {
+    readonly status: "open" | "released" | "refunded";
+    readonly settlementRail: EscrowSettlementRail;
+    readonly escrowId: string;
+    readonly releaseMode: EscrowSettlementReleaseMode;
+    readonly invocationId: string;
+    readonly actionId: string;
+    readonly actionContractId: string;
+    readonly actionContractVersion: string;
+    readonly providerPayoutRef: string;
+    readonly platformFeeRef: string;
+    readonly refundDestinationRef: string;
+    readonly providerNetAmount: ReceiptAmount;
+    readonly platformFeeAmount: ReceiptAmount;
+    readonly openedTransactionDigest: string;
+    readonly providerExecutionReceiptHash?: string;
+    readonly evidenceAttestationHash?: string;
+    readonly settlementReceiptHash?: string;
+    readonly buyerFacingReceiptHash?: string;
+    readonly settlementTransactionDigest?: string;
+    readonly releaseProofHash?: string;
+    readonly refundReason?: string;
+    readonly platformFeePaid?: boolean;
 }
 export interface PayPerCallReceipt {
     readonly receiptId: string;
@@ -228,6 +255,40 @@ export interface CreateSubscriptionReceiptInput {
 export interface TransitionOptions {
     readonly at: Date;
 }
+export interface RecordEscrowSettlementOpenOptions extends TransitionOptions {
+    readonly settlementRail: EscrowSettlementRail;
+    readonly escrowId: string;
+    readonly releaseMode: EscrowSettlementReleaseMode;
+    readonly invocationId: string;
+    readonly actionId: string;
+    readonly actionContractId: string;
+    readonly actionContractVersion: string;
+    readonly providerPayoutRef: string;
+    readonly platformFeeRef: string;
+    readonly refundDestinationRef: string;
+    readonly providerNetAmount: ReceiptAmount;
+    readonly platformFeeAmount: ReceiptAmount;
+    readonly transactionDigest: string;
+}
+export interface RecordEscrowSettlementReleaseOptions extends TransitionOptions {
+    readonly verifierId: string;
+    readonly escrowId: string;
+    readonly invocationId: string;
+    readonly releaseProofHash: string;
+    readonly providerExecutionReceiptHash: string;
+    readonly evidenceAttestationHash: string;
+    readonly settlementReceiptHash: string;
+    readonly buyerFacingReceiptHash: string;
+    readonly transactionDigest: string;
+}
+export interface RecordEscrowSettlementRefundOptions extends TransitionOptions {
+    readonly escrowId: string;
+    readonly invocationId: string;
+    readonly reason: string;
+    readonly settlementReceiptHash: string;
+    readonly buyerFacingReceiptHash: string;
+    readonly transactionDigest: string;
+}
 export declare class ReceiptTransitionError extends Error {
     readonly code: "INVALID_TRANSITION" | "UNAUTHORIZED_VERIFIER";
     constructor(code: "INVALID_TRANSITION" | "UNAUTHORIZED_VERIFIER", message: string);
@@ -363,6 +424,9 @@ export declare function refundEscrow(receipt: EscrowReceipt, options: Transition
 export declare function expireEscrow(receipt: EscrowReceipt, options: TransitionOptions & {
     readonly reason: string;
 }): EscrowReceipt;
+export declare function recordEscrowSettlementOpen(receipt: EscrowReceipt, options: RecordEscrowSettlementOpenOptions): EscrowReceipt;
+export declare function recordEscrowSettlementRelease(receipt: EscrowReceipt, options: RecordEscrowSettlementReleaseOptions): EscrowReceipt;
+export declare function recordEscrowSettlementRefund(receipt: EscrowReceipt, options: RecordEscrowSettlementRefundOptions): EscrowReceipt;
 export declare function linkExternalPaymentState(receipt: EscrowReceipt, state: LinkedReceiptState): EscrowReceipt;
 export declare function linkIotaReceiptState(receipt: EscrowReceipt, state: LinkedReceiptState): EscrowReceipt;
 export * from "./x402Receipt.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./ap2Receipt.js";
+const escrowSettlementRails = ["local", "iota-testnet", "iota-mainnet"];
+const escrowSettlementReleaseModes = ["proof", "acceptance", "review"];
 export class ReceiptTransitionError extends Error {
     code;
     constructor(code, message) {
@@ -457,6 +459,97 @@ export function expireEscrow(receipt, options) {
         refundReason: options.reason,
     }, options.reason);
 }
+export function recordEscrowSettlementOpen(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "record escrow settlement open");
+    if (receipt.escrowSettlement) {
+        throw new ReceiptTransitionError("INVALID_TRANSITION", "Escrow settlement is already recorded.");
+    }
+    requireEscrowSettlementRail(options.settlementRail);
+    requireEscrowSettlementReleaseMode(options.releaseMode);
+    requireNonEmpty(options.escrowId, "escrowId");
+    requireNonEmpty(options.invocationId, "invocationId");
+    requireNonEmpty(options.actionId, "actionId");
+    requireNonEmpty(options.actionContractId, "actionContractId");
+    requireNonEmpty(options.actionContractVersion, "actionContractVersion");
+    requireNonEmpty(options.transactionDigest, "transactionDigest");
+    requireSafeSettlementReference(options.providerPayoutRef, "providerPayoutRef");
+    requireSafeSettlementReference(options.platformFeeRef, "platformFeeRef");
+    requireSafeSettlementReference(options.refundDestinationRef, "refundDestinationRef");
+    requireFeeSplit(receipt.amount, options.providerNetAmount, options.platformFeeAmount);
+    return withReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+        escrowSettlement: {
+            status: "open",
+            settlementRail: options.settlementRail,
+            escrowId: options.escrowId,
+            releaseMode: options.releaseMode,
+            invocationId: options.invocationId,
+            actionId: options.actionId,
+            actionContractId: options.actionContractId,
+            actionContractVersion: options.actionContractVersion,
+            providerPayoutRef: options.providerPayoutRef,
+            platformFeeRef: options.platformFeeRef,
+            refundDestinationRef: options.refundDestinationRef,
+            providerNetAmount: options.providerNetAmount,
+            platformFeeAmount: options.platformFeeAmount,
+            openedTransactionDigest: options.transactionDigest,
+        },
+    });
+}
+export function recordEscrowSettlementRelease(receipt, options) {
+    const settlement = requireOpenEscrowSettlement(receipt);
+    requireSettlementBinding(settlement, options.escrowId, options.invocationId);
+    requireSafeHashReference(options.releaseProofHash, "releaseProofHash");
+    requireSafeHashReference(options.providerExecutionReceiptHash, "providerExecutionReceiptHash");
+    requireSafeHashReference(options.evidenceAttestationHash, "evidenceAttestationHash");
+    requireSafeHashReference(options.settlementReceiptHash, "settlementReceiptHash");
+    requireSafeHashReference(options.buyerFacingReceiptHash, "buyerFacingReceiptHash");
+    requireNonEmpty(options.transactionDigest, "transactionDigest");
+    const released = releaseEscrow(receipt, {
+        at: options.at,
+        verifierId: options.verifierId,
+        releaseProofHash: options.releaseProofHash,
+    });
+    return {
+        ...released,
+        escrowSettlement: {
+            ...settlement,
+            status: "released",
+            releaseProofHash: options.releaseProofHash,
+            providerExecutionReceiptHash: options.providerExecutionReceiptHash,
+            evidenceAttestationHash: options.evidenceAttestationHash,
+            settlementReceiptHash: options.settlementReceiptHash,
+            buyerFacingReceiptHash: options.buyerFacingReceiptHash,
+            settlementTransactionDigest: options.transactionDigest,
+            platformFeePaid: true,
+        },
+    };
+}
+export function recordEscrowSettlementRefund(receipt, options) {
+    const settlement = requireOpenEscrowSettlement(receipt);
+    requireSettlementBinding(settlement, options.escrowId, options.invocationId);
+    requireNonEmpty(options.reason, "reason");
+    requireSafeHashReference(options.settlementReceiptHash, "settlementReceiptHash");
+    requireSafeHashReference(options.buyerFacingReceiptHash, "buyerFacingReceiptHash");
+    requireNonEmpty(options.transactionDigest, "transactionDigest");
+    const refunded = refundEscrow(receipt, {
+        at: options.at,
+        reason: options.reason,
+    });
+    return {
+        ...refunded,
+        escrowSettlement: {
+            ...settlement,
+            status: "refunded",
+            settlementReceiptHash: options.settlementReceiptHash,
+            buyerFacingReceiptHash: options.buyerFacingReceiptHash,
+            settlementTransactionDigest: options.transactionDigest,
+            refundReason: options.reason,
+            platformFeePaid: false,
+        },
+    };
+}
 export function linkExternalPaymentState(receipt, state) {
     return {
         ...receipt,
@@ -480,13 +573,35 @@ function requireEscrowOpen(receipt, action) {
         throw new ReceiptTransitionError("INVALID_TRANSITION", `Cannot ${action} escrow from ${receipt.escrow.status}.`);
     }
 }
+function requireOpenEscrowSettlement(receipt) {
+    const settlement = receipt.escrowSettlement;
+    if (!settlement || settlement.status !== "open") {
+        throw new ReceiptTransitionError("INVALID_TRANSITION", "Escrow settlement must be open.");
+    }
+    return settlement;
+}
+function requireSettlementBinding(settlement, escrowId, invocationId) {
+    if (settlement.escrowId !== escrowId || settlement.invocationId !== invocationId) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "Escrow settlement binding does not match the receipt.");
+    }
+}
+function requireEscrowSettlementRail(value) {
+    if (!escrowSettlementRails.includes(value)) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "settlementRail must be a supported escrow settlement rail.");
+    }
+}
+function requireEscrowSettlementReleaseMode(value) {
+    if (!escrowSettlementReleaseModes.includes(value)) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "releaseMode must be a supported escrow settlement release mode.");
+    }
+}
 function requireReceiptStatus(receipt, allowed, action) {
     if (!allowed.includes(receipt.status)) {
         throw new ReceiptTransitionError("INVALID_TRANSITION", `Cannot ${action} receipt from ${receipt.status}.`);
     }
 }
 function requireNonEmpty(value, field) {
-    if (value.trim() === "") {
+    if (typeof value !== "string" || value.trim() === "") {
         throw new ReceiptInputError("FIELD_REQUIRED", `${field} is required.`);
     }
 }
@@ -497,6 +612,60 @@ function requireSafeHashReference(value, field) {
         throw new ReceiptInputError("FIELD_REQUIRED", `${field} must be a safe sha256 reference.`);
     }
 }
+function requireSafeSettlementReference(value, field) {
+    requireNonEmpty(value, field);
+    if (value.length > 160 ||
+        !/^[A-Za-z0-9._:-]+$/.test(value) ||
+        /^0x[a-f0-9]{16,}$/i.test(value) ||
+        /^(iota|sui)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{20,}$/i.test(value) ||
+        /(private prompt|review payload|bearer|access-token|signer_ref|payment credential|privateKey|mnemonic|seed|raw transaction|user signature)/i.test(value)) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} must be an opaque public reference, not raw settlement material.`);
+    }
+}
+function requireFeeSplit(gross, providerNet, platformFee) {
+    requireReceiptAmount(gross, "amount");
+    requireReceiptAmount(providerNet, "providerNetAmount");
+    requireReceiptAmount(platformFee, "platformFeeAmount");
+    if (gross.asset !== providerNet.asset || gross.asset !== platformFee.asset) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "Escrow fee split assets must match the gross amount asset.");
+    }
+    const grossAmount = parseDecimalAmount(gross.amount, "amount");
+    const providerNetAmount = parseDecimalAmount(providerNet.amount, "providerNetAmount");
+    const platformFeeAmount = parseDecimalAmount(platformFee.amount, "platformFeeAmount");
+    const scale = Math.max(grossAmount.scale, providerNetAmount.scale, platformFeeAmount.scale);
+    const grossUnits = scaleDecimal(grossAmount, scale);
+    const providerUnits = scaleDecimal(providerNetAmount, scale);
+    const platformUnits = scaleDecimal(platformFeeAmount, scale);
+    if (providerUnits + platformUnits !== grossUnits) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "Escrow fee split must equal the gross receipt amount.");
+    }
+}
+function requireReceiptAmount(value, field) {
+    if (!value || typeof value !== "object") {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} is required.`);
+    }
+    requireNonEmpty(value.amount, `${field}.amount`);
+    requireNonEmpty(value.asset, `${field}.asset`);
+}
+function parseDecimalAmount(value, field) {
+    if (value.length > 80) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} is too large.`);
+    }
+    if (!/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(value)) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} must be a non-negative decimal amount.`);
+    }
+    const [whole, fraction = ""] = value.split(".");
+    if (fraction.length > 18) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} has too many decimal places.`);
+    }
+    return {
+        units: BigInt(`${whole}${fraction}`),
+        scale: fraction.length,
+    };
+}
+function scaleDecimal(value, targetScale) {
+    return value.units * (10n ** BigInt(targetScale - value.scale));
+}
 function requireMatchingField(left, right, leftField, rightField) {
     if (left !== right) {
         throw new ReceiptInputError("FIELD_REQUIRED", `${leftField} must match ${rightField}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vallum/receipts",
-  "version": "0.0.0-prerelease",
+  "version": "0.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   }
 }