@rerout/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@rerout/sdk` are documented in this file. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-20
+
+### Added
+
+- Initial public release.
+- `Rerout` client with `links`, `project`, and `qr` namespaces.
+- Link operations: `create`, `list`, `get`, `update`, `delete`, `stats`.
+- Project operations: `stats`, `me`.
+- QR helpers: pure URL builder + signed SVG fetch.
+- `verifyReroutSignature` — HMAC-SHA256 webhook signature verification with
+  configurable timestamp tolerance and constant-time comparison.
+- `ReroutError` with stable `code`, `status`, `details`; `isRateLimited`,
+  `isServerError` convenience flags.
+- ESM + CJS dual build with bundled `.d.ts` declarations.
+
+[0.1.0]: https://github.com/ModestNerds-Co/rerout-sdks/releases/tag/typescript-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codecraft Solutions
+
+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,128 @@
+# @rerout/sdk
+
+Official TypeScript / JavaScript SDK for the [Rerout](https://rerout.co) API.
+
+## Install
+
+```bash
+npm install @rerout/sdk
+# or
+pnpm add @rerout/sdk
+# or
+bun add @rerout/sdk
+```
+
+Requires Node 18+ (uses the global `fetch` and `AbortController`). Works in
+modern bundlers, Bun, Deno, and Cloudflare Workers — pass a custom `fetch` in
+edge runtimes if needed.
+
+## Usage
+
+```ts
+import { Rerout } from '@rerout/sdk'
+
+const rerout = new Rerout({ apiKey: process.env.REROUT_API_KEY! })
+
+const link = await rerout.links.create({
+  target_url: 'https://example.com/q4-sale',
+  domain_hostname: 'go.brand.com',
+  code: 'q4',
+})
+
+console.log(link.short_url) // https://go.brand.com/q4
+
+const stats = await rerout.project.stats(7)
+console.log(`Last 7 days: ${stats.total_clicks} clicks, ${stats.qr_scans} QR scans`)
+```
+
+## API
+
+### Construction
+
+```ts
+const rerout = new Rerout({
+  apiKey: 'rrk_…',                // required
+  baseUrl: 'https://api.rerout.co', // optional, defaults shown
+  timeoutMs: 30_000,                // optional
+  fetch: customFetch,               // optional — inject your own fetch
+  defaultHeaders: {                 // optional — added to every request
+    'user-agent': 'my-app/1.0',
+  },
+})
+```
+
+### Links
+
+```ts
+rerout.links.create({ target_url, domain_hostname?, code?, expires_at?, ...seo })
+rerout.links.list({ cursor?, limit? })
+rerout.links.get(code)
+rerout.links.update(code, { target_url?, expires_at?, is_active?, ...seo })
+rerout.links.delete(code)
+rerout.links.stats(code, days = 30)
+```
+
+### Project
+
+```ts
+rerout.project.stats(days = 30)
+rerout.project.me()
+```
+
+### QR codes
+
+```ts
+rerout.qr.url(code, { size?, margin?, ecc?, domain?, refresh? }) // returns string
+await rerout.qr.svg(code, opts) // fetches the rendered SVG
+```
+
+### Webhook signature verification
+
+```ts
+import { verifyReroutSignature } from '@rerout/sdk'
+
+const ok = verifyReroutSignature({
+  rawBody,
+  signatureHeader: req.headers['x-rerout-signature']!,
+  secret: process.env.REROUT_WEBHOOK_SECRET!,
+})
+```
+
+Defaults to a 5-minute timestamp tolerance; pass `toleranceSeconds: 0` to
+disable that check.
+
+## Error handling
+
+Every method throws `ReroutError` on failure:
+
+```ts
+import { ReroutError } from '@rerout/sdk'
+
+try {
+  await rerout.links.create({ target_url: 'http://insecure.example' })
+} catch (err) {
+  if (err instanceof ReroutError) {
+    console.error(err.code)    // 'bad_target_url'
+    console.error(err.status)  // 400
+    console.error(err.message) // 'target_url must use https.'
+    if (err.isRateLimited) { /* back off */ }
+  }
+}
+```
+
+Synthetic codes when the server didn't return a JSON body:
+`network_error`, `timeout`, `unexpected_response`, `unauthorized`,
+`forbidden`, `not_found`, `rate_limited`, `server_error`, `client_error`.
+
+## Local development
+
+```bash
+npm install
+npm run typecheck
+npm run test
+npm run build
+```
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

package/dist/index.cjs

@@ -0,0 +1,369 @@
+"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, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_SIGNATURE_TOLERANCE_SECONDS: () => DEFAULT_SIGNATURE_TOLERANCE_SECONDS,
+  Links: () => Links,
+  Project: () => Project,
+  Qr: () => Qr,
+  Rerout: () => Rerout,
+  ReroutError: () => ReroutError,
+  buildQrUrl: () => buildQrUrl,
+  verifyReroutSignature: () => verifyReroutSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ReroutError = class extends Error {
+  /** Stable error code, either from the API or a synthetic client-side one. */
+  code;
+  /** HTTP status code, or 0 when the request never reached the server. */
+  status;
+  /** The raw response body (parsed JSON or string), useful for debugging. */
+  details;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "ReroutError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.details = opts.details;
+  }
+  /** True for HTTP 5xx responses (server-side issues). */
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+  /** True for HTTP 429 — caller should back off and retry. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+
+// src/qr.ts
+function buildQrUrl(args) {
+  const base = args.baseUrl.replace(/\/+$/, "");
+  const url = new URL(`${base}/v1/links/${encodeURIComponent(args.code)}/qr`);
+  const opts = args.options ?? {};
+  if (opts.size !== void 0) url.searchParams.set("size", String(opts.size));
+  if (opts.margin !== void 0) url.searchParams.set("margin", String(opts.margin));
+  if (opts.ecc !== void 0) url.searchParams.set("ecc", opts.ecc);
+  if (opts.domain !== void 0) url.searchParams.set("domain", opts.domain);
+  if (opts.refresh !== void 0) {
+    url.searchParams.set("refresh", opts.refresh === true ? "1" : opts.refresh);
+  }
+  return url.toString();
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.rerout.co";
+var Rerout = class {
+  /** Link operations: create, list, get, update, delete, stats. */
+  links;
+  /** Project-level operations: aggregate stats. */
+  project;
+  /** QR helpers (pure URL builders + signed fetch). */
+  qr;
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  defaultHeaders;
+  constructor(options) {
+    if (!options.apiKey || typeof options.apiKey !== "string") {
+      throw new ReroutError({
+        code: "missing_api_key",
+        message: "A project API key is required to construct Rerout.",
+        status: 0
+      });
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? (typeof fetch !== "undefined" ? fetch : (() => {
+      throw new ReroutError({
+        code: "missing_fetch",
+        message: "No global fetch available. Pass `fetch` in ReroutClientOptions or run on Node 18+.",
+        status: 0
+      });
+    })());
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.links = new Links(this);
+    this.project = new Project(this);
+    this.qr = new Qr(this);
+  }
+  /** @internal — invoked by Links / Project / Qr. */
+  async request(init) {
+    const url = new URL(this.baseUrl + init.path);
+    if (init.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      accept: "application/json",
+      ...this.defaultHeaders
+    };
+    const body = init.body === void 0 ? void 0 : JSON.stringify(init.body);
+    if (body !== void 0) headers["content-type"] = "application/json";
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(url.toString(), {
+        method: init.method,
+        headers,
+        body,
+        signal: abort.signal
+      });
+    } catch (error) {
+      throw new ReroutError({
+        code: abort.signal.aborted ? "timeout" : "network_error",
+        message: error instanceof Error ? error.message : "Request to Rerout failed before the server replied.",
+        status: 0,
+        details: error
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await response.text();
+    if (!response.ok) throw parseError(response.status, text);
+    if (text.length === 0) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new ReroutError({
+        code: "unexpected_response",
+        message: "Rerout returned a non-JSON success body.",
+        status: response.status,
+        details: { body: text, error }
+      });
+    }
+  }
+  /** Internal — used by Qr to expose the resolved base URL. */
+  get resolvedBaseUrl() {
+    return this.baseUrl;
+  }
+};
+function parseError(status, body) {
+  if (body.length === 0) {
+    return new ReroutError({
+      code: synthCodeForStatus(status),
+      message: `Rerout returned HTTP ${status} with no body.`,
+      status
+    });
+  }
+  try {
+    const parsed = JSON.parse(body);
+    return new ReroutError({
+      code: parsed.code ?? synthCodeForStatus(status),
+      message: parsed.message ?? `Rerout returned HTTP ${status}.`,
+      status,
+      details: parsed
+    });
+  } catch {
+    return new ReroutError({
+      code: synthCodeForStatus(status),
+      message: `Rerout returned HTTP ${status} (non-JSON body).`,
+      status,
+      details: { body }
+    });
+  }
+}
+function synthCodeForStatus(status) {
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "server_error";
+  return "client_error";
+}
+var Links = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Create a new short link. */
+  create(input) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/links",
+      body: input
+    });
+  }
+  /** Paginated list of links in the project. */
+  list(params) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/links",
+      query: params
+    });
+  }
+  /** Get a single link by code. */
+  get(code) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/links/${encodeURIComponent(code)}`
+    });
+  }
+  /** Patch a link. Only fields present in `input` are changed. */
+  update(code, input) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/v1/links/${encodeURIComponent(code)}`,
+      body: input
+    });
+  }
+  /** Soft-delete a link. The short URL stops redirecting and is gone from lists. */
+  delete(code) {
+    return this.client.request({
+      method: "DELETE",
+      path: `/v1/links/${encodeURIComponent(code)}`
+    });
+  }
+  /** Per-link click stats. Defaults to 30 days. */
+  stats(code, days = 30) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/links/${encodeURIComponent(code)}/stats`,
+      query: { days }
+    });
+  }
+};
+var Project = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Aggregate stats across every link in the project. */
+  stats(days = 30) {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/projects/me/stats",
+      query: { days }
+    });
+  }
+  /** Info about the project that owns the current API key. */
+  me() {
+    return this.client.request({
+      method: "GET",
+      path: "/v1/projects/me"
+    });
+  }
+};
+var Qr = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Build the URL the API serves the QR SVG from. Pure — does not call the API.
+   */
+  url(code, options) {
+    return buildQrUrl({
+      baseUrl: this.client.resolvedBaseUrl,
+      code,
+      options
+    });
+  }
+  /**
+   * Fetch the QR as an SVG string. Hits the same endpoint as `url()` but
+   * attaches the bearer token and returns the rendered body.
+   */
+  async svg(code, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/v1/links/${encodeURIComponent(code)}/qr` + qrQueryString(options)
+    });
+  }
+};
+function qrQueryString(options) {
+  if (!options) return "";
+  const params = new URLSearchParams();
+  if (options.size !== void 0) params.set("size", String(options.size));
+  if (options.margin !== void 0) params.set("margin", String(options.margin));
+  if (options.ecc !== void 0) params.set("ecc", options.ecc);
+  if (options.domain !== void 0) params.set("domain", options.domain);
+  if (options.refresh !== void 0) {
+    params.set("refresh", options.refresh === true ? "1" : options.refresh);
+  }
+  const qs = params.toString();
+  return qs.length === 0 ? "" : `?${qs}`;
+}
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+var DEFAULT_SIGNATURE_TOLERANCE_SECONDS = 300;
+function verifyReroutSignature(opts) {
+  if (!opts.signatureHeader || !opts.secret || opts.rawBody === void 0) {
+    return false;
+  }
+  const parts = parseSignatureHeader(opts.signatureHeader);
+  if (!parts) return false;
+  const tolerance = opts.toleranceSeconds ?? DEFAULT_SIGNATURE_TOLERANCE_SECONDS;
+  if (tolerance > 0) {
+    const now = opts.now ? opts.now() : Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - parts.timestamp) > tolerance) return false;
+  }
+  const expectedHex = (0, import_node_crypto.createHmac)("sha256", opts.secret).update(`${parts.timestamp}.${opts.rawBody}`).digest("hex");
+  const expected = safeFromHex(expectedHex);
+  const actual = safeFromHex(parts.v1);
+  if (!expected || !actual || expected.length !== actual.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(expected, actual);
+}
+function parseSignatureHeader(header) {
+  let timestamp;
+  let v1;
+  for (const segment of header.split(",")) {
+    const eq = segment.indexOf("=");
+    if (eq <= 0) continue;
+    const key = segment.slice(0, eq).trim().toLowerCase();
+    const value = segment.slice(eq + 1).trim();
+    if (key === "t") {
+      const parsed = Number.parseInt(value, 10);
+      if (Number.isFinite(parsed) && parsed > 0) timestamp = parsed;
+    } else if (key === "v1") {
+      v1 = value;
+    }
+  }
+  if (timestamp === void 0 || !v1) return null;
+  return { timestamp, v1 };
+}
+function safeFromHex(hex) {
+  if (hex.length === 0 || hex.length % 2 !== 0) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+  return Buffer.from(hex, "hex");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  DEFAULT_SIGNATURE_TOLERANCE_SECONDS,
+  Links,
+  Project,
+  Qr,
+  Rerout,
+  ReroutError,
+  buildQrUrl,
+  verifyReroutSignature
+});