@shake-defi/node 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,290 @@
+# @shake-defi/node
+
+Node.js SDK for the **Token Purchase Platform API** — sell tokens for stablecoins without your customers touching wallets, gas, or smart contracts directly.
+
+Modeled on Stripe's Payment Intents API: your backend creates a `TokenPurchaseIntent`, a hosted checkout widget confirms it on-chain, and a webhook tells you what actually happened.
+
+```js
+const { PlatformClient } = require('@shake-defi/node');
+const client = new PlatformClient(process.env.PLATFORM_SECRET_KEY);
+
+const customer = await client.customers.create({ external_customer_id: 'user_88210' });
+
+const intent = await client.tokenPurchaseIntents.create({
+  customer: customer.id,
+  amount: 5.00,
+  payment_currency: 'USDC',
+});
+
+// Send intent._widget_params (or intent.client_secret) to your frontend
+// to initialize the checkout widget.
+```
+
+## Installation
+
+```bash
+npm install @shake-defi/node
+```
+
+Requires Node.js 18 or later (uses the built-in `fetch` and `AbortSignal.timeout`).
+
+## Authentication
+
+Every request from your backend is authenticated with a secret key:
+
+```js
+const client = new PlatformClient('sk_live_51Hxyz...');
+```
+
+| Key prefix | Used where | Can do |
+|---|---|---|
+| `sk_test_` / `sk_live_` | Your backend (this SDK) | Create and retrieve resources |
+| `pk_test_` / `pk_live_` | Your frontend (checkout widget) | Initialize the widget only |
+
+`PlatformClient` throws synchronously if the key doesn't start with `sk_live_` or `sk_test_` — **never pass a publishable key (`pk_…`) to this SDK.**
+
+### Test vs. live mode
+
+Which mode you're in is determined entirely by the key you construct the client with — there's no separate network parameter to set. Test mode runs on **Base Sepolia** with test stablecoins; live mode runs on **Base mainnet** with real ones. Test and live objects (customers, intents) are fully isolated from each other. Every object returned by the API carries a `livemode` boolean so you can confirm which mode produced it.
+
+## Client options
+
+```js
+const client = new PlatformClient(secretKey, {
+  baseUrl:    'https://api.shake-defi.com', // override for a proxy or mock server
+  timeout:    30_000,                        // per-request timeout, ms
+  maxRetries: 2,                             // retries on network errors / 5xx only
+});
+```
+
+Requests are retried with exponential back-off (`200ms, 400ms, ...`) on network failures and `5xx` responses. `4xx` responses are never retried.
+
+## Customers
+
+One record per payer. Create it once, the first time a customer interacts with the API, and store the returned `id` in your own database.
+
+```js
+const customer = await client.customers.create({
+  external_customer_id: 'user_88210', // your own internal ID for this user
+});
+// => { id: 'cus_1JX9k2', object: 'customer', external_customer_id: 'user_88210', created: ..., livemode: true }
+
+const same = await client.customers.retrieve('cus_1JX9k2');
+```
+
+Creating a customer with an `external_customer_id` that already exists for your account and mode returns the existing customer rather than creating a duplicate — the call is safe to retry as-is, or you can also pass an idempotency key:
+
+```js
+await client.customers.create(
+  { external_customer_id: 'user_88210' },
+  { idempotencyKey: 'user_88210_signup' }
+);
+```
+
+## Token Purchase Intents
+
+The core resource — a single attempt to buy tokens with a stablecoin.
+
+### Create an intent
+
+```js
+const intent = await client.tokenPurchaseIntents.create({
+  customer: 'cus_1JX9k2',
+  amount: 5.00,             // human-readable units — 5.00 means $5.00 equivalent, NOT smallest units
+  payment_currency: 'USDC', // must be a key in GET /account's currency_contracts
+}, {
+  idempotencyKey: 'order_8841_attempt_1', // recommended: {order_id}_attempt_{n}
+});
+```
+
+The intent is created in `pending` status. **The creation response is only ever "accepted" — final status (`succeeded`, `failed`, `canceled`) arrives via [webhook](#webhooks), not in this response.** It expires to `canceled` if left unconfirmed for 30 minutes.
+
+### Initializing the checkout widget
+
+The create response includes everything a frontend checkout widget needs — pass **one** of the following two fields to your widget SDK:
+
+- **`intent._widget_params`** — a snapshot taken at creation time. No further API calls required from the frontend.
+- **`intent.client_secret`** — a bearer credential (`{intent_id}_secret_{random}`) the widget exchanges for live params — including the current on-chain price — via the public `GET /v1/widget/params?client_secret=...` endpoint. This is safe to send to the browser by design, but treat it like any other credential: don't log it, and don't let one customer see another's.
+
+```js
+res.json({
+  clientSecret: intent.client_secret, // hand this to your frontend
+});
+```
+
+`client_secret` is returned **only** on creation — it is never present on retrieve or list responses and can't be recovered afterward, since only its hash is persisted server-side.
+
+### Retrieve an intent
+
+```js
+const intent = await client.tokenPurchaseIntents.retrieve('tpi_3LMnop');
+```
+
+You can poll this to check status, or rely on webhooks — both work. Webhooks are preferred in production to avoid polling overhead.
+
+### List intents
+
+```js
+const page = await client.tokenPurchaseIntents.list({
+  customer: 'cus_1JX9k2',   // optional
+  status: 'succeeded',      // optional: pending | succeeded | failed | canceled
+  limit: 25,                // optional, 1-100, default 10
+  starting_after: 'tpi_3LMnop', // optional cursor — pass the last id from the previous page
+});
+
+// => { object: 'list', data: [...], has_more: false }
+```
+
+### Token amounts are 18-decimal integers — use BigInt
+
+`token_amount_estimate` and `token_amount` are ERC-20 amounts in 18-decimal wei units and routinely exceed `Number.MAX_SAFE_INTEGER`. The API returns them as JSON numbers for readability, but you should re-parse them as `BigInt` before doing any arithmetic:
+
+```js
+const wei = BigInt(intent.token_amount_estimate);
+```
+
+`amount` and `price_snapshot`, by contrast, are ordinary human-readable decimals (`5.00` = $5.00) — don't multiply these by `10^6` or `10^18`.
+
+## Account
+
+Read-only reference info for the account tied to your API key: current token price, contract addresses, accepted payment currencies, and active network.
+
+```js
+const account = await client.account.retrieve();
+// => {
+//   object: 'account',
+//   network: 'base-mainnet',
+//   token_contract: '0x...',
+//   swap_contract: '0x...',
+//   company_wallet: '0x...',
+//   price_per_token: 1.0,
+//   currency_contracts: { USDC: '0x...', USDT: '0x...' },
+//   livemode: true,
+// }
+```
+
+Call this on startup to confirm you're using the right key type and to discover which `payment_currency` values are currently valid — the keys of `currency_contracts`.
+
+## Webhooks
+
+The create-intent response only ever means "accepted." Final settlement is asynchronous and delivered to your endpoint as one of four events:
+
+| Event | Fired when |
+|---|---|
+| `token_purchase_intent.created` | A new intent is created. |
+| `token_purchase_intent.succeeded` | The on-chain `Purchase` event is confirmed. Credit `data.object.token_amount` to the customer. |
+| `token_purchase_intent.failed` | The on-chain transaction reverts or confirmation times out. `data.object.error` explains why. |
+| `token_purchase_intent.canceled` | The intent expired unconfirmed after 30 minutes. |
+
+Verify the signature and parse the payload with `client.webhooks.constructEvent` (also usable standalone via the named export, without constructing a client):
+
+```js
+const { PlatformClient } = require('@shake-defi/node');
+const client = new PlatformClient(process.env.PLATFORM_SECRET_KEY);
+
+app.post('/webhooks/shake', express.raw({ type: 'application/json' }), (req, res) => {
+  let event;
+  try {
+    event = client.webhooks.constructEvent(
+      req.body,                             // raw request body (Buffer or string — NOT parsed JSON)
+      req.headers['platform-signature'],
+      process.env.PLATFORM_WEBHOOK_SECRET,
+    );
+  } catch (err) {
+    console.error('Webhook signature verification failed:', err.message);
+    return res.status(400).send('Invalid signature');
+  }
+
+  switch (event.type) {
+    case 'token_purchase_intent.succeeded': {
+      const intent = event.data.object;
+      // creditLedger(intent.customer, BigInt(intent.token_amount));
+      break;
+    }
+    case 'token_purchase_intent.failed':
+    case 'token_purchase_intent.canceled':
+      // notify the customer, optionally prompt a retry
+      break;
+  }
+
+  res.status(200).end(); // any 2xx acknowledges receipt
+});
+```
+
+Signatures are verified with HMAC-SHA256 over `{timestamp}.{raw_body}` and compared using a timing-safe check. Requests older than 5 minutes are rejected as possible replays. Return any non-2xx and the platform retries with exponential back-off (`5s → 30s → 5m → 30m → 2h`).
+
+**Important:** the raw, unparsed request body is required for signature verification — make sure whatever body parser you use (e.g. `express.raw()`) doesn't JSON-parse this route before `constructEvent` sees it.
+
+## Error handling
+
+Failed requests reject with a `PlatformApiError`:
+
+```js
+const { PlatformApiError } = require('@shake-defi/node');
+
+try {
+  await client.tokenPurchaseIntents.create({
+    customer: 'cus_1JX9k2',
+    amount: -5,
+    payment_currency: 'USDC',
+  });
+} catch (err) {
+  if (err instanceof PlatformApiError) {
+    console.error(err.status);  // 400
+    console.error(err.type);    // 'invalid_request_error' | 'chain_error' | 'api_error'
+    console.error(err.code);    // e.g. 'missing_required_param', 'insufficient_allowance'
+    console.error(err.param);   // e.g. 'amount'
+    console.error(err.message); // human-readable explanation
+  }
+}
+```
+
+`chain_error` responses (surfaced when a widget confirmation ends in `failed`, and reflected in `intent.error`) use `code` to tell you what went wrong on-chain:
+
+| Code | Meaning |
+|---|---|
+| `insufficient_allowance` | Customer hasn't approved enough of the payment currency. |
+| `transaction_reverted` | The on-chain `buy` call reverted. |
+| `price_changed` | Live price moved beyond tolerance between intent creation and confirmation. |
+| `chain_congested` | RPC or mempool issues prevented submission. |
+| `confirmation_timeout` | Required confirmations weren't reached within the expiry window. |
+
+Webhook signature failures raise a separate `SignatureError`:
+
+```js
+const { SignatureError } = require('@shake-defi/node');
+```
+
+## Idempotency
+
+Pass an `Idempotency-Key` on `create` calls to make retries safe:
+
+```js
+await client.tokenPurchaseIntents.create(params, { idempotencyKey: 'order_8841_attempt_1' });
+```
+
+If the same key is received again before the original response expires, the original response is returned rather than creating a duplicate resource. Recommended format: `{order_id}_attempt_{n}`.
+
+## TypeScript
+
+Type definitions are published alongside the package (`index.d.ts`) and resolve automatically — no `@types` package needed.
+
+## API reference
+
+This SDK covers the full [Token Purchase Platform API](https://api.shake-defi.com):
+
+| Method | HTTP |
+|---|---|
+| `client.customers.create(params, opts?)` | `POST /v1/customers` |
+| `client.customers.retrieve(id)` | `GET /v1/customers/:id` |
+| `client.tokenPurchaseIntents.create(params, opts?)` | `POST /v1/token_purchase_intents` |
+| `client.tokenPurchaseIntents.retrieve(id)` | `GET /v1/token_purchase_intents/:id` |
+| `client.tokenPurchaseIntents.list(params?)` | `GET /v1/token_purchase_intents` |
+| `client.account.retrieve()` | `GET /v1/account` |
+| `client.webhooks.constructEvent(rawBody, header, secret)` | verifies + parses inbound webhooks |
+
+For full request/response schemas, field-level documentation, and the widget's public `GET /widget/params` endpoint (called by the checkout widget itself — you generally won't call it directly), see the OpenAPI spec.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shake-defi/node",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Node.js SDK for the Token Purchase Platform",
   "main": "index.js",
   "types": "./index.d.ts",