@vallum/receipts 0.0.0-prerelease

package/README.md

@@ -0,0 +1,8 @@
+# @vallum/receipts
+
+Receipt and contract workflow state machines for Vallum.
+
+This package models local receipt state transitions for sponsored agent actions,
+including escrow, pay-per-call, data-license, and service-bounty workflows. It
+does not settle payments, make policy decisions, custody funds, verify
+providers, or submit transactions.

package/dist/ap2Receipt.d.ts

@@ -0,0 +1,43 @@
+import type { LinkedReceiptState } from "./index.js";
+export type AP2ReceiptStatus = "Success" | "Error";
+export interface AP2CheckoutReceipt {
+    readonly status: AP2ReceiptStatus;
+    readonly iss: string;
+    readonly iat: number;
+    readonly reference: string;
+    readonly error?: string;
+    readonly error_description?: string;
+    readonly order_id?: string;
+}
+export interface AP2PaymentReceipt {
+    readonly status: AP2ReceiptStatus;
+    readonly iss: string;
+    readonly iat: number;
+    readonly reference: string;
+    readonly error?: string;
+    readonly error_description?: string;
+    readonly payment_id: string;
+    readonly psp_confirmation_id?: string;
+    readonly network_confirmation_id?: string;
+}
+export interface AP2ReceiptBundle {
+    readonly checkoutReceipt: AP2CheckoutReceipt;
+    readonly paymentReceipt: AP2PaymentReceipt;
+}
+export interface CreateAP2MandateReceiptStateInput extends AP2ReceiptBundle {
+    readonly manifestId: string;
+    readonly checkoutHash: string;
+    readonly paymentMandateId: string;
+    readonly disputeEvidenceReference?: string;
+}
+export interface AP2MandateReceiptState {
+    readonly linkedState: LinkedReceiptState;
+    readonly metadata: Record<string, string>;
+}
+export type AP2ReceiptErrorCode = "INVALID_AP2_RECEIPT_STATUS" | "AP2_RECEIPT_REFERENCE_MISMATCH";
+export declare class AP2ReceiptError extends Error {
+    readonly code: AP2ReceiptErrorCode;
+    constructor(code: AP2ReceiptErrorCode, message: string);
+}
+export declare function createAP2MandateReceiptState(input: CreateAP2MandateReceiptStateInput): AP2MandateReceiptState;
+export declare function redactAP2MandateMetadata(value: unknown): unknown;

package/dist/ap2Receipt.js

@@ -0,0 +1,75 @@
+export class AP2ReceiptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AP2ReceiptError";
+    }
+}
+export function createAP2MandateReceiptState(input) {
+    validateReceiptReferences(input);
+    const status = input.checkoutReceipt.status === "Success" && input.paymentReceipt.status === "Success"
+        ? "succeeded"
+        : "failed";
+    const metadata = {
+        ap2ManifestId: input.manifestId,
+        ap2CheckoutHash: input.checkoutHash,
+        ap2PaymentMandateId: input.paymentMandateId,
+        ap2CheckoutReference: input.checkoutReceipt.reference,
+        ap2PaymentReference: input.paymentReceipt.reference,
+        ap2CheckoutReceiptStatus: input.checkoutReceipt.status,
+        ap2PaymentReceiptStatus: input.paymentReceipt.status,
+        ap2PaymentId: input.paymentReceipt.payment_id,
+    };
+    if (input.disputeEvidenceReference)
+        metadata.ap2DisputeEvidenceReference = input.disputeEvidenceReference;
+    if (input.checkoutReceipt.order_id)
+        metadata.ap2OrderId = input.checkoutReceipt.order_id;
+    if (input.checkoutReceipt.error)
+        metadata.ap2CheckoutError = input.checkoutReceipt.error;
+    if (input.paymentReceipt.error)
+        metadata.ap2PaymentError = input.paymentReceipt.error;
+    if (input.paymentReceipt.psp_confirmation_id)
+        metadata.ap2PspConfirmationId = input.paymentReceipt.psp_confirmation_id;
+    if (input.paymentReceipt.network_confirmation_id) {
+        metadata.ap2NetworkConfirmationId = input.paymentReceipt.network_confirmation_id;
+    }
+    return {
+        linkedState: {
+            status,
+            referenceId: `ap2:${input.paymentReceipt.payment_id}`,
+        },
+        metadata,
+    };
+}
+function validateReceiptReferences(input) {
+    requireReceiptStatus(input.checkoutReceipt.status);
+    requireReceiptStatus(input.paymentReceipt.status);
+    if (input.checkoutReceipt.reference !== input.checkoutHash) {
+        throw new AP2ReceiptError("AP2_RECEIPT_REFERENCE_MISMATCH", "AP2 checkout receipt reference must match the checkout mandate hash.");
+    }
+    if (input.paymentReceipt.reference !== input.paymentMandateId) {
+        throw new AP2ReceiptError("AP2_RECEIPT_REFERENCE_MISMATCH", "AP2 payment receipt reference must match the payment mandate id.");
+    }
+}
+function requireReceiptStatus(status) {
+    if (status !== "Success" && status !== "Error") {
+        throw new AP2ReceiptError("INVALID_AP2_RECEIPT_STATUS", "AP2 receipt status is unsupported.");
+    }
+}
+export function redactAP2MandateMetadata(value) {
+    if (Array.isArray(value))
+        return value.map((item) => redactAP2MandateMetadata(item));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        isSensitiveAP2MetadataKey(key) ? "[REDACTED]" : redactAP2MandateMetadata(child),
+    ]));
+}
+function isSensitiveAP2MetadataKey(key) {
+    return /^(checkout_jwt|payment_instrument|risk_data|.*authorization.*|.*credential.*|.*signature.*|.*token.*|.*card.*|.*bank.*)$/i.test(key);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+export * from "./ap2Receipt.js";
+export type ReceiptStatus = "attempted" | "denied" | "approved" | "sponsored" | "submitted" | "active" | "renewed" | "canceled" | "completed" | "released" | "refunded" | "disputed" | "revoked" | "failed";
+export type EscrowStatus = "open" | "released" | "refunded" | "expired";
+export interface ReceiptAmount {
+    readonly amount: string;
+    readonly asset: string;
+}
+export interface EscrowReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly escrow: EscrowState;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly evidenceHash?: string;
+    readonly releaseProofHash?: string;
+    readonly refundReason?: string;
+    readonly events: readonly ReceiptEvent[];
+    readonly externalPayment?: LinkedReceiptState;
+    readonly iotaReceipt?: LinkedReceiptState;
+}
+export interface PayPerCallReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly toolName: string;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly resultHash?: string;
+    readonly failureReason?: string;
+    readonly events: readonly ReceiptEvent[];
+}
+export interface DataLicenseReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly licenseeId: string;
+    readonly datasetId: string;
+    readonly termsHash: string;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly accessProofHash?: string;
+    readonly expiresAt?: string;
+    readonly failureReason?: string;
+    readonly revocationReason?: string;
+    readonly events: readonly ReceiptEvent[];
+}
+export interface ServiceBountyReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly requesterId: string;
+    readonly providerId: string;
+    readonly bountyId: string;
+    readonly deliverableHash: string;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly completionProofHash?: string;
+    readonly releaseProofHash?: string;
+    readonly failureReason?: string;
+    readonly events: readonly ReceiptEvent[];
+}
+export interface ReputationReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly issuerId: string;
+    readonly subjectId: string;
+    readonly interactionId: string;
+    readonly criteriaHash: string;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly score?: number;
+    readonly evidenceHash?: string;
+    readonly attestationHash?: string;
+    readonly failureReason?: string;
+    readonly events: readonly ReceiptEvent[];
+}
+export interface SubscriptionReceipt {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly subscriberId: string;
+    readonly providerId: string;
+    readonly planId: string;
+    readonly termsHash: string;
+    readonly periodStart: string;
+    readonly periodEnd: string;
+    readonly renewalCount: number;
+    readonly status: ReceiptStatus;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+    readonly renewalSponsorshipId?: string;
+    readonly renewalTransactionDigest?: string;
+    readonly activationProofHash?: string;
+    readonly renewalProofHash?: string;
+    readonly cancellationReason?: string;
+    readonly failureReason?: string;
+    readonly events: readonly ReceiptEvent[];
+}
+export interface EscrowState {
+    readonly status: EscrowStatus;
+    readonly providerId: string;
+    readonly verifierId: string;
+}
+export interface LinkedReceiptState {
+    readonly status: "pending" | "succeeded" | "failed";
+    readonly referenceId: string;
+}
+export interface ReceiptEvent {
+    readonly type: "escrow_created" | "pay_per_call_created" | "data_license_created" | "service_bounty_created" | "reputation_receipt_created" | "subscription_created" | "approved" | "denied" | "sponsored" | "submitted" | "activated" | "renewed" | "canceled" | "completed" | "access_granted" | "access_revoked" | "released" | "refunded" | "expired" | "failed";
+    readonly at: string;
+    readonly reason?: string;
+}
+export interface CreateEscrowReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly verifierId: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface CreatePayPerCallReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly toolName: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface CreateDataLicenseReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly licenseeId: string;
+    readonly datasetId: string;
+    readonly termsHash: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface CreateServiceBountyReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly requesterId: string;
+    readonly providerId: string;
+    readonly bountyId: string;
+    readonly deliverableHash: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface CreateReputationReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly issuerId: string;
+    readonly subjectId: string;
+    readonly interactionId: string;
+    readonly criteriaHash: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface CreateSubscriptionReceiptInput {
+    readonly receiptId: string;
+    readonly manifestId: string;
+    readonly idempotencyKey: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly subscriberId: string;
+    readonly providerId: string;
+    readonly planId: string;
+    readonly termsHash: string;
+    readonly periodStart: string;
+    readonly periodEnd: string;
+    readonly amount: ReceiptAmount;
+    readonly createdAt: Date;
+}
+export interface TransitionOptions {
+    readonly at: Date;
+}
+export declare class ReceiptTransitionError extends Error {
+    readonly code: "INVALID_TRANSITION" | "UNAUTHORIZED_VERIFIER";
+    constructor(code: "INVALID_TRANSITION" | "UNAUTHORIZED_VERIFIER", message: string);
+}
+export declare class ReceiptInputError extends Error {
+    readonly code: "FIELD_REQUIRED";
+    constructor(code: "FIELD_REQUIRED", message: string);
+}
+export declare function createEscrowReceipt(input: CreateEscrowReceiptInput): EscrowReceipt;
+export declare function createPayPerCallReceipt(input: CreatePayPerCallReceiptInput): PayPerCallReceipt;
+export declare function createDataLicenseReceipt(input: CreateDataLicenseReceiptInput): DataLicenseReceipt;
+export declare function createServiceBountyReceipt(input: CreateServiceBountyReceiptInput): ServiceBountyReceipt;
+export declare function createReputationReceipt(input: CreateReputationReceiptInput): ReputationReceipt;
+export declare function createSubscriptionReceipt(input: CreateSubscriptionReceiptInput): SubscriptionReceipt;
+export declare function approveReceipt(receipt: EscrowReceipt, options: TransitionOptions): EscrowReceipt;
+export declare function approvePayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions): PayPerCallReceipt;
+export declare function approveDataLicenseReceipt(receipt: DataLicenseReceipt, options: TransitionOptions): DataLicenseReceipt;
+export declare function approveServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions): ServiceBountyReceipt;
+export declare function approveReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions): ReputationReceipt;
+export declare function approveSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions): SubscriptionReceipt;
+export declare function denyReceipt(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): EscrowReceipt;
+export declare function denyPayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): PayPerCallReceipt;
+export declare function denyDataLicenseReceipt(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): DataLicenseReceipt;
+export declare function denyServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): ServiceBountyReceipt;
+export declare function denyReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): ReputationReceipt;
+export declare function denySubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): SubscriptionReceipt;
+export declare function sponsorReceipt(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): EscrowReceipt;
+export declare function sponsorPayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): PayPerCallReceipt;
+export declare function sponsorDataLicenseReceipt(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): DataLicenseReceipt;
+export declare function sponsorServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): ServiceBountyReceipt;
+export declare function sponsorReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): ReputationReceipt;
+export declare function sponsorSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly sponsorshipId: string;
+}): SubscriptionReceipt;
+export declare function submitReceipt(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): EscrowReceipt;
+export declare function submitPayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): PayPerCallReceipt;
+export declare function submitDataLicenseReceipt(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): DataLicenseReceipt;
+export declare function submitServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): ServiceBountyReceipt;
+export declare function submitReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): ReputationReceipt;
+export declare function submitSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly transactionDigest: string;
+}): SubscriptionReceipt;
+export declare function completeEscrow(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly evidenceHash: string;
+}): EscrowReceipt;
+export declare function completePayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions & {
+    readonly resultHash: string;
+}): PayPerCallReceipt;
+export declare function failPayPerCallReceipt(receipt: PayPerCallReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): PayPerCallReceipt;
+export declare function grantDataLicenseAccess(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly accessProofHash: string;
+    readonly expiresAt?: string;
+}): DataLicenseReceipt;
+export declare function failDataLicenseReceipt(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): DataLicenseReceipt;
+export declare function completeServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly completionProofHash: string;
+}): ServiceBountyReceipt;
+export declare function releaseServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly releaseProofHash: string;
+}): ServiceBountyReceipt;
+export declare function failServiceBountyReceipt(receipt: ServiceBountyReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): ServiceBountyReceipt;
+export declare function completeReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions & {
+    readonly score: number;
+    readonly evidenceHash: string;
+    readonly attestationHash: string;
+}): ReputationReceipt;
+export declare function failReputationReceipt(receipt: ReputationReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): ReputationReceipt;
+export declare function activateSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly activationProofHash: string;
+}): SubscriptionReceipt;
+export declare function renewSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly periodEnd: string;
+    readonly renewalProofHash: string;
+    readonly sponsorshipId?: string;
+    readonly transactionDigest?: string;
+}): SubscriptionReceipt;
+export declare function cancelSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): SubscriptionReceipt;
+export declare function failSubscriptionReceipt(receipt: SubscriptionReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): SubscriptionReceipt;
+export declare function revokeDataLicenseAccess(receipt: DataLicenseReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): DataLicenseReceipt;
+export declare function releaseEscrow(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly verifierId: string;
+    readonly releaseProofHash: string;
+}): EscrowReceipt;
+export declare function refundEscrow(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): EscrowReceipt;
+export declare function expireEscrow(receipt: EscrowReceipt, options: TransitionOptions & {
+    readonly reason: string;
+}): 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

@@ -0,0 +1,612 @@
+export * from "./ap2Receipt.js";
+export class ReceiptTransitionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ReceiptTransitionError";
+    }
+}
+export class ReceiptInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ReceiptInputError";
+    }
+}
+export function createEscrowReceipt(input) {
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        status: "attempted",
+        amount: input.amount,
+        escrow: {
+            status: "open",
+            providerId: input.providerId,
+            verifierId: input.verifierId,
+        },
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "escrow_created", at }],
+    };
+}
+export function createPayPerCallReceipt(input) {
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        providerId: input.providerId,
+        toolName: input.toolName,
+        status: "attempted",
+        amount: input.amount,
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "pay_per_call_created", at }],
+    };
+}
+export function createDataLicenseReceipt(input) {
+    requireNonEmpty(input.providerId, "providerId");
+    requireNonEmpty(input.licenseeId, "licenseeId");
+    requireNonEmpty(input.datasetId, "datasetId");
+    requireNonEmpty(input.termsHash, "termsHash");
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        providerId: input.providerId,
+        licenseeId: input.licenseeId,
+        datasetId: input.datasetId,
+        termsHash: input.termsHash,
+        status: "attempted",
+        amount: input.amount,
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "data_license_created", at }],
+    };
+}
+export function createServiceBountyReceipt(input) {
+    requireNonEmpty(input.requesterId, "requesterId");
+    requireNonEmpty(input.providerId, "providerId");
+    requireNonEmpty(input.bountyId, "bountyId");
+    requireNonEmpty(input.deliverableHash, "deliverableHash");
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        requesterId: input.requesterId,
+        providerId: input.providerId,
+        bountyId: input.bountyId,
+        deliverableHash: input.deliverableHash,
+        status: "attempted",
+        amount: input.amount,
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "service_bounty_created", at }],
+    };
+}
+export function createReputationReceipt(input) {
+    requireNonEmpty(input.issuerId, "issuerId");
+    requireNonEmpty(input.subjectId, "subjectId");
+    requireNonEmpty(input.interactionId, "interactionId");
+    requireNonEmpty(input.criteriaHash, "criteriaHash");
+    requireMatchingField(input.issuerId, input.agentId, "issuerId", "agentId");
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        issuerId: input.issuerId,
+        subjectId: input.subjectId,
+        interactionId: input.interactionId,
+        criteriaHash: input.criteriaHash,
+        status: "attempted",
+        amount: input.amount,
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "reputation_receipt_created", at }],
+    };
+}
+export function createSubscriptionReceipt(input) {
+    requireNonEmpty(input.subscriberId, "subscriberId");
+    requireNonEmpty(input.providerId, "providerId");
+    requireNonEmpty(input.planId, "planId");
+    requireSafeHashReference(input.termsHash, "termsHash");
+    requireNonEmpty(input.periodStart, "periodStart");
+    requireNonEmpty(input.periodEnd, "periodEnd");
+    requireMatchingField(input.subscriberId, input.agentId, "subscriberId", "agentId");
+    requirePeriodAfter(input.periodStart, input.periodEnd, "periodEnd");
+    const at = input.createdAt.toISOString();
+    return {
+        receiptId: input.receiptId,
+        manifestId: input.manifestId,
+        idempotencyKey: input.idempotencyKey,
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        subscriberId: input.subscriberId,
+        providerId: input.providerId,
+        planId: input.planId,
+        termsHash: input.termsHash,
+        periodStart: input.periodStart,
+        periodEnd: input.periodEnd,
+        renewalCount: 0,
+        status: "attempted",
+        amount: input.amount,
+        createdAt: at,
+        updatedAt: at,
+        events: [{ type: "subscription_created", at }],
+    };
+}
+export function approveReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function approvePayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withPayPerCallReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function approveDataLicenseReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withDataLicenseReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function approveServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withServiceBountyReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function approveReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withReputationReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function approveSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "approve");
+    return withSubscriptionReceiptEvent(receipt, "approved", options.at, { status: "approved" });
+}
+export function denyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+    }, options.reason);
+}
+export function denyPayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withPayPerCallReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function denyDataLicenseReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withDataLicenseReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function denyServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withServiceBountyReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function denyReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withReputationReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function denySubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted"], "deny");
+    return withSubscriptionReceiptEvent(receipt, "denied", options.at, {
+        status: "denied",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function sponsorReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function sponsorPayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withPayPerCallReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function sponsorDataLicenseReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withDataLicenseReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function sponsorServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withServiceBountyReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function sponsorReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withReputationReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function sponsorSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["approved"], "sponsor");
+    return withSubscriptionReceiptEvent(receipt, "sponsored", options.at, {
+        status: "sponsored",
+        sponsorshipId: options.sponsorshipId,
+    });
+}
+export function submitReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function submitPayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withPayPerCallReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function submitDataLicenseReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withDataLicenseReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function submitServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withServiceBountyReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function submitReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withReputationReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function submitSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["sponsored"], "submit");
+    return withSubscriptionReceiptEvent(receipt, "submitted", options.at, {
+        status: "submitted",
+        transactionDigest: options.transactionDigest,
+    });
+}
+export function completeEscrow(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "complete");
+    requireEscrowOpen(receipt, "complete");
+    return withReceiptEvent(receipt, "completed", options.at, {
+        status: "completed",
+        evidenceHash: options.evidenceHash,
+    });
+}
+export function completePayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "complete");
+    return withPayPerCallReceiptEvent(receipt, "completed", options.at, {
+        status: "completed",
+        resultHash: options.resultHash,
+    });
+}
+export function failPayPerCallReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted"], "fail");
+    return withPayPerCallReceiptEvent(receipt, "failed", options.at, {
+        status: "failed",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function grantDataLicenseAccess(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "grant access");
+    requireNonEmpty(options.accessProofHash, "accessProofHash");
+    return withDataLicenseReceiptEvent(receipt, "access_granted", options.at, {
+        status: "completed",
+        accessProofHash: options.accessProofHash,
+        ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+    });
+}
+export function failDataLicenseReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted"], "fail");
+    return withDataLicenseReceiptEvent(receipt, "failed", options.at, {
+        status: "failed",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function completeServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "complete");
+    requireNonEmpty(options.completionProofHash, "completionProofHash");
+    return withServiceBountyReceiptEvent(receipt, "completed", options.at, {
+        status: "completed",
+        completionProofHash: options.completionProofHash,
+    });
+}
+export function releaseServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["completed"], "release");
+    requireNonEmpty(options.releaseProofHash, "releaseProofHash");
+    return withServiceBountyReceiptEvent(receipt, "released", options.at, {
+        status: "released",
+        releaseProofHash: options.releaseProofHash,
+    });
+}
+export function failServiceBountyReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted", "completed"], "fail");
+    return withServiceBountyReceiptEvent(receipt, "failed", options.at, {
+        status: "failed",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function completeReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "complete");
+    requireScore(options.score);
+    requireNonEmpty(options.evidenceHash, "evidenceHash");
+    requireNonEmpty(options.attestationHash, "attestationHash");
+    return withReputationReceiptEvent(receipt, "completed", options.at, {
+        status: "completed",
+        score: options.score,
+        evidenceHash: options.evidenceHash,
+        attestationHash: options.attestationHash,
+    });
+}
+export function failReputationReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted"], "fail");
+    return withReputationReceiptEvent(receipt, "failed", options.at, {
+        status: "failed",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function activateSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["submitted"], "activate");
+    requireSafeHashReference(options.activationProofHash, "activationProofHash");
+    return withSubscriptionReceiptEvent(receipt, "activated", options.at, {
+        status: "active",
+        activationProofHash: options.activationProofHash,
+    });
+}
+export function renewSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["active", "renewed"], "renew");
+    requireNonEmpty(options.periodEnd, "periodEnd");
+    requireSafeHashReference(options.renewalProofHash, "renewalProofHash");
+    if (options.sponsorshipId !== undefined)
+        requireNonEmpty(options.sponsorshipId, "sponsorshipId");
+    if (options.transactionDigest !== undefined)
+        requireNonEmpty(options.transactionDigest, "transactionDigest");
+    requirePeriodAfter(receipt.periodEnd, options.periodEnd, "periodEnd");
+    return withSubscriptionReceiptEvent(receipt, "renewed", options.at, {
+        status: "renewed",
+        periodEnd: options.periodEnd,
+        renewalCount: receipt.renewalCount + 1,
+        renewalProofHash: options.renewalProofHash,
+        ...(options.sponsorshipId ? { renewalSponsorshipId: options.sponsorshipId } : {}),
+        ...(options.transactionDigest ? { renewalTransactionDigest: options.transactionDigest } : {}),
+    });
+}
+export function cancelSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["active", "renewed"], "cancel");
+    requireNonEmpty(options.reason, "reason");
+    return withSubscriptionReceiptEvent(receipt, "canceled", options.at, {
+        status: "canceled",
+        cancellationReason: options.reason,
+    }, options.reason);
+}
+export function failSubscriptionReceipt(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted", "active", "renewed"], "fail");
+    return withSubscriptionReceiptEvent(receipt, "failed", options.at, {
+        status: "failed",
+        failureReason: options.reason,
+    }, options.reason);
+}
+export function revokeDataLicenseAccess(receipt, options) {
+    requireReceiptStatus(receipt, ["completed"], "revoke access");
+    return withDataLicenseReceiptEvent(receipt, "access_revoked", options.at, {
+        status: "revoked",
+        revocationReason: options.reason,
+    }, options.reason);
+}
+export function releaseEscrow(receipt, options) {
+    requireVerifier(receipt, options.verifierId);
+    requireReceiptStatus(receipt, ["completed"], "release");
+    requireEscrowOpen(receipt, "release");
+    return withReceiptEvent(receipt, "released", options.at, {
+        status: "released",
+        escrow: { ...receipt.escrow, status: "released" },
+        releaseProofHash: options.releaseProofHash,
+    });
+}
+export function refundEscrow(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted", "completed"], "refund");
+    requireEscrowOpen(receipt, "refund");
+    return withReceiptEvent(receipt, "refunded", options.at, {
+        status: "refunded",
+        escrow: { ...receipt.escrow, status: "refunded" },
+        refundReason: options.reason,
+    }, options.reason);
+}
+export function expireEscrow(receipt, options) {
+    requireReceiptStatus(receipt, ["attempted", "approved", "sponsored", "submitted", "completed"], "expire");
+    requireEscrowOpen(receipt, "expire");
+    return withReceiptEvent(receipt, "expired", options.at, {
+        status: "refunded",
+        escrow: { ...receipt.escrow, status: "expired" },
+        refundReason: options.reason,
+    }, options.reason);
+}
+export function linkExternalPaymentState(receipt, state) {
+    return {
+        ...receipt,
+        externalPayment: state,
+    };
+}
+export function linkIotaReceiptState(receipt, state) {
+    return {
+        ...receipt,
+        iotaReceipt: state,
+    };
+}
+export * from "./x402Receipt.js";
+function requireVerifier(receipt, verifierId) {
+    if (receipt.escrow.verifierId !== verifierId) {
+        throw new ReceiptTransitionError("UNAUTHORIZED_VERIFIER", "Only the configured verifier can release escrow.");
+    }
+}
+function requireEscrowOpen(receipt, action) {
+    if (receipt.escrow.status !== "open") {
+        throw new ReceiptTransitionError("INVALID_TRANSITION", `Cannot ${action} escrow from ${receipt.escrow.status}.`);
+    }
+}
+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() === "") {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} is required.`);
+    }
+}
+function requireSafeHashReference(value, field) {
+    requireNonEmpty(value, field);
+    if (!/^sha256:[A-Za-z0-9._:-]+$/.test(value)
+        || /(private prompt|review payload|bearer|access-token|signer_ref|payment credential|privateKey|mnemonic|seed)/i.test(value)) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} must be a safe sha256 reference.`);
+    }
+}
+function requireMatchingField(left, right, leftField, rightField) {
+    if (left !== right) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${leftField} must match ${rightField}.`);
+    }
+}
+function requirePeriodAfter(start, end, field) {
+    const startTime = Date.parse(start);
+    const endTime = Date.parse(end);
+    if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) {
+        throw new ReceiptInputError("FIELD_REQUIRED", `${field} must be after the current period end.`);
+    }
+}
+function requireScore(score) {
+    if (!Number.isInteger(score) || score < 1 || score > 5) {
+        throw new ReceiptInputError("FIELD_REQUIRED", "score must be an integer between 1 and 5.");
+    }
+}
+function withReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}
+function withPayPerCallReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}
+function withDataLicenseReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}
+function withServiceBountyReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}
+function withReputationReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}
+function withSubscriptionReceiptEvent(receipt, eventType, at, patch, reason) {
+    const timestamp = at.toISOString();
+    return {
+        ...receipt,
+        ...patch,
+        updatedAt: timestamp,
+        events: [
+            ...receipt.events,
+            {
+                type: eventType,
+                at: timestamp,
+                ...(reason ? { reason } : {}),
+            },
+        ],
+    };
+}

package/dist/x402Receipt.d.ts

@@ -0,0 +1,31 @@
+import type { LinkedReceiptState } from "./index.js";
+export interface X402VerifyEvidence {
+    readonly isValid: boolean;
+    readonly invalidReason?: string;
+    readonly invalidMessage?: string;
+    readonly payer?: string;
+    readonly extensions?: Record<string, unknown>;
+    readonly extra?: Record<string, unknown>;
+}
+export interface X402SettleEvidence {
+    readonly success: boolean;
+    readonly errorReason?: string;
+    readonly errorMessage?: string;
+    readonly payer?: string;
+    readonly transaction: string;
+    readonly network: string;
+    readonly amount?: string;
+    readonly extensions?: Record<string, unknown>;
+    readonly extra?: Record<string, unknown>;
+}
+export interface CreateX402ExternalPaymentReceiptStateInput {
+    readonly paymentId: string;
+    readonly verify: X402VerifyEvidence;
+    readonly settle?: X402SettleEvidence;
+}
+export interface X402ExternalPaymentReceiptState {
+    readonly linkedState: LinkedReceiptState;
+    readonly metadata: Record<string, string>;
+}
+export declare function createX402ExternalPaymentReceiptState(input: CreateX402ExternalPaymentReceiptStateInput): X402ExternalPaymentReceiptState;
+export declare function redactX402PaymentMetadata(value: unknown): unknown;

package/dist/x402Receipt.js

@@ -0,0 +1,48 @@
+export function createX402ExternalPaymentReceiptState(input) {
+    const settlementStatus = settlementStatusFor(input.verify, input.settle);
+    const metadata = {
+        x402PaymentId: input.paymentId,
+        x402VerifyStatus: input.verify.isValid ? "valid" : "invalid",
+        x402SettlementStatus: settlementStatus,
+    };
+    if (input.verify.invalidReason)
+        metadata.x402VerifyInvalidReason = input.verify.invalidReason;
+    if (input.settle?.errorReason)
+        metadata.x402SettleErrorReason = input.settle.errorReason;
+    if (input.settle?.network)
+        metadata.x402Network = input.settle.network;
+    if (input.settle?.transaction)
+        metadata.x402Transaction = input.settle.transaction;
+    if (input.settle?.amount)
+        metadata.x402Amount = input.settle.amount;
+    return {
+        linkedState: {
+            status: settlementStatus === "succeeded" ? "succeeded" : settlementStatus === "failed" ? "failed" : "pending",
+            referenceId: `x402:${input.paymentId}`,
+        },
+        metadata,
+    };
+}
+export function redactX402PaymentMetadata(value) {
+    if (Array.isArray(value))
+        return value.map((item) => redactX402PaymentMetadata(item));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        isSensitiveX402MetadataKey(key) ? "[REDACTED]" : redactX402PaymentMetadata(child),
+    ]));
+}
+function settlementStatusFor(verify, settle) {
+    if (!verify.isValid)
+        return "failed";
+    if (!settle)
+        return "pending";
+    return settle.success ? "succeeded" : "failed";
+}
+function isSensitiveX402MetadataKey(key) {
+    return /^(payer.*|paymentPayload|payload|paymentCredential|.*signature.*|.*authorization.*|.*credential.*)$/i.test(key);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vallum/receipts",
+  "version": "0.0.0-prerelease",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "license": "Apache-2.0",
+  "description": "Receipt and escrow state machine for Vallum.",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}