@sneekin/sdk 0.3.2 → 1.0.0

package/dist/pay/payments.d.ts

@@ -0,0 +1,90 @@
+import type { CreateOrderResponse, GetOrderResponse, Settlement as GeneratedSettlement, VerifyPayment, VerifyPaymentResponse } from '../core/generated/api.js';
+import { SneekApiError, type SneekClientOptions } from '../core/index.js';
+/**
+ * Options for {@link SneekPayClient}.
+ */
+export type SneekPayClientOptions = SneekClientOptions;
+export type PaymentStatus = GetOrderResponse['status'];
+export interface CreateOrderInput {
+    /** Amount in MAJOR units (rupees), e.g. `499` or `'499.50'`. Max 2 decimals. */
+    amount: number | string;
+    /** ISO-4217 code. Defaults to `INR`. */
+    currency?: string;
+    /** Your own reference. Unique per application; a repeat returns the original order. */
+    receipt?: string;
+    /** Your correlation id, echoed back on reads. */
+    clientRef?: string;
+    /** Non-PII metadata forwarded to the gateway. */
+    notes?: Record<string, unknown>;
+    /**
+     * When your event ends. The organizer share stays on hold until this moment
+     * plus the platform refund window, so buyer refunds can be reversed from it.
+     * Omit to hold for the refund window from payment only.
+     */
+    settleAfter?: string | Date;
+    /** Sent as the `Idempotency-Key` header so a retried call cannot double-charge. */
+    idempotencyKey?: string;
+}
+export type SettlementStatus = GeneratedSettlement['status'];
+/** Where the organizer share of a partner payment stands. Amounts in major units. */
+export type Settlement = GeneratedSettlement;
+export type CreateOrderResult = CreateOrderResponse;
+export type PaymentOrder = GetOrderResponse;
+/** Exactly the three fields the browser checkout handler hands back. */
+export interface VerifyInput {
+    orderId: VerifyPayment['order_id'];
+    paymentId: VerifyPayment['payment_id'];
+    signature: VerifyPayment['signature'];
+}
+export type VerifyResult = VerifyPaymentResponse;
+/**
+ * Accept payments with only your Sneek application API key.
+ *
+ * Sneek holds the payment-gateway merchant credentials centrally, exactly as it
+ * holds the SMS/WhatsApp/email provider credentials centrally. Your
+ * server never stores a gateway secret; the only gateway value you ever receive
+ * is `key_id`, the PUBLIC key the browser checkout widget needs.
+ *
+ * @example
+ * const pay = new SneekPayClient({ apiUrl: 'https://sneek.in', apiKey });
+ *
+ * // 1. Server: create the order.
+ * const order = await pay.orders.create({ amount: '499.00', receipt: 'inv-1001' });
+ *
+ * // 2. Browser: open checkout with order.key_id and order.provider_order_id.
+ *
+ * // 3. Server: verify what the browser handler returned.
+ * const result = await pay.verify({
+ *     orderId: handler.razorpay_order_id,
+ *     paymentId: handler.razorpay_payment_id,
+ *     signature: handler.razorpay_signature,
+ * });
+ */
+export declare class SneekPayClient {
+    private readonly client;
+    readonly orders: OrdersClient;
+    constructor(options: SneekPayClientOptions);
+    /** @internal */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /**
+     * Verify the checkout handler payload and settle the order. Idempotent:
+     * calling it twice with the same pair returns the same result.
+     */
+    verify(input: VerifyInput): Promise<VerifyResult>;
+}
+export declare class OrdersClient {
+    private readonly pay;
+    constructor(pay: SneekPayClient);
+    create(input: CreateOrderInput): Promise<CreateOrderResult>;
+    get(id: string): Promise<PaymentOrder>;
+    /**
+     * The event moved: hold the organizer share until the new end plus the
+     * platform refund window. Only works while the payout is still on hold;
+     * a released payout answers 409.
+     */
+    reschedule(id: string, input: {
+        settleAfter: string | Date;
+    }): Promise<PaymentOrder>;
+}
+export { SneekApiError };
+export default SneekPayClient;

package/dist/verify/index.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/verify/index.ts
+var verify_exports = {};
+__export(verify_exports, {
+  SneekApiError: () => SneekApiError,
+  SneekClient: () => SneekClient,
+  deriveKeys: () => deriveKeys
+});
+module.exports = __toCommonJS(verify_exports);
+
+// src/core/client.ts
+var SneekApiError = class extends Error {
+  constructor(status, type, title, detail) {
+    super(`${title}${detail ? `: ${detail}` : ""} [${status}]`);
+    this.status = status;
+    this.type = type;
+    this.title = title;
+    this.detail = detail;
+    this.name = "SneekApiError";
+  }
+  status;
+  type;
+  title;
+  detail;
+};
+var SneekClient = class {
+  apiUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  retryBaseMs;
+  constructor(options) {
+    if (!options.apiUrl) throw new Error("apiUrl is required");
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.retryBaseMs = options.retryBaseMs ?? 200;
+  }
+  async request(method, path, body, extraHeaders) {
+    const raw = body === void 0 ? void 0 : JSON.stringify(body);
+    let attempt = 0;
+    let lastError;
+    for (; ; ) {
+      try {
+        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+          method,
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+            ...extraHeaders ?? {}
+          },
+          body: raw
+        });
+        const text = await response.text();
+        const parsed = text ? parseJson(text) : void 0;
+        if (!response.ok) {
+          const problem = asProblem(parsed);
+          const error = new SneekApiError(
+            response.status,
+            problem.type ?? "about:blank",
+            problem.title ?? response.statusText,
+            problem.detail
+          );
+          if (response.status >= 500 && attempt < this.maxRetries) {
+            lastError = error;
+            await this.backoff(attempt++);
+            continue;
+          }
+          throw error;
+        }
+        return parsed;
+      } catch (error) {
+        if (error instanceof SneekApiError) throw error;
+        if (attempt < this.maxRetries) {
+          lastError = error;
+          await this.backoff(attempt++);
+          continue;
+        }
+        throw lastError ?? error;
+      }
+    }
+  }
+  backoff(attempt) {
+    return new Promise((resolve) => setTimeout(resolve, this.retryBaseMs * 2 ** attempt));
+  }
+};
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function asProblem(value) {
+  if (typeof value !== "object" || value === null) return {};
+  const problem = value;
+  return {
+    type: typeof problem.type === "string" ? problem.type : void 0,
+    title: typeof problem.title === "string" ? problem.title : void 0,
+    detail: typeof problem.detail === "string" ? problem.detail : void 0
+  };
+}
+
+// src/core/derive-keys.ts
+var import_node_crypto = require("crypto");
+var KEY_LABELS = {
+  qrSigningKey: "sneek-qr-v1",
+  webhookSigningKey: "sneek-webhook-v1",
+  proofKey: "sneek-proof-v1"
+};
+function deriveKeys(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new TypeError("apiKey must be a nonempty string");
+  }
+  const inputKeyMaterial = Buffer.from(apiKey, "utf8");
+  const derive = (label) => Buffer.from(
+    (0, import_node_crypto.hkdfSync)("sha256", inputKeyMaterial, Buffer.alloc(0), label, 32)
+  );
+  return {
+    qrSigningKey: derive(KEY_LABELS.qrSigningKey),
+    webhookSigningKey: derive(KEY_LABELS.webhookSigningKey),
+    proofKey: derive(KEY_LABELS.proofKey)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SneekApiError,
+  SneekClient,
+  deriveKeys
+});

package/dist/verify/index.d.ts

@@ -0,0 +1 @@
+export * from '../core/index.js';

package/dist/verify/index.js

@@ -0,0 +1,121 @@
+// src/core/client.ts
+var SneekApiError = class extends Error {
+  constructor(status, type, title, detail) {
+    super(`${title}${detail ? `: ${detail}` : ""} [${status}]`);
+    this.status = status;
+    this.type = type;
+    this.title = title;
+    this.detail = detail;
+    this.name = "SneekApiError";
+  }
+  status;
+  type;
+  title;
+  detail;
+};
+var SneekClient = class {
+  apiUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  retryBaseMs;
+  constructor(options) {
+    if (!options.apiUrl) throw new Error("apiUrl is required");
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.retryBaseMs = options.retryBaseMs ?? 200;
+  }
+  async request(method, path, body, extraHeaders) {
+    const raw = body === void 0 ? void 0 : JSON.stringify(body);
+    let attempt = 0;
+    let lastError;
+    for (; ; ) {
+      try {
+        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+          method,
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+            ...extraHeaders ?? {}
+          },
+          body: raw
+        });
+        const text = await response.text();
+        const parsed = text ? parseJson(text) : void 0;
+        if (!response.ok) {
+          const problem = asProblem(parsed);
+          const error = new SneekApiError(
+            response.status,
+            problem.type ?? "about:blank",
+            problem.title ?? response.statusText,
+            problem.detail
+          );
+          if (response.status >= 500 && attempt < this.maxRetries) {
+            lastError = error;
+            await this.backoff(attempt++);
+            continue;
+          }
+          throw error;
+        }
+        return parsed;
+      } catch (error) {
+        if (error instanceof SneekApiError) throw error;
+        if (attempt < this.maxRetries) {
+          lastError = error;
+          await this.backoff(attempt++);
+          continue;
+        }
+        throw lastError ?? error;
+      }
+    }
+  }
+  backoff(attempt) {
+    return new Promise((resolve) => setTimeout(resolve, this.retryBaseMs * 2 ** attempt));
+  }
+};
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function asProblem(value) {
+  if (typeof value !== "object" || value === null) return {};
+  const problem = value;
+  return {
+    type: typeof problem.type === "string" ? problem.type : void 0,
+    title: typeof problem.title === "string" ? problem.title : void 0,
+    detail: typeof problem.detail === "string" ? problem.detail : void 0
+  };
+}
+
+// src/core/derive-keys.ts
+import { hkdfSync } from "crypto";
+var KEY_LABELS = {
+  qrSigningKey: "sneek-qr-v1",
+  webhookSigningKey: "sneek-webhook-v1",
+  proofKey: "sneek-proof-v1"
+};
+function deriveKeys(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new TypeError("apiKey must be a nonempty string");
+  }
+  const inputKeyMaterial = Buffer.from(apiKey, "utf8");
+  const derive = (label) => Buffer.from(
+    hkdfSync("sha256", inputKeyMaterial, Buffer.alloc(0), label, 32)
+  );
+  return {
+    qrSigningKey: derive(KEY_LABELS.qrSigningKey),
+    webhookSigningKey: derive(KEY_LABELS.webhookSigningKey),
+    proofKey: derive(KEY_LABELS.proofKey)
+  };
+}
+export {
+  SneekApiError,
+  SneekClient,
+  deriveKeys
+};

package/package.json

@@ -1,49 +1,69 @@
 {
-  "name": "@sneekin/sdk",
-  "version": "0.3.2",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "Node.js SDK for the Sneek Messaging API",
-  "homepage": "https://sneek.in/docs",
-  "bugs": {
-    "url": "https://sneek.in/docs"
-  },
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+    "name": "@sneekin/sdk",
+    "version": "1.0.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "Server-side SDK for Sneek verification, messaging, and payments",
+    "homepage": "https://sneek.in/docs",
+    "bugs": {
+        "url": "https://sneek.in/docs"
+    },
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        },
+        "./verify": {
+            "types": "./dist/verify/index.d.ts",
+            "import": "./dist/verify/index.js",
+            "require": "./dist/verify/index.cjs"
+        },
+        "./messages": {
+            "types": "./dist/messages/index.d.ts",
+            "import": "./dist/messages/index.js",
+            "require": "./dist/messages/index.cjs"
+        },
+        "./pay": {
+            "types": "./dist/pay/index.d.ts",
+            "import": "./dist/pay/index.js",
+            "require": "./dist/pay/index.cjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "build": "tsup && tsc -p tsconfig.json --emitDeclarationOnly",
+        "type-check": "tsc -p tsconfig.json --noEmit",
+        "test": "node --test --import tsx test/*.test.ts test/*.test.mjs",
+        "test:package": "node --test test/package-built.test.mjs"
+    },
+    "keywords": [
+        "sneek",
+        "verification",
+        "messaging",
+        "payments"
+    ],
+    "author": "Abblor Tech Pvt Ltd <abblorltd@gmail.com> (https://sneek.in)",
+    "license": "UNLICENSED",
+    "dependencies": {
+        "jose": "6.2.8",
+        "zod": "3.25.76"
+    },
+    "devDependencies": {
+        "@types/node": "22.19.17",
+        "tsup": "8.5.1",
+        "tsx": "4.21.0",
+        "typescript": "6.0.3"
+    },
+    "engines": {
+        "node": ">=20"
     }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "type-check": "tsc --noEmit",
-    "test": "node --test --import tsx test/*.test.ts"
-  },
-  "keywords": [
-    "sneek",
-    "messaging",
-    "sms",
-    "whatsapp",
-    "email",
-    "otp"
-  ],
-  "author": "Abblor Tech Pvt Ltd <abblorltd@gmail.com> (https://sneek.in)",
-  "license": "UNLICENSED",
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "tsup": "^8.0.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+}

package/README.md

@@ -1,134 +0,0 @@
-# @sneekin/sdk
-
-Node.js SDK for the **Sneek Send** API — deliver OTPs and transactional
-messages over SMS, WhatsApp, and email through Sneek's pre-approved DLT
-sender, WhatsApp BSP number, and warmed email domain.
-
-> Sneek **delivers**; your app generates and verifies its own OTP codes.
-
-## Installation
-
-```bash
-npm install @sneekin/sdk
-```
-
-## Quick start
-
-```ts
-import { Sneek } from '@sneekin/sdk';
-
-const sneek = new Sneek({
-  apiUrl: process.env.SNEEK_API_URL ?? 'https://api.sneek.in',
-  apiKey: process.env.SNEEK_API_KEY!, // snk_live_… or snk_test_…
-});
-
-// Generic send (body OR template)
-await sneek.messages.send({
-  to: '+919876543210',
-  body: 'Your OTP to login to ConfHub is 482917. Do not share it.',
-  channel: 'sms', // 'auto' | 'sms' | 'whatsapp' | 'email'
-});
-
-// Channel helpers
-await sneek.sendSMS('+919876543210', 'Your code is 482917');
-await sneek.sendWhatsApp('+919876543210', 'Your code is 482917');
-await sneek.sendEmail('user@example.com', 'Your code is 482917');
-
-// OTP body-formatting helper (you generate the code yourself)
-await sneek.sendOTP({
-  to: '+919876543210',
-  code: '482917',
-  appName: 'ConfHub',
-  channel: 'auto',
-});
-
-// DLT/provider templates (server-rendered)
-await sneek.messages.send({
-  to: '+919876543210',
-  channel: 'sms',
-  template: 'otp_login',
-  variables: { appName: 'ConfHub', otp: '482917' },
-});
-```
-
-### Message intent (`type`)
-
-Declare whether a message is an OTP or a plain communication so Sneek picks the
-correct approved provider template — instead of guessing from the body text:
-
-```ts
-// Auth / OTP template
-await sneek.messages.send({ to, body: 'Your code is 482917', type: 'otp' });
-
-// Utility / communication template
-await sneek.messages.send({
-  to,
-  body: 'Your booking BK-7781 is confirmed.',
-  type: 'transactional',
-});
-```
-
-`type` accepts `'otp'` or `'transactional'`. When omitted, Sneek infers intent
-from the body (which can misclassify digit groups like `BK-7781` as an OTP), so
-**passing `type` explicitly is recommended.** `sendOTP(...)` always tags
-`type: 'otp'` for you.
-
-## Authentication
-
-Every request is sent with `Authorization: Bearer <apiKey>`. Mint keys from the
-Sneek admin (`/o/<org>/applications/<id>` → API keys). Keys are shown **once**;
-store them in your environment / secret manager. `snk_test_…` keys hit dev
-adapters; `snk_live_…` keys deliver for real.
-
-## Errors & retries
-
-- Non-2xx responses throw `SneekApiError` with `{ status, type, title, detail }`
-  (RFC-7807 problem-details).
-- Transient `5xx` and network failures are retried with exponential backoff
-  (`maxRetries`, default 2; `retryBaseMs`, default 200ms).
-
-## Idempotency & rate limits
-
-Pass `idempotencyKey` to make a send safely repeatable — the first call is
-processed and its result is replayed for any retry with the same key (per
-application), so a dropped connection never sends twice. This pairs with the
-SDK's automatic `5xx` retries.
-
-```ts
-await sneek.messages.send({
-  to: '+919876543210',
-  type: 'otp',
-  body: 'Your code is 482917',
-  idempotencyKey: 'order-4815-otp',
-});
-```
-
-Sends are rate-limited per application (your plan's per-minute / per-day quota),
-per recipient, and per source IP. Exceeding a limit throws `SneekApiError` with
-`status === 429`; the problem body carries `retry_after` (seconds).
-
-
-```ts
-import { SneekApiError } from '@sneekin/sdk';
-
-try {
-  await sneek.sendSMS('+91…', 'hi');
-} catch (err) {
-  if (err instanceof SneekApiError && err.status === 401) {
-    // invalid / revoked key
-  }
-}
-```
-
-## API
-
-| Method | Description |
-| --- | --- |
-| `messages.send(input)` | Send a message (body or template; optional `type` intent). Returns `202` accepted envelope. |
-| `messages.get(id)` | Fetch a previously-sent message by id. |
-| `sendSMS/sendWhatsApp/sendEmail(to, body, clientRef?)` | Channel-pinned helpers. |
-| `sendOTP({ to, code, appName?, channel?, template?, variables? })` | Format + send an OTP body. |
-
-## License
-
-UNLICENSED — © Abblor Tech Pvt Ltd.