@rerout/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,334 @@
+// 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
+import { createHmac, timingSafeEqual } from "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 = 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 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");
+}
+export {
+  DEFAULT_BASE_URL,
+  DEFAULT_SIGNATURE_TOLERANCE_SECONDS,
+  Links,
+  Project,
+  Qr,
+  Rerout,
+  ReroutError,
+  buildQrUrl,
+  verifyReroutSignature
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@rerout/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript / JavaScript SDK for the Rerout branded-link API.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Codecraft Solutions <hello@codecraftsolutions.co.za>",
+  "homepage": "https://github.com/ModestNerds-Co/rerout-sdks/tree/master/typescript",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ModestNerds-Co/rerout-sdks.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/ModestNerds-Co/rerout-sdks/issues"
+  },
+  "keywords": [
+    "rerout",
+    "url-shortener",
+    "branded-links",
+    "qr-codes",
+    "webhooks",
+    "cloudflare"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target node18",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "@types/node": "^22.10.0"
+  }
+}