qrflow 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Native Code LLC
+
+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,126 @@
+# qrflow
+
+The official client for the [QRFLOW.codes](https://qrflow.codes) API: create QR codes from your code, **change where a printed code points without reprinting**, print codes on **your own domain**, read **scan analytics**, and verify **webhooks**.
+
+Zero dependencies. Runs anywhere `fetch` runs: Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, Supabase Edge Functions. Full TypeScript types. ESM and CommonJS.
+
+```bash
+npm install qrflow
+```
+
+## Five lines
+
+```ts
+import { QRFlow } from "qrflow";
+
+const qr = new QRFlow(process.env.QRFLOW_KEY!);            // Business API key, server-side only
+
+const { code } = await qr.createCode({
+  type: "url",
+  destination_data: { url: "https://acme.com/menu" },
+  label: "Table tents",
+});
+console.log(code.short_url);                                // print this
+
+await qr.updateCode(code.id, { destination_data: { url: "https://acme.com/menu-fall" } });
+// the printed code now opens the fall menu. Nothing was reprinted.
+```
+
+## What you need
+
+- A QRFLOW.codes account on the **Business** plan ($29/month) and an API key from **Account › API keys**. Keys look like `qrf_live_…` and are shown once.
+- Keep the key on the server. The API refuses browser origins on purpose; call it from a route handler, server action, edge function or backend.
+
+No key yet? The MCP server at `https://qrflow.codes/mcp` works on every plan from Claude, ChatGPT, Cursor and Claude Code, and the free generator at qrflow.codes makes static codes with no account.
+
+## The one concept that matters
+
+A **static** code has the content inside the picture; it can never change. A **dynamic** code (url, phone, email, sms, location on paid plans) contains a short link, `code.short_url`, that QRFLOW redirects. You print `short_url` once and change the destination as often as you like. Every scan is counted.
+
+`short_url` is `https://qrflow.codes/q/<short_code>` until you connect a domain on the Account page, then `https://go.yourbrand.com/<slug or short_code>`. Set link names (`slug`) *before* printing; changing one changes the link.
+
+## Everything the client does
+
+```ts
+const qr = new QRFlow(key, { baseUrl?, fetch?, retries? });
+
+await qr.me();                                   // plan, features, limits, scopes
+await qr.catalog();                              // every kind of code and the fields it needs
+await qr.listCodes({ limit: 50, q: "menu" });    // newest first
+await qr.getCode(id);
+await qr.createCode({ type, destination_data, label?, fg_color?, bg_color?, frame_style?, frame_caption?, domain_id? });
+await qr.updateCode(id, { destination_data?, label?, paused?, expires_at?, slug?, domain_id?, ... });
+await qr.makeDynamic(id);                        // static -> dynamic (re-render afterwards)
+await qr.deleteCode(id);                         // permanent; prefer { paused: true } when a print exists
+await qr.scans(id, { from?, to?, group: "day" | "device" | "country" | "city" | "browser" | "os" | "referrer" });
+await qr.bulkCreate([{ destination, label? }, ...]);   // up to 2,000 dynamic url codes per call
+await qr.domains();                              // your link domains and the default
+await qr.listWebhooks(); qr.createWebhook({ url, events }); qr.testWebhook(id); qr.deleteWebhook(id);
+qr.imageUrl(id, size);                           // the SVG address (needs the Authorization header)
+await qr.image(id, size);                        // the print-ready SVG as a string
+```
+
+Every error is a `QRFlowError` with `status`, `code` (`invalid_token`, `upgrade_required`, `insufficient_scope`, `not_found`, `conflict`, `rate_limited`, `not_dynamic`, `no_domain`, …) and a human `message`. A 429 is retried automatically after `Retry-After` (twice by default; `retries: 0` to disable).
+
+## Kinds of codes
+
+`type` is the encoding: `url`, `text`, `wifi`, `vcard`, `email`, `phone`, `sms`, `location`. Friendlier kinds are url codes with `destination_data.subtype`:
+
+```ts
+await qr.createCode({ type: "url", destination_data: { subtype: "googlereview", placeId: "ChIJ…" }, label: "Receipt footer" });
+await qr.createCode({ type: "url", destination_data: { subtype: "instagram", handle: "acme" } });
+await qr.createCode({ type: "wifi", destination_data: { ssid: "CafeGuest", password: "latte-2026", encryption: "WPA" } });
+```
+
+`await qr.catalog()` lists all of them with their fields.
+
+## Show the image
+
+`code.image_url` needs the Authorization header, so either proxy it or render the link yourself:
+
+```ts
+// Next.js route handler: app/api/qr/[id]/image/route.ts
+export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;                       // check the signed-in user owns this id
+  const svg = await qr.image(id, 1024);
+  return new Response(svg, { headers: { "Content-Type": "image/svg+xml", "Cache-Control": "private, max-age=3600" } });
+}
+```
+
+```ts
+// Or on the client, with any QR library: the code IS the short link
+import QRCode from "qrcode";
+const dataUrl = await QRCode.toDataURL(code.short_url, { width: 512 });
+```
+
+## Webhooks
+
+Create one on Account › Webhooks or with `createWebhook`. Events: `scan` (batched every few minutes), `code.created`, `code.updated`, `code.deleted`, `ping`. Every delivery is `{ id, event, created_at, data }` and signed with `X-QRFLOW-Signature: t=<unix>,v1=<hex>`.
+
+```ts
+import { parseWebhook } from "qrflow";
+
+// Next.js App Router
+export async function POST(req: Request) {
+  const raw = await req.text();                                   // the exact bytes, before JSON.parse
+  const evt = await parseWebhook(raw, req.headers.get("x-qrflow-signature") ?? "", process.env.QRFLOW_WEBHOOK_SECRET!);
+  // evt.id is stable across retries: dedupe on it
+  if (evt.event === "scan") for (const s of evt.data.scans) console.log(s.code_id, s.country, s.device);
+  return new Response(null, { status: 204 });                     // answer within 8 seconds
+}
+```
+
+`verifyWebhook(raw, header, secret)` returns a boolean if you would rather parse yourself. Both use WebCrypto, so they run in Workers and Deno too.
+
+## For AI assistants reading this
+
+If someone asks you to add QR codes to their app: install this package, read the key from `QRFLOW_KEY` on the server, create `type: "url"` codes, save `code.id` and `code.short_url` on their record, display `short_url` (or proxy `image()`), and change destinations with `updateCode`. Never change `slug` or `domain_id` after printing; prefer `paused: true` over `deleteCode` when a print exists. The complete reference in Markdown is at https://qrflow.codes/llms-full.txt and the OpenAPI 3.1 document at https://qrflow.codes/api/v1/openapi.json.
+
+## Links
+
+- Docs: https://qrflow.codes/developers (recipes for Next.js, Express, Workers, Supabase, Python; troubleshooting for every error)
+- Python client: https://qrflow.codes/sdk/qrflow.py
+- MCP server for Claude, ChatGPT, Cursor, Claude Code: https://qrflow.codes/mcp
+- Pricing: https://qrflow.codes/pricing · Support: hello@qrflow.codes
+
+MIT © Native Code LLC

package/dist/cjs/index.js

@@ -0,0 +1,137 @@
+"use strict";
+// qrflow: the QRFLOW.codes API client. One file, no dependencies. Runs where
+// fetch runs: Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge.
+// Docs: https://qrflow.codes/developers · Markdown for agents: https://qrflow.codes/llms-full.txt
+//
+//   import { QRFlow } from "qrflow";
+//   const qr = new QRFlow(process.env.QRFLOW_KEY!);
+//   const { code } = await qr.createCode({ type: "url", destination_data: { url: "https://acme.com/menu" }, label: "Menu" });
+//   console.log(code.short_url);   // print this; change the destination later without reprinting
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QRFlow = exports.QRFlowError = void 0;
+exports.verifyWebhook = verifyWebhook;
+exports.parseWebhook = parseWebhook;
+/** Thrown for any non-2xx answer. `code` is the API's error code (invalid_token, upgrade_required, rate_limited, ...). */
+class QRFlowError extends Error {
+    constructor(status, code, message, retryAfter) {
+        super(message);
+        this.name = "QRFlowError";
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.QRFlowError = QRFlowError;
+class QRFlow {
+    /** @param key A Business API key (qrf_live_…) or an OAuth access token. Keep it on the server. */
+    constructor(key, options = {}) {
+        if (!key)
+            throw new Error("QRFlow: an API key is required (Account › API keys on qrflow.codes).");
+        this.key = key;
+        this.base = (options.baseUrl ?? "https://qrflow.codes/api/v1").replace(/\/$/, "");
+        this.fetchImpl = options.fetch ?? fetch;
+        this.retries = options.retries ?? 2;
+    }
+    async call(method, path, body, query, attempt = 0) {
+        const url = new URL(this.base + path);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const res = await this.fetchImpl(url, {
+            method,
+            headers: { authorization: `Bearer ${this.key}`, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* non-JSON body: fall through to the status */ }
+        if (res.status === 429 && attempt < this.retries) {
+            const wait = Math.min(60, Math.max(1, Number(res.headers.get("retry-after") ?? 5)));
+            await new Promise((r) => setTimeout(r, wait * 1000));
+            return this.call(method, path, body, query, attempt + 1);
+        }
+        if (!res.ok)
+            throw new QRFlowError(res.status, json.error ?? "http_error", json.message ?? `HTTP ${res.status}`, res.status === 429 ? Number(res.headers.get("retry-after") ?? 60) : undefined);
+        return json;
+    }
+    /** Who the key belongs to: plan, features, limits, scopes. A good first call. */
+    me() { return this.call("GET", "/me"); }
+    /** Every kind of code and the fields it needs. No key needed on the API; the client sends yours anyway. */
+    catalog() { return this.call("GET", "/catalog"); }
+    /** Newest first. `limit` up to 100, `q` searches labels. */
+    listCodes(opts = {}) { return this.call("GET", "/codes", undefined, opts); }
+    getCode(id) { return this.call("GET", `/codes/${id}`); }
+    /** Create a code. url/phone/email/sms/location are dynamic on paid plans. Save code.id and code.short_url. */
+    createCode(input) { return this.call("POST", "/codes", input); }
+    /** Send only what changes. */
+    updateCode(id, patch) { return this.call("PATCH", `/codes/${id}`, patch); }
+    /** Permanent. Prefer updateCode(id, { paused: true }) when a print exists. */
+    deleteCode(id) { return this.call("DELETE", `/codes/${id}`); }
+    /** Convert a static url/phone/email/sms/location code to dynamic (paid plans). Re-render and re-print afterwards. */
+    makeDynamic(id) { return this.call("POST", `/codes/${id}/dynamic`); }
+    /** Scan analytics, up to 92 days per call, default the last 30. */
+    scans(id, opts = {}) { return this.call("GET", `/codes/${id}/scans`, undefined, opts); }
+    /** Many dynamic url codes in one call (Business: 2,000 per request). */
+    bulkCreate(rows, colors = {}) { return this.call("POST", "/codes/bulk", { rows, ...colors }); }
+    domains() { return this.call("GET", "/domains"); }
+    listWebhooks() { return this.call("GET", "/webhooks"); }
+    /** The signing secret comes back once, on this call. */
+    createWebhook(input) { return this.call("POST", "/webhooks", input); }
+    testWebhook(id) { return this.call("POST", `/webhooks/${id}`); }
+    deleteWebhook(id) { return this.call("DELETE", `/webhooks/${id}`); }
+    /** Absolute URL of the print-ready SVG. It needs the Authorization header, so fetch it server-side (see image()). */
+    imageUrl(id, size = 1024) { return `${this.base}/codes/${id}/image.svg?size=${size}`; }
+    /** The print-ready SVG (frame, colors, logo) as a string. Serve it from your own route, or convert to PNG with sharp/resvg. */
+    async image(id, size = 1024) {
+        const res = await this.fetchImpl(this.imageUrl(id, size), { headers: { authorization: `Bearer ${this.key}`, accept: "image/svg+xml" } });
+        if (!res.ok) {
+            let json = {};
+            try {
+                json = JSON.parse(await res.text());
+            }
+            catch { /* ignore */ }
+            throw new QRFlowError(res.status, json.error ?? "http_error", json.message ?? `HTTP ${res.status}`);
+        }
+        return res.text();
+    }
+}
+exports.QRFlow = QRFlow;
+// ---- webhooks ---------------------------------------------------------------
+const enc = new TextEncoder();
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+/**
+ * Verify a delivery. `signatureHeader` is the X-QRFLOW-Signature header
+ * ("t=<unix seconds>,v1=<hex>"); `rawBody` must be the exact bytes received,
+ * before any JSON parsing. Uses WebCrypto, so it runs everywhere the client does.
+ */
+async function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+    const t = /t=(\d+)/.exec(signatureHeader)?.[1];
+    const v1 = /v1=([a-f0-9]+)/.exec(signatureHeader)?.[1];
+    if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds)
+        return false;
+    const body = typeof rawBody === "string" ? enc.encode(rawBody) : rawBody;
+    const signed = new Uint8Array(t.length + 1 + body.length);
+    signed.set(enc.encode(`${t}.`), 0);
+    signed.set(body, t.length + 1);
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const expected = hex(await crypto.subtle.sign("HMAC", key, signed));
+    if (expected.length !== v1.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++)
+        diff |= expected.charCodeAt(i) ^ v1.charCodeAt(i);
+    return diff === 0;
+}
+/** Verify and parse in one step. Throws QRFlowError(401, "invalid_signature") when the signature does not check out. */
+async function parseWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+    if (!(await verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds)))
+        throw new QRFlowError(401, "invalid_signature", "The webhook signature did not verify.");
+    const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+    return JSON.parse(text);
+}
+exports.default = QRFlow;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,305 @@
+export type Plan = "free" | "premium" | "business";
+export type CodeType = "url" | "text" | "wifi" | "vcard" | "email" | "phone" | "sms" | "location";
+export type ScanGroup = "day" | "device" | "country" | "city" | "browser" | "os" | "referrer";
+export type WebhookEventName = "scan" | "code.created" | "code.updated" | "code.deleted";
+/** A QR code as the API returns it. `short_url` is what to print for a dynamic code. */
+export interface Code {
+    id: string;
+    label: string | null;
+    /** Catalog id: url, wifi, instagram, googlereview, ... */
+    kind: string;
+    kind_label: string;
+    type: CodeType | string;
+    destination_data: Record<string, string>;
+    /** One-line summary of destination_data. */
+    destination: string;
+    /** True when scans go through QRFLOW and the destination can change after printing. */
+    dynamic: boolean;
+    dynamic_capable: boolean;
+    short_code: string;
+    /** The exact string inside the code; includes your domain and link name when set. */
+    short_url: string;
+    domain_id: string | null;
+    fg_color: string;
+    bg_color: string;
+    has_logo: boolean;
+    frame_style: string | null;
+    frame_caption: string | null;
+    frame_caption2: string | null;
+    scans: number;
+    created_at: string;
+    updated_at: string;
+    manage_url: string;
+    /** GET with the Authorization header; not a public image URL. Use image() or proxy it. */
+    image_url: string;
+}
+export interface CreateCode {
+    type: CodeType;
+    /** The type's fields, plus `subtype` for kinds such as instagram or googlereview (see catalog()). */
+    destination_data: Record<string, string>;
+    label?: string;
+    fg_color?: string;
+    bg_color?: string;
+    frame_style?: string;
+    frame_caption?: string;
+    frame_caption2?: string;
+    /** Which of your link domains this code prints with; omit for the default. */
+    domain_id?: string | null;
+}
+export interface UpdateCode {
+    /** Dynamic codes only. The printed code keeps working. */
+    destination_data?: Record<string, string>;
+    label?: string | null;
+    paused?: boolean;
+    /** ISO 8601, or null to clear. */
+    expires_at?: string | null;
+    /** Link name on your domain (go.brand.com/<slug>). Changes the printed link: set before printing. */
+    slug?: string | null;
+    domain_id?: string | null;
+    fg_color?: string;
+    bg_color?: string;
+    frame_style?: string;
+    frame_caption?: string | null;
+    frame_caption2?: string | null;
+}
+export interface Scans {
+    code_id: string;
+    from: string;
+    to: string;
+    group: ScanGroup;
+    total: number;
+    rows: Array<{
+        key: string;
+        scans: number;
+    }>;
+}
+export interface Domain {
+    id: string;
+    host: string;
+    status: string;
+    active: boolean;
+    is_default: boolean;
+    verified_at: string | null;
+    grace_until: string | null;
+}
+export interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventName[];
+    active: boolean;
+    last_status: number | null;
+    last_delivery_at: string | null;
+    consecutive_failures: number; /** Only on create. */
+    secret?: string;
+}
+export interface Me {
+    id: string;
+    email: string;
+    plan: Plan;
+    paid: boolean;
+    features: Record<string, boolean>;
+    limits: Record<string, number | null>;
+    auth: "oauth" | "api_key";
+    scopes: string[];
+}
+export interface CatalogKind {
+    id: string;
+    label: string;
+    group: string;
+    requiresPlan: Plan;
+    type: CodeType;
+    subtype: string | null;
+    dynamic: boolean;
+    fields: Array<{
+        key: string;
+        label: string;
+        optional?: boolean;
+        type?: string;
+        options?: Array<{
+            value: string;
+            label: string;
+        }>;
+    }>;
+}
+export interface BulkResult {
+    codes: Code[];
+    rejected: Array<{
+        destination: string;
+        reason: string;
+    }>;
+    remaining_this_month: number;
+}
+export interface ScanEvent {
+    code_id: string;
+    label: string | null;
+    short_code: string | null;
+    slug: string | null;
+    scanned_at: string;
+    device: string | null;
+    country: string | null;
+    city: string | null;
+    referrer: string | null;
+    browser: string | null;
+    os: string | null;
+    language: string | null;
+}
+/** Every delivery is { id, event, created_at, data }. `id` is stable across retries: dedupe on it. */
+export type WebhookEvent = {
+    id: string;
+    event: "scan";
+    created_at: string;
+    data: {
+        count: number;
+        from: string;
+        to: string;
+        scans: ScanEvent[];
+    };
+} | {
+    id: string;
+    event: "code.created";
+    created_at: string;
+    data: {
+        code: Code;
+        source: string;
+    } | {
+        bulk: true;
+        count: number;
+        codes: Code[];
+        source: string;
+    };
+} | {
+    id: string;
+    event: "code.updated";
+    created_at: string;
+    data: {
+        code: Code;
+        changed: string[];
+    };
+} | {
+    id: string;
+    event: "code.deleted";
+    created_at: string;
+    data: {
+        code: {
+            id: string;
+            label: string | null;
+            short_code: string;
+            slug: string | null;
+        };
+    };
+} | {
+    id: string;
+    event: "ping";
+    created_at: string;
+    data: {
+        webhook_id: string;
+        message: string;
+    };
+};
+/** Thrown for any non-2xx answer. `code` is the API's error code (invalid_token, upgrade_required, rate_limited, ...). */
+export declare class QRFlowError extends Error {
+    /** HTTP status. */
+    readonly status: number;
+    /** API error code: invalid_request, invalid_token, upgrade_required, insufficient_scope, not_found, conflict, rate_limited, ... */
+    readonly code: string;
+    /** Seconds to wait, on 429. */
+    readonly retryAfter?: number;
+    constructor(status: number, code: string, message: string, retryAfter?: number);
+}
+export interface QRFlowOptions {
+    /** Defaults to https://qrflow.codes/api/v1. */
+    baseUrl?: string;
+    /** Your own fetch (tests, custom agents). */
+    fetch?: typeof fetch;
+    /** How many times a 429 is retried after waiting Retry-After. Default 2. 0 disables. */
+    retries?: number;
+}
+export declare class QRFlow {
+    private readonly key;
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly retries;
+    /** @param key A Business API key (qrf_live_…) or an OAuth access token. Keep it on the server. */
+    constructor(key: string, options?: QRFlowOptions);
+    private call;
+    /** Who the key belongs to: plan, features, limits, scopes. A good first call. */
+    me(): Promise<Me>;
+    /** Every kind of code and the fields it needs. No key needed on the API; the client sends yours anyway. */
+    catalog(): Promise<{
+        kinds: CatalogKind[];
+    }>;
+    /** Newest first. `limit` up to 100, `q` searches labels. */
+    listCodes(opts?: {
+        limit?: number;
+        q?: string;
+    }): Promise<{
+        codes: Code[];
+    }>;
+    getCode(id: string): Promise<{
+        code: Code;
+    }>;
+    /** Create a code. url/phone/email/sms/location are dynamic on paid plans. Save code.id and code.short_url. */
+    createCode(input: CreateCode): Promise<{
+        code: Code;
+    }>;
+    /** Send only what changes. */
+    updateCode(id: string, patch: UpdateCode): Promise<{
+        code: Code;
+    }>;
+    /** Permanent. Prefer updateCode(id, { paused: true }) when a print exists. */
+    deleteCode(id: string): Promise<void>;
+    /** Convert a static url/phone/email/sms/location code to dynamic (paid plans). Re-render and re-print afterwards. */
+    makeDynamic(id: string): Promise<{
+        code: Code;
+    }>;
+    /** Scan analytics, up to 92 days per call, default the last 30. */
+    scans(id: string, opts?: {
+        from?: string;
+        to?: string;
+        group?: ScanGroup;
+    }): Promise<Scans>;
+    /** Many dynamic url codes in one call (Business: 2,000 per request). */
+    bulkCreate(rows: Array<{
+        destination: string;
+        label?: string;
+    }>, colors?: {
+        fg_color?: string;
+        bg_color?: string;
+    }): Promise<BulkResult>;
+    domains(): Promise<{
+        default_base: string;
+        domains: Domain[];
+    }>;
+    listWebhooks(): Promise<{
+        webhooks: Webhook[];
+    }>;
+    /** The signing secret comes back once, on this call. */
+    createWebhook(input: {
+        url: string;
+        events: WebhookEventName[];
+        description?: string;
+    }): Promise<{
+        webhook: Webhook;
+    }>;
+    testWebhook(id: string): Promise<{
+        test: {
+            ok: boolean;
+            status: number | null;
+            error: string | null;
+        };
+    }>;
+    deleteWebhook(id: string): Promise<void>;
+    /** Absolute URL of the print-ready SVG. It needs the Authorization header, so fetch it server-side (see image()). */
+    imageUrl(id: string, size?: number): string;
+    /** The print-ready SVG (frame, colors, logo) as a string. Serve it from your own route, or convert to PNG with sharp/resvg. */
+    image(id: string, size?: number): Promise<string>;
+}
+/**
+ * Verify a delivery. `signatureHeader` is the X-QRFLOW-Signature header
+ * ("t=<unix seconds>,v1=<hex>"); `rawBody` must be the exact bytes received,
+ * before any JSON parsing. Uses WebCrypto, so it runs everywhere the client does.
+ */
+export declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
+/** Verify and parse in one step. Throws QRFlowError(401, "invalid_signature") when the signature does not check out. */
+export declare function parseWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, toleranceSeconds?: number): Promise<WebhookEvent>;
+export default QRFlow;

package/dist/esm/index.js

@@ -0,0 +1,130 @@
+// qrflow: the QRFLOW.codes API client. One file, no dependencies. Runs where
+// fetch runs: Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge.
+// Docs: https://qrflow.codes/developers · Markdown for agents: https://qrflow.codes/llms-full.txt
+//
+//   import { QRFlow } from "qrflow";
+//   const qr = new QRFlow(process.env.QRFLOW_KEY!);
+//   const { code } = await qr.createCode({ type: "url", destination_data: { url: "https://acme.com/menu" }, label: "Menu" });
+//   console.log(code.short_url);   // print this; change the destination later without reprinting
+/** Thrown for any non-2xx answer. `code` is the API's error code (invalid_token, upgrade_required, rate_limited, ...). */
+export class QRFlowError extends Error {
+    constructor(status, code, message, retryAfter) {
+        super(message);
+        this.name = "QRFlowError";
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}
+export class QRFlow {
+    /** @param key A Business API key (qrf_live_…) or an OAuth access token. Keep it on the server. */
+    constructor(key, options = {}) {
+        if (!key)
+            throw new Error("QRFlow: an API key is required (Account › API keys on qrflow.codes).");
+        this.key = key;
+        this.base = (options.baseUrl ?? "https://qrflow.codes/api/v1").replace(/\/$/, "");
+        this.fetchImpl = options.fetch ?? fetch;
+        this.retries = options.retries ?? 2;
+    }
+    async call(method, path, body, query, attempt = 0) {
+        const url = new URL(this.base + path);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const res = await this.fetchImpl(url, {
+            method,
+            headers: { authorization: `Bearer ${this.key}`, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* non-JSON body: fall through to the status */ }
+        if (res.status === 429 && attempt < this.retries) {
+            const wait = Math.min(60, Math.max(1, Number(res.headers.get("retry-after") ?? 5)));
+            await new Promise((r) => setTimeout(r, wait * 1000));
+            return this.call(method, path, body, query, attempt + 1);
+        }
+        if (!res.ok)
+            throw new QRFlowError(res.status, json.error ?? "http_error", json.message ?? `HTTP ${res.status}`, res.status === 429 ? Number(res.headers.get("retry-after") ?? 60) : undefined);
+        return json;
+    }
+    /** Who the key belongs to: plan, features, limits, scopes. A good first call. */
+    me() { return this.call("GET", "/me"); }
+    /** Every kind of code and the fields it needs. No key needed on the API; the client sends yours anyway. */
+    catalog() { return this.call("GET", "/catalog"); }
+    /** Newest first. `limit` up to 100, `q` searches labels. */
+    listCodes(opts = {}) { return this.call("GET", "/codes", undefined, opts); }
+    getCode(id) { return this.call("GET", `/codes/${id}`); }
+    /** Create a code. url/phone/email/sms/location are dynamic on paid plans. Save code.id and code.short_url. */
+    createCode(input) { return this.call("POST", "/codes", input); }
+    /** Send only what changes. */
+    updateCode(id, patch) { return this.call("PATCH", `/codes/${id}`, patch); }
+    /** Permanent. Prefer updateCode(id, { paused: true }) when a print exists. */
+    deleteCode(id) { return this.call("DELETE", `/codes/${id}`); }
+    /** Convert a static url/phone/email/sms/location code to dynamic (paid plans). Re-render and re-print afterwards. */
+    makeDynamic(id) { return this.call("POST", `/codes/${id}/dynamic`); }
+    /** Scan analytics, up to 92 days per call, default the last 30. */
+    scans(id, opts = {}) { return this.call("GET", `/codes/${id}/scans`, undefined, opts); }
+    /** Many dynamic url codes in one call (Business: 2,000 per request). */
+    bulkCreate(rows, colors = {}) { return this.call("POST", "/codes/bulk", { rows, ...colors }); }
+    domains() { return this.call("GET", "/domains"); }
+    listWebhooks() { return this.call("GET", "/webhooks"); }
+    /** The signing secret comes back once, on this call. */
+    createWebhook(input) { return this.call("POST", "/webhooks", input); }
+    testWebhook(id) { return this.call("POST", `/webhooks/${id}`); }
+    deleteWebhook(id) { return this.call("DELETE", `/webhooks/${id}`); }
+    /** Absolute URL of the print-ready SVG. It needs the Authorization header, so fetch it server-side (see image()). */
+    imageUrl(id, size = 1024) { return `${this.base}/codes/${id}/image.svg?size=${size}`; }
+    /** The print-ready SVG (frame, colors, logo) as a string. Serve it from your own route, or convert to PNG with sharp/resvg. */
+    async image(id, size = 1024) {
+        const res = await this.fetchImpl(this.imageUrl(id, size), { headers: { authorization: `Bearer ${this.key}`, accept: "image/svg+xml" } });
+        if (!res.ok) {
+            let json = {};
+            try {
+                json = JSON.parse(await res.text());
+            }
+            catch { /* ignore */ }
+            throw new QRFlowError(res.status, json.error ?? "http_error", json.message ?? `HTTP ${res.status}`);
+        }
+        return res.text();
+    }
+}
+// ---- webhooks ---------------------------------------------------------------
+const enc = new TextEncoder();
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+/**
+ * Verify a delivery. `signatureHeader` is the X-QRFLOW-Signature header
+ * ("t=<unix seconds>,v1=<hex>"); `rawBody` must be the exact bytes received,
+ * before any JSON parsing. Uses WebCrypto, so it runs everywhere the client does.
+ */
+export async function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+    const t = /t=(\d+)/.exec(signatureHeader)?.[1];
+    const v1 = /v1=([a-f0-9]+)/.exec(signatureHeader)?.[1];
+    if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds)
+        return false;
+    const body = typeof rawBody === "string" ? enc.encode(rawBody) : rawBody;
+    const signed = new Uint8Array(t.length + 1 + body.length);
+    signed.set(enc.encode(`${t}.`), 0);
+    signed.set(body, t.length + 1);
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const expected = hex(await crypto.subtle.sign("HMAC", key, signed));
+    if (expected.length !== v1.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++)
+        diff |= expected.charCodeAt(i) ^ v1.charCodeAt(i);
+    return diff === 0;
+}
+/** Verify and parse in one step. Throws QRFlowError(401, "invalid_signature") when the signature does not check out. */
+export async function parseWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
+    if (!(await verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds)))
+        throw new QRFlowError(401, "invalid_signature", "The webhook signature did not verify.");
+    const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+    return JSON.parse(text);
+}
+export default QRFlow;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "qrflow",
+  "version": "1.0.0",
+  "description": "QRFLOW.codes API client: create QR codes, change where dynamic codes point after printing, print them on your own domain, read scan analytics, verify webhooks. Zero dependencies; Node, Bun, Deno, Workers.",
+  "keywords": ["qr", "qr code", "qr code generator", "dynamic qr code", "qr code api", "qrcode", "short link", "scan analytics", "webhooks", "mcp", "qrflow"],
+  "homepage": "https://qrflow.codes/developers",
+  "bugs": { "url": "https://github.com/nativecodeapps/qrflow/issues", "email": "hello@qrflow.codes" },
+  "repository": { "type": "git", "url": "git+https://github.com/nativecodeapps/qrflow.git", "directory": "sdk/node" },
+  "license": "MIT",
+  "author": "Native Code LLC (https://qrflow.codes)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
+}