@pulsebyshiga/node 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiga Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# @pulsebyshiga/node
+
+Official Node.js SDK for the Pulse API: quotes, offramp and onramp orders, bank
+name-enquiry, collection sessions, and webhook verification. Idempotent requests,
+automatic retries, and typed errors are built in.
+
+> **Status: pre-release (0.1.0).** The quote/offramp/onramp/banks surface is reconciled
+> 1:1 against the live engine contract
+> ([Swagger](https://engine-api.shiga.io/swagger/public/index.html)). The collection-session
+> and webhook surface is the product extension landing in the engine — see
+> [docs/engine-gap.md](../../docs/engine-gap.md).
+
+**New to the SDK?** The [backend integration guide](../../docs/backend-integration.md) walks
+through the whole server-side pattern — service methods, typed-error handling, webhooks, and
+handing the `cs_` session token to the browser component.
+
+## Requirements
+
+- Node.js ≥ 18.17
+- ESM (`import`) — this package does not ship a CommonJS build
+
+## Installation
+
+```sh
+npm install @pulsebyshiga/node
+# pnpm add @pulsebyshiga/node · yarn add @pulsebyshiga/node
+```
+
+## Usage
+
+```ts
+import Pulse, { useApiKey } from '@pulsebyshiga/node';
+
+const pulse = new Pulse(useApiKey(process.env.PULSE_API_KEY), {
+  webhookSecret: process.env.PULSE_WEBHOOK_SECRET,
+});
+```
+
+`useApiKey(...)` declares the server credential (a bare string still works for back-compat).
+The key is sent as `X-API-Key` (the engine's auth scheme) and as a `Bearer` token (the
+session surface's scheme) — one key, both means. Default host is
+`https://engine-api.shiga.io`; override with `baseUrl` for local development or a future
+sandbox.
+
+### Quote-first flow (engine)
+
+Everything starts with a locked price; orders are created from the `quote.id` before
+`expires_at` passes.
+
+**Just the rate (no order):** `rates.preview` wraps a quote for display — nothing settles
+and no order is created.
+
+```ts
+const rate = await pulse.rates.preview({
+  from: 'USDC',
+  to: 'NGN',
+  amount: '100.00',
+  network: 'BASE',
+});
+// → { rate, youSend, youReceive, expiresAt, quoteId }
+// Proceed to an order with quoteId to transact at exactly this locked rate.
+```
+
+**Offramp — crypto in, fiat out** (the collection direction):
+
+```ts
+const quote = await pulse.quotes.create({
+  amount: '100.50',
+  source_currency: 'USDC',
+  destination_currency: 'NGN',
+  network: 'BASE', // BASE | POLYGON | ARBITRUM | OPTIMISM | ETHEREUM | BSC
+});
+
+// Verify the payout account first (name enquiry).
+const account = await pulse.banks.resolve({ account_number: '0123456789', bank_code: '000013' });
+
+const order = await pulse.offramp.create({
+  quote_id: quote.id,
+  customer_id: 'your_user_123',
+  customer_name: account.account_name,
+  customer_email: 'user@example.com',
+  account_number: account.account_number,
+  account_name: account.account_name,
+  bank_code: account.bank_code,
+  bank_name: account.bank_name,
+});
+// Show order.deposit_address — the user sends quote.source_amount there.
+// Poll pulse.offramp.retrieve(order.id) until a terminal status.
+```
+
+**Onramp — fiat in, crypto out:**
+
+```ts
+const quote = await pulse.quotes.create({
+  amount: '50000.00',
+  source_currency: 'NGN',
+  destination_currency: 'USDC',
+  network: 'BASE',
+});
+const order = await pulse.onramp.create({
+  quote_id: quote.id,
+  customer_id: 'your_user_123',
+  customer_name: 'Ada Lovelace',
+  customer_email: 'user@example.com',
+  destination_address: '0xUserWallet…',
+});
+// order.account is the virtual bank account to pay (amount + expires_at).
+// Poll pulse.onramp.retrieve(order.id) until a terminal status.
+```
+
+**Banks:** `pulse.banks.list()` returns supported banks (name + NIP code).
+
+## Product surface — collection sessions (landing in the engine)
+
+The embedded components run on this surface; the dev mock implements it today and
+[docs/engine-gap.md](../../docs/engine-gap.md) tracks its adoption into the engine.
+
+### Create a collection session
+
+```ts
+// Naira gate — funds settle to the user's named virtual account.
+// First use provisions the account from BVN/NIN; returning users pass the reference.
+const session = await pulse.collectionSessions.create(
+  {
+    gate: 'naira',
+    target: { currency: 'NGN', amount: '1000000.00' },
+    asset: 'USDT',
+    network: 'solana',
+    user_ref: 'your_user_123',
+    account: { provision: true, bvn: '...', nin: '...' },
+  },
+  { idempotencyKey: `fund-${depositId}` },
+);
+
+// USD gate — funds settle to your omnibus account; no per-user identity.
+const usdSession = await pulse.collectionSessions.create({
+  gate: 'usd',
+  target: { currency: 'USD', amount: '500.00' },
+  asset: 'USDC',
+  network: 'base',
+});
+
+// Hand session.session_token (cs_*) to your frontend. Nothing else.
+```
+
+**Direction.** Sessions default to `offramp` (crypto in → fiat out). Pass
+`direction: 'onramp'` for the reverse — the user pays a virtual bank account
+(carried on the order as `pay_account`) and receives crypto at a wallet. The
+embedded component renders the matching UI automatically (bank-transfer
+instructions instead of a deposit address/QR).
+
+```ts
+const onrampSession = await pulse.collectionSessions.create({
+  gate: 'naira',
+  direction: 'onramp',
+  target: { currency: 'NGN', amount: '50000.00' },
+  asset: 'USDT',
+  network: 'base',
+  user_ref: 'your_user_123',
+  account: { provision: false, virtual_account_ref: 'va_...' },
+});
+```
+
+### Query orders
+
+```ts
+const order = await pulse.collectionOrders.retrieve(orderId); // ground truth for one order
+const page = await pulse.collectionOrders.list({ gate: 'naira', status: 'completed', limit: 50 });
+const relocked = await pulse.collectionOrders.refreshQuote(orderId); // new quote window for an expired order
+```
+
+## Webhooks
+
+Deliveries are signed with a `Pulse-Signature` header:
+
+```
+Pulse-Signature: t=<unix-seconds>,v1=<hex hmac-sha256 of "<t>.<raw body>">
+```
+
+Verification requires the **raw** request body — do not parse JSON first.
+
+```ts
+import express from 'express';
+
+app.post('/webhooks/pulse', express.raw({ type: '*/*' }), async (req, res) => {
+  const event = await pulse.webhooks.verifyOnce(req.body, req.header('pulse-signature') ?? '');
+  if (event === null) return res.sendStatus(200); // redelivery — already processed
+
+  switch (event.type) {
+    case 'disbursement.completed':
+      await creditPosition(event.data.order_id, event.data.disbursement.settlement_ref);
+      break;
+    case 'collection.amount.underpaid':
+      await handleShortfall(event.data); // { expected, received, asset, network, tx_hash }
+      break;
+  }
+  res.sendStatus(200);
+});
+```
+
+| Method                                                    | Behavior                                                                                                                                  |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `webhooks.verify(payload, header, secret?, options?)`     | Constant-time HMAC check + replay-window check (default tolerance 300 s). Returns the typed event or throws `SignatureVerificationError`. |
+| `webhooks.verifyOnce(payload, header, secret?, options?)` | Everything `verify` does, plus de-duplication on the event id. Returns `null` for a redelivery.                                           |
+
+Delivery is **at-least-once**: handlers must tolerate duplicates. `verifyOnce` de-duplicates
+in-process by default; multi-instance deployments must back it with a shared store:
+
+```ts
+import Pulse, { type ProcessedEventStore } from '@pulsebyshiga/node';
+
+const store: ProcessedEventStore = {
+  has: (id) => redis.exists(`pulse:evt:${id}`).then(Boolean),
+  add: (id) => redis.set(`pulse:evt:${id}`, '1', 'EX', 86_400).then(() => undefined),
+};
+
+const pulse = new Pulse(apiKey, { webhookSecret, webhookEventStore: store });
+```
+
+### Event types
+
+| Event                                      | Fires when                                                                                   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `collection.order.created`                 | Session created; the full order is attached.                                                 |
+| `collection.deposit.detected`              | On-chain deposit seen, not yet confirmed.                                                    |
+| `collection.deposit.confirmed`             | Deposit confirmed at the required depth.                                                     |
+| `collection.deposit.wrong_chain`           | Funds arrived on a network other than the order's; the order stays payable on the right one. |
+| `collection.amount.underpaid` / `overpaid` | Confirmed amount differs from the quote; carries `expected` vs `received`.                   |
+| `disbursement.completed`                   | Fiat settled. **The only event that credits a user.**                                        |
+| `collection.order.expired`                 | Quote window elapsed without payment.                                                        |
+| `collection.order.failed`                  | Terminal failure; carries a `reason`.                                                        |
+
+**Credit positions from `disbursement.completed` only.** Client-side callbacks such as the
+embed's `onSuccess` are UX signals and can be spoofed; the signed webhook cannot.
+
+## Reliability
+
+- **Idempotency** — every POST carries an `Idempotency-Key` (yours via `idempotencyKey`,
+  otherwise a generated UUID), so retries can never double-create an order.
+- **Retries** — network errors, HTTP 429 and 5xx are retried with exponential backoff
+  (2 retries, 250 ms base delay by default). Other 4xx responses throw immediately.
+- **Identification, not telemetry** — every request carries a static
+  `X-Pulse-SDK: pulse-node/<version> node/<version> (<platform>)` header so the API can
+  measure adoption and error rates per SDK version server-side. The SDK never emits
+  telemetry from your infrastructure.
+
+## Configuration
+
+```ts
+new Pulse(apiKey, options?)
+```
+
+| Option              | Type                  | Default                 | Description                                                         |
+| ------------------- | --------------------- | ----------------------- | ------------------------------------------------------------------- |
+| `baseUrl`           | `string`              | derived from key prefix | API host override (local mock, staging).                            |
+| `maxRetries`        | `number`              | `2`                     | Retry count for network errors / 429 / 5xx.                         |
+| `retryDelayMs`      | `number`              | `250`                   | Base backoff delay, doubled per attempt.                            |
+| `fetchImpl`         | `FetchLike`           | global `fetch`          | Injectable transport for tests/instrumentation.                     |
+| `webhookSecret`     | `string`              | —                       | Default secret for `webhooks.verify*`; can also be passed per call. |
+| `webhookEventStore` | `ProcessedEventStore` | in-memory               | Shared de-duplication store for `verifyOnce`.                       |
+
+## Error handling
+
+All errors extend `PulseError`:
+
+| Class                        | Thrown when                                                        | Notable fields                                             |
+| ---------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `PulseApiError`              | API returned a non-retryable error, or retries were exhausted      | `status`, `code` (e.g. `network_not_enabled`), `requestId` |
+| `PulseConnectionError`       | Request never produced an HTTP response                            | —                                                          |
+| `SignatureVerificationError` | Webhook signature invalid, malformed, or outside the replay window | —                                                          |
+
+```ts
+import { PulseApiError } from '@pulsebyshiga/node';
+
+try {
+  await pulse.collectionSessions.create(params);
+} catch (error) {
+  if (error instanceof PulseApiError && error.code === 'network_not_enabled') {
+    // asset/network is disabled in your partner configuration
+  } else {
+    throw error;
+  }
+}
+```
+
+## TypeScript
+
+Written in TypeScript; every request, response, webhook event, and error is fully typed and
+exported (`CollectionOrder`, `WebhookEvent`, `PartnerConfig`, `Network`, …). The webhook
+event union discriminates on `type`, so a `switch` narrows `event.data` automatically.
+
+## Security model
+
+- `sk_*` keys and BVN/NIN are **server-to-server only** — never ship them to a browser or
+  mobile app. Clients receive only the short-lived, single-order `session_token` (`cs_*`).
+- Verify every webhook before acting on it; verification is constant-time and replay-bounded.
+- Credit users exclusively from the signed `disbursement.completed` event.
+
+## License
+
+[MIT](../../LICENSE) © Shiga Digital

package/dist/auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Auth. One SDK, two ways to authenticate — the caller declares which credential
+ * it holds and every feature routes itself:
+ *
+ *   - apiKey  : the partner's root secret. Full engine surface. SERVER ONLY —
+ *               it must never reach a browser bundle (see the guard in client.ts).
+ *   - session : a short-lived, single-order `cs_*` minted server-side by
+ *               collectionSessions.create(). Safe to hand to a browser/app.
+ *
+ * These are the only two credentials that exist: the session token is a
+ * scoped-down delegate the API key mints, so a caller never holds both — pick
+ * the one for where the code runs. The `use*` factories are the ergonomic entry
+ * points; pass their result to `new Pulse(...)`.
+ */
+export type PulseAuth = {
+    readonly mode: 'apiKey';
+    readonly apiKey: string;
+} | {
+    readonly mode: 'session';
+    readonly sessionToken: string;
+};
+/** Full engine access with the partner's root key. Server-side only. */
+export declare function useApiKey(apiKey: string): PulseAuth;
+/** Scope every call to one order's session token (`cs_*`). Browser-safe. */
+export declare function useSession(sessionToken: string): PulseAuth;
+/** Normalize the constructor arg: a bare string is treated as an API key. */
+export declare function toAuth(auth: string | PulseAuth): PulseAuth;

package/dist/auth.js

@@ -0,0 +1,12 @@
+/** Full engine access with the partner's root key. Server-side only. */
+export function useApiKey(apiKey) {
+    return { mode: 'apiKey', apiKey };
+}
+/** Scope every call to one order's session token (`cs_*`). Browser-safe. */
+export function useSession(sessionToken) {
+    return { mode: 'session', sessionToken };
+}
+/** Normalize the constructor arg: a bare string is treated as an API key. */
+export function toAuth(auth) {
+    return typeof auth === 'string' ? { mode: 'apiKey', apiKey: auth } : auth;
+}

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import { type PulseAuth } from './auth.js';
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export type HttpClientOptions = {
+    /** Override the API host (e.g. a local Pulse or the dev mock). Otherwise derived from the key prefix. */
+    baseUrl?: string;
+    /** Retries on network errors, 429 and 5xx. Default 2. */
+    maxRetries?: number;
+    /** Base backoff delay. Default 250ms, doubled per attempt. */
+    retryDelayMs?: number;
+    fetchImpl?: FetchLike;
+};
+export type QueryValue = string | number | undefined;
+export type RequestParams = {
+    method: 'GET' | 'POST';
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    idempotencyKey?: string;
+};
+export declare class HttpClient {
+    private readonly auth;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly fetchImpl;
+    constructor(auth: PulseAuth, options?: HttpClientOptions);
+    request<T>(params: RequestParams): Promise<T>;
+    private authHeaders;
+    private buildUrl;
+}

package/dist/client.js

@@ -0,0 +1,121 @@
+import { randomUUID } from 'node:crypto';
+import { PulseAccessError, PulseApiError, PulseConnectionError } from './errors.js';
+import { SDK_VERSION } from './version.js';
+// The live engine host (public Swagger at /swagger/public/index.html).
+// A sandbox host is on the gap list; override baseUrl until one exists.
+const DEFAULT_BASE_URL = 'https://engine-api.shiga.io';
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 250;
+// Identification only — lets the API measure adoption/error rates per SDK
+// version server-side. The SDK never emits telemetry from partner infra.
+const SDK_IDENTIFIER = `pulse-node/${SDK_VERSION} node/${process.version} (${process.platform})`;
+export class HttpClient {
+    auth;
+    baseUrl;
+    maxRetries;
+    retryDelayMs;
+    fetchImpl;
+    constructor(auth, options = {}) {
+        if (auth.mode === 'apiKey' && auth.apiKey.trim() === '') {
+            throw new PulseConnectionError('Pulse: apiKey is required');
+        }
+        if (auth.mode === 'session' && auth.sessionToken.trim() === '') {
+            throw new PulseConnectionError('Pulse: sessionToken is required');
+        }
+        // Never let a root key reach a browser bundle: it is exfiltratable from
+        // devtools/source. Sessions (cs_*) are the browser-safe credential.
+        if (auth.mode === 'apiKey' && typeof window !== 'undefined') {
+            throw new PulseAccessError('Pulse: an API key must never run in a browser. Mint a session server-side ' +
+                '(collectionSessions.create) and use useSession(cs_…) on the client.');
+        }
+        this.auth = auth;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+        this.fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    async request(params) {
+        const url = this.buildUrl(params.path, params.query);
+        const headers = {
+            Accept: 'application/json',
+            'X-Pulse-SDK': SDK_IDENTIFIER,
+            ...this.authHeaders(),
+        };
+        if (params.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (params.method === 'POST') {
+            // Idempotency on every POST: safe retries even when the caller passes no key.
+            headers['Idempotency-Key'] = params.idempotencyKey ?? randomUUID();
+        }
+        const init = {
+            method: params.method,
+            headers,
+            body: params.body === undefined ? undefined : JSON.stringify(params.body),
+        };
+        let lastError = new PulseConnectionError(`Request to ${params.path} failed`);
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            if (attempt > 0) {
+                await sleep(this.retryDelayMs * 2 ** (attempt - 1));
+            }
+            let response;
+            try {
+                response = await this.fetchImpl(url, init);
+            }
+            catch (error) {
+                lastError = new PulseConnectionError(`Request to ${params.path} failed: ${describeError(error)}`);
+                continue;
+            }
+            if (response.status >= 500 || response.status === 429) {
+                lastError = await toApiError(response);
+                continue;
+            }
+            if (!response.ok) {
+                throw await toApiError(response);
+            }
+            return (await response.json());
+        }
+        throw lastError;
+    }
+    authHeaders() {
+        if (this.auth.mode === 'session') {
+            return { Authorization: `Bearer ${this.auth.sessionToken}` };
+        }
+        // apiKey: the engine authenticates with X-API-Key (Swagger ApiKeyAuth); the
+        // product surface was specified with a Bearer. One key, both schemes, until
+        // the engine settles on one (see docs/engine-gap.md).
+        return { 'X-API-Key': this.auth.apiKey, Authorization: `Bearer ${this.auth.apiKey}` };
+    }
+    buildUrl(path, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query !== undefined) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+}
+async function toApiError(response) {
+    let code = 'unknown_error';
+    let message = `HTTP ${response.status}`;
+    try {
+        const body = (await response.json());
+        if (typeof body.error?.code === 'string')
+            code = body.error.code;
+        if (typeof body.error?.message === 'string')
+            message = body.error.message;
+    }
+    catch {
+        // Non-JSON error body — keep the defaults.
+    }
+    return new PulseApiError(response.status, code, message, response.headers.get('request-id'));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class PulseError extends Error {
+    constructor(message: string);
+}
+export declare class PulseApiError extends PulseError {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, requestId: string | null);
+}
+export declare class PulseConnectionError extends PulseError {
+}
+export declare class SignatureVerificationError extends PulseError {
+}
+/**
+ * A credential was used where it isn't allowed — e.g. an API key constructed in
+ * a browser, or a feature invoked without the credential it needs.
+ */
+export declare class PulseAccessError extends PulseError {
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+export class PulseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class PulseApiError extends PulseError {
+    status;
+    code;
+    requestId;
+    constructor(status, code, message, requestId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+export class PulseConnectionError extends PulseError {
+}
+export class SignatureVerificationError extends PulseError {
+}
+/**
+ * A credential was used where it isn't allowed — e.g. an API key constructed in
+ * a browser, or a feature invoked without the credential it needs.
+ */
+export class PulseAccessError extends PulseError {
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { type PulseAuth } from './auth.js';
+import { type HttpClientOptions } from './client.js';
+import { Banks } from './resources/banks.js';
+import { CollectionOrders } from './resources/collectionOrders.js';
+import { CollectionSessions } from './resources/collectionSessions.js';
+import { Offramp } from './resources/offramp.js';
+import { Onramp } from './resources/onramp.js';
+import { Quotes } from './resources/quotes.js';
+import { Rates } from './resources/rates.js';
+import { Webhooks, type ProcessedEventStore } from './webhooks.js';
+export type PulseOptions = HttpClientOptions & {
+    /** Default secret for webhooks.verify(); can also be passed per call. */
+    webhookSecret?: string;
+    /** Backing store for verifyOnce() de-duplication. Defaults to in-memory (single process). */
+    webhookEventStore?: ProcessedEventStore;
+};
+export declare class Pulse {
+    readonly quotes: Quotes;
+    readonly rates: Rates;
+    readonly offramp: Offramp;
+    readonly onramp: Onramp;
+    readonly banks: Banks;
+    readonly collectionSessions: CollectionSessions;
+    readonly collectionOrders: CollectionOrders;
+    readonly webhooks: Webhooks;
+    /**
+     * @param auth Either a bare API-key string (treated as `useApiKey`), or an
+     *   auth descriptor from `useApiKey` / `useSession`.
+     */
+    constructor(auth: string | PulseAuth, options?: PulseOptions);
+}
+export default Pulse;
+export * from './types.js';
+export * from './errors.js';
+export { useApiKey, useSession, toAuth, type PulseAuth } from './auth.js';
+export { Rates, type RatePreview, type RatePreviewParams } from './resources/rates.js';
+export { InMemoryProcessedEventStore, Webhooks, signPayload, type ProcessedEventStore, type VerifyOptions, } from './webhooks.js';
+export type { FetchLike, HttpClientOptions } from './client.js';
+export type { CreateSessionOptions } from './resources/collectionSessions.js';
+export { SDK_VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,45 @@
+import { toAuth } from './auth.js';
+import { HttpClient } from './client.js';
+import { Banks } from './resources/banks.js';
+import { CollectionOrders } from './resources/collectionOrders.js';
+import { CollectionSessions } from './resources/collectionSessions.js';
+import { Offramp } from './resources/offramp.js';
+import { Onramp } from './resources/onramp.js';
+import { Quotes } from './resources/quotes.js';
+import { Rates } from './resources/rates.js';
+import { Webhooks } from './webhooks.js';
+export class Pulse {
+    // Engine surface — live contract (quote-first).
+    quotes;
+    rates;
+    offramp;
+    onramp;
+    banks;
+    // Product surface — collection sessions + webhooks (see docs/engine-gap.md).
+    collectionSessions;
+    collectionOrders;
+    webhooks;
+    /**
+     * @param auth Either a bare API-key string (treated as `useApiKey`), or an
+     *   auth descriptor from `useApiKey` / `useSession`.
+     */
+    constructor(auth, options = {}) {
+        const { webhookSecret, webhookEventStore, ...httpOptions } = options;
+        const http = new HttpClient(toAuth(auth), httpOptions);
+        this.quotes = new Quotes(http);
+        this.rates = new Rates(http);
+        this.offramp = new Offramp(http);
+        this.onramp = new Onramp(http);
+        this.banks = new Banks(http);
+        this.collectionSessions = new CollectionSessions(http);
+        this.collectionOrders = new CollectionOrders(http);
+        this.webhooks = new Webhooks(webhookSecret, webhookEventStore);
+    }
+}
+export default Pulse;
+export * from './types.js';
+export * from './errors.js';
+export { useApiKey, useSession, toAuth } from './auth.js';
+export { Rates } from './resources/rates.js';
+export { InMemoryProcessedEventStore, Webhooks, signPayload, } from './webhooks.js';
+export { SDK_VERSION } from './version.js';

package/dist/resources/banks.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from '../client.js';
+import type { Bank, ResolveAccountParams, VerifiedAccount } from '../types.js';
+export declare class Banks {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Supported banks (name + NIP code) for offramp payout targets. */
+    list(): Promise<Bank[]>;
+    /** Name enquiry — verify an account before creating an offramp order against it. */
+    resolve(params: ResolveAccountParams): Promise<VerifiedAccount>;
+}