veilreceipt-sdk 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# @veilreceipt/sdk
+
+TypeScript SDK for integrating **VeilReceipt** — private, ZK-powered payments on Aleo — into any application.
+
+## Installation
+
+```bash
+npm install @veilreceipt/sdk
+```
+
+## Quick Start
+
+```ts
+import { VeilReceipt } from '@veilreceipt/sdk';
+
+const veil = new VeilReceipt({
+  baseUrl: 'https://api.veilreceipt.com',
+  apiKey: 'vr_live_...',
+});
+
+// Resolve a payment link
+const link = await veil.resolvePaymentLink('a1b2c3d4');
+console.log(link.label, link.amount, link.currency);
+
+// Get a payment session
+const session = await veil.getPaymentSession('sess_abc123');
+
+// Verify a purchase on-chain
+const result = await veil.verifyPurchase('field1234...');
+console.log(result.on_chain_verified);
+```
+
+## Features
+
+- **Payment Sessions** — Create and complete checkout sessions
+- **Payment Links** — Shareable one-time, recurring, or open-amount payment links
+- **Products** — CRUD operations for merchant product catalog
+- **Receipts** — Store and retrieve ZK receipt metadata
+- **Escrow** — Built-in escrow with buyer protection
+- **On-chain Verification** — Verify purchases on Aleo testnet
+- **Delegated Proving** — Submit transitions for server-side proof generation
+- **API Keys & Webhooks** — Full merchant integration management
+
+## Payment Links
+
+```ts
+// Create a payment link (merchant auth required)
+const link = await veil.createPaymentLink({
+  link_hash: 'abc123...',
+  amount: 5_000_000, // microcredits
+  currency: 'credits',
+  link_type: 'recurring',
+  label: 'Monthly Subscription',
+  description: 'Pay monthly',
+  tx_id: 'at1...',
+});
+
+// Resolve by hash (public, no auth)
+const publicLink = await veil.resolvePaymentLink('abc123...');
+
+// Record fulfillment
+await veil.fulfillPaymentLink(link.id, {
+  link_id: link.id,
+  purchase_commitment: 'field...',
+  buyer_address_hash: 'hash...',
+  amount: 5_000_000,
+  tx_id: 'at1...',
+  payment_mode: 'private',
+});
+
+// Close a link
+await veil.closePaymentLink(link.id);
+```
+
+## Escrow
+
+```ts
+// Create escrow
+const escrow = await veil.createEscrow({
+  purchaseCommitment: 'field...',
+  buyerAddress: 'aleo1...',
+  merchantAddress: 'aleo1...',
+  total: 10_000_000,
+  txId: 'at1...',
+});
+
+// Complete or refund
+await veil.resolveEscrow(escrow.escrow.id, 'complete', 'at1...');
+```
+
+## Webhooks
+
+```ts
+// Register a webhook
+const wh = await veil.createWebhook(
+  'https://yourserver.com/webhooks/veil',
+  ['payment.confirmed', 'link.fulfilled', 'escrow.resolved']
+);
+console.log('Signing secret:', wh.signing_secret);
+```
+
+## Error Handling
+
+```ts
+import { VeilReceipt, VeilReceiptError } from '@veilreceipt/sdk';
+
+try {
+  await veil.getPaymentSession('invalid');
+} catch (err) {
+  if (err instanceof VeilReceiptError) {
+    console.error(`API Error ${err.status}: ${err.message}`);
+  }
+}
+```
+
+## Configuration
+
+| Option    | Type     | Default | Description                          |
+| --------- | -------- | ------- | ------------------------------------ |
+| `baseUrl` | `string` | —       | VeilReceipt API base URL (required)  |
+| `apiKey`  | `string` | —       | API key from merchant dashboard      |
+| `token`   | `string` | —       | JWT token for session auth           |
+| `timeout` | `number` | 30000   | Request timeout in milliseconds      |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,366 @@
+type AleoAddress = string;
+type AleoField = string;
+type AleoTransactionId = string;
+interface PaymentSession {
+    id: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    description: string;
+    status: string;
+    merchant_address: AleoAddress;
+    payment_mode: string | null;
+    tx_id: string | null;
+    redirect_url: string | null;
+    cancel_url: string | null;
+    expires_at: string;
+}
+interface CompleteSessionParams {
+    purchase_commitment: string;
+    tx_id: string;
+    payment_mode: 'private' | 'public' | 'escrow';
+    buyer_address?: string;
+}
+interface SessionResult {
+    success: boolean;
+    session_id: string;
+    redirect_url: string | null;
+}
+interface PaymentLink {
+    id: string;
+    merchant_id: string;
+    merchant_address: AleoAddress;
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    is_active: boolean;
+    total_contributions: number;
+    total_collected: number;
+    tx_id: string;
+    created_at: string;
+}
+interface PaymentLinkPublic {
+    id: string;
+    merchant_address: AleoAddress;
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    is_active: boolean;
+    total_contributions: number;
+}
+interface CreatePaymentLinkParams {
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    tx_id: string;
+}
+interface FulfillLinkParams {
+    link_id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    amount: number;
+    tx_id: string;
+    payment_mode: 'private' | 'escrow';
+}
+interface Product {
+    id: string;
+    merchant_id: string;
+    merchant_address: AleoAddress;
+    name: string;
+    description: string;
+    price: number;
+    price_type: 'credits' | 'usdcx' | 'usad';
+    sku: string;
+    image_url?: string;
+    category?: string;
+    in_stock: boolean;
+    created_at: string;
+}
+interface CreateProductParams {
+    name: string;
+    description: string;
+    price: number;
+    price_type: 'credits' | 'usdcx' | 'usad';
+    sku: string;
+    imageUrl?: string;
+    category?: string;
+}
+interface Receipt {
+    id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    merchant_address_hash: string;
+    total: number;
+    token_type: number;
+    cart_commitment: string;
+    tx_id: string;
+    status: string;
+    created_at: string;
+}
+interface Escrow {
+    id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    merchant_address_hash: string;
+    total: number;
+    status: 'active' | 'completed' | 'refunded';
+    escrow_tx_id: string;
+    resolve_tx_id: string;
+    created_block: number;
+    created_at: string;
+}
+interface StoreReceiptParams {
+    txId: string;
+    onChainTxId?: string;
+    merchantAddress: string;
+    buyerAddress: string;
+    total: number;
+    tokenType?: 'credits' | 'usdcx' | 'usad';
+    purchaseType?: 'private' | 'public' | 'escrow';
+    status?: 'confirmed' | 'escrowed';
+    cartCommitment?: string;
+    timestamp?: number;
+    blockHeight?: number;
+    items?: {
+        sku: string;
+        quantity: number;
+        price: number;
+    }[];
+}
+interface VerificationResult {
+    commitment: string;
+    on_chain_verified: boolean;
+    receipt: {
+        total: number;
+        token_type: number;
+        status: string;
+        tx_id: string;
+    } | null;
+}
+interface ApiKey {
+    id: string;
+    prefix: string;
+    label: string;
+    permissions: string[];
+    is_active: boolean;
+    last_used_at: string | null;
+    created_at: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    is_active: boolean;
+    failure_count: number;
+    created_at: string;
+}
+interface ProvingHealth {
+    dps_configured: boolean;
+    sponsor_configured: boolean;
+    program_id: string;
+    network: string;
+}
+interface DelegateProofParams {
+    transition: string;
+    inputs: string[];
+    fee_record?: string;
+}
+interface TxStatus {
+    txId: string;
+    status: 'confirmed' | 'pending' | 'failed' | 'not_found';
+    blockHeight?: number;
+}
+interface VeilReceiptConfig {
+    /** Base URL of the VeilReceipt backend API */
+    baseUrl: string;
+    /** API key for authentication (from merchant dashboard) */
+    apiKey?: string;
+    /** JWT token for session-based auth */
+    token?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
+declare class VeilReceiptError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+/**
+ * VeilReceipt SDK Client
+ *
+ * ```ts
+ * import { VeilReceipt } from '@veilreceipt/sdk';
+ *
+ * const veil = new VeilReceipt({
+ *   baseUrl: 'https://api.veilreceipt.com',
+ *   apiKey: 'vr_live_...',
+ * });
+ *
+ * // Get a payment session
+ * const session = await veil.getPaymentSession('sess_abc123');
+ *
+ * // Resolve a payment link
+ * const link = await veil.resolvePaymentLink('a1b2c3d4');
+ * ```
+ */
+declare class VeilReceipt {
+    private baseUrl;
+    private apiKey?;
+    private token?;
+    private timeout;
+    constructor(config: VeilReceiptConfig);
+    /** Update the auth token (e.g. after login) */
+    setToken(token: string | null): void;
+    /** Update the API key */
+    setApiKey(key: string | null): void;
+    private request;
+    /** Check API health */
+    health(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+    /** Get details of a payment session */
+    getPaymentSession(sessionId: string): Promise<PaymentSession>;
+    /** Complete a payment session after on-chain tx */
+    completePaymentSession(sessionId: string, params: CompleteSessionParams): Promise<SessionResult>;
+    /** Create a new payment link (requires merchant auth) */
+    createPaymentLink(params: CreatePaymentLinkParams): Promise<PaymentLink>;
+    /** List payment links for the authenticated merchant */
+    listPaymentLinks(): Promise<PaymentLink[]>;
+    /** Resolve a payment link by its public hash (no auth required) */
+    resolvePaymentLink(hash: string): Promise<PaymentLinkPublic>;
+    /** Get a specific payment link by ID */
+    getPaymentLink(id: string): Promise<PaymentLink>;
+    /** Record a link fulfillment after on-chain tx */
+    fulfillPaymentLink(id: string, params: FulfillLinkParams): Promise<{
+        success: boolean;
+    }>;
+    /** Close/deactivate a payment link (merchant only) */
+    closePaymentLink(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** List products, optionally filtered */
+    getProducts(filters?: {
+        merchant?: string;
+        category?: string;
+        inStock?: boolean;
+    }): Promise<{
+        products: Product[];
+    }>;
+    /** Get a single product by ID */
+    getProduct(id: string): Promise<{
+        product: Product;
+    }>;
+    /** Create a product (merchant auth required) */
+    createProduct(params: CreateProductParams): Promise<{
+        product: Product;
+    }>;
+    /** Update a product (merchant auth required) */
+    updateProduct(id: string, params: Partial<{
+        name: string;
+        description: string;
+        price: number;
+        imageUrl: string;
+        category: string;
+        inStock: boolean;
+    }>): Promise<{
+        product: Product;
+    }>;
+    /** Delete a product (merchant auth required) */
+    deleteProduct(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Store receipt metadata */
+    storeReceipt(params: StoreReceiptParams): Promise<{
+        receipt: Receipt;
+    }>;
+    /** Get all receipts for authenticated user */
+    getReceipts(): Promise<{
+        receipts: Receipt[];
+        count: number;
+    }>;
+    /** Get receipts by buyer address */
+    getReceiptsByBuyer(address: string): Promise<{
+        receipts: Receipt[];
+        count: number;
+    }>;
+    /** Get a receipt by transaction ID */
+    getReceiptByTxId(txId: string): Promise<{
+        receipt: Receipt;
+    }>;
+    /** Create an escrow record */
+    createEscrow(params: {
+        purchaseCommitment: string;
+        buyerAddress: string;
+        merchantAddress: string;
+        total: number;
+        txId: string;
+    }): Promise<{
+        escrow: Escrow;
+    }>;
+    /** Resolve an escrow (complete or refund) */
+    resolveEscrow(id: string, action: 'complete' | 'refund', txId: string): Promise<{
+        escrow: Escrow;
+    }>;
+    /** Get escrows for authenticated user */
+    getMyEscrows(): Promise<{
+        escrows: Escrow[];
+    }>;
+    /** Verify a purchase commitment on-chain */
+    verifyPurchase(commitment: string): Promise<VerificationResult>;
+    /** Check transaction status on-chain */
+    getTransactionStatus(txId: string): Promise<TxStatus>;
+    /** Get current chain block height */
+    getChainHeight(): Promise<{
+        height: number;
+    }>;
+    /** Create an API key */
+    createApiKey(label: string, permissions: string[]): Promise<ApiKey & {
+        key: string;
+        warning: string;
+    }>;
+    /** List API keys */
+    listApiKeys(): Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Revoke an API key */
+    revokeApiKey(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Create a webhook */
+    createWebhook(url: string, events: string[]): Promise<Webhook & {
+        signing_secret: string;
+        warning: string;
+    }>;
+    /** List webhooks */
+    listWebhooks(): Promise<{
+        webhooks: Webhook[];
+    }>;
+    /** Delete a webhook */
+    deleteWebhook(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Check proving service health */
+    getProvingHealth(): Promise<ProvingHealth>;
+    /** Submit a transition for delegated proving */
+    submitDelegatedProof(params: DelegateProofParams): Promise<{
+        proof_id: string;
+    }>;
+    /** Check delegated proof status */
+    getProvingStatus(proofId: string): Promise<{
+        status: string;
+        tx_id?: string;
+    }>;
+}
+
+export { type AleoAddress, type AleoField, type AleoTransactionId, type ApiKey, type CompleteSessionParams, type CreatePaymentLinkParams, type CreateProductParams, type DelegateProofParams, type Escrow, type FulfillLinkParams, type PaymentLink, type PaymentLinkPublic, type PaymentSession, type Product, type ProvingHealth, type Receipt, type SessionResult, type StoreReceiptParams, type TxStatus, VeilReceipt, type VeilReceiptConfig, VeilReceiptError, type VerificationResult, type Webhook };

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+type AleoAddress = string;
+type AleoField = string;
+type AleoTransactionId = string;
+interface PaymentSession {
+    id: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    description: string;
+    status: string;
+    merchant_address: AleoAddress;
+    payment_mode: string | null;
+    tx_id: string | null;
+    redirect_url: string | null;
+    cancel_url: string | null;
+    expires_at: string;
+}
+interface CompleteSessionParams {
+    purchase_commitment: string;
+    tx_id: string;
+    payment_mode: 'private' | 'public' | 'escrow';
+    buyer_address?: string;
+}
+interface SessionResult {
+    success: boolean;
+    session_id: string;
+    redirect_url: string | null;
+}
+interface PaymentLink {
+    id: string;
+    merchant_id: string;
+    merchant_address: AleoAddress;
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    is_active: boolean;
+    total_contributions: number;
+    total_collected: number;
+    tx_id: string;
+    created_at: string;
+}
+interface PaymentLinkPublic {
+    id: string;
+    merchant_address: AleoAddress;
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    is_active: boolean;
+    total_contributions: number;
+}
+interface CreatePaymentLinkParams {
+    link_hash: string;
+    amount: number;
+    currency: 'credits' | 'usdcx' | 'usad';
+    link_type: 'one_time' | 'recurring' | 'open';
+    label: string;
+    description: string;
+    tx_id: string;
+}
+interface FulfillLinkParams {
+    link_id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    amount: number;
+    tx_id: string;
+    payment_mode: 'private' | 'escrow';
+}
+interface Product {
+    id: string;
+    merchant_id: string;
+    merchant_address: AleoAddress;
+    name: string;
+    description: string;
+    price: number;
+    price_type: 'credits' | 'usdcx' | 'usad';
+    sku: string;
+    image_url?: string;
+    category?: string;
+    in_stock: boolean;
+    created_at: string;
+}
+interface CreateProductParams {
+    name: string;
+    description: string;
+    price: number;
+    price_type: 'credits' | 'usdcx' | 'usad';
+    sku: string;
+    imageUrl?: string;
+    category?: string;
+}
+interface Receipt {
+    id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    merchant_address_hash: string;
+    total: number;
+    token_type: number;
+    cart_commitment: string;
+    tx_id: string;
+    status: string;
+    created_at: string;
+}
+interface Escrow {
+    id: string;
+    purchase_commitment: string;
+    buyer_address_hash: string;
+    merchant_address_hash: string;
+    total: number;
+    status: 'active' | 'completed' | 'refunded';
+    escrow_tx_id: string;
+    resolve_tx_id: string;
+    created_block: number;
+    created_at: string;
+}
+interface StoreReceiptParams {
+    txId: string;
+    onChainTxId?: string;
+    merchantAddress: string;
+    buyerAddress: string;
+    total: number;
+    tokenType?: 'credits' | 'usdcx' | 'usad';
+    purchaseType?: 'private' | 'public' | 'escrow';
+    status?: 'confirmed' | 'escrowed';
+    cartCommitment?: string;
+    timestamp?: number;
+    blockHeight?: number;
+    items?: {
+        sku: string;
+        quantity: number;
+        price: number;
+    }[];
+}
+interface VerificationResult {
+    commitment: string;
+    on_chain_verified: boolean;
+    receipt: {
+        total: number;
+        token_type: number;
+        status: string;
+        tx_id: string;
+    } | null;
+}
+interface ApiKey {
+    id: string;
+    prefix: string;
+    label: string;
+    permissions: string[];
+    is_active: boolean;
+    last_used_at: string | null;
+    created_at: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    is_active: boolean;
+    failure_count: number;
+    created_at: string;
+}
+interface ProvingHealth {
+    dps_configured: boolean;
+    sponsor_configured: boolean;
+    program_id: string;
+    network: string;
+}
+interface DelegateProofParams {
+    transition: string;
+    inputs: string[];
+    fee_record?: string;
+}
+interface TxStatus {
+    txId: string;
+    status: 'confirmed' | 'pending' | 'failed' | 'not_found';
+    blockHeight?: number;
+}
+interface VeilReceiptConfig {
+    /** Base URL of the VeilReceipt backend API */
+    baseUrl: string;
+    /** API key for authentication (from merchant dashboard) */
+    apiKey?: string;
+    /** JWT token for session-based auth */
+    token?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
+declare class VeilReceiptError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+/**
+ * VeilReceipt SDK Client
+ *
+ * ```ts
+ * import { VeilReceipt } from '@veilreceipt/sdk';
+ *
+ * const veil = new VeilReceipt({
+ *   baseUrl: 'https://api.veilreceipt.com',
+ *   apiKey: 'vr_live_...',
+ * });
+ *
+ * // Get a payment session
+ * const session = await veil.getPaymentSession('sess_abc123');
+ *
+ * // Resolve a payment link
+ * const link = await veil.resolvePaymentLink('a1b2c3d4');
+ * ```
+ */
+declare class VeilReceipt {
+    private baseUrl;
+    private apiKey?;
+    private token?;
+    private timeout;
+    constructor(config: VeilReceiptConfig);
+    /** Update the auth token (e.g. after login) */
+    setToken(token: string | null): void;
+    /** Update the API key */
+    setApiKey(key: string | null): void;
+    private request;
+    /** Check API health */
+    health(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+    /** Get details of a payment session */
+    getPaymentSession(sessionId: string): Promise<PaymentSession>;
+    /** Complete a payment session after on-chain tx */
+    completePaymentSession(sessionId: string, params: CompleteSessionParams): Promise<SessionResult>;
+    /** Create a new payment link (requires merchant auth) */
+    createPaymentLink(params: CreatePaymentLinkParams): Promise<PaymentLink>;
+    /** List payment links for the authenticated merchant */
+    listPaymentLinks(): Promise<PaymentLink[]>;
+    /** Resolve a payment link by its public hash (no auth required) */
+    resolvePaymentLink(hash: string): Promise<PaymentLinkPublic>;
+    /** Get a specific payment link by ID */
+    getPaymentLink(id: string): Promise<PaymentLink>;
+    /** Record a link fulfillment after on-chain tx */
+    fulfillPaymentLink(id: string, params: FulfillLinkParams): Promise<{
+        success: boolean;
+    }>;
+    /** Close/deactivate a payment link (merchant only) */
+    closePaymentLink(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** List products, optionally filtered */
+    getProducts(filters?: {
+        merchant?: string;
+        category?: string;
+        inStock?: boolean;
+    }): Promise<{
+        products: Product[];
+    }>;
+    /** Get a single product by ID */
+    getProduct(id: string): Promise<{
+        product: Product;
+    }>;
+    /** Create a product (merchant auth required) */
+    createProduct(params: CreateProductParams): Promise<{
+        product: Product;
+    }>;
+    /** Update a product (merchant auth required) */
+    updateProduct(id: string, params: Partial<{
+        name: string;
+        description: string;
+        price: number;
+        imageUrl: string;
+        category: string;
+        inStock: boolean;
+    }>): Promise<{
+        product: Product;
+    }>;
+    /** Delete a product (merchant auth required) */
+    deleteProduct(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Store receipt metadata */
+    storeReceipt(params: StoreReceiptParams): Promise<{
+        receipt: Receipt;
+    }>;
+    /** Get all receipts for authenticated user */
+    getReceipts(): Promise<{
+        receipts: Receipt[];
+        count: number;
+    }>;
+    /** Get receipts by buyer address */
+    getReceiptsByBuyer(address: string): Promise<{
+        receipts: Receipt[];
+        count: number;
+    }>;
+    /** Get a receipt by transaction ID */
+    getReceiptByTxId(txId: string): Promise<{
+        receipt: Receipt;
+    }>;
+    /** Create an escrow record */
+    createEscrow(params: {
+        purchaseCommitment: string;
+        buyerAddress: string;
+        merchantAddress: string;
+        total: number;
+        txId: string;
+    }): Promise<{
+        escrow: Escrow;
+    }>;
+    /** Resolve an escrow (complete or refund) */
+    resolveEscrow(id: string, action: 'complete' | 'refund', txId: string): Promise<{
+        escrow: Escrow;
+    }>;
+    /** Get escrows for authenticated user */
+    getMyEscrows(): Promise<{
+        escrows: Escrow[];
+    }>;
+    /** Verify a purchase commitment on-chain */
+    verifyPurchase(commitment: string): Promise<VerificationResult>;
+    /** Check transaction status on-chain */
+    getTransactionStatus(txId: string): Promise<TxStatus>;
+    /** Get current chain block height */
+    getChainHeight(): Promise<{
+        height: number;
+    }>;
+    /** Create an API key */
+    createApiKey(label: string, permissions: string[]): Promise<ApiKey & {
+        key: string;
+        warning: string;
+    }>;
+    /** List API keys */
+    listApiKeys(): Promise<{
+        keys: ApiKey[];
+    }>;
+    /** Revoke an API key */
+    revokeApiKey(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Create a webhook */
+    createWebhook(url: string, events: string[]): Promise<Webhook & {
+        signing_secret: string;
+        warning: string;
+    }>;
+    /** List webhooks */
+    listWebhooks(): Promise<{
+        webhooks: Webhook[];
+    }>;
+    /** Delete a webhook */
+    deleteWebhook(id: string): Promise<{
+        success: boolean;
+    }>;
+    /** Check proving service health */
+    getProvingHealth(): Promise<ProvingHealth>;
+    /** Submit a transition for delegated proving */
+    submitDelegatedProof(params: DelegateProofParams): Promise<{
+        proof_id: string;
+    }>;
+    /** Check delegated proof status */
+    getProvingStatus(proofId: string): Promise<{
+        status: string;
+        tx_id?: string;
+    }>;
+}
+
+export { type AleoAddress, type AleoField, type AleoTransactionId, type ApiKey, type CompleteSessionParams, type CreatePaymentLinkParams, type CreateProductParams, type DelegateProofParams, type Escrow, type FulfillLinkParams, type PaymentLink, type PaymentLinkPublic, type PaymentSession, type Product, type ProvingHealth, type Receipt, type SessionResult, type StoreReceiptParams, type TxStatus, VeilReceipt, type VeilReceiptConfig, VeilReceiptError, type VerificationResult, type Webhook };

package/dist/index.js

@@ -0,0 +1,260 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  VeilReceipt: () => VeilReceipt,
+  VeilReceiptError: () => VeilReceiptError
+});
+module.exports = __toCommonJS(index_exports);
+var VeilReceiptError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "VeilReceiptError";
+  }
+};
+var VeilReceipt = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.token = config.token;
+    this.timeout = config.timeout ?? 3e4;
+  }
+  /** Update the auth token (e.g. after login) */
+  setToken(token) {
+    this.token = token ?? void 0;
+  }
+  /** Update the API key */
+  setApiKey(key) {
+    this.apiKey = key ?? void 0;
+  }
+  // ───────────────────────────────────────
+  // Internal
+  // ───────────────────────────────────────
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
+    }
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        throw new VeilReceiptError(
+          data.error || `Request failed: ${res.status}`,
+          res.status
+        );
+      }
+      return data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ───────────────────────────────────────
+  // Health
+  // ───────────────────────────────────────
+  /** Check API health */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  // ───────────────────────────────────────
+  // Payment Sessions
+  // ───────────────────────────────────────
+  /** Get details of a payment session */
+  async getPaymentSession(sessionId) {
+    return this.request("GET", `/integrate/payments/${encodeURIComponent(sessionId)}`);
+  }
+  /** Complete a payment session after on-chain tx */
+  async completePaymentSession(sessionId, params) {
+    return this.request("POST", `/integrate/payments/${encodeURIComponent(sessionId)}/complete`, params);
+  }
+  // ───────────────────────────────────────
+  // Payment Links
+  // ───────────────────────────────────────
+  /** Create a new payment link (requires merchant auth) */
+  async createPaymentLink(params) {
+    return this.request("POST", "/links", params);
+  }
+  /** List payment links for the authenticated merchant */
+  async listPaymentLinks() {
+    return this.request("GET", "/links");
+  }
+  /** Resolve a payment link by its public hash (no auth required) */
+  async resolvePaymentLink(hash) {
+    return this.request("GET", `/links/resolve/${encodeURIComponent(hash)}`);
+  }
+  /** Get a specific payment link by ID */
+  async getPaymentLink(id) {
+    return this.request("GET", `/links/${encodeURIComponent(id)}`);
+  }
+  /** Record a link fulfillment after on-chain tx */
+  async fulfillPaymentLink(id, params) {
+    return this.request("POST", `/links/${encodeURIComponent(id)}/fulfill`, params);
+  }
+  /** Close/deactivate a payment link (merchant only) */
+  async closePaymentLink(id) {
+    return this.request("POST", `/links/${encodeURIComponent(id)}/close`);
+  }
+  // ───────────────────────────────────────
+  // Products
+  // ───────────────────────────────────────
+  /** List products, optionally filtered */
+  async getProducts(filters) {
+    const params = new URLSearchParams();
+    if (filters?.merchant) params.set("merchant", filters.merchant);
+    if (filters?.category) params.set("category", filters.category);
+    if (filters?.inStock !== void 0) params.set("inStock", String(filters.inStock));
+    const q = params.toString();
+    return this.request("GET", `/products${q ? `?${q}` : ""}`);
+  }
+  /** Get a single product by ID */
+  async getProduct(id) {
+    return this.request("GET", `/products/${encodeURIComponent(id)}`);
+  }
+  /** Create a product (merchant auth required) */
+  async createProduct(params) {
+    return this.request("POST", "/products", params);
+  }
+  /** Update a product (merchant auth required) */
+  async updateProduct(id, params) {
+    return this.request("PUT", `/products/${encodeURIComponent(id)}`, params);
+  }
+  /** Delete a product (merchant auth required) */
+  async deleteProduct(id) {
+    return this.request("DELETE", `/products/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Receipts
+  // ───────────────────────────────────────
+  /** Store receipt metadata */
+  async storeReceipt(params) {
+    return this.request("POST", "/receipts", params);
+  }
+  /** Get all receipts for authenticated user */
+  async getReceipts() {
+    return this.request("GET", "/receipts");
+  }
+  /** Get receipts by buyer address */
+  async getReceiptsByBuyer(address) {
+    return this.request("GET", `/receipts/buyer/${encodeURIComponent(address)}`);
+  }
+  /** Get a receipt by transaction ID */
+  async getReceiptByTxId(txId) {
+    return this.request("GET", `/receipts/tx/${encodeURIComponent(txId)}`);
+  }
+  // ───────────────────────────────────────
+  // Escrow
+  // ───────────────────────────────────────
+  /** Create an escrow record */
+  async createEscrow(params) {
+    return this.request("POST", "/escrow", params);
+  }
+  /** Resolve an escrow (complete or refund) */
+  async resolveEscrow(id, action, txId) {
+    return this.request("POST", `/escrow/${encodeURIComponent(id)}/resolve`, { action, txId });
+  }
+  /** Get escrows for authenticated user */
+  async getMyEscrows() {
+    return this.request("GET", "/escrow/my");
+  }
+  // ───────────────────────────────────────
+  // Verification
+  // ───────────────────────────────────────
+  /** Verify a purchase commitment on-chain */
+  async verifyPurchase(commitment) {
+    return this.request("GET", `/integrate/verify/${encodeURIComponent(commitment)}`);
+  }
+  // ───────────────────────────────────────
+  // Transaction Status
+  // ───────────────────────────────────────
+  /** Check transaction status on-chain */
+  async getTransactionStatus(txId) {
+    return this.request("GET", `/tx/${encodeURIComponent(txId)}/status`);
+  }
+  /** Get current chain block height */
+  async getChainHeight() {
+    return this.request("GET", "/chain/height");
+  }
+  // ───────────────────────────────────────
+  // API Keys (merchant dashboard)
+  // ───────────────────────────────────────
+  /** Create an API key */
+  async createApiKey(label, permissions) {
+    return this.request("POST", "/integrate/keys", { label, permissions });
+  }
+  /** List API keys */
+  async listApiKeys() {
+    return this.request("GET", "/integrate/keys");
+  }
+  /** Revoke an API key */
+  async revokeApiKey(id) {
+    return this.request("DELETE", `/integrate/keys/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Webhooks (merchant dashboard)
+  // ───────────────────────────────────────
+  /** Create a webhook */
+  async createWebhook(url, events) {
+    return this.request("POST", "/integrate/webhooks", { url, events });
+  }
+  /** List webhooks */
+  async listWebhooks() {
+    return this.request("GET", "/integrate/webhooks");
+  }
+  /** Delete a webhook */
+  async deleteWebhook(id) {
+    return this.request("DELETE", `/integrate/webhooks/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Delegated Proving
+  // ───────────────────────────────────────
+  /** Check proving service health */
+  async getProvingHealth() {
+    return this.request("GET", "/proving/health");
+  }
+  /** Submit a transition for delegated proving */
+  async submitDelegatedProof(params) {
+    return this.request("POST", "/proving/delegate", params);
+  }
+  /** Check delegated proof status */
+  async getProvingStatus(proofId) {
+    return this.request("GET", `/proving/status/${encodeURIComponent(proofId)}`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VeilReceipt,
+  VeilReceiptError
+});

package/dist/index.mjs

@@ -0,0 +1,234 @@
+// src/index.ts
+var VeilReceiptError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "VeilReceiptError";
+  }
+};
+var VeilReceipt = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.token = config.token;
+    this.timeout = config.timeout ?? 3e4;
+  }
+  /** Update the auth token (e.g. after login) */
+  setToken(token) {
+    this.token = token ?? void 0;
+  }
+  /** Update the API key */
+  setApiKey(key) {
+    this.apiKey = key ?? void 0;
+  }
+  // ───────────────────────────────────────
+  // Internal
+  // ───────────────────────────────────────
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
+    }
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        throw new VeilReceiptError(
+          data.error || `Request failed: ${res.status}`,
+          res.status
+        );
+      }
+      return data;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ───────────────────────────────────────
+  // Health
+  // ───────────────────────────────────────
+  /** Check API health */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  // ───────────────────────────────────────
+  // Payment Sessions
+  // ───────────────────────────────────────
+  /** Get details of a payment session */
+  async getPaymentSession(sessionId) {
+    return this.request("GET", `/integrate/payments/${encodeURIComponent(sessionId)}`);
+  }
+  /** Complete a payment session after on-chain tx */
+  async completePaymentSession(sessionId, params) {
+    return this.request("POST", `/integrate/payments/${encodeURIComponent(sessionId)}/complete`, params);
+  }
+  // ───────────────────────────────────────
+  // Payment Links
+  // ───────────────────────────────────────
+  /** Create a new payment link (requires merchant auth) */
+  async createPaymentLink(params) {
+    return this.request("POST", "/links", params);
+  }
+  /** List payment links for the authenticated merchant */
+  async listPaymentLinks() {
+    return this.request("GET", "/links");
+  }
+  /** Resolve a payment link by its public hash (no auth required) */
+  async resolvePaymentLink(hash) {
+    return this.request("GET", `/links/resolve/${encodeURIComponent(hash)}`);
+  }
+  /** Get a specific payment link by ID */
+  async getPaymentLink(id) {
+    return this.request("GET", `/links/${encodeURIComponent(id)}`);
+  }
+  /** Record a link fulfillment after on-chain tx */
+  async fulfillPaymentLink(id, params) {
+    return this.request("POST", `/links/${encodeURIComponent(id)}/fulfill`, params);
+  }
+  /** Close/deactivate a payment link (merchant only) */
+  async closePaymentLink(id) {
+    return this.request("POST", `/links/${encodeURIComponent(id)}/close`);
+  }
+  // ───────────────────────────────────────
+  // Products
+  // ───────────────────────────────────────
+  /** List products, optionally filtered */
+  async getProducts(filters) {
+    const params = new URLSearchParams();
+    if (filters?.merchant) params.set("merchant", filters.merchant);
+    if (filters?.category) params.set("category", filters.category);
+    if (filters?.inStock !== void 0) params.set("inStock", String(filters.inStock));
+    const q = params.toString();
+    return this.request("GET", `/products${q ? `?${q}` : ""}`);
+  }
+  /** Get a single product by ID */
+  async getProduct(id) {
+    return this.request("GET", `/products/${encodeURIComponent(id)}`);
+  }
+  /** Create a product (merchant auth required) */
+  async createProduct(params) {
+    return this.request("POST", "/products", params);
+  }
+  /** Update a product (merchant auth required) */
+  async updateProduct(id, params) {
+    return this.request("PUT", `/products/${encodeURIComponent(id)}`, params);
+  }
+  /** Delete a product (merchant auth required) */
+  async deleteProduct(id) {
+    return this.request("DELETE", `/products/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Receipts
+  // ───────────────────────────────────────
+  /** Store receipt metadata */
+  async storeReceipt(params) {
+    return this.request("POST", "/receipts", params);
+  }
+  /** Get all receipts for authenticated user */
+  async getReceipts() {
+    return this.request("GET", "/receipts");
+  }
+  /** Get receipts by buyer address */
+  async getReceiptsByBuyer(address) {
+    return this.request("GET", `/receipts/buyer/${encodeURIComponent(address)}`);
+  }
+  /** Get a receipt by transaction ID */
+  async getReceiptByTxId(txId) {
+    return this.request("GET", `/receipts/tx/${encodeURIComponent(txId)}`);
+  }
+  // ───────────────────────────────────────
+  // Escrow
+  // ───────────────────────────────────────
+  /** Create an escrow record */
+  async createEscrow(params) {
+    return this.request("POST", "/escrow", params);
+  }
+  /** Resolve an escrow (complete or refund) */
+  async resolveEscrow(id, action, txId) {
+    return this.request("POST", `/escrow/${encodeURIComponent(id)}/resolve`, { action, txId });
+  }
+  /** Get escrows for authenticated user */
+  async getMyEscrows() {
+    return this.request("GET", "/escrow/my");
+  }
+  // ───────────────────────────────────────
+  // Verification
+  // ───────────────────────────────────────
+  /** Verify a purchase commitment on-chain */
+  async verifyPurchase(commitment) {
+    return this.request("GET", `/integrate/verify/${encodeURIComponent(commitment)}`);
+  }
+  // ───────────────────────────────────────
+  // Transaction Status
+  // ───────────────────────────────────────
+  /** Check transaction status on-chain */
+  async getTransactionStatus(txId) {
+    return this.request("GET", `/tx/${encodeURIComponent(txId)}/status`);
+  }
+  /** Get current chain block height */
+  async getChainHeight() {
+    return this.request("GET", "/chain/height");
+  }
+  // ───────────────────────────────────────
+  // API Keys (merchant dashboard)
+  // ───────────────────────────────────────
+  /** Create an API key */
+  async createApiKey(label, permissions) {
+    return this.request("POST", "/integrate/keys", { label, permissions });
+  }
+  /** List API keys */
+  async listApiKeys() {
+    return this.request("GET", "/integrate/keys");
+  }
+  /** Revoke an API key */
+  async revokeApiKey(id) {
+    return this.request("DELETE", `/integrate/keys/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Webhooks (merchant dashboard)
+  // ───────────────────────────────────────
+  /** Create a webhook */
+  async createWebhook(url, events) {
+    return this.request("POST", "/integrate/webhooks", { url, events });
+  }
+  /** List webhooks */
+  async listWebhooks() {
+    return this.request("GET", "/integrate/webhooks");
+  }
+  /** Delete a webhook */
+  async deleteWebhook(id) {
+    return this.request("DELETE", `/integrate/webhooks/${encodeURIComponent(id)}`);
+  }
+  // ───────────────────────────────────────
+  // Delegated Proving
+  // ───────────────────────────────────────
+  /** Check proving service health */
+  async getProvingHealth() {
+    return this.request("GET", "/proving/health");
+  }
+  /** Submit a transition for delegated proving */
+  async submitDelegatedProof(params) {
+    return this.request("POST", "/proving/delegate", params);
+  }
+  /** Check delegated proof status */
+  async getProvingStatus(proofId) {
+    return this.request("GET", `/proving/status/${encodeURIComponent(proofId)}`);
+  }
+};
+export {
+  VeilReceipt,
+  VeilReceiptError
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "veilreceipt-sdk",
+  "version": "1.0.0",
+  "description": "VeilReceipt SDK — Accept private payments on Aleo with payment links, escrow, and ZK receipts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "aleo",
+    "zk",
+    "zero-knowledge",
+    "privacy",
+    "payments",
+    "receipts",
+    "escrow",
+    "web3"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}