@pulsebyshiga/node 0.2.0 → 0.2.1

package/README.md

@@ -1,18 +1,15 @@
 # @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.
+The 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 fully-typed responses and 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).
+Server-side only: your `sk_*` key and user identity (BVN/NIN) never leave your backend. The
+browser and mobile SDKs receive only a short-lived, single-order session token (`cs_*`).
 
-**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.
+> **Pre-release (0.2.0).** The public API may still change. Quotes, offramp/onramp orders, and
+> bank name-enquiry map 1:1 to the live engine contract
+> ([Swagger](https://engine-api.shiga.io/swagger/public/index.html)).
 
 ## Requirements
 
@@ -26,7 +23,7 @@ npm install @pulsebyshiga/node
 # pnpm add @pulsebyshiga/node · yarn add @pulsebyshiga/node
 ```
 
-## Usage
+## Quickstart
 
 ```ts
 import Pulse, { useApiKey } from '@pulsebyshiga/node';
@@ -34,21 +31,28 @@ import Pulse, { useApiKey } from '@pulsebyshiga/node';
 const pulse = new Pulse(useApiKey(process.env.PULSE_API_KEY), {
   webhookSecret: process.env.PULSE_WEBHOOK_SECRET,
 });
+
+// Lock a price, then create an order against it.
+const quote = await pulse.quotes.create({
+  amount: '100.50',
+  source_currency: 'USDC',
+  destination_currency: 'NGN',
+  network: 'BASE',
+});
 ```
 
 `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.
+The key is sent as `X-API-Key` (the engine's scheme) and as a `Bearer` token (the session
+surface's scheme) — one key, both means. The default host is `https://engine-api.shiga.io`;
+override it with `baseUrl` for local development or a future sandbox.
 
-### Quote-first flow (engine)
+## Core concept — quote first
 
-Everything starts with a locked price; orders are created from the `quote.id` before
-`expires_at` passes.
+Everything starts with a locked price. Create a quote, then create an order from `quote.id`
+before `expires_at` passes. Amounts are decimal strings; networks are UPPERCASE.
 
-**Just the rate (no order):** `rates.preview` wraps a quote for display — nothing settles
-and no order is created.
+**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({
@@ -61,7 +65,9 @@ const rate = await pulse.rates.preview({
 // Proceed to an order with quoteId to transact at exactly this locked rate.
 ```
 
-**Offramp — crypto in, fiat out** (the collection direction):
+## Offramp — crypto in, fiat out
+
+The collection direction. Verify the payout account (name enquiry), then create the order:
 
 ```ts
 const quote = await pulse.quotes.create({
@@ -71,7 +77,6 @@ const quote = await pulse.quotes.create({
   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({
@@ -88,7 +93,7 @@ const order = await pulse.offramp.create({
 // Poll pulse.offramp.retrieve(order.id) until a terminal status.
 ```
 
-**Onramp — fiat in, crypto out:**
+## Onramp — fiat in, crypto out
 
 ```ts
 const quote = await pulse.quotes.create({
@@ -108,14 +113,15 @@ const order = await pulse.onramp.create({
 // Poll pulse.onramp.retrieve(order.id) until a terminal status.
 ```
 
-**Banks:** `pulse.banks.list()` returns supported banks (name + NIP code).
+## Banks
 
-## Product surface — collection sessions (landing in the engine)
+- `pulse.banks.list()` — supported banks (name + NIP code).
+- `pulse.banks.resolve({ account_number, bank_code })` — name enquiry; run it before creating an offramp order.
 
-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.
+## Collection sessions
 
-### Create a collection session
+The surface the embedded components run on. Create a session server-side and hand the `cs_*`
+token to your frontend — nothing else.
 
 ```ts
 // Naira gate — funds settle to the user's named virtual account.
@@ -143,11 +149,10 @@ const usdSession = await pulse.collectionSessions.create({
 // 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).
+**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({
@@ -161,7 +166,7 @@ const onrampSession = await pulse.collectionSessions.create({
 });
 ```
 
-### Query orders
+**Query orders.**
 
 ```ts
 const order = await pulse.collectionOrders.retrieve(orderId); // ground truth for one order
@@ -235,14 +240,9 @@ 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.
+- **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. The SDK never emits telemetry from your infrastructure.
 
 ## Configuration
 
@@ -252,7 +252,7 @@ new Pulse(apiKey, options?)
 
 | Option              | Type                  | Default                 | Description                                                         |
 | ------------------- | --------------------- | ----------------------- | ------------------------------------------------------------------- |
-| `baseUrl`           | `string`              | derived from key prefix | API host override (local mock, staging).                            |
+| `baseUrl`           | `string`              | derived from key prefix | API host override (local development, 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.                     |
@@ -286,16 +286,21 @@ try {
 ## 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.
+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_*`).
+- `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.
 
+## Related packages
+
+- [`@pulsebyshiga/collect-js`](https://www.npmjs.com/package/@pulsebyshiga/collect-js) — framework-agnostic web loader for the payment embed.
+- [`@pulsebyshiga/collect-react`](https://www.npmjs.com/package/@pulsebyshiga/collect-react) — React bindings.
+- [`@pulsebyshiga/collect-react-native`](https://www.npmjs.com/package/@pulsebyshiga/collect-react-native) — React Native bindings.
+
 ## License
 
-[MIT](../../LICENSE) © Shiga Digital
+MIT © Shiga Digital

package/dist/version.d.ts

@@ -3,4 +3,4 @@
  * a source constant avoids JSON-import interop differences across Node
  * versions this SDK supports.
  */
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.2.1";

package/dist/version.js

@@ -3,4 +3,4 @@
  * a source constant avoids JSON-import interop differences across Node
  * versions this SDK supports.
  */
-export const SDK_VERSION = '0.2.0';
+export const SDK_VERSION = '0.2.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsebyshiga/node",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pulse Collect backend SDK — collection sessions, orders, and webhook signature verification",
   "license": "MIT",
   "author": "Shiga Digital",