@pacspace-io/sdk 0.1.0 → 0.2.1

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, WaitForVerifiedOptions, UsageResponse, SequenceGapsOptions, SequenceGapsResponse, BulkDelta, BulkEmitOptions, BulkEmitResponse, ListWebhookDeliveriesOptions, ListWebhookDeliveriesResponse, ListCustomersOptions, ListCustomersResponse, GetCustomerOptions, CustomerRecordDetail, 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 recordId - The record ID returned from emit.
+     * @param options - Request overrides.
+     * @returns Delta status with receipt and transaction details.
+     *
+     * @example
+     * ```typescript
+     * const status = await pac.balance.deltaStatus('rec_abc123');
+     * console.log(status.status); // 'QUEUED', 'PROCESSING', etc.
+     * ```
+     */
+    deltaStatus(recordId: string, options?: RequestOptions): Promise<DeltaStatusResponse>;
+    /**
+     * Alias for `deltaStatus()` with lifecycle-oriented naming.
+     */
+    getRecordStatus(recordId: string, options?: RequestOptions): Promise<DeltaStatusResponse>;
+    /**
+     * Poll record lifecycle until it reaches a terminal status.
+     *
+     * Terminal statuses are `VERIFIED` and `FAILED`.
+     */
+    waitForVerified(recordId: string, options?: WaitForVerifiedOptions): 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,40 +197,158 @@ 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 record 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 record 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.
-     * @returns Checkpoint details with Merkle root and status.
+     * @returns Checkpoint details with proof root and status.
      *
      * @example
      * ```typescript
      * const checkpoint = await pac.balance.checkpoint('cust_123', {
      *   period: '2026-02',
      * });
-     * console.log(checkpoint.merkleRoot); // Include in your invoice
+     * console.log(checkpoint.proofRoot); // Include in your invoice
      * ```
      */
     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 balance records for your account.
+     *
+     * Each unique customerId passed to emit() automatically creates an
+     * isolated customer record. This method returns a paginated list.
+     *
+     * @param options - Search, pagination, and request overrides.
+     * @returns Paginated list of customer records.
+     *
+     * @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 record detail for a specific customer.
+     *
+     * Returns the derived customer reference, computed balance, delta count,
+     * and latest checkpoint. The customer reference is deterministic.
+     *
+     * @param customerId - The customer to look up.
+     * @param options - Activity pagination and request overrides.
+     * @returns Customer detail including balance and references.
+     *
+     * @example
+     * ```typescript
+     * const customer = await pac.balance.customer('cust_001');
+     * console.log(customer.customerReference); // 0xA1b2...Ef34
+     * console.log(customer.computedBalance);   // 4500.00
+     * ```
+     */
+    customer(customerId: string, options?: GetCustomerOptions): Promise<CustomerRecordDetail>;
+    private normalizeEmitResponse;
+    private mergeEmitWithStatus;
+    private normalizeDeltaStatusResponse;
+    private normalizeDeriveResponse;
+    private normalizeCompareResponse;
+    private normalizeReceiptResponse;
+    private normalizeInvoiceProofResponse;
+    private normalizeCheckpointResponse;
+    private normalizeListCheckpointsResponse;
+    private normalizeSequenceGapsResponse;
+    private normalizeBulkEmitResponse;
+    private normalizeListCustomersResponse;
+    private normalizeCustomerDetailResponse;
+    /**
+     * 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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"}