@rerout/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,309 @@
+/**
+ * Public types returned by the Rerout API. Fields mirror the server-side
+ * `LinkResponse` / `ProjectStatsResponse` etc. shapes so JSON is parsed
+ * without transformation.
+ */
+interface Link {
+    code: string;
+    short_url: string;
+    domain_hostname: string | null;
+    target_url: string;
+    project_id: string;
+    expires_at: number | null;
+    is_active: boolean;
+    seo_title: string | null;
+    seo_description: string | null;
+    seo_image_url: string | null;
+    seo_canonical_url: string | null;
+    seo_noindex: boolean;
+    seo_updated_at: number | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateLinkInput {
+    target_url: string;
+    /** Verified custom domain to host this link on. Omit for `rerout.co/:code`. */
+    domain_hostname?: string;
+    /** Custom path. Only allowed with verified domain_hostname. */
+    code?: string;
+    /** Unix seconds. Omit for a permanent link. */
+    expires_at?: number;
+    /** Override social preview title. Max 90 chars. */
+    seo_title?: string | null;
+    /** Override social preview description. Max 220 chars. */
+    seo_description?: string | null;
+    /** Absolute https:// social preview image. */
+    seo_image_url?: string | null;
+    /** Canonical URL for the preview HTML. */
+    seo_canonical_url?: string | null;
+    /** Whether the preview page should be indexed. Default: false (noindex). */
+    seo_noindex?: boolean;
+}
+interface UpdateLinkInput {
+    target_url?: string;
+    expires_at?: number | null;
+    is_active?: boolean;
+    seo_title?: string | null;
+    seo_description?: string | null;
+    seo_image_url?: string | null;
+    seo_canonical_url?: string | null;
+    seo_noindex?: boolean;
+}
+interface ListLinksParams {
+    /** Pagination cursor returned by a previous call. */
+    cursor?: number;
+    /** Page size. Server-side default + max apply. */
+    limit?: number;
+}
+interface ListLinksResult {
+    links: Link[];
+    next_cursor: number | null;
+}
+interface StatsBreakdown {
+    value: string;
+    clicks: number;
+}
+interface DailyClicksPoint {
+    day: number;
+    clicks: number;
+    qr_scans: number;
+}
+interface ProjectStats {
+    days: number;
+    total_clicks: number;
+    qr_scans: number;
+    daily: DailyClicksPoint[];
+    countries: StatsBreakdown[];
+    referrers: StatsBreakdown[];
+    devices: StatsBreakdown[];
+    browsers: StatsBreakdown[];
+    top_codes: StatsBreakdown[];
+}
+interface LinkStats {
+    code: string;
+    days: number;
+    total_clicks: number;
+    qr_scans: number;
+    countries: StatsBreakdown[];
+    referrers: StatsBreakdown[];
+}
+interface QrUrlOptions {
+    /** Module size in px. 1–32. Server default: 8. */
+    size?: number;
+    /** Quiet zone in modules. 0–16. Server default: 4. */
+    margin?: number;
+    /** Error correction level. */
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    /** Force the QR to encode a specific verified custom domain. */
+    domain?: string;
+    /** Cache-bust on regenerate. */
+    refresh?: string | true;
+}
+
+/** Default production API URL. Override via `baseUrl` for staging / self-hosted. */
+declare const DEFAULT_BASE_URL = "https://api.rerout.co";
+interface ReroutClientOptions {
+    /** Project API key (`rrk_…`). Required. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.rerout.co`. */
+    baseUrl?: string;
+    /** Inject a custom `fetch` implementation. Useful in tests and edge runtimes. */
+    fetch?: typeof fetch;
+    /** Request timeout in ms. Defaults to 30 000. */
+    timeoutMs?: number;
+    /** Additional headers added to every request (e.g. `user-agent`). */
+    defaultHeaders?: Record<string, string>;
+}
+interface RequestInitLike {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+}
+/**
+ * Official client for the Rerout API.
+ *
+ * @example
+ * ```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/sale',
+ * })
+ * console.log(link.short_url)
+ * ```
+ */
+declare class Rerout {
+    /** Link operations: create, list, get, update, delete, stats. */
+    readonly links: Links;
+    /** Project-level operations: aggregate stats. */
+    readonly project: Project;
+    /** QR helpers (pure URL builders + signed fetch). */
+    readonly qr: Qr;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly defaultHeaders;
+    constructor(options: ReroutClientOptions);
+    /** @internal — invoked by Links / Project / Qr. */
+    request<T>(init: RequestInitLike): Promise<T>;
+    /** Internal — used by Qr to expose the resolved base URL. */
+    get resolvedBaseUrl(): string;
+}
+declare class Links {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /** Create a new short link. */
+    create(input: CreateLinkInput): Promise<Link>;
+    /** Paginated list of links in the project. */
+    list(params?: ListLinksParams): Promise<ListLinksResult>;
+    /** Get a single link by code. */
+    get(code: string): Promise<Link>;
+    /** Patch a link. Only fields present in `input` are changed. */
+    update(code: string, input: UpdateLinkInput): Promise<Link>;
+    /** Soft-delete a link. The short URL stops redirecting and is gone from lists. */
+    delete(code: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Per-link click stats. Defaults to 30 days. */
+    stats(code: string, days?: number): Promise<LinkStats>;
+}
+declare class Project {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /** Aggregate stats across every link in the project. */
+    stats(days?: number): Promise<ProjectStats>;
+    /** Info about the project that owns the current API key. */
+    me(): Promise<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+}
+declare class Qr {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /**
+     * Build the URL the API serves the QR SVG from. Pure — does not call the API.
+     */
+    url(code: string, options?: QrUrlOptions): string;
+    /**
+     * Fetch the QR as an SVG string. Hits the same endpoint as `url()` but
+     * attaches the bearer token and returns the rendered body.
+     */
+    svg(code: string, options?: QrUrlOptions): Promise<string>;
+}
+
+/**
+ * Error thrown for any Rerout API failure — network, HTTP non-2xx, or invalid
+ * response shape. The `code` field matches the stable string identifier
+ * returned by the API (e.g. `bad_target_url`, `rate_limited`, `not_found`) so
+ * callers can branch on it without parsing the human-readable message.
+ *
+ * For network or non-JSON failures the `code` is set to one of the synthetic
+ * values: `network_error`, `unexpected_response`, `client_error`.
+ */
+declare class ReroutError extends Error {
+    /** Stable error code, either from the API or a synthetic client-side one. */
+    readonly code: string;
+    /** HTTP status code, or 0 when the request never reached the server. */
+    readonly status: number;
+    /** The raw response body (parsed JSON or string), useful for debugging. */
+    readonly details: unknown;
+    constructor(opts: {
+        code: string;
+        message: string;
+        status: number;
+        details?: unknown;
+    });
+    /** True for HTTP 5xx responses (server-side issues). */
+    get isServerError(): boolean;
+    /** True for HTTP 429 — caller should back off and retry. */
+    get isRateLimited(): boolean;
+}
+
+/**
+ * Default tolerance window (in seconds) between the `t=` timestamp in the
+ * signature header and the current time. Any signed payload older than this
+ * is rejected — protects against captured-replay attacks. Five minutes.
+ */
+declare const DEFAULT_SIGNATURE_TOLERANCE_SECONDS = 300;
+interface VerifyOptions {
+    /** Raw, unmodified request body. Reading as `await req.text()` or equivalent. */
+    rawBody: string;
+    /** Value of the `X-Rerout-Signature` header. */
+    signatureHeader: string;
+    /** Endpoint signing secret (`whsec_…`) from the dashboard. */
+    secret: string;
+    /** Window in seconds; defaults to 300. Set 0 to disable timestamp check. */
+    toleranceSeconds?: number;
+    /**
+     * Injectable clock for testing. Returns the current time in unix seconds.
+     * Defaults to `Math.floor(Date.now() / 1000)`.
+     */
+    now?: () => number;
+}
+/**
+ * Verify a Rerout webhook signature.
+ *
+ * The header format is `t={unix},v1={hex_hmac}`. The HMAC is computed over
+ * `${timestamp}.${rawBody}` with the endpoint signing secret as the key.
+ *
+ * Returns `true` only when:
+ * - the header parses cleanly,
+ * - the timestamp is within `toleranceSeconds` of `now()`,
+ * - and the computed HMAC matches the supplied `v1` in constant time.
+ *
+ * @example
+ * ```ts
+ * import { verifyReroutSignature } from '@rerout/sdk'
+ *
+ * app.post('/webhooks/rerout', async (req, res) => {
+ *   const raw = await readRawBody(req)
+ *   const ok = verifyReroutSignature({
+ *     rawBody: raw,
+ *     signatureHeader: req.headers['x-rerout-signature'] as string,
+ *     secret: process.env.REROUT_WEBHOOK_SECRET!,
+ *   })
+ *   if (!ok) return res.status(400).end('bad signature')
+ *   // handle event…
+ *   res.status(200).end()
+ * })
+ * ```
+ */
+declare function verifyReroutSignature(opts: VerifyOptions): boolean;
+
+/**
+ * Build the URL the Rerout API serves the QR SVG from. This is a pure helper
+ * — it does not call the API. Pass the resulting URL to an `<img>` tag,
+ * download it server-side, or send it to a render pipeline.
+ *
+ * Authentication is the caller's responsibility — the endpoint is API-key
+ * authenticated, so any `<img>` tag will need a way to send the bearer token
+ * (typically via a server-side proxy).
+ *
+ * @example
+ * ```ts
+ * const url = buildQrUrl({ baseUrl: 'https://api.rerout.co', code: 'q4' })
+ * // → https://api.rerout.co/v1/links/q4/qr
+ *
+ * const branded = buildQrUrl({
+ *   baseUrl: 'https://api.rerout.co',
+ *   code: 'q4',
+ *   options: { size: 12, ecc: 'H', domain: 'go.brand.com' },
+ * })
+ * ```
+ */
+declare function buildQrUrl(args: {
+    baseUrl: string;
+    code: string;
+    options?: QrUrlOptions;
+}): string;
+
+export { type CreateLinkInput, DEFAULT_BASE_URL, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DailyClicksPoint, type Link, type LinkStats, Links, type ListLinksParams, type ListLinksResult, Project, type ProjectStats, Qr, type QrUrlOptions, Rerout, type ReroutClientOptions, ReroutError, type StatsBreakdown, type UpdateLinkInput, type VerifyOptions, buildQrUrl, verifyReroutSignature };

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Public types returned by the Rerout API. Fields mirror the server-side
+ * `LinkResponse` / `ProjectStatsResponse` etc. shapes so JSON is parsed
+ * without transformation.
+ */
+interface Link {
+    code: string;
+    short_url: string;
+    domain_hostname: string | null;
+    target_url: string;
+    project_id: string;
+    expires_at: number | null;
+    is_active: boolean;
+    seo_title: string | null;
+    seo_description: string | null;
+    seo_image_url: string | null;
+    seo_canonical_url: string | null;
+    seo_noindex: boolean;
+    seo_updated_at: number | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateLinkInput {
+    target_url: string;
+    /** Verified custom domain to host this link on. Omit for `rerout.co/:code`. */
+    domain_hostname?: string;
+    /** Custom path. Only allowed with verified domain_hostname. */
+    code?: string;
+    /** Unix seconds. Omit for a permanent link. */
+    expires_at?: number;
+    /** Override social preview title. Max 90 chars. */
+    seo_title?: string | null;
+    /** Override social preview description. Max 220 chars. */
+    seo_description?: string | null;
+    /** Absolute https:// social preview image. */
+    seo_image_url?: string | null;
+    /** Canonical URL for the preview HTML. */
+    seo_canonical_url?: string | null;
+    /** Whether the preview page should be indexed. Default: false (noindex). */
+    seo_noindex?: boolean;
+}
+interface UpdateLinkInput {
+    target_url?: string;
+    expires_at?: number | null;
+    is_active?: boolean;
+    seo_title?: string | null;
+    seo_description?: string | null;
+    seo_image_url?: string | null;
+    seo_canonical_url?: string | null;
+    seo_noindex?: boolean;
+}
+interface ListLinksParams {
+    /** Pagination cursor returned by a previous call. */
+    cursor?: number;
+    /** Page size. Server-side default + max apply. */
+    limit?: number;
+}
+interface ListLinksResult {
+    links: Link[];
+    next_cursor: number | null;
+}
+interface StatsBreakdown {
+    value: string;
+    clicks: number;
+}
+interface DailyClicksPoint {
+    day: number;
+    clicks: number;
+    qr_scans: number;
+}
+interface ProjectStats {
+    days: number;
+    total_clicks: number;
+    qr_scans: number;
+    daily: DailyClicksPoint[];
+    countries: StatsBreakdown[];
+    referrers: StatsBreakdown[];
+    devices: StatsBreakdown[];
+    browsers: StatsBreakdown[];
+    top_codes: StatsBreakdown[];
+}
+interface LinkStats {
+    code: string;
+    days: number;
+    total_clicks: number;
+    qr_scans: number;
+    countries: StatsBreakdown[];
+    referrers: StatsBreakdown[];
+}
+interface QrUrlOptions {
+    /** Module size in px. 1–32. Server default: 8. */
+    size?: number;
+    /** Quiet zone in modules. 0–16. Server default: 4. */
+    margin?: number;
+    /** Error correction level. */
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    /** Force the QR to encode a specific verified custom domain. */
+    domain?: string;
+    /** Cache-bust on regenerate. */
+    refresh?: string | true;
+}
+
+/** Default production API URL. Override via `baseUrl` for staging / self-hosted. */
+declare const DEFAULT_BASE_URL = "https://api.rerout.co";
+interface ReroutClientOptions {
+    /** Project API key (`rrk_…`). Required. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.rerout.co`. */
+    baseUrl?: string;
+    /** Inject a custom `fetch` implementation. Useful in tests and edge runtimes. */
+    fetch?: typeof fetch;
+    /** Request timeout in ms. Defaults to 30 000. */
+    timeoutMs?: number;
+    /** Additional headers added to every request (e.g. `user-agent`). */
+    defaultHeaders?: Record<string, string>;
+}
+interface RequestInitLike {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+}
+/**
+ * Official client for the Rerout API.
+ *
+ * @example
+ * ```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/sale',
+ * })
+ * console.log(link.short_url)
+ * ```
+ */
+declare class Rerout {
+    /** Link operations: create, list, get, update, delete, stats. */
+    readonly links: Links;
+    /** Project-level operations: aggregate stats. */
+    readonly project: Project;
+    /** QR helpers (pure URL builders + signed fetch). */
+    readonly qr: Qr;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly defaultHeaders;
+    constructor(options: ReroutClientOptions);
+    /** @internal — invoked by Links / Project / Qr. */
+    request<T>(init: RequestInitLike): Promise<T>;
+    /** Internal — used by Qr to expose the resolved base URL. */
+    get resolvedBaseUrl(): string;
+}
+declare class Links {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /** Create a new short link. */
+    create(input: CreateLinkInput): Promise<Link>;
+    /** Paginated list of links in the project. */
+    list(params?: ListLinksParams): Promise<ListLinksResult>;
+    /** Get a single link by code. */
+    get(code: string): Promise<Link>;
+    /** Patch a link. Only fields present in `input` are changed. */
+    update(code: string, input: UpdateLinkInput): Promise<Link>;
+    /** Soft-delete a link. The short URL stops redirecting and is gone from lists. */
+    delete(code: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Per-link click stats. Defaults to 30 days. */
+    stats(code: string, days?: number): Promise<LinkStats>;
+}
+declare class Project {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /** Aggregate stats across every link in the project. */
+    stats(days?: number): Promise<ProjectStats>;
+    /** Info about the project that owns the current API key. */
+    me(): Promise<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+}
+declare class Qr {
+    private readonly client;
+    /** @internal */
+    constructor(client: Rerout);
+    /**
+     * Build the URL the API serves the QR SVG from. Pure — does not call the API.
+     */
+    url(code: string, options?: QrUrlOptions): string;
+    /**
+     * Fetch the QR as an SVG string. Hits the same endpoint as `url()` but
+     * attaches the bearer token and returns the rendered body.
+     */
+    svg(code: string, options?: QrUrlOptions): Promise<string>;
+}
+
+/**
+ * Error thrown for any Rerout API failure — network, HTTP non-2xx, or invalid
+ * response shape. The `code` field matches the stable string identifier
+ * returned by the API (e.g. `bad_target_url`, `rate_limited`, `not_found`) so
+ * callers can branch on it without parsing the human-readable message.
+ *
+ * For network or non-JSON failures the `code` is set to one of the synthetic
+ * values: `network_error`, `unexpected_response`, `client_error`.
+ */
+declare class ReroutError extends Error {
+    /** Stable error code, either from the API or a synthetic client-side one. */
+    readonly code: string;
+    /** HTTP status code, or 0 when the request never reached the server. */
+    readonly status: number;
+    /** The raw response body (parsed JSON or string), useful for debugging. */
+    readonly details: unknown;
+    constructor(opts: {
+        code: string;
+        message: string;
+        status: number;
+        details?: unknown;
+    });
+    /** True for HTTP 5xx responses (server-side issues). */
+    get isServerError(): boolean;
+    /** True for HTTP 429 — caller should back off and retry. */
+    get isRateLimited(): boolean;
+}
+
+/**
+ * Default tolerance window (in seconds) between the `t=` timestamp in the
+ * signature header and the current time. Any signed payload older than this
+ * is rejected — protects against captured-replay attacks. Five minutes.
+ */
+declare const DEFAULT_SIGNATURE_TOLERANCE_SECONDS = 300;
+interface VerifyOptions {
+    /** Raw, unmodified request body. Reading as `await req.text()` or equivalent. */
+    rawBody: string;
+    /** Value of the `X-Rerout-Signature` header. */
+    signatureHeader: string;
+    /** Endpoint signing secret (`whsec_…`) from the dashboard. */
+    secret: string;
+    /** Window in seconds; defaults to 300. Set 0 to disable timestamp check. */
+    toleranceSeconds?: number;
+    /**
+     * Injectable clock for testing. Returns the current time in unix seconds.
+     * Defaults to `Math.floor(Date.now() / 1000)`.
+     */
+    now?: () => number;
+}
+/**
+ * Verify a Rerout webhook signature.
+ *
+ * The header format is `t={unix},v1={hex_hmac}`. The HMAC is computed over
+ * `${timestamp}.${rawBody}` with the endpoint signing secret as the key.
+ *
+ * Returns `true` only when:
+ * - the header parses cleanly,
+ * - the timestamp is within `toleranceSeconds` of `now()`,
+ * - and the computed HMAC matches the supplied `v1` in constant time.
+ *
+ * @example
+ * ```ts
+ * import { verifyReroutSignature } from '@rerout/sdk'
+ *
+ * app.post('/webhooks/rerout', async (req, res) => {
+ *   const raw = await readRawBody(req)
+ *   const ok = verifyReroutSignature({
+ *     rawBody: raw,
+ *     signatureHeader: req.headers['x-rerout-signature'] as string,
+ *     secret: process.env.REROUT_WEBHOOK_SECRET!,
+ *   })
+ *   if (!ok) return res.status(400).end('bad signature')
+ *   // handle event…
+ *   res.status(200).end()
+ * })
+ * ```
+ */
+declare function verifyReroutSignature(opts: VerifyOptions): boolean;
+
+/**
+ * Build the URL the Rerout API serves the QR SVG from. This is a pure helper
+ * — it does not call the API. Pass the resulting URL to an `<img>` tag,
+ * download it server-side, or send it to a render pipeline.
+ *
+ * Authentication is the caller's responsibility — the endpoint is API-key
+ * authenticated, so any `<img>` tag will need a way to send the bearer token
+ * (typically via a server-side proxy).
+ *
+ * @example
+ * ```ts
+ * const url = buildQrUrl({ baseUrl: 'https://api.rerout.co', code: 'q4' })
+ * // → https://api.rerout.co/v1/links/q4/qr
+ *
+ * const branded = buildQrUrl({
+ *   baseUrl: 'https://api.rerout.co',
+ *   code: 'q4',
+ *   options: { size: 12, ecc: 'H', domain: 'go.brand.com' },
+ * })
+ * ```
+ */
+declare function buildQrUrl(args: {
+    baseUrl: string;
+    code: string;
+    options?: QrUrlOptions;
+}): string;
+
+export { type CreateLinkInput, DEFAULT_BASE_URL, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DailyClicksPoint, type Link, type LinkStats, Links, type ListLinksParams, type ListLinksResult, Project, type ProjectStats, Qr, type QrUrlOptions, Rerout, type ReroutClientOptions, ReroutError, type StatsBreakdown, type UpdateLinkInput, type VerifyOptions, buildQrUrl, verifyReroutSignature };