@pacspace-io/sdk 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# @pacspace-io/sdk
+
+Official TypeScript SDK for the [PacSpace Balance API](https://docs.pacspace.io). Zero dependencies, fully typed, built for Node.js 18+.
+
+## Install
+
+```bash
+npm install @pacspace-io/sdk
+```
+
+## Quick Start
+
+```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');
+console.log(delta.receiptId); // Store for later verification
+
+// 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',
+});
+```
+
+## API Reference
+
+### `new PacSpace(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | **required** | Your PacSpace API key (`pk_live_*` or `pk_test_*`) |
+| `baseUrl` | `string` | `https://balance-api.pacspace.io` | API base URL |
+| `chainId` | `number` | auto-detected | Default chain ID (296 for sandbox, 295 for production) |
+| `maxRetries` | `number` | `2` | Max retries on transient errors |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `webhookSecret` | `string` | — | Webhook signing secret (enables `pac.webhooks`) |
+
+### Balance API
+
+#### `pac.balance.emit(customerId, delta, reason, options?)`
+
+Record a credit or debit delta. Returns immediately with `QUEUED` status.
+
+```typescript
+const delta = await pac.balance.emit('cust_123', -42.50, 'usage_charge', {
+  referenceId: 'inv_001',
+  metadata: { plan: 'growth' },
+});
+```
+
+#### `pac.balance.emitAndWait(customerId, delta, reason, options?)`
+
+Record a delta and poll until it reaches a terminal status (`VERIFIED` or `FAILED`).
+
+```typescript
+const verified = await pac.balance.emitAndWait('cust_123', -42.50, 'usage', {
+  timeout: 30_000,
+  pollInterval: 1000,
+});
+```
+
+#### `pac.balance.derive(customerId, options?)`
+
+Derive a customer's balance from all verified deltas.
+
+```typescript
+const result = await pac.balance.derive('cust_123');
+console.log(result.computedBalance);
+
+// With checkpointing for efficiency:
+const next = await pac.balance.derive('cust_123', {
+  startingBalance: result.computedBalance,
+  startingCheckpoint: result.latestReceiptId!,
+});
+```
+
+#### `pac.balance.compare(customerId, balances, options?)`
+
+Compare balances against neutral truth for dispute resolution.
+
+```typescript
+const report = await pac.balance.compare('cust_123', {
+  yours: 95000,
+  theirs: 98000,
+});
+
+if (report.matchesYours) {
+  console.log('Your balance is correct');
+}
+```
+
+#### `pac.balance.receipt(customerId, options?)`
+
+Generate a verifiable receipt with cryptographic proof data.
+
+```typescript
+const receipt = await pac.balance.receipt('cust_123');
+console.log(receipt.finalBalance);
+console.log(receipt.verification.itemHashes);
+```
+
+#### `pac.balance.checkpoint(customerId?, options?)`
+
+Commit a period-end checkpoint (Merkle root anchored on-chain).
+
+```typescript
+const checkpoint = await pac.balance.checkpoint('cust_123', {
+  period: '2026-02',
+});
+console.log(checkpoint.merkleRoot); // Include in your invoice
+```
+
+### Webhooks
+
+Verify webhook signatures and process events with type safety.
+
+```typescript
+const pac = new PacSpace({
+  apiKey: process.env.PACSPACE_API_KEY!,
+  webhookSecret: process.env.PACSPACE_WEBHOOK_SECRET!,
+});
+
+// Express middleware
+app.use('/webhooks', express.json({
+  verify: (req, _res, buf) => { (req as any).rawBody = buf.toString(); }
+}));
+
+app.post('/webhooks/pacspace', pac.webhooks!.middleware(), (req, res) => {
+  const event = (req as any).pacspaceEvent;
+
+  if (event.event === 'delta.verified') {
+    console.log('Delta verified:', event.data.receiptId);
+  }
+
+  res.status(200).json({ received: true });
+});
+
+// Manual verification
+const event = pac.webhooks!.verify(signature, timestamp, rawBody);
+```
+
+### Error Handling
+
+All errors extend `PacSpaceError` with structured data:
+
+```typescript
+import { PacSpace, InsufficientCreditsError, RateLimitError } from '@pacspace-io/sdk';
+
+try {
+  await pac.balance.emit('cust_123', -1000, 'charge');
+} catch (err) {
+  if (err instanceof InsufficientCreditsError) {
+    console.log('Buy more credits');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Retry after ${err.retryAfter}s`);
+  }
+}
+```
+
+| Error Class | Status | When |
+|-------------|--------|------|
+| `ValidationError` | 400 | Invalid request data |
+| `InvalidApiKeyError` | 401 | Bad or missing API key |
+| `InsufficientCreditsError` | 402 | Not enough credits |
+| `NotFoundError` | 404 | Resource not found |
+| `ContractNotDeployedError` | 412 | No contract provisioned |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `TimeoutError` | — | Polling timeout exceeded |
+
+## Environment Detection
+
+The SDK auto-detects your environment from the API key prefix:
+
+- `pk_test_*` → Sandbox (Hedera Testnet, chain 296)
+- `pk_live_*` → Production (Hedera Mainnet, chain 295)
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- TypeScript 5+ (for full type inference)

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import type { PacSpaceConfig, RequestOptions } from './types/config';
+/**
+ * Low-level HTTP client for the PacSpace API.
+ * Handles authentication, response unwrapping, retries, and error mapping.
+ *
+ * @internal — Use the PacSpace class instead of this directly.
+ */
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly fetchFn;
+    /** Default chain ID, auto-detected from API key prefix or explicit config. */
+    readonly defaultChainId: number | undefined;
+    /** Default credit pool ID. */
+    readonly defaultCreditPoolId: number | undefined;
+    constructor(config: PacSpaceConfig);
+    /**
+     * Make a GET request and return unwrapped data.
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a POST request and return unwrapped data.
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Core request method with retry logic, auth injection, and response unwrapping.
+     */
+    private request;
+    /**
+     * Build HTTP headers with auth and optional overrides.
+     */
+    private buildHeaders;
+    /**
+     * Fetch with an AbortController-based timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * Calculate retry delay with exponential backoff.
+     * Respects Retry-After header for rate limit errors.
+     */
+    private getRetryDelay;
+    /**
+     * Safely parse JSON from a response, returning null on failure.
+     */
+    private safeParseJson;
+    /**
+     * Extract a string error message from a parsed error body.
+     */
+    private extractErrorMessage;
+    /**
+     * Auto-detect chain ID from API key prefix.
+     */
+    private detectChainId;
+    /**
+     * Promise-based sleep utility.
+     */
+    private sleep;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAwBrE;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,8BAA8B;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;gBAErC,MAAM,EAAE,cAAc;IA4BlC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhE;;OAEG;IACG,IAAI,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC;IAIb;;OAEG;YACW,OAAO;IAwFrB;;OAEG;IACH,OAAO,CAAC,YAAY;IAwBpB;;OAEG;YACW,gBAAgB;IAoC9B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAcrB;;OAEG;YACW,aAAa;IAU3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}

package/dist/client.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("./errors");
+/**
+ * Default base URL for the PacSpace API.
+ */
+const DEFAULT_BASE_URL = 'https://balance-api.pacspace.io';
+/**
+ * Default request timeout in milliseconds.
+ */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Default maximum number of retries on transient errors.
+ */
+const DEFAULT_MAX_RETRIES = 2;
+/**
+ * HTTP status codes that are safe to retry.
+ */
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Low-level HTTP client for the PacSpace API.
+ * Handles authentication, response unwrapping, retries, and error mapping.
+ *
+ * @internal — Use the PacSpace class instead of this directly.
+ */
+class HttpClient {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new errors_1.PacSpaceError('API key is required. Pass it via new PacSpace({ apiKey: "pk_..." })', 0, 'MISSING_API_KEY');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.fetchFn = config.fetch || globalThis.fetch;
+        // Auto-detect chain ID from API key prefix
+        this.defaultChainId = config.chainId ?? this.detectChainId(config.apiKey);
+        this.defaultCreditPoolId = config.creditPoolId;
+        if (!this.fetchFn) {
+            throw new errors_1.PacSpaceError('No global fetch found. Upgrade to Node 18+ or pass a custom fetch implementation via config.', 0, 'NO_FETCH');
+        }
+    }
+    /**
+     * Make a GET request and return unwrapped data.
+     */
+    async get(path, options) {
+        return this.request('GET', path, undefined, options);
+    }
+    /**
+     * Make a POST request and return unwrapped data.
+     */
+    async post(path, body, options) {
+        return this.request('POST', path, body, options);
+    }
+    /**
+     * Core request method with retry logic, auth injection, and response unwrapping.
+     */
+    async request(method, path, body, options) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = this.buildHeaders(options);
+        const requestInit = {
+            method,
+            headers,
+            signal: options?.signal,
+        };
+        if (body !== undefined) {
+            requestInit.body = JSON.stringify(body);
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            // Wait before retrying (exponential backoff)
+            if (attempt > 0) {
+                const delayMs = this.getRetryDelay(attempt, lastError);
+                await this.sleep(delayMs);
+            }
+            let response;
+            try {
+                response = await this.fetchWithTimeout(url, requestInit);
+            }
+            catch (err) {
+                // Network errors are retryable
+                lastError =
+                    err instanceof Error
+                        ? err
+                        : new Error(String(err));
+                if (attempt < this.maxRetries) {
+                    continue;
+                }
+                throw new errors_1.PacSpaceError(`Network error: ${lastError.message}`, 0, 'NETWORK_ERROR', path);
+            }
+            // Successful response — parse and unwrap
+            if (response.ok) {
+                const raw = (await response.json());
+                if (raw.success && raw.data !== undefined) {
+                    return raw.data;
+                }
+                // success: false in a 2xx response (shouldn't happen, but handle it)
+                throw (0, errors_1.mapApiError)(response.status, raw.error || raw.message || 'Unknown error', path, response.headers);
+            }
+            // Non-retryable error — throw immediately
+            if (!RETRYABLE_STATUS_CODES.has(response.status)) {
+                const errorBody = await this.safeParseJson(response);
+                const message = this.extractErrorMessage(errorBody, response.statusText);
+                throw (0, errors_1.mapApiError)(response.status, message, path, response.headers);
+            }
+            // Retryable error — continue to next attempt
+            const errorBody = await this.safeParseJson(response);
+            lastError = (0, errors_1.mapApiError)(response.status, this.extractErrorMessage(errorBody, response.statusText), path, response.headers);
+        }
+        // All retries exhausted
+        throw lastError || new errors_1.PacSpaceError('Request failed', 0, 'UNKNOWN', path);
+    }
+    /**
+     * Build HTTP headers with auth and optional overrides.
+     */
+    buildHeaders(options) {
+        const headers = {
+            'X-Api-Key': this.apiKey,
+            'Content-Type': 'application/json',
+            'User-Agent': '@pacspace-io/sdk/0.1.0',
+        };
+        const chainId = options?.chainId ?? this.defaultChainId;
+        if (chainId !== undefined) {
+            headers['X-Chain-Id'] = String(chainId);
+        }
+        const creditPoolId = options?.creditPoolId ?? this.defaultCreditPoolId;
+        if (creditPoolId !== undefined) {
+            headers['X-Credit-Pool-Id'] = String(creditPoolId);
+        }
+        if (options?.idempotencyKey) {
+            headers['Idempotency-Key'] = options.idempotencyKey;
+        }
+        return headers;
+    }
+    /**
+     * Fetch with an AbortController-based timeout.
+     */
+    async fetchWithTimeout(url, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        // Merge external signal with timeout signal
+        const externalSignal = init.signal;
+        if (externalSignal) {
+            externalSignal.addEventListener('abort', () => controller.abort());
+        }
+        try {
+            return await this.fetchFn(url, {
+                ...init,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === 'AbortError') {
+                if (externalSignal?.aborted) {
+                    throw new errors_1.PacSpaceError('Request cancelled', 0, 'CANCELLED', url);
+                }
+                throw new errors_1.PacSpaceError(`Request timed out after ${this.timeout}ms`, 0, 'TIMEOUT', url);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Calculate retry delay with exponential backoff.
+     * Respects Retry-After header for rate limit errors.
+     */
+    getRetryDelay(attempt, lastError) {
+        // Respect rate limit retry-after
+        if (lastError instanceof errors_1.RateLimitError && lastError.retryAfter) {
+            return lastError.retryAfter * 1000;
+        }
+        // Exponential backoff: 500ms, 1500ms, 3500ms, ...
+        const baseDelay = 500;
+        const delay = baseDelay * Math.pow(2, attempt - 1);
+        // Add jitter (0–25% of delay)
+        const jitter = delay * 0.25 * Math.random();
+        return delay + jitter;
+    }
+    /**
+     * Safely parse JSON from a response, returning null on failure.
+     */
+    async safeParseJson(response) {
+        try {
+            return (await response.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Extract a string error message from a parsed error body.
+     */
+    extractErrorMessage(errorBody, fallback) {
+        if (!errorBody)
+            return fallback;
+        if (typeof errorBody.error === 'string')
+            return errorBody.error;
+        if (typeof errorBody.message === 'string')
+            return errorBody.message;
+        return fallback;
+    }
+    /**
+     * Auto-detect chain ID from API key prefix.
+     */
+    detectChainId(apiKey) {
+        if (apiKey.startsWith('pk_test_')) {
+            return 296; // Hedera Testnet
+        }
+        if (apiKey.startsWith('pk_live_')) {
+            return 295; // Hedera Mainnet
+        }
+        return undefined;
+    }
+    /**
+     * Promise-based sleep utility.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.HttpClient = HttpClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Base error class for all PacSpace SDK errors.
+ * Extends native Error with structured API error data.
+ */
+export declare class PacSpaceError extends Error {
+    /** HTTP status code from the API response. */
+    readonly statusCode: number;
+    /** Machine-readable error code (e.g., 'INSUFFICIENT_CREDITS'). */
+    readonly code: string;
+    /** The original API request path that triggered this error. */
+    readonly requestPath?: string;
+    constructor(message: string, statusCode: number, code: string, requestPath?: string);
+}
+/**
+ * Thrown when the API key is missing, invalid, or disabled (HTTP 401).
+ */
+export declare class InvalidApiKeyError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when the tenant has insufficient credits for the operation (HTTP 402).
+ */
+export declare class InsufficientCreditsError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when the requested resource is not found (HTTP 404).
+ */
+export declare class NotFoundError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when no contract is deployed for the tenant (HTTP 412).
+ */
+export declare class ContractNotDeployedError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when the API rate limit is exceeded (HTTP 429).
+ */
+export declare class RateLimitError extends PacSpaceError {
+    /** Seconds to wait before retrying, if provided by the API. */
+    readonly retryAfter: number | null;
+    constructor(message?: string, retryAfter?: number | null, requestPath?: string);
+}
+/**
+ * Thrown when the API returns a validation error (HTTP 400).
+ */
+export declare class ValidationError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when a polling operation exceeds the configured timeout.
+ */
+export declare class TimeoutError extends PacSpaceError {
+    constructor(message?: string, requestPath?: string);
+}
+/**
+ * Thrown when the webhook signature is invalid.
+ */
+export declare class WebhookVerificationError extends PacSpaceError {
+    constructor(message?: string);
+}
+/**
+ * Map an HTTP status code + API response to the appropriate typed error.
+ * @internal
+ */
+export declare function mapApiError(statusCode: number, message: string, requestPath?: string, headers?: Headers): PacSpaceError;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM;CAWvB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,SAA+B,EAAE,WAAW,CAAC,EAAE,MAAM;CAIzE;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAEvD,OAAO,SAA4C,EACnD,WAAW,CAAC,EAAE,MAAM;CAKvB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,aAAa;gBAClC,OAAO,SAAuB,EAAE,WAAW,CAAC,EAAE,MAAM;CAIjE;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAEvD,OAAO,SAA0D,EACjE,WAAW,CAAC,EAAE,MAAM;CAKvB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGjC,OAAO,SAAwB,EAC/B,UAAU,GAAE,MAAM,GAAG,IAAW,EAChC,WAAW,CAAC,EAAE,MAAM;CAMvB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,SAAyB,EAAE,WAAW,CAAC,EAAE,MAAM;CAInE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,aAAa;gBAE3C,OAAO,SAAiD,EACxD,WAAW,CAAC,EAAE,MAAM;CAKvB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,SAA0C;CAI9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,aAAa,CAuBf"}