@elapse/sdk 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @elapse/sdk
+
+Per-second billing on Monad, integrated like Stripe. **You only pay what elapsed.**
+
+```sh
+npm install @elapse/sdk
+```
+
+```ts
+import { Elapse } from "@elapse/sdk";
+
+const elapse = new Elapse({ secretKey: process.env.ELAPSE_SECRET_KEY });
+
+const product = await elapse.products.create({
+  name: "GPU · 4090",
+  rateUsdPerSecond: "0.004",
+});
+
+const session = await elapse.checkout.sessions.create({
+  product: product.id,
+  successUrl: "https://merchant.example/ok",
+  cancelUrl: "https://merchant.example/cancel",
+});
+
+const event = elapse.webhooks.constructEvent(
+  rawBody,
+  headers["x-elapse-signature"],
+  process.env.ELAPSE_WEBHOOK_SECRET
+);
+```
+
+Send the subscriber to `session.url`. They start a meter, watch the counter tick, and cancel whenever. Your server finds out through a signed webhook, not a cron job.
+
+## Surface
+
+| Method | REST |
+| --- | --- |
+| `products.create / retrieve / list` | `POST /v1/products`, `GET /v1/products/:id`, `GET /v1/products` |
+| `checkout.sessions.create` | `POST /v1/checkout/sessions` |
+| `subscriptions.retrieve / list / cancel` | `GET /v1/subscriptions/:id`, `GET /v1/subscriptions`, `POST /v1/subscriptions/:id/cancel` |
+| `customers.retrieve` | `GET /v1/customers/:id` |
+| `invoices.list` | `GET /v1/invoices` |
+| `webhooks.constructEvent(rawBody, header, secret)` | local |
+
+Requests take the camelCase keys shown above. Responses are the API's objects as they come, snake_case, identical to the cURL tab and to webhook bodies.
+
+## Webhooks
+
+Six event types: `checkout.session.completed`, `subscription.created`, `subscription.updated`, `subscription.canceled`, `invoice.settled`, `invoice.payment_failed`. Never anything per second: compute a live meter from `rate_usd_per_second` and `started_at`.
+
+Verify with the **raw** request body. If your framework parses JSON before your handler, disable that for the webhook route.
+
+```ts
+app.post("/webhooks/elapse", express.raw({ type: "application/json" }), (req, res) => {
+  let event;
+  try {
+    event = elapse.webhooks.constructEvent(req.body, req.header("x-elapse-signature"), process.env.ELAPSE_WEBHOOK_SECRET);
+  } catch {
+    return res.status(400).end();
+  }
+  if (event.type === "subscription.canceled") {
+    // event.data.object.seconds_elapsed, event.data.object.amount_settled
+  }
+  res.status(200).end();
+});
+```
+
+`constructEvent` checks the timestamp is within 300 s and compares every signature in constant time. While you rotate a signing secret, pass both: `constructEvent(body, header, [newSecret, oldSecret])`.
+
+## Errors
+
+Everything thrown extends `ElapseError`: `ElapseAuthenticationError` (401/403), `ElapseInvalidRequestError` (400/404/422, and client-side validation), `ElapseRateLimitError` (429), `ElapseAPIError` (5xx, network, `code: "timeout"`), `ElapseSignatureVerificationError`. Network errors, 429 and 5xx are retried twice with backoff; every `create` and `cancel` carries an `Idempotency-Key`, so retries never double-create. Pass `{ idempotencyKey, timeoutMs }` as the last argument of any method.
+
+## Keep the secret key server-side
+
+`sk_…` keys authorise everything on your account. Read them from the server environment only. The SDK refuses to construct in a browser. Webhooks documentation: <https://docs.elapse.dev/webhooks>.
+
+Node 20+. Zero runtime dependencies. MIT.

package/dist/index.cjs

@@ -0,0 +1,367 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Elapse: () => Elapse,
+  ElapseAPIError: () => ElapseAPIError,
+  ElapseAuthenticationError: () => ElapseAuthenticationError,
+  ElapseError: () => ElapseError,
+  ElapseInvalidRequestError: () => ElapseInvalidRequestError,
+  ElapseRateLimitError: () => ElapseRateLimitError,
+  ElapseSignatureVerificationError: () => ElapseSignatureVerificationError,
+  constructEvent: () => constructEvent
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ElapseError = class extends Error {
+  /** HTTP status, when the error came from a response. */
+  status;
+  /** The API's `error.type` (`invalid_request_error`, …), when present. */
+  type;
+  code;
+  param;
+  requestId;
+  constructor(message, fields = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.status = fields.status;
+    this.type = fields.type;
+    this.code = fields.code;
+    this.param = fields.param;
+    this.requestId = fields.requestId;
+  }
+};
+var ElapseAuthenticationError = class extends ElapseError {
+};
+var ElapseInvalidRequestError = class extends ElapseError {
+};
+var ElapseRateLimitError = class extends ElapseError {
+  retryAfter;
+  constructor(message, fields = {}) {
+    super(message, fields);
+    this.retryAfter = fields.retryAfter;
+  }
+};
+var ElapseAPIError = class extends ElapseError {
+};
+var ElapseSignatureVerificationError = class extends ElapseError {
+};
+
+// src/http.ts
+var import_node_crypto = require("crypto");
+var VERSION = "0.1.0";
+var Transport = class {
+  /** A real private field: `util.inspect` and `console.log` never show it (BR-SDK-002). */
+  #cfg;
+  constructor(cfg) {
+    this.#cfg = cfg;
+  }
+  /** Overridable for tests. */
+  _sleep(ms) {
+    return new Promise((f) => setTimeout(f, ms));
+  }
+  async request(method, path, body, opts = {}) {
+    const url = `${this.#cfg.baseUrl}/v1${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.#cfg.secretKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": `elapse-node/${VERSION}`,
+      Accept: "application/json"
+    };
+    if (method === "POST") headers["Idempotency-Key"] = opts.idempotencyKey ?? (0, import_node_crypto.randomUUID)();
+    const timeoutMs = opts.timeoutMs ?? this.#cfg.timeoutMs;
+    const payload = body === void 0 ? void 0 : JSON.stringify(body);
+    let attempt = 0;
+    for (; ; ) {
+      let res;
+      try {
+        const init = { method, headers, signal: AbortSignal.timeout(timeoutMs) };
+        if (payload !== void 0) init.body = payload;
+        res = await (this.#cfg.fetchImpl ?? fetch)(url, init);
+      } catch (e) {
+        const err2 = networkError(e);
+        if (attempt < this.#cfg.maxRetries) {
+          await this._sleep(backoff(attempt++));
+          continue;
+        }
+        throw err2;
+      }
+      const requestId = res.headers.get("request-id") ?? void 0;
+      const text = await res.text();
+      if (res.ok) {
+        try {
+          return JSON.parse(text);
+        } catch {
+          throw new ElapseAPIError("Invalid JSON received from the Elapse API.", { status: res.status, ...requestId ? { requestId } : {} });
+        }
+      }
+      const err = mapError(res.status, text, requestId, res.headers.get("retry-after"));
+      const retryable = res.status === 429 || res.status >= 500;
+      if (retryable && attempt < this.#cfg.maxRetries) {
+        const ra = err instanceof ElapseRateLimitError && err.retryAfter !== void 0 ? err.retryAfter * 1e3 : void 0;
+        await this._sleep(ra ?? backoff(attempt));
+        attempt++;
+        continue;
+      }
+      throw err;
+    }
+  }
+};
+function backoff(n) {
+  const base = 500 * 2 ** n;
+  return Math.round(base * (0.75 + Math.random() * 0.5));
+}
+function networkError(e) {
+  const name = e instanceof Error ? e.name : "";
+  if (name === "TimeoutError" || name === "AbortError") return new ElapseAPIError("Request timed out.", { code: "timeout" });
+  const msg = e instanceof Error ? e.message : String(e);
+  return new ElapseAPIError(`Network error: ${msg}`, { code: "network_error" });
+}
+function mapError(status, text, requestId, retryAfter) {
+  let type;
+  let message = `Request failed with status ${status}.`;
+  let code;
+  let param;
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed?.error) {
+      type = parsed.error.type;
+      message = parsed.error.message ?? message;
+      code = parsed.error.code;
+      param = parsed.error.param;
+    }
+  } catch {
+  }
+  const fields = {
+    status,
+    ...type ? { type } : {},
+    ...code ? { code } : {},
+    ...param ? { param } : {},
+    ...requestId ? { requestId } : {}
+  };
+  if (status === 401 || status === 403) return new ElapseAuthenticationError(message, fields);
+  if (status === 429) {
+    const ra = retryAfter !== null && /^\d+$/.test(retryAfter) ? Number(retryAfter) : void 0;
+    return new ElapseRateLimitError(message, { ...fields, ...ra !== void 0 ? { retryAfter: ra } : {} });
+  }
+  if (status >= 400 && status < 500) return new ElapseInvalidRequestError(message, fields);
+  return new ElapseAPIError(message, fields);
+}
+
+// src/resources.ts
+var DECIMAL = /^\d+(\.\d+)?$/;
+var STATUSES = ["incomplete", "active", "paused", "canceled"];
+function assertId(id, prefix, name) {
+  if (typeof id !== "string" || !id.startsWith(`${prefix}_`) || id.length <= prefix.length + 1) {
+    throw new ElapseInvalidRequestError(`${name} must be an id starting with '${prefix}_'.`, { param: name });
+  }
+  return id;
+}
+function query(params) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v !== void 0) q.set(k, String(v));
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+function products(t) {
+  return {
+    create(params, opts) {
+      if (typeof params.rateUsdPerSecond !== "string" || !DECIMAL.test(params.rateUsdPerSecond)) {
+        return Promise.reject(
+          new ElapseInvalidRequestError('rateUsdPerSecond must be a decimal string such as "0.004" (never a number).', { param: "rateUsdPerSecond" })
+        );
+      }
+      const body = { name: params.name, rate_usd_per_second: params.rateUsdPerSecond };
+      if (params.allowPause !== void 0) body.allow_pause = params.allowPause;
+      if (params.description !== void 0) body.description = params.description;
+      return t.request("POST", "/products", body, opts);
+    },
+    retrieve(id, opts) {
+      return Promise.resolve().then(() => assertId(id, "prod", "id")).then((v) => t.request("GET", `/products/${v}`, void 0, opts));
+    },
+    list(params = {}, opts) {
+      return t.request("GET", `/products${query({ limit: params.limit, starting_after: params.startingAfter })}`, void 0, opts);
+    }
+  };
+}
+function checkout(t) {
+  return {
+    sessions: {
+      create(params, opts) {
+        return Promise.resolve().then(() => assertId(params.product, "prod", "product")).then((product) => {
+          const body = { product, success_url: params.successUrl, cancel_url: params.cancelUrl };
+          if (params.maxDurationSeconds !== void 0) body.max_duration_seconds = params.maxDurationSeconds;
+          return t.request("POST", "/checkout/sessions", body, opts);
+        });
+      }
+    }
+  };
+}
+function subscriptions(t) {
+  return {
+    retrieve(id, opts) {
+      return Promise.resolve().then(() => assertId(id, "sub", "id")).then((v) => t.request("GET", `/subscriptions/${v}`, void 0, opts));
+    },
+    list(params = {}, opts) {
+      if (params.status !== void 0 && !STATUSES.includes(params.status)) {
+        return Promise.reject(new ElapseInvalidRequestError(`status must be one of ${STATUSES.join(", ")}.`, { param: "status" }));
+      }
+      return t.request(
+        "GET",
+        `/subscriptions${query({ customer: params.customer, product: params.product, status: params.status, limit: params.limit, starting_after: params.startingAfter })}`,
+        void 0,
+        opts
+      );
+    },
+    /** Asks the platform to end the meter; the `canceled` status arrives via webhook once the chain confirms (API FR-API-042). */
+    cancel(id, opts) {
+      return Promise.resolve().then(() => assertId(id, "sub", "id")).then((v) => t.request("POST", `/subscriptions/${v}/cancel`, {}, opts));
+    }
+  };
+}
+function customers(t) {
+  return {
+    retrieve(id, opts) {
+      return Promise.resolve().then(() => assertId(id, "cus", "id")).then((v) => t.request("GET", `/customers/${v}`, void 0, opts));
+    }
+  };
+}
+function invoices(t) {
+  return {
+    list(params = {}, opts) {
+      return t.request(
+        "GET",
+        `/invoices${query({ subscription: params.subscription, customer: params.customer, limit: params.limit, starting_after: params.startingAfter })}`,
+        void 0,
+        opts
+      );
+    }
+  };
+}
+
+// src/webhooks.ts
+var import_node_crypto2 = require("crypto");
+var DEFAULT_TOLERANCE_S = 300;
+var MAX_SIGNATURES = 4;
+var HEX64 = /^[0-9a-f]{64}$/;
+function constructEvent(rawBody, header, secret, options = {}) {
+  if (header === void 0 || header === null) throw new ElapseSignatureVerificationError("Missing X-Elapse-Signature header.");
+  const secrets = typeof secret === "string" ? [secret] : secret === void 0 ? [] : [...secret];
+  if (secrets.length === 0 || secrets.some((s) => typeof s !== "string" || s.length === 0)) {
+    throw new ElapseSignatureVerificationError("At least one non-empty webhook secret is required.");
+  }
+  const { t, signatures } = parseHeader(header);
+  const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_S;
+  const now = options.now ? options.now() : Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - t) > tolerance) {
+    throw new ElapseSignatureVerificationError(`Timestamp outside the tolerance zone (${tolerance} s).`);
+  }
+  const body = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+  const payload = `${t}.${body}`;
+  let matched = false;
+  for (const s of secrets) {
+    const expected = Buffer.from((0, import_node_crypto2.createHmac)("sha256", s).update(payload).digest("hex"), "hex");
+    for (const sig of signatures) {
+      const given = Buffer.from(sig, "hex");
+      if ((0, import_node_crypto2.timingSafeEqual)(given, expected)) matched = true;
+    }
+  }
+  if (!matched) throw new ElapseSignatureVerificationError("No signatures found matching the expected signature for payload.");
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new ElapseSignatureVerificationError("Payload is not valid JSON.");
+  }
+}
+function parseHeader(header) {
+  let t;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) throw new ElapseSignatureVerificationError("Malformed X-Elapse-Signature header.");
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t") {
+      if (t !== void 0 || !/^\d+$/.test(value)) throw new ElapseSignatureVerificationError("Malformed X-Elapse-Signature header: bad timestamp.");
+      t = Number(value);
+    } else if (key === "v1") {
+      if (!HEX64.test(value)) throw new ElapseSignatureVerificationError("Malformed X-Elapse-Signature header: bad signature.");
+      signatures.push(value);
+    }
+  }
+  if (t === void 0 || signatures.length === 0) throw new ElapseSignatureVerificationError("Malformed X-Elapse-Signature header: missing t or v1.");
+  if (signatures.length > MAX_SIGNATURES) throw new ElapseSignatureVerificationError("Malformed X-Elapse-Signature header: too many signatures.");
+  return { t, signatures };
+}
+
+// src/index.ts
+var Elapse = class {
+  #transport;
+  baseUrl;
+  maxRetries;
+  timeoutMs;
+  products;
+  checkout;
+  subscriptions;
+  customers;
+  invoices;
+  webhooks = {
+    /** Verify a webhook and parse the event. Pass the raw body, never a parsed object. */
+    constructEvent: (rawBody, header, secret, options) => constructEvent(rawBody, header, secret, options)
+  };
+  constructor(config) {
+    if (typeof globalThis !== "undefined" && "window" in globalThis && typeof globalThis.document !== "undefined") {
+      throw new ElapseInvalidRequestError("@elapse/sdk is server-side only: your secret key must never reach a browser.");
+    }
+    if (!config || typeof config.secretKey !== "string" || config.secretKey.length === 0) {
+      throw new ElapseInvalidRequestError("Missing secretKey. Pass { secretKey: 'sk_test_\u2026' } from your server environment.");
+    }
+    this.baseUrl = (config.baseUrl ?? "https://api.elapse.dev").replace(/\/+$/, "");
+    this.maxRetries = config.maxRetries ?? 2;
+    this.timeoutMs = config.timeoutMs ?? 3e4;
+    this.#transport = new Transport({ secretKey: config.secretKey, baseUrl: this.baseUrl, maxRetries: this.maxRetries, timeoutMs: this.timeoutMs });
+    this.products = products(this.#transport);
+    this.checkout = checkout(this.#transport);
+    this.subscriptions = subscriptions(this.#transport);
+    this.customers = customers(this.#transport);
+    this.invoices = invoices(this.#transport);
+  }
+  /** Test hook: override the retry sleep. Not part of the public surface. */
+  set _sleep(fn) {
+    this.#transport._sleep = fn;
+  }
+  /** Never leak the key through logging (BR-SDK-002). */
+  toJSON() {
+    return { baseUrl: this.baseUrl };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Elapse,
+  ElapseAPIError,
+  ElapseAuthenticationError,
+  ElapseError,
+  ElapseInvalidRequestError,
+  ElapseRateLimitError,
+  ElapseSignatureVerificationError,
+  constructEvent
+});