@pacspace-io/sdk 0.1.0

package/dist/errors/index.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.TimeoutError = exports.ValidationError = exports.RateLimitError = exports.ContractNotDeployedError = exports.NotFoundError = exports.InsufficientCreditsError = exports.InvalidApiKeyError = exports.PacSpaceError = void 0;
+exports.mapApiError = mapApiError;
+/**
+ * Base error class for all PacSpace SDK errors.
+ * Extends native Error with structured API error data.
+ */
+class PacSpaceError extends Error {
+    constructor(message, statusCode, code, requestPath) {
+        super(message);
+        this.name = 'PacSpaceError';
+        this.statusCode = statusCode;
+        this.code = code;
+        this.requestPath = requestPath;
+        // Ensure instanceof works correctly in TS
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PacSpaceError = PacSpaceError;
+/**
+ * Thrown when the API key is missing, invalid, or disabled (HTTP 401).
+ */
+class InvalidApiKeyError extends PacSpaceError {
+    constructor(message = 'Invalid or missing API key', requestPath) {
+        super(message, 401, 'INVALID_API_KEY', requestPath);
+        this.name = 'InvalidApiKeyError';
+    }
+}
+exports.InvalidApiKeyError = InvalidApiKeyError;
+/**
+ * Thrown when the tenant has insufficient credits for the operation (HTTP 402).
+ */
+class InsufficientCreditsError extends PacSpaceError {
+    constructor(message = 'Insufficient credits for this operation', requestPath) {
+        super(message, 402, 'INSUFFICIENT_CREDITS', requestPath);
+        this.name = 'InsufficientCreditsError';
+    }
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
+/**
+ * Thrown when the requested resource is not found (HTTP 404).
+ */
+class NotFoundError extends PacSpaceError {
+    constructor(message = 'Resource not found', requestPath) {
+        super(message, 404, 'NOT_FOUND', requestPath);
+        this.name = 'NotFoundError';
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Thrown when no contract is deployed for the tenant (HTTP 412).
+ */
+class ContractNotDeployedError extends PacSpaceError {
+    constructor(message = 'No contract deployed. Provision an environment first.', requestPath) {
+        super(message, 412, 'CONTRACT_NOT_DEPLOYED', requestPath);
+        this.name = 'ContractNotDeployedError';
+    }
+}
+exports.ContractNotDeployedError = ContractNotDeployedError;
+/**
+ * Thrown when the API rate limit is exceeded (HTTP 429).
+ */
+class RateLimitError extends PacSpaceError {
+    constructor(message = 'Rate limit exceeded', retryAfter = null, requestPath) {
+        super(message, 429, 'RATE_LIMITED', requestPath);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Thrown when the API returns a validation error (HTTP 400).
+ */
+class ValidationError extends PacSpaceError {
+    constructor(message = 'Invalid request data', requestPath) {
+        super(message, 400, 'VALIDATION_ERROR', requestPath);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Thrown when a polling operation exceeds the configured timeout.
+ */
+class TimeoutError extends PacSpaceError {
+    constructor(message = 'Operation timed out waiting for verification', requestPath) {
+        super(message, 0, 'TIMEOUT', requestPath);
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Thrown when the webhook signature is invalid.
+ */
+class WebhookVerificationError extends PacSpaceError {
+    constructor(message = 'Webhook signature verification failed') {
+        super(message, 0, 'WEBHOOK_VERIFICATION_FAILED');
+        this.name = 'WebhookVerificationError';
+    }
+}
+exports.WebhookVerificationError = WebhookVerificationError;
+/**
+ * Map an HTTP status code + API response to the appropriate typed error.
+ * @internal
+ */
+function mapApiError(statusCode, message, requestPath, headers) {
+    switch (statusCode) {
+        case 400:
+            return new ValidationError(message, requestPath);
+        case 401:
+            return new InvalidApiKeyError(message, requestPath);
+        case 402:
+            return new InsufficientCreditsError(message, requestPath);
+        case 404:
+            return new NotFoundError(message, requestPath);
+        case 412:
+            return new ContractNotDeployedError(message, requestPath);
+        case 429: {
+            const retryAfter = headers?.get('retry-after');
+            return new RateLimitError(message, retryAfter ? parseInt(retryAfter, 10) : null, requestPath);
+        }
+        default:
+            return new PacSpaceError(message, statusCode, 'API_ERROR', requestPath);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { BalanceResource } from './resources/balance';
+import { Webhooks } from './webhooks/verify';
+import type { PacSpaceConfig } from './types/config';
+/**
+ * PacSpace SDK — the official TypeScript client for the PacSpace Balance API.
+ *
+ * @example
+ * ```typescript
+ * import { PacSpace } from '@pacspace-io/sdk';
+ *
+ * const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
+ *
+ * // Record a delta
+ * const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
+ *
+ * // Derive balance
+ * const { computedBalance } = await pac.balance.derive('cust_123');
+ *
+ * // Compare against counterparty
+ * const report = await pac.balance.compare('cust_123', {
+ *   yours: 95000,
+ *   theirs: 98000,
+ * });
+ *
+ * // Period-end checkpoint
+ * const checkpoint = await pac.balance.checkpoint('cust_123', {
+ *   period: '2026-02',
+ * });
+ * ```
+ */
+export declare class PacSpace {
+    /** @internal */
+    private readonly client;
+    /**
+     * Balance API resource — emit deltas, derive balances, compare, receipt, checkpoint.
+     */
+    readonly balance: BalanceResource;
+    /**
+     * Webhook verification helper.
+     * Only available when a `webhookSecret` is provided.
+     */
+    readonly webhooks: Webhooks | undefined;
+    /**
+     * Create a new PacSpace SDK instance.
+     *
+     * @param config - SDK configuration.
+     * @param config.apiKey - Your PacSpace API key (required).
+     * @param config.baseUrl - API base URL (optional, defaults to production).
+     * @param config.chainId - Default chain ID (optional, auto-detected from key prefix).
+     * @param config.maxRetries - Max retries on transient errors (default: 2).
+     * @param config.timeout - Request timeout in ms (default: 30000).
+     */
+    constructor(config: PacSpaceConfig & {
+        webhookSecret?: string;
+    });
+}
+export type { PacSpaceConfig, RequestOptions } from './types/config';
+export type { AnchorStatus, CheckpointType } from './types/common';
+export type { EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, VerifiedDelta, WindowSummary, CompareOptions, CompareBalances, CompareResponse, DiscrepancyReport, ReceiptResponse, CheckpointOptions, CheckpointResponse, } from './types/balance';
+export { PacSpaceError, InvalidApiKeyError, InsufficientCreditsError, NotFoundError, ContractNotDeployedError, RateLimitError, ValidationError, TimeoutError, WebhookVerificationError, } from './errors';
+export { Webhooks } from './webhooks/verify';
+export type { VerifyOptions, } from './webhooks/verify';
+export type { WebhookEventType, WebhookEvent, WebhookEventMap, WebhookHeaders, DeltaVerifiedPayload, DeltaStoredPayload, CheckpointVerifiedPayload, FactVerifiedPayload, RecordTransferredPayload, } from './webhooks/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,QAAQ;IACnB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAExC;;;;;;;;;OASG;gBACS,MAAM,EAAE,cAAc,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;CAQhE;AAOD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGnE,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,EACb,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EACV,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = exports.WebhookVerificationError = exports.TimeoutError = exports.ValidationError = exports.RateLimitError = exports.ContractNotDeployedError = exports.NotFoundError = exports.InsufficientCreditsError = exports.InvalidApiKeyError = exports.PacSpaceError = exports.PacSpace = void 0;
+const client_1 = require("./client");
+const balance_1 = require("./resources/balance");
+const verify_1 = require("./webhooks/verify");
+/**
+ * PacSpace SDK — the official TypeScript client for the PacSpace Balance API.
+ *
+ * @example
+ * ```typescript
+ * import { PacSpace } from '@pacspace-io/sdk';
+ *
+ * const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
+ *
+ * // Record a delta
+ * const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
+ *
+ * // Derive balance
+ * const { computedBalance } = await pac.balance.derive('cust_123');
+ *
+ * // Compare against counterparty
+ * const report = await pac.balance.compare('cust_123', {
+ *   yours: 95000,
+ *   theirs: 98000,
+ * });
+ *
+ * // Period-end checkpoint
+ * const checkpoint = await pac.balance.checkpoint('cust_123', {
+ *   period: '2026-02',
+ * });
+ * ```
+ */
+class PacSpace {
+    /**
+     * Create a new PacSpace SDK instance.
+     *
+     * @param config - SDK configuration.
+     * @param config.apiKey - Your PacSpace API key (required).
+     * @param config.baseUrl - API base URL (optional, defaults to production).
+     * @param config.chainId - Default chain ID (optional, auto-detected from key prefix).
+     * @param config.maxRetries - Max retries on transient errors (default: 2).
+     * @param config.timeout - Request timeout in ms (default: 30000).
+     */
+    constructor(config) {
+        this.client = new client_1.HttpClient(config);
+        this.balance = new balance_1.BalanceResource(this.client);
+        if (config.webhookSecret) {
+            this.webhooks = new verify_1.Webhooks(config.webhookSecret);
+        }
+    }
+}
+exports.PacSpace = PacSpace;
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "PacSpaceError", { enumerable: true, get: function () { return errors_1.PacSpaceError; } });
+Object.defineProperty(exports, "InvalidApiKeyError", { enumerable: true, get: function () { return errors_1.InvalidApiKeyError; } });
+Object.defineProperty(exports, "InsufficientCreditsError", { enumerable: true, get: function () { return errors_1.InsufficientCreditsError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ContractNotDeployedError", { enumerable: true, get: function () { return errors_1.ContractNotDeployedError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_1.TimeoutError; } });
+Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, get: function () { return errors_1.WebhookVerificationError; } });
+// Webhooks
+var verify_2 = require("./webhooks/verify");
+Object.defineProperty(exports, "Webhooks", { enumerable: true, get: function () { return verify_2.Webhooks; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAAsC;AACtC,iDAAsD;AACtD,8CAA6C;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,QAAQ;IAenB;;;;;;;;;OASG;IACH,YAAY,MAAmD;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,mBAAU,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,yBAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhD,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACzB,IAAI,CAAC,QAAQ,GAAG,IAAI,iBAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AAjCD,4BAiCC;AA4BD,SAAS;AACT,mCAUkB;AAThB,uGAAA,aAAa,OAAA;AACb,4GAAA,kBAAkB,OAAA;AAClB,kHAAA,wBAAwB,OAAA;AACxB,uGAAA,aAAa,OAAA;AACb,kHAAA,wBAAwB,OAAA;AACxB,wGAAA,cAAc,OAAA;AACd,yGAAA,eAAe,OAAA;AACf,sGAAA,YAAY,OAAA;AACZ,kHAAA,wBAAwB,OAAA;AAG1B,WAAW;AACX,4CAA6C;AAApC,kGAAA,QAAQ,OAAA"}

package/dist/resources/balance.d.ts

@@ -0,0 +1,148 @@
+import type { HttpClient } from '../client';
+import type { EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, CompareOptions, CompareBalances, CompareResponse, ReceiptResponse, CheckpointOptions, CheckpointResponse } from '../types/balance';
+import type { RequestOptions } from '../types/config';
+/**
+ * PacSpace Balance API resource.
+ *
+ * Provides methods for the five core Balance API operations:
+ * - `emit()` — Record a credit/debit delta
+ * - `emitAndWait()` — Record a delta and wait for verification
+ * - `derive()` — Derive balance from verified deltas
+ * - `compare()` — Compare balances against neutral truth
+ * - `receipt()` — Generate a verifiable receipt
+ * - `checkpoint()` — Commit a period-end checkpoint
+ */
+export declare class BalanceResource {
+    private readonly client;
+    /** @internal */
+    constructor(client: HttpClient);
+    /**
+     * Record a credit or debit delta for a customer.
+     *
+     * The delta is queued, independently verified, and confirmed via webhook.
+     * Returns immediately with `status: 'QUEUED'`. Use `emitAndWait()` to
+     * block until verification completes.
+     *
+     * @param customerId - Unique identifier for the customer account.
+     * @param delta - Amount to adjust. Positive = credit, negative = debit.
+     * @param reason - Human-readable reason for the adjustment (audit trail).
+     * @param options - Optional reference ID, metadata, and request overrides.
+     * @returns The queued delta with its `receiptId`.
+     *
+     * @example
+     * ```typescript
+     * const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
+     * console.log(delta.receiptId); // Store this for verification
+     * ```
+     */
+    emit(customerId: string, delta: number, reason: string, options?: EmitOptions): Promise<EmitResponse>;
+    /**
+     * Record a delta and wait for it to be verified.
+     *
+     * Combines `emit()` with status polling. Resolves when the delta reaches
+     * a terminal status (`VERIFIED` or `FAILED`), or throws `TimeoutError`
+     * if the timeout is exceeded.
+     *
+     * @param customerId - Unique identifier for the customer account.
+     * @param delta - Amount to adjust. Positive = credit, negative = debit.
+     * @param reason - Human-readable reason for the adjustment.
+     * @param options - Polling timeout, interval, and emit options.
+     * @returns The verified delta.
+     *
+     * @example
+     * ```typescript
+     * const verified = await pac.balance.emitAndWait('cust_123', -42.50, 'usage', {
+     *   timeout: 30_000,
+     *   pollInterval: 1000,
+     * });
+     * console.log(verified.status); // 'VERIFIED' or 'FAILED'
+     * ```
+     */
+    emitAndWait(customerId: string, delta: number, reason: string, options?: EmitAndWaitOptions): Promise<EmitResponse>;
+    /**
+     * Derive a customer's balance from all verified deltas.
+     *
+     * Any party can independently compute the same balance from the same deltas.
+     * Supports checkpointing to avoid replaying from genesis at scale.
+     *
+     * @param customerId - The customer account to derive balance for.
+     * @param options - Starting balance, checkpoint, and request overrides.
+     * @returns Derived balance with delta history and window summaries.
+     *
+     * @example
+     * ```typescript
+     * const { computedBalance, latestReceiptId } = await pac.balance.derive('cust_123');
+     *
+     * // Use checkpoint for efficient subsequent derivations:
+     * const next = await pac.balance.derive('cust_123', {
+     *   startingBalance: computedBalance,
+     *   startingCheckpoint: latestReceiptId,
+     * });
+     * ```
+     */
+    derive(customerId: string, options?: DeriveOptions): Promise<DeriveResponse>;
+    /**
+     * Compare balances against neutral truth for dispute resolution.
+     *
+     * Submit your balance and your counterparty's balance. PacSpace derives
+     * the neutral truth from verified deltas and returns a discrepancy report
+     * showing which party matches and which window(s) diverged.
+     *
+     * @param customerId - The customer account to compare.
+     * @param balances - Your balance and their balance.
+     * @param options - Starting balance, checkpoint, and request overrides.
+     * @returns Comparison result with discrepancy report.
+     *
+     * @example
+     * ```typescript
+     * const report = await pac.balance.compare('cust_123', {
+     *   yours: 95000,
+     *   theirs: 98000,
+     * });
+     *
+     * if (report.matchesYours) {
+     *   console.log('Your balance is correct');
+     * }
+     * ```
+     */
+    compare(customerId: string, balances: CompareBalances, options?: CompareOptions): Promise<CompareResponse>;
+    /**
+     * Generate a verifiable receipt for a customer.
+     *
+     * Returns a human-readable receipt containing all verified deltas
+     * and cryptographic proof data that any party can independently verify.
+     *
+     * @param customerId - The customer account to generate a receipt for.
+     * @param options - Request overrides.
+     * @returns Receipt with verification data.
+     *
+     * @example
+     * ```typescript
+     * const receipt = await pac.balance.receipt('cust_123');
+     * console.log(receipt.finalBalance);
+     * console.log(receipt.verification.itemHashes);
+     * ```
+     */
+    receipt(customerId: string, options?: RequestOptions): Promise<ReceiptResponse>;
+    /**
+     * Commit a period-end checkpoint.
+     *
+     * Computes a Merkle root over all verified deltas in the billing window
+     * and anchors it on-chain. The checkpoint hash can be included in invoices
+     * for instant counterparty verification.
+     *
+     * @param customerId - Customer to checkpoint (omit for all customers).
+     * @param options - Period (YYYY-MM) and request overrides.
+     * @returns Checkpoint details with Merkle root and status.
+     *
+     * @example
+     * ```typescript
+     * const checkpoint = await pac.balance.checkpoint('cust_123', {
+     *   period: '2026-02',
+     * });
+     * console.log(checkpoint.merkleRoot); // Include in your invoice
+     * ```
+     */
+    checkpoint(customerId?: string, options?: CheckpointOptions): Promise<CheckpointResponse>;
+}
+//# sourceMappingURL=balance.d.ts.map

package/dist/resources/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../../src/resources/balance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAEd,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,gBAAgB;gBACa,MAAM,EAAE,UAAU;IAM/C;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,CACR,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,YAAY,CAAC;IAmBxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAiCxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,cAAc,CAAC;IA8B1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;IAiC3B;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CACX,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;IAW3B;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACd,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;CAa/B"}

package/dist/resources/balance.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BalanceResource = void 0;
+const polling_1 = require("../utils/polling");
+/**
+ * PacSpace Balance API resource.
+ *
+ * Provides methods for the five core Balance API operations:
+ * - `emit()` — Record a credit/debit delta
+ * - `emitAndWait()` — Record a delta and wait for verification
+ * - `derive()` — Derive balance from verified deltas
+ * - `compare()` — Compare balances against neutral truth
+ * - `receipt()` — Generate a verifiable receipt
+ * - `checkpoint()` — Commit a period-end checkpoint
+ */
+class BalanceResource {
+    /** @internal */
+    constructor(client) {
+        this.client = client;
+    }
+    // -------------------------------------------------------------------------
+    // Emit
+    // -------------------------------------------------------------------------
+    /**
+     * Record a credit or debit delta for a customer.
+     *
+     * The delta is queued, independently verified, and confirmed via webhook.
+     * Returns immediately with `status: 'QUEUED'`. Use `emitAndWait()` to
+     * block until verification completes.
+     *
+     * @param customerId - Unique identifier for the customer account.
+     * @param delta - Amount to adjust. Positive = credit, negative = debit.
+     * @param reason - Human-readable reason for the adjustment (audit trail).
+     * @param options - Optional reference ID, metadata, and request overrides.
+     * @returns The queued delta with its `receiptId`.
+     *
+     * @example
+     * ```typescript
+     * const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge');
+     * console.log(delta.receiptId); // Store this for verification
+     * ```
+     */
+    async emit(customerId, delta, reason, options) {
+        const { referenceId, metadata, ...requestOptions } = options ?? {};
+        const body = {
+            customerId,
+            delta,
+            reason,
+        };
+        if (referenceId !== undefined)
+            body.referenceId = referenceId;
+        if (metadata !== undefined)
+            body.metadata = metadata;
+        return this.client.post('/api/v1/balance/delta', body, requestOptions);
+    }
+    /**
+     * Record a delta and wait for it to be verified.
+     *
+     * Combines `emit()` with status polling. Resolves when the delta reaches
+     * a terminal status (`VERIFIED` or `FAILED`), or throws `TimeoutError`
+     * if the timeout is exceeded.
+     *
+     * @param customerId - Unique identifier for the customer account.
+     * @param delta - Amount to adjust. Positive = credit, negative = debit.
+     * @param reason - Human-readable reason for the adjustment.
+     * @param options - Polling timeout, interval, and emit options.
+     * @returns The verified delta.
+     *
+     * @example
+     * ```typescript
+     * const verified = await pac.balance.emitAndWait('cust_123', -42.50, 'usage', {
+     *   timeout: 30_000,
+     *   pollInterval: 1000,
+     * });
+     * console.log(verified.status); // 'VERIFIED' or 'FAILED'
+     * ```
+     */
+    async emitAndWait(customerId, delta, reason, options) {
+        const { timeout = 60000, pollInterval = 2000, signal, ...emitOpts } = options ?? {};
+        const initial = await this.emit(customerId, delta, reason, {
+            ...emitOpts,
+            signal,
+        });
+        // If already terminal, return immediately
+        if (['ANCHORED', 'VERIFIED', 'FAILED'].includes(initial.status)) {
+            return initial;
+        }
+        // Poll for terminal status using the anchor endpoint from writes controller
+        return (0, polling_1.pollUntilTerminal)(() => this.client.get(`/api/v1/writes/${initial.anchorId}`, { signal }), { timeout, pollInterval, signal });
+    }
+    // -------------------------------------------------------------------------
+    // Derive
+    // -------------------------------------------------------------------------
+    /**
+     * Derive a customer's balance from all verified deltas.
+     *
+     * Any party can independently compute the same balance from the same deltas.
+     * Supports checkpointing to avoid replaying from genesis at scale.
+     *
+     * @param customerId - The customer account to derive balance for.
+     * @param options - Starting balance, checkpoint, and request overrides.
+     * @returns Derived balance with delta history and window summaries.
+     *
+     * @example
+     * ```typescript
+     * const { computedBalance, latestReceiptId } = await pac.balance.derive('cust_123');
+     *
+     * // Use checkpoint for efficient subsequent derivations:
+     * const next = await pac.balance.derive('cust_123', {
+     *   startingBalance: computedBalance,
+     *   startingCheckpoint: latestReceiptId,
+     * });
+     * ```
+     */
+    async derive(customerId, options) {
+        const { startingBalance, startingCheckpoint, startingCheckpointType, ...requestOptions } = options ?? {};
+        // Build query string
+        const params = new URLSearchParams();
+        if (startingBalance !== undefined) {
+            params.set('startingBalance', String(startingBalance));
+        }
+        if (startingCheckpoint !== undefined) {
+            params.set('startingCheckpoint', startingCheckpoint);
+        }
+        if (startingCheckpointType !== undefined) {
+            params.set('startingCheckpointType', startingCheckpointType);
+        }
+        const query = params.toString();
+        const path = `/api/v1/balance/derive/${encodeURIComponent(customerId)}${query ? `?${query}` : ''}`;
+        return this.client.get(path, requestOptions);
+    }
+    // -------------------------------------------------------------------------
+    // Compare
+    // -------------------------------------------------------------------------
+    /**
+     * Compare balances against neutral truth for dispute resolution.
+     *
+     * Submit your balance and your counterparty's balance. PacSpace derives
+     * the neutral truth from verified deltas and returns a discrepancy report
+     * showing which party matches and which window(s) diverged.
+     *
+     * @param customerId - The customer account to compare.
+     * @param balances - Your balance and their balance.
+     * @param options - Starting balance, checkpoint, and request overrides.
+     * @returns Comparison result with discrepancy report.
+     *
+     * @example
+     * ```typescript
+     * const report = await pac.balance.compare('cust_123', {
+     *   yours: 95000,
+     *   theirs: 98000,
+     * });
+     *
+     * if (report.matchesYours) {
+     *   console.log('Your balance is correct');
+     * }
+     * ```
+     */
+    async compare(customerId, balances, options) {
+        const { startingBalance = 0, startingCheckpoint, startingCheckpointType, ...requestOptions } = options ?? {};
+        const body = {
+            customerId,
+            yourBalance: balances.yours,
+            theirBalance: balances.theirs,
+            startingBalance,
+        };
+        if (startingCheckpoint !== undefined) {
+            body.startingCheckpoint = startingCheckpoint;
+        }
+        if (startingCheckpointType !== undefined) {
+            body.startingCheckpointType = startingCheckpointType;
+        }
+        return this.client.post('/api/v1/balance/compare', body, requestOptions);
+    }
+    // -------------------------------------------------------------------------
+    // Receipt
+    // -------------------------------------------------------------------------
+    /**
+     * Generate a verifiable receipt for a customer.
+     *
+     * Returns a human-readable receipt containing all verified deltas
+     * and cryptographic proof data that any party can independently verify.
+     *
+     * @param customerId - The customer account to generate a receipt for.
+     * @param options - Request overrides.
+     * @returns Receipt with verification data.
+     *
+     * @example
+     * ```typescript
+     * const receipt = await pac.balance.receipt('cust_123');
+     * console.log(receipt.finalBalance);
+     * console.log(receipt.verification.itemHashes);
+     * ```
+     */
+    async receipt(customerId, options) {
+        return this.client.get(`/api/v1/balance/receipt/${encodeURIComponent(customerId)}`, options);
+    }
+    // -------------------------------------------------------------------------
+    // Checkpoint
+    // -------------------------------------------------------------------------
+    /**
+     * Commit a period-end checkpoint.
+     *
+     * Computes a Merkle root over all verified deltas in the billing window
+     * and anchors it on-chain. The checkpoint hash can be included in invoices
+     * for instant counterparty verification.
+     *
+     * @param customerId - Customer to checkpoint (omit for all customers).
+     * @param options - Period (YYYY-MM) and request overrides.
+     * @returns Checkpoint details with Merkle root and status.
+     *
+     * @example
+     * ```typescript
+     * const checkpoint = await pac.balance.checkpoint('cust_123', {
+     *   period: '2026-02',
+     * });
+     * console.log(checkpoint.merkleRoot); // Include in your invoice
+     * ```
+     */
+    async checkpoint(customerId, options) {
+        const { period, ...requestOptions } = options ?? {};
+        const body = {};
+        if (customerId !== undefined)
+            body.customerId = customerId;
+        if (period !== undefined)
+            body.period = period;
+        return this.client.post('/api/v1/balance/checkpoint', body, requestOptions);
+    }
+}
+exports.BalanceResource = BalanceResource;
+//# sourceMappingURL=balance.js.map

package/dist/resources/balance.js.map

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