@pacspace-io/sdk 0.1.0 → 0.2.0

package/dist/errors/index.js

@@ -1,6 +1,6 @@
 "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.WebhookVerificationError = exports.TimeoutError = exports.ValidationError = exports.ServiceUnavailableError = exports.CadenceLimitError = 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.
@@ -69,6 +69,33 @@ class RateLimitError extends PacSpaceError {
     }
 }
 exports.RateLimitError = RateLimitError;
+/**
+ * Thrown when a customer's submission cadence window has not elapsed (HTTP 429).
+ * This error is terminal for the current request and should not be auto-retried.
+ */
+class CadenceLimitError extends PacSpaceError {
+    constructor(message = 'Submission cadence limit reached', retryAfterSeconds = null, customerId = null, requestPath) {
+        super(message, 429, 'CADENCE_LIMIT', requestPath);
+        this.name = 'CadenceLimitError';
+        this.retryAfterMs =
+            retryAfterSeconds && Number.isFinite(retryAfterSeconds)
+                ? Math.max(0, Math.floor(retryAfterSeconds * 1000))
+                : null;
+        this.customerId = customerId;
+    }
+}
+exports.CadenceLimitError = CadenceLimitError;
+/**
+ * Thrown when the API is temporarily unavailable (HTTP 503).
+ */
+class ServiceUnavailableError extends PacSpaceError {
+    constructor(message = 'Service temporarily unavailable', retryAfter = null, requestPath) {
+        super(message, 503, 'SERVICE_UNAVAILABLE', requestPath);
+        this.name = 'ServiceUnavailableError';
+        this.retryAfter = retryAfter;
+    }
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;
 /**
  * Thrown when the API returns a validation error (HTTP 400).
  */
@@ -103,7 +130,15 @@ exports.WebhookVerificationError = WebhookVerificationError;
  * Map an HTTP status code + API response to the appropriate typed error.
  * @internal
  */
-function mapApiError(statusCode, message, requestPath, headers) {
+function mapApiError(statusCode, message, requestPath, headers, apiError) {
+    const headerRetryAfter = headers?.get('retry-after');
+    const parsedHeaderRetryAfter = headerRetryAfter
+        ? Number.parseInt(headerRetryAfter, 10)
+        : null;
+    const retryAfterSeconds = apiError?.retryAfterSeconds ??
+        (Number.isFinite(parsedHeaderRetryAfter)
+            ? parsedHeaderRetryAfter
+            : null);
     switch (statusCode) {
         case 400:
             return new ValidationError(message, requestPath);
@@ -116,8 +151,13 @@ function mapApiError(statusCode, message, requestPath, headers) {
         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);
+            if (apiError?.code === 'CADENCE_LIMIT') {
+                return new CadenceLimitError(message, retryAfterSeconds, apiError.customerId ?? null, requestPath);
+            }
+            return new RateLimitError(message, retryAfterSeconds, requestPath);
+        }
+        case 503: {
+            return new ServiceUnavailableError(message, retryAfterSeconds, requestPath);
         }
         default:
             return new PacSpaceError(message, statusCode, 'API_ERROR', requestPath);

package/dist/errors/index.js.map

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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { BalanceResource } from './resources/balance';
 import { Webhooks } from './webhooks/verify';
 import type { PacSpaceConfig } from './types/config';
+import type { VerifyResponse } from './types/balance';
 /**
  * PacSpace SDK — the official TypeScript client for the PacSpace Balance API.
  *
@@ -22,15 +23,24 @@ import type { PacSpaceConfig } from './types/config';
  *   theirs: 98000,
  * });
  *
- * // Period-end checkpoint
- * const checkpoint = await pac.balance.checkpoint('cust_123', {
- *   period: '2026-02',
- * });
+ * // Period-end receipt (shareable verification proof)
+ * const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
+ *
+ * // Verify a proof root (public, no auth)
+ * const verification = await pac.verify(receipt.proofRoot);
  * ```
  */
 export declare class PacSpace {
+    /**
+     * Preferred SDK initializer for Phase 3 surface.
+     */
+    static init(apiKey: string, options?: Omit<PacSpaceConfig, 'apiKey'>): PacSpace;
     /** @internal */
     private readonly client;
+    /** Base URL for API (used by verify, which requires no auth). */
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly timeoutMs;
     /**
      * Balance API resource — emit deltas, derive balances, compare, receipt, checkpoint.
      */
@@ -45,20 +55,48 @@ export declare class PacSpace {
      *
      * @param config - SDK configuration.
      * @param config.apiKey - Your PacSpace API key (required).
-     * @param config.baseUrl - API base URL (optional, defaults to production).
+     * @param config.baseUrl - API base URL (optional, overrides auto-routing).
+     * @param config.sandboxUrl - Custom sandbox URL (optional, used for `pk_test_*` keys).
+     * @param config.productionUrl - Custom production URL (optional, used for `pk_live_*` keys).
      * @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;
-    });
+    constructor(config: PacSpaceConfig);
+    /**
+     * Close the SDK client and reject buffered write requests.
+     */
+    close(reason?: string): void;
+    /**
+     * Graceful shutdown: flush summary queue and close the client.
+     */
+    shutdown(reason?: string): Promise<void>;
+    /**
+     * Verify a proof root via the public verification endpoint.
+     *
+     * No API key required — the proof root itself serves as the access key.
+     * Anyone with a proof root can verify it independently.
+     *
+     * @param proofRoot - The proof root from a receipt (hex string).
+     * @returns Verification result with records and metadata.
+     *
+     * @example
+     * ```typescript
+     * const result = await pac.verify('0x7f3a9b2c1d4e5f6a...');
+     * if (result.verified) {
+     *   console.log(result.verification?.publicLedgerUrl);
+     *   console.log(result.summary?.recordCount);
+     * }
+     * ```
+     */
+    verify(proofRoot: string): Promise<VerifyResponse>;
 }
 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 type { EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, VerifiedDelta, WindowSummary, CompareOptions, CompareBalances, CompareResponse, DiscrepancyReport, ReceiptResponse, CheckpointOptions, CheckpointResponse, DeltaStatusResponse, WaitForAnchoredOptions, UsageResponse, SequenceGapsOptions, SequenceGapRange, SequenceGapsResponse, BulkDelta, BulkEmitOptions, BulkEmitResponse, BulkDeltaResult, ListWebhookDeliveriesOptions, ListWebhookDeliveriesResponse, CustomerLedgerSummary, CustomerLedgerDetail, CustomerLedgerActivity, ListCustomersOptions, ListCustomersResponse, GetCustomerOptions, InvoiceProofOptions, InvoiceProofResponse, InvoiceProofDelta, InvoiceProofWindowSummary, InvoiceProofVerification, VerifyResponse, VerifySummary, VerifyRecord, VerifyVerification, } from './types/balance';
+export type { SubmissionProfile, SubmissionAutomationOptions, CustomerUsageSummary, QueuedUsageSummary, FlushSummariesOptions, SummaryFlushFailure, SummaryFlushResult, SubmissionQueueState, } from './types/submission';
+export { PacSpaceError, InvalidApiKeyError, InsufficientCreditsError, NotFoundError, ContractNotDeployedError, CadenceLimitError, RateLimitError, ServiceUnavailableError, 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';
+export type { KnownWebhookEventType, WebhookEventType, WebhookEvent, WebhookEventMap, WebhookHeaders, DeltaVerifiedPayload, DeltaFailedPayload, } from './webhooks/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQtD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAQ;IACnB;;OAEG;IACH,MAAM,CAAC,IAAI,CACT,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAM,GAC3C,QAAQ;IAIX,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAExC;;;;;;;;;;;OAWG;gBACS,MAAM,EAAE,cAAc;IA4BlC;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5B;;OAEG;IACG,QAAQ,CAAC,MAAM,SAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAyCzD;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,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,4BAA4B,EAC5B,6BAA6B,EAC7B,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,uBAAuB,EACvB,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,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,9 +1,13 @@
 "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;
+exports.Webhooks = exports.WebhookVerificationError = exports.TimeoutError = exports.ValidationError = exports.ServiceUnavailableError = exports.RateLimitError = exports.CadenceLimitError = 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");
+/** Default sandbox API base URL. */
+const DEFAULT_SANDBOX_URL = 'https://api-sandbox-wnizuypena-uw.a.run.app';
+/** Default production API base URL. */
+const DEFAULT_PRODUCTION_URL = 'https://api.pacspace.io';
 /**
  * PacSpace SDK — the official TypeScript client for the PacSpace Balance API.
  *
@@ -25,30 +29,123 @@ const verify_1 = require("./webhooks/verify");
  *   theirs: 98000,
  * });
  *
- * // Period-end checkpoint
- * const checkpoint = await pac.balance.checkpoint('cust_123', {
- *   period: '2026-02',
- * });
+ * // Period-end receipt (shareable verification proof)
+ * const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
+ *
+ * // Verify a proof root (public, no auth)
+ * const verification = await pac.verify(receipt.proofRoot);
  * ```
  */
 class PacSpace {
+    /**
+     * Preferred SDK initializer for Phase 3 surface.
+     */
+    static init(apiKey, options = {}) {
+        return new PacSpace({ apiKey, ...options });
+    }
     /**
      * 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.baseUrl - API base URL (optional, overrides auto-routing).
+     * @param config.sandboxUrl - Custom sandbox URL (optional, used for `pk_test_*` keys).
+     * @param config.productionUrl - Custom production URL (optional, used for `pk_live_*` keys).
      * @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) {
+        // HttpClient handles base URL auto-routing internally
         this.client = new client_1.HttpClient(config);
-        this.balance = new balance_1.BalanceResource(this.client);
+        this.fetchFn = config.fetch || globalThis.fetch;
+        this.timeoutMs = config.timeout ?? 30000;
+        // For verify() method, we need to determine base URL ourselves
+        // Use explicit baseUrl if provided, otherwise auto-route
+        if (config.baseUrl) {
+            this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        }
+        else {
+            const apiKey = config.apiKey;
+            if (apiKey.startsWith('pk_test_')) {
+                this.baseUrl = (config.sandboxUrl || DEFAULT_SANDBOX_URL).replace(/\/+$/, '');
+            }
+            else if (apiKey.startsWith('pk_live_')) {
+                this.baseUrl = (config.productionUrl || DEFAULT_PRODUCTION_URL).replace(/\/+$/, '');
+            }
+            else {
+                // Fallback to production
+                this.baseUrl = (config.productionUrl || DEFAULT_PRODUCTION_URL).replace(/\/+$/, '');
+            }
+        }
+        this.balance = new balance_1.BalanceResource(this.client, config.submission);
         if (config.webhookSecret) {
             this.webhooks = new verify_1.Webhooks(config.webhookSecret);
         }
     }
+    /**
+     * Close the SDK client and reject buffered write requests.
+     */
+    close(reason) {
+        this.balance.stopSummaryScheduler();
+        this.client.close(reason);
+    }
+    /**
+     * Graceful shutdown: flush summary queue and close the client.
+     */
+    async shutdown(reason = 'SDK shutdown') {
+        await this.balance.shutdownSummaryScheduler();
+        this.client.close(reason);
+    }
+    /**
+     * Verify a proof root via the public verification endpoint.
+     *
+     * No API key required — the proof root itself serves as the access key.
+     * Anyone with a proof root can verify it independently.
+     *
+     * @param proofRoot - The proof root from a receipt (hex string).
+     * @returns Verification result with records and metadata.
+     *
+     * @example
+     * ```typescript
+     * const result = await pac.verify('0x7f3a9b2c1d4e5f6a...');
+     * if (result.verified) {
+     *   console.log(result.verification?.publicLedgerUrl);
+     *   console.log(result.summary?.recordCount);
+     * }
+     * ```
+     */
+    async verify(proofRoot) {
+        const url = `${this.baseUrl}/api/v1/verify/${encodeURIComponent(proofRoot)}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method: 'GET',
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Verification request timed out after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            const msg = body.error ?? body.message ?? response.statusText;
+            throw new Error(`Verification failed: ${msg}`);
+        }
+        const raw = (await response.json());
+        if (raw.success && raw.data !== undefined) {
+            return raw.data;
+        }
+        throw new Error('Verification failed: unexpected response format');
+    }
 }
 exports.PacSpace = PacSpace;
 // Errors
@@ -58,7 +155,9 @@ Object.defineProperty(exports, "InvalidApiKeyError", { enumerable: true, get: fu
 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, "CadenceLimitError", { enumerable: true, get: function () { return errors_1.CadenceLimitError; } });
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ServiceUnavailableError", { enumerable: true, get: function () { return errors_1.ServiceUnavailableError; } });
 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; } });

package/dist/index.js.map

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

package/dist/resources/balance.d.ts

@@ -1,6 +1,8 @@
 import type { HttpClient } from '../client';
-import type { EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, CompareOptions, CompareBalances, CompareResponse, ReceiptResponse, CheckpointOptions, CheckpointResponse } from '../types/balance';
+import type { EmitOptions, EmitAndWaitOptions, EmitResponse, DeriveOptions, DeriveResponse, CompareOptions, CompareBalances, CompareResponse, ReceiptResponse, CheckpointOptions, CheckpointResponse, ListCheckpointsOptions, ListCheckpointsResponse, DeltaStatusResponse, WaitForAnchoredOptions, UsageResponse, SequenceGapsOptions, SequenceGapsResponse, BulkDelta, BulkEmitOptions, BulkEmitResponse, ListWebhookDeliveriesOptions, ListWebhookDeliveriesResponse, ListCustomersOptions, ListCustomersResponse, GetCustomerOptions, CustomerLedgerDetail, InvoiceProofOptions, InvoiceProofResponse } from '../types/balance';
 import type { RequestOptions } from '../types/config';
+import type { CustomerUsageSummary, FlushSummariesOptions, QueuedUsageSummary, SubmissionAutomationOptions, SubmissionQueueState, SummaryFlushResult } from '../types/submission';
+import { SubmissionCoordinator } from './submission';
 /**
  * PacSpace Balance API resource.
  *
@@ -14,8 +16,12 @@ import type { RequestOptions } from '../types/config';
  */
 export declare class BalanceResource {
     private readonly client;
+    /**
+     * Submission automation coordinator for tenant-produced summaries.
+     */
+    readonly submission: SubmissionCoordinator;
     /** @internal */
-    constructor(client: HttpClient);
+    constructor(client: HttpClient, submissionOptions?: SubmissionAutomationOptions);
     /**
      * Record a credit or debit delta for a customer.
      *
@@ -59,6 +65,88 @@ export declare class BalanceResource {
      * ```
      */
     emitAndWait(customerId: string, delta: number, reason: string, options?: EmitAndWaitOptions): Promise<EmitResponse>;
+    /**
+     * Check the status of a previously emitted delta.
+     *
+     * @param anchorId - The anchor ID returned from emit.
+     * @param options - Request overrides.
+     * @returns Delta status with receipt and transaction details.
+     *
+     * @example
+     * ```typescript
+     * const status = await pac.balance.deltaStatus('anc_abc123');
+     * console.log(status.status); // 'QUEUED', 'ANCHORED', etc.
+     * ```
+     */
+    deltaStatus(anchorId: string, options?: RequestOptions): Promise<DeltaStatusResponse>;
+    /**
+     * Alias for `deltaStatus()` with lifecycle-oriented naming.
+     */
+    getAnchorStatus(anchorId: string, options?: RequestOptions): Promise<DeltaStatusResponse>;
+    /**
+     * Poll anchor lifecycle until it reaches a terminal status.
+     *
+     * Terminal statuses are `ANCHORED`, `VERIFIED`, and `FAILED`.
+     */
+    waitForAnchored(anchorId: string, options?: WaitForAnchoredOptions): Promise<DeltaStatusResponse>;
+    /**
+     * Retrieve tenant usage counters and remaining allotment.
+     */
+    usage(options?: RequestOptions): Promise<UsageResponse>;
+    /**
+     * Detect missing per-customer sequence ranges.
+     *
+     * Use this to identify gaps and re-emit missing deltas safely.
+     */
+    gaps(customerId: string, options?: SequenceGapsOptions): Promise<SequenceGapsResponse>;
+    /**
+     * Record multiple deltas in a single batch request.
+     *
+     * Ideal for end-of-day reconciliation or importing historical data.
+     * Up to 100 deltas per batch.
+     *
+     * @param deltas - Array of deltas to record.
+     * @param options - Request overrides.
+     * @returns Per-delta results with totals.
+     *
+     * @example
+     * ```typescript
+     * const result = await pac.balance.emitBatch([
+     *   { customerId: 'cust_123', delta: -100, reason: 'usage' },
+     *   { customerId: 'cust_456', delta: -200, reason: 'usage' },
+     * ]);
+     * console.log(result.totalQueued); // 2
+     * ```
+     */
+    emitBatch(deltas: BulkDelta[], options?: BulkEmitOptions): Promise<BulkEmitResponse>;
+    /**
+     * Queue one tenant-produced summary for SDK-managed submission.
+     */
+    queueSummary(summary: CustomerUsageSummary): QueuedUsageSummary;
+    /**
+     * Queue multiple tenant-produced summaries.
+     */
+    queueSummaries(summaries: CustomerUsageSummary[]): QueuedUsageSummary[];
+    /**
+     * Flush queued summaries immediately.
+     */
+    flushSummaries(options?: FlushSummariesOptions): Promise<SummaryFlushResult>;
+    /**
+     * Start periodic summary submission scheduling.
+     */
+    startSummaryScheduler(): void;
+    /**
+     * Stop periodic summary submission scheduling.
+     */
+    stopSummaryScheduler(): void;
+    /**
+     * Get queue/scheduler state for summary submission automation.
+     */
+    getSummaryQueueState(): SubmissionQueueState;
+    /**
+     * Stop scheduler and flush queued summaries (best for graceful shutdown).
+     */
+    shutdownSummaryScheduler(): Promise<void>;
     /**
      * Derive a customer's balance from all verified deltas.
      *
@@ -109,27 +197,38 @@ export declare class BalanceResource {
     /**
      * 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.
+     * When `options.period` is provided, returns a period-specific receipt (proof root,
+     * verifyUrl, verificationReference) suitable for sharing on invoices. When
+     * omitted, returns the full ledger receipt with all verified deltas.
      *
      * @param customerId - The customer account to generate a receipt for.
-     * @param options - Request overrides.
-     * @returns Receipt with verification data.
+     * @param options - Optional period (YYYY-MM) and request overrides.
+     * @returns Receipt with verification data; shape depends on whether period is set.
      *
      * @example
      * ```typescript
-     * const receipt = await pac.balance.receipt('cust_123');
-     * console.log(receipt.finalBalance);
-     * console.log(receipt.verification.itemHashes);
+     * // Period-specific receipt (shareable proof for invoices)
+     * const receipt = await pac.balance.receipt('cust_123', { period: '2026-02' });
+     * console.log(receipt.proofRoot);   // Include on invoice
+     * console.log(receipt.verifyUrl);   // Share with counterparty
+     *
+     * // Full ledger receipt
+     * const full = await pac.balance.receipt('cust_123');
+     * console.log(full.finalBalance);
      * ```
      */
-    receipt(customerId: string, options?: RequestOptions): Promise<ReceiptResponse>;
+    receipt(customerId: string, options?: InvoiceProofOptions & RequestOptions): Promise<ReceiptResponse | InvoiceProofResponse>;
+    /**
+     * @internal
+     * Generate a period-specific receipt (proof root, verifyUrl). Used by receipt().
+     */
+    private receiptForPeriod;
     /**
      * 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.
+     * Computes a proof root over all verified deltas in the billing window
+     * and records it on the public verification layer. The proof root 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.
@@ -144,5 +243,100 @@ export declare class BalanceResource {
      * ```
      */
     checkpoint(customerId?: string, options?: CheckpointOptions): Promise<CheckpointResponse>;
+    /**
+     * List committed checkpoints for your tenant.
+     *
+     * Returns a paginated list of checkpoints, optionally filtered by
+     * customer ID and/or billing period.
+     *
+     * @param options - Filter and pagination options.
+     * @returns Paginated list of checkpoints.
+     *
+     * @example
+     * ```typescript
+     * const { checkpoints } = await pac.balance.listCheckpoints({
+     *   period: '2026-02',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    listCheckpoints(options?: ListCheckpointsOptions): Promise<ListCheckpointsResponse>;
+    /**
+     * List webhook delivery history.
+     *
+     * @param options - Filter and pagination options.
+     * @returns Paginated list of webhook deliveries.
+     *
+     * @example
+     * ```typescript
+     * const { deliveries } = await pac.balance.listWebhookDeliveries({
+     *   status: 'failed',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    listWebhookDeliveries(options?: ListWebhookDeliveriesOptions): Promise<ListWebhookDeliveriesResponse>;
+    /**
+     * Retry a failed webhook delivery.
+     *
+     * @param eventId - The event ID of the failed delivery.
+     * @param options - Request overrides.
+     *
+     * @example
+     * ```typescript
+     * await pac.balance.retryWebhook('evt_abc123');
+     * ```
+     */
+    retryWebhook(eventId: string, options?: RequestOptions): Promise<{
+        eventId: string;
+        status: string;
+        message: string;
+    }>;
+    /**
+     * List all customer ledgers for your account.
+     *
+     * Each unique customerId passed to emit() automatically creates an
+     * isolated ledger. This method returns a paginated list of all ledgers.
+     *
+     * @param options - Search, pagination, and request overrides.
+     * @returns Paginated list of customer ledgers.
+     *
+     * @example
+     * ```typescript
+     * const { customers } = await pac.balance.customers();
+     * for (const c of customers) {
+     *   console.log(c.customerId, c.totalDeltas);
+     * }
+     * ```
+     */
+    customers(options?: ListCustomersOptions): Promise<ListCustomersResponse>;
+    /**
+     * Get the full ledger detail for a specific customer.
+     *
+     * Returns the derived ledger identifier, computed balance, delta count,
+     * and latest checkpoint. The ledger identifier is deterministic --
+     * the same customerId always produces the same identifier.
+     *
+     * @param customerId - The customer to look up.
+     * @param options - Activity pagination and request overrides.
+     * @returns Customer ledger detail including balance and identifiers.
+     *
+     * @example
+     * ```typescript
+     * const ledger = await pac.balance.customer('cust_001');
+     * console.log(ledger.ledgerIdentifier); // 0xA1b2...Ef34
+     * console.log(ledger.computedBalance);  // 4500.00
+     * ```
+     */
+    customer(customerId: string, options?: GetCustomerOptions): Promise<CustomerLedgerDetail>;
+    /**
+     * Generate an invoice-ready receipt for a customer's billing period.
+     *
+     * @deprecated Use `receipt(customerId, { period })` instead.
+     * @param customerId - The customer to generate the receipt for.
+     * @param options - Period selection and request overrides.
+     * @returns Receipt with proof root, verifyUrl, and verification data.
+     */
+    invoiceProof(customerId: string, options?: InvoiceProofOptions): Promise<InvoiceProofResponse>;
 }
 //# sourceMappingURL=balance.d.ts.map

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

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