@profullstack/affiliates 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { parseArgs } from 'node:util';
+import { Affiliates } from "./affiliates.js";
+import { sqliteStore } from "./sqlite.js";
+const HELP = `affiliates - scarce invite codes and affiliate links on a SQLite file
+
+Usage: affiliates [--db FILE] [--json] <command>
+
+  invite create <inviterId> [--note TEXT]   mint one invite (prints the code once)
+  invite list <inviterId>                   list a user's invites (no codes, only hashes are stored)
+  invite revoke <inviteId>                  revoke an unused invite (refunds the quota slot)
+  invite redeem <code> <newUserId>          spend an invite
+  quota get <userId>                        show total / used / left
+  quota set <userId> <total>                give someone more (or fewer) invites
+  invitedby <userId>                        who invited this user
+  invitees <inviterId>                      who joined on this user's invites
+  code <userId>                             the user's affiliate code (created on first call)
+  attribute <code> <newUserId>              first-touch affiliate attribution
+  affiliateof <userId>                      the affiliate a user is attributed to
+  commission <amountCents>                  discount + commission for an amount
+
+Options:
+  --db FILE            SQLite file (default $AFFILIATES_DB or ./affiliates.db)
+  --prefix P           table prefix (default aff_)
+  --default-quota N    invites per user without a custom quota (default 3)
+  --ttl-days N         invite lifetime in days, 0 for none (default 30)
+  --json               machine-readable output
+  -h, --help
+`;
+async function openDb(file) {
+    if (globalThis.Bun) {
+        const mod = await import(__rewriteRelativeImportExtension('bun:sqlite'));
+        return new mod.Database(file, { create: true });
+    }
+    const mod = await import(__rewriteRelativeImportExtension('node:sqlite'));
+    return new mod.DatabaseSync(file);
+}
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            db: { type: 'string' },
+            prefix: { type: 'string' },
+            'default-quota': { type: 'string' },
+            'ttl-days': { type: 'string' },
+            note: { type: 'string' },
+            json: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    const json = values.json === true;
+    const [cmd, sub, ...rest] = positionals;
+    if (values.help || !cmd) {
+        process.stdout.write(HELP);
+        return values.help ? 0 : 1;
+    }
+    const file = values.db ?? process.env.AFFILIATES_DB ?? './affiliates.db';
+    const ttlDays = values['ttl-days'] === undefined ? 30 : Number(values['ttl-days']);
+    const db = await openDb(file);
+    const aff = new Affiliates(sqliteStore(db, values.prefix ? { prefix: values.prefix } : {}), {
+        defaultQuota: values['default-quota'] === undefined ? 3 : Number(values['default-quota']),
+        inviteTtlMs: ttlDays > 0 ? ttlDays * 86_400_000 : null,
+    });
+    const need = (v, name) => {
+        if (!v)
+            throw new Error(`missing <${name}>`);
+        return v;
+    };
+    const out = (data, text) => {
+        process.stdout.write(json ? JSON.stringify(data, null, 2) + '\n' : text + '\n');
+    };
+    const when = (ms) => (ms === null ? '-' : new Date(ms).toISOString());
+    try {
+        if (cmd === 'invite') {
+            if (sub === 'create') {
+                const inv = await aff.createInvite(need(rest[0], 'inviterId'), values.note ?? '');
+                out(inv, `${inv.code}\n(id ${inv.id}, expires ${when(inv.expiresAt)}; the code is shown only once)`);
+            }
+            else if (sub === 'list') {
+                const list = await aff.invites(need(rest[0], 'inviterId'));
+                out(list, list.length === 0
+                    ? 'no invites'
+                    : list
+                        .map((i) => {
+                        const state = i.revokedAt !== null && !i.usedBy ? 'revoked' : i.usedBy ? `used by ${i.usedBy}` : 'open';
+                        return `${i.id}  ${when(i.createdAt)}  ${state}${i.note ? `  ${i.note}` : ''}`;
+                    })
+                        .join('\n'));
+            }
+            else if (sub === 'revoke') {
+                const id = need(rest[0], 'inviteId');
+                await aff.revokeInvite(id);
+                out({ ok: true, id }, `revoked ${id}`);
+            }
+            else if (sub === 'redeem') {
+                const r = await aff.redeemInvite(need(rest[0], 'code'), need(rest[1], 'newUserId'));
+                out(r, r.ok ? `ok: invited by ${r.inviterId}` : `refused: ${r.reason}`);
+                return r.ok ? 0 : 2;
+            }
+            else
+                throw new Error('usage: invite create|list|revoke|redeem');
+        }
+        else if (cmd === 'quota') {
+            if (sub === 'set') {
+                const user = need(rest[0], 'userId');
+                await aff.setQuota(user, Number(need(rest[1], 'total')));
+                const q = await aff.quota(user);
+                out({ userId: user, ...q }, `${user}: ${q.left} of ${q.total} left`);
+            }
+            else if (sub === 'get') {
+                const user = need(rest[0], 'userId');
+                const q = await aff.quota(user);
+                out({ userId: user, ...q }, `${user}: ${q.left} of ${q.total} left (${q.used} used)`);
+            }
+            else
+                throw new Error('usage: quota get|set');
+        }
+        else if (cmd === 'invitedby') {
+            const who = await aff.invitedBy(need(sub, 'userId'));
+            out({ userId: sub, invitedBy: who }, who ?? 'nobody');
+        }
+        else if (cmd === 'invitees') {
+            const list = await aff.invitees(need(sub, 'inviterId'));
+            out(list, list.length ? list.map((i) => `${i.userId}  ${when(i.at)}`).join('\n') : 'nobody yet');
+        }
+        else if (cmd === 'code') {
+            const code = await aff.affiliateCode(need(sub, 'userId'));
+            out({ userId: sub, code }, code);
+        }
+        else if (cmd === 'attribute') {
+            const r = await aff.attribute(need(sub, 'code'), need(rest[0], 'newUserId'));
+            out(r, r.ok ? `attributed to ${r.affiliateId}` : r.affiliateId ? `already attributed to ${r.affiliateId}` : 'refused');
+            return r.ok ? 0 : 2;
+        }
+        else if (cmd === 'affiliateof') {
+            const a = await aff.affiliateOf(need(sub, 'userId'));
+            out({ userId: sub, affiliateId: a }, a ?? 'none');
+        }
+        else if (cmd === 'commission') {
+            const amount = Number(need(sub, 'amountCents'));
+            const c = aff.commission(amount);
+            out({ amountCents: amount, ...c }, `discount ${c.discountCents}c, commission ${c.commissionCents}c`);
+        }
+        else {
+            throw new Error(`unknown command: ${cmd}`);
+        }
+        return 0;
+    }
+    finally {
+        db.close?.();
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (process.argv.includes('--json'))
+        process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+    else
+        process.stderr.write(`affiliates: ${msg}\n`);
+    process.exit(1);
+});

package/dist/codes.d.ts

@@ -0,0 +1,19 @@
+/** Crockford base32 alphabet: no I, L, O, U. */
+export declare const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** `n` random Crockford base32 characters from the CSPRNG (5 bits each). */
+export declare function randomCrockford(n: number): string;
+/** A new invite code, e.g. INV-7K3M-QX9D-2F8H (60 random bits). */
+export declare function generateInviteCode(): string;
+/** A new public affiliate code, 8 Crockford characters (40 random bits). */
+export declare function generateAffiliateCode(): string;
+/**
+ * Canonical form of a user-typed code: case-insensitive, ignores spaces,
+ * dashes and other punctuation, maps the Crockford look-alikes O->0 and I/L->1.
+ * Invite codes come back as INV-XXXX-XXXX-XXXX (the INV prefix is optional on
+ * input); anything else comes back as uppercase Crockford characters.
+ */
+export declare function normalizeCode(input: string): string;
+/** sha256 hex of the normalized code. Only this is stored. */
+export declare function hashCode(code: string): string;
+/** Random opaque id for rows. */
+export declare function newId(): string;

package/dist/codes.js

@@ -0,0 +1,48 @@
+import { createHash, randomBytes } from 'node:crypto';
+/** Crockford base32 alphabet: no I, L, O, U. */
+export const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** `n` random Crockford base32 characters from the CSPRNG (5 bits each). */
+export function randomCrockford(n) {
+    const bytes = randomBytes(n);
+    let out = '';
+    for (let i = 0; i < n; i++)
+        out += CROCKFORD[bytes[i] & 31];
+    return out;
+}
+/** A new invite code, e.g. INV-7K3M-QX9D-2F8H (60 random bits). */
+export function generateInviteCode() {
+    const body = randomCrockford(12);
+    return `INV-${body.slice(0, 4)}-${body.slice(4, 8)}-${body.slice(8, 12)}`;
+}
+/** A new public affiliate code, 8 Crockford characters (40 random bits). */
+export function generateAffiliateCode() {
+    return randomCrockford(8);
+}
+function crockfordFix(s) {
+    return s.replace(/O/g, '0').replace(/[IL]/g, '1');
+}
+/**
+ * Canonical form of a user-typed code: case-insensitive, ignores spaces,
+ * dashes and other punctuation, maps the Crockford look-alikes O->0 and I/L->1.
+ * Invite codes come back as INV-XXXX-XXXX-XXXX (the INV prefix is optional on
+ * input); anything else comes back as uppercase Crockford characters.
+ */
+export function normalizeCode(input) {
+    const s = String(input ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+    if (s.length === 15 && s.startsWith('INV'))
+        return formatInvite(crockfordFix(s.slice(3)));
+    if (s.length === 12)
+        return formatInvite(crockfordFix(s)); // invite typed without INV-
+    return crockfordFix(s);
+}
+function formatInvite(body) {
+    return `INV-${body.slice(0, 4)}-${body.slice(4, 8)}-${body.slice(8, 12)}`;
+}
+/** sha256 hex of the normalized code. Only this is stored. */
+export function hashCode(code) {
+    return createHash('sha256').update(normalizeCode(code)).digest('hex');
+}
+/** Random opaque id for rows. */
+export function newId() {
+    return randomBytes(12).toString('base64url');
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { Affiliates } from './affiliates.js';
+export type { Invite, RedeemInviteResult, AffiliatesOptions, AttributeResult, ExternalCodes } from './affiliates.js';
+export type { AffiliateStore, InviteRow, AttributionRow } from './store.js';
+export { memoryStore } from './memory.js';
+export { sqliteStore } from './sqlite.js';
+export type { SqliteLike } from './sqlite.js';
+export { postgresStore } from './postgres.js';
+export type { PgLike } from './postgres.js';
+export type { SqlStoreOptions } from './sql.js';
+export { supabaseStore, supabaseMigrationSql } from './supabase.js';
+export type { SupabaseLike, SupabaseStoreOptions } from './supabase.js';
+export { REF_COOKIE, REF_PARAM, refFromRequest } from './ref.js';
+export type { RequestLike } from './ref.js';
+export { normalizeCode, generateInviteCode, hashCode } from './codes.js';
+export { buildReferralUrl, extractCode, calculateReferral, DEFAULT_SPLIT } from '@profullstack/referrals';
+export type { ReferralSplit } from '@profullstack/referrals';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { Affiliates } from "./affiliates.js";
+export { memoryStore } from "./memory.js";
+export { sqliteStore } from "./sqlite.js";
+export { postgresStore } from "./postgres.js";
+export { supabaseStore, supabaseMigrationSql } from "./supabase.js";
+export { REF_COOKIE, REF_PARAM, refFromRequest } from "./ref.js";
+export { normalizeCode, generateInviteCode, hashCode } from "./codes.js";
+export { buildReferralUrl, extractCode, calculateReferral, DEFAULT_SPLIT } from '@profullstack/referrals';

package/dist/memory.d.ts

@@ -0,0 +1,3 @@
+import type { AffiliateStore } from './store.js';
+/** In-process store for tests and prototypes. Every method body is synchronous, so it is atomic. */
+export declare function memoryStore(): AffiliateStore;

package/dist/memory.js

@@ -0,0 +1,105 @@
+const counted = (r) => r.revokedAt === null || r.usedBy !== null;
+/** In-process store for tests and prototypes. Every method body is synchronous, so it is atomic. */
+export function memoryStore() {
+    const quotas = new Map();
+    const invites = new Map();
+    const byHash = new Map();
+    const codes = new Map(); // userId -> code
+    const codeOwners = new Map(); // code -> userId
+    const attributions = new Map();
+    const copy = (r) => (r ? { ...r } : null);
+    return {
+        async getQuota(userId) {
+            return quotas.has(userId) ? quotas.get(userId) : null;
+        },
+        async setQuota(userId, total) {
+            quotas.set(userId, total);
+        },
+        async countInvites(inviterId) {
+            let n = 0;
+            for (const r of invites.values())
+                if (r.inviterId === inviterId && counted(r))
+                    n++;
+            return n;
+        },
+        async insertInvite(row, limit) {
+            let n = 0;
+            for (const r of invites.values())
+                if (r.inviterId === row.inviterId && counted(r))
+                    n++;
+            if (n >= limit)
+                return false;
+            if (byHash.has(row.codeHash))
+                throw new Error('invite code collision');
+            invites.set(row.id, { ...row });
+            byHash.set(row.codeHash, row.id);
+            return true;
+        },
+        async getInviteByHash(codeHash) {
+            const id = byHash.get(codeHash);
+            return id ? copy(invites.get(id)) : null;
+        },
+        async getInvite(id) {
+            return copy(invites.get(id));
+        },
+        async claimInvite(id, userId, at) {
+            const r = invites.get(id);
+            if (!r || r.usedBy !== null || r.revokedAt !== null)
+                return false;
+            r.usedBy = userId;
+            r.usedAt = at;
+            return true;
+        },
+        async revokeInvite(id, at) {
+            const r = invites.get(id);
+            if (r && r.revokedAt === null)
+                r.revokedAt = at;
+        },
+        async listInvites(inviterId) {
+            return [...invites.values()]
+                .filter((r) => r.inviterId === inviterId)
+                .sort((a, b) => b.createdAt - a.createdAt)
+                .map((r) => ({ ...r }));
+        },
+        async invitedBy(userId) {
+            let best = null;
+            for (const r of invites.values()) {
+                if (r.usedBy === userId && (best === null || (r.usedAt ?? 0) < (best.usedAt ?? 0)))
+                    best = r;
+            }
+            return best ? best.inviterId : null;
+        },
+        async invitees(inviterId) {
+            return [...invites.values()]
+                .filter((r) => r.inviterId === inviterId && r.usedBy !== null)
+                .sort((a, b) => (a.usedAt ?? 0) - (b.usedAt ?? 0))
+                .map((r) => ({ userId: r.usedBy, at: r.usedAt }));
+        },
+        async getAffiliateCode(userId) {
+            return codes.get(userId) ?? null;
+        },
+        async putAffiliateCode(userId, code) {
+            const existing = codes.get(userId);
+            if (existing)
+                return existing;
+            if (codeOwners.has(code))
+                return null;
+            codes.set(userId, code);
+            codeOwners.set(code, userId);
+            return code;
+        },
+        async affiliateByCode(code) {
+            return codeOwners.get(code) ?? null;
+        },
+        async attribute(row) {
+            if (attributions.has(row.userId))
+                return false;
+            attributions.set(row.userId, { ...row });
+            return true;
+        },
+        async getAttribution(userId) {
+            const r = attributions.get(userId);
+            return r ? { ...r } : null;
+        },
+    };
+}

package/dist/postgres.d.ts

@@ -0,0 +1,10 @@
+import { type SqlStoreOptions } from './sql.js';
+import type { AffiliateStore } from './store.js';
+/** Anything with a node-postgres style `query` (pg.Pool, pg.Client, @profullstack/libsql-pg, ...). */
+export interface PgLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+/** Store on Postgres. Creates its tables (prefix `aff_`) on first use. */
+export declare function postgresStore(pool: PgLike, opts?: SqlStoreOptions): AffiliateStore;

package/dist/postgres.js

@@ -0,0 +1,8 @@
+import { sqlStore } from "./sql.js";
+/** Store on Postgres. Creates its tables (prefix `aff_`) on first use. */
+export function postgresStore(pool, opts = {}) {
+    return sqlStore(async (sql, params) => {
+        const res = await pool.query(sql, params.map((v) => (v === undefined ? null : v)));
+        return res?.rows ?? [];
+    }, opts, 'postgres');
+}

package/dist/ref.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cookie name used by @profullstack/referrals (`trackReferralCode` in its `next` adapter defaults
+ * `cookieName` to this; its React `ReferralProvider` uses the same string as its sessionStorage key).
+ * Sites already on @profullstack/referrals keep setting this one cookie; affiliates reads it and never
+ * sets a second one, so one sign-up is counted once.
+ */
+export declare const REF_COOKIE = "referral_code";
+/** Query parameter for affiliate links, the same default as @profullstack/referrals (`?ref=`). */
+export declare const REF_PARAM = "ref";
+export type RequestLike = Request | {
+    headers: Headers;
+    url: string;
+};
+/**
+ * The referral/affiliate code a request carries: `?ref=` on the URL first (the click being handled),
+ * otherwise the `referral_code` cookie that @profullstack/referrals' middleware set on an earlier
+ * visit. Returns null when neither is present. Pass the result to `aff.attribute(code, newUserId)`.
+ */
+export declare function refFromRequest(req: RequestLike, opts?: {
+    param?: string;
+    cookieName?: string;
+}): string | null;

package/dist/ref.js

@@ -0,0 +1,49 @@
+/**
+ * Cookie name used by @profullstack/referrals (`trackReferralCode` in its `next` adapter defaults
+ * `cookieName` to this; its React `ReferralProvider` uses the same string as its sessionStorage key).
+ * Sites already on @profullstack/referrals keep setting this one cookie; affiliates reads it and never
+ * sets a second one, so one sign-up is counted once.
+ */
+export const REF_COOKIE = 'referral_code';
+/** Query parameter for affiliate links, the same default as @profullstack/referrals (`?ref=`). */
+export const REF_PARAM = 'ref';
+function readCookie(header, name) {
+    if (!header)
+        return null;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() !== name)
+            continue;
+        let v = part.slice(eq + 1).trim();
+        if (v.startsWith('"') && v.endsWith('"') && v.length >= 2)
+            v = v.slice(1, -1);
+        try {
+            v = decodeURIComponent(v);
+        }
+        catch {
+            /* keep raw */
+        }
+        return v || null;
+    }
+    return null;
+}
+/**
+ * The referral/affiliate code a request carries: `?ref=` on the URL first (the click being handled),
+ * otherwise the `referral_code` cookie that @profullstack/referrals' middleware set on an earlier
+ * visit. Returns null when neither is present. Pass the result to `aff.attribute(code, newUserId)`.
+ */
+export function refFromRequest(req, opts = {}) {
+    const param = opts.param ?? REF_PARAM;
+    const cookieName = opts.cookieName ?? REF_COOKIE;
+    try {
+        const q = new URL(req.url, 'http://localhost').searchParams.get(param)?.trim();
+        if (q)
+            return q;
+    }
+    catch {
+        /* unparseable url: fall through to the cookie */
+    }
+    return readCookie(req.headers.get('cookie'), cookieName)?.trim() || null;
+}

package/dist/sql.d.ts

@@ -0,0 +1,12 @@
+import type { AffiliateStore } from './store.js';
+/** Runs one statement written with $1..$n placeholders and returns its rows. */
+export type Exec = (sql: string, params: unknown[]) => Promise<any[]>;
+export interface SqlStoreOptions {
+    /** Table name prefix. Default `aff_`. */
+    prefix?: string;
+}
+/** Internal: which engine the SQL runs on. */
+export type Dialect = 'sqlite' | 'postgres';
+export declare function ddl(prefix: string, dialect?: Dialect): string[];
+/** Store over any SQL engine that speaks the common subset of SQLite and Postgres (RETURNING, ON CONFLICT). */
+export declare function sqlStore(exec: Exec, opts?: SqlStoreOptions, dialect?: Dialect): AffiliateStore;

package/dist/sql.js

@@ -0,0 +1,172 @@
+function checkPrefix(prefix) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix))
+        throw new Error(`invalid table prefix: ${prefix}`);
+    return prefix;
+}
+const num = (v) => (v === null || v === undefined ? null : Number(v));
+const str = (v) => (v === null || v === undefined ? null : String(v));
+function toInvite(r) {
+    return {
+        id: String(r.id),
+        codeHash: String(r.code_hash),
+        inviterId: String(r.inviter_id),
+        createdAt: Number(r.created_at),
+        expiresAt: num(r.expires_at),
+        usedBy: str(r.used_by),
+        usedAt: num(r.used_at),
+        note: r.note == null ? '' : String(r.note),
+        revokedAt: num(r.revoked_at),
+    };
+}
+export function ddl(prefix, dialect = 'sqlite') {
+    const p = checkPrefix(prefix);
+    const pgOnly = dialect === 'postgres'
+        ? [
+            // Quota check + insert under a per-inviter advisory lock. A plpgsql function takes a fresh
+            // snapshot per statement, so the count after the lock sees every committed invite; a single
+            // INSERT ... SELECT WHERE count < limit would race under READ COMMITTED.
+            `CREATE OR REPLACE FUNCTION ${p}insert_invite(
+            p_id TEXT, p_hash TEXT, p_inviter TEXT, p_created BIGINT, p_expires BIGINT, p_note TEXT, p_limit INTEGER
+          ) RETURNS BOOLEAN LANGUAGE plpgsql AS $fn$
+          BEGIN
+            PERFORM pg_advisory_xact_lock(hashtext('${p}invites'), hashtext(p_inviter));
+            IF (SELECT count(*) FROM ${p}invites
+                WHERE inviter_id = p_inviter AND (revoked_at IS NULL OR used_by IS NOT NULL)) >= p_limit THEN
+              RETURN FALSE;
+            END IF;
+            INSERT INTO ${p}invites (id, code_hash, inviter_id, created_at, expires_at, note)
+              VALUES (p_id, p_hash, p_inviter, p_created, p_expires, p_note);
+            RETURN TRUE;
+          END
+          $fn$`,
+        ]
+        : [];
+    return [
+        `CREATE TABLE IF NOT EXISTS ${p}invites (
+      id TEXT PRIMARY KEY,
+      code_hash TEXT NOT NULL UNIQUE,
+      inviter_id TEXT NOT NULL,
+      created_at BIGINT NOT NULL,
+      expires_at BIGINT,
+      used_by TEXT,
+      used_at BIGINT,
+      note TEXT NOT NULL DEFAULT '',
+      revoked_at BIGINT
+    )`,
+        `CREATE INDEX IF NOT EXISTS ${p}invites_inviter_idx ON ${p}invites (inviter_id)`,
+        `CREATE INDEX IF NOT EXISTS ${p}invites_used_by_idx ON ${p}invites (used_by)`,
+        `CREATE TABLE IF NOT EXISTS ${p}quotas (
+      user_id TEXT PRIMARY KEY,
+      total INTEGER NOT NULL
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${p}codes (
+      user_id TEXT PRIMARY KEY,
+      code TEXT NOT NULL UNIQUE,
+      created_at BIGINT NOT NULL
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${p}attributions (
+      user_id TEXT PRIMARY KEY,
+      affiliate_id TEXT NOT NULL,
+      code TEXT NOT NULL,
+      at BIGINT NOT NULL
+    )`,
+        `CREATE INDEX IF NOT EXISTS ${p}attributions_affiliate_idx ON ${p}attributions (affiliate_id)`,
+        ...pgOnly,
+    ];
+}
+/** Store over any SQL engine that speaks the common subset of SQLite and Postgres (RETURNING, ON CONFLICT). */
+export function sqlStore(exec, opts = {}, dialect = 'sqlite') {
+    const p = checkPrefix(opts.prefix ?? 'aff_');
+    let ready = null;
+    const init = () => (ready ??= (async () => {
+        for (const stmt of ddl(p, dialect))
+            await exec(stmt, []);
+    })().catch((err) => {
+        ready = null;
+        throw err;
+    }));
+    const q = async (sql, params = []) => {
+        await init();
+        return exec(sql, params);
+    };
+    const COUNTED = `(revoked_at IS NULL OR used_by IS NOT NULL)`;
+    return {
+        async getQuota(userId) {
+            const rows = await q(`SELECT total FROM ${p}quotas WHERE user_id = $1`, [userId]);
+            return rows[0] ? Number(rows[0].total) : null;
+        },
+        async setQuota(userId, total) {
+            await q(`INSERT INTO ${p}quotas (user_id, total) VALUES ($1, $2)
+         ON CONFLICT (user_id) DO UPDATE SET total = excluded.total`, [userId, total]);
+        },
+        async countInvites(inviterId) {
+            const rows = await q(`SELECT count(*) AS n FROM ${p}invites WHERE inviter_id = $1 AND ${COUNTED}`, [inviterId]);
+            return Number(rows[0]?.n ?? 0);
+        },
+        async insertInvite(row, limit) {
+            if (dialect === 'postgres') {
+                const res = await q(`SELECT ${p}insert_invite($1, $2, $3, $4, $5, $6, $7) AS ok`, [
+                    row.id, row.codeHash, row.inviterId, row.createdAt, row.expiresAt, row.note, limit,
+                ]);
+                return res[0]?.ok === true || res[0]?.ok === 't' || res[0]?.ok === 1;
+            }
+            // SQLite: writers are serialized, so the check and the insert cannot interleave.
+            const rows = await q(`INSERT INTO ${p}invites (id, code_hash, inviter_id, created_at, expires_at, used_by, used_at, note, revoked_at)
+         SELECT CAST($1 AS TEXT), CAST($2 AS TEXT), CAST($3 AS TEXT), CAST($4 AS BIGINT), CAST($5 AS BIGINT), NULL, NULL, CAST($6 AS TEXT), NULL
+         WHERE (SELECT count(*) FROM ${p}invites WHERE inviter_id = CAST($3 AS TEXT) AND ${COUNTED}) < CAST($7 AS INTEGER)
+         RETURNING id`, [row.id, row.codeHash, row.inviterId, row.createdAt, row.expiresAt, row.note, limit]);
+            return rows.length > 0;
+        },
+        async getInviteByHash(codeHash) {
+            const rows = await q(`SELECT * FROM ${p}invites WHERE code_hash = $1`, [codeHash]);
+            return rows[0] ? toInvite(rows[0]) : null;
+        },
+        async getInvite(id) {
+            const rows = await q(`SELECT * FROM ${p}invites WHERE id = $1`, [id]);
+            return rows[0] ? toInvite(rows[0]) : null;
+        },
+        async claimInvite(id, userId, at) {
+            const rows = await q(`UPDATE ${p}invites SET used_by = $2, used_at = $3
+         WHERE id = $1 AND used_by IS NULL AND revoked_at IS NULL RETURNING id`, [id, userId, at]);
+            return rows.length > 0;
+        },
+        async revokeInvite(id, at) {
+            await q(`UPDATE ${p}invites SET revoked_at = $2 WHERE id = $1 AND revoked_at IS NULL`, [id, at]);
+        },
+        async listInvites(inviterId) {
+            const rows = await q(`SELECT * FROM ${p}invites WHERE inviter_id = $1 ORDER BY created_at DESC, id`, [inviterId]);
+            return rows.map(toInvite);
+        },
+        async invitedBy(userId) {
+            const rows = await q(`SELECT inviter_id FROM ${p}invites WHERE used_by = $1 ORDER BY used_at ASC LIMIT 1`, [userId]);
+            return rows[0] ? String(rows[0].inviter_id) : null;
+        },
+        async invitees(inviterId) {
+            const rows = await q(`SELECT used_by, used_at FROM ${p}invites WHERE inviter_id = $1 AND used_by IS NOT NULL ORDER BY used_at ASC`, [inviterId]);
+            return rows.map((r) => ({ userId: String(r.used_by), at: Number(r.used_at) }));
+        },
+        async getAffiliateCode(userId) {
+            const rows = await q(`SELECT code FROM ${p}codes WHERE user_id = $1`, [userId]);
+            return rows[0] ? String(rows[0].code) : null;
+        },
+        async putAffiliateCode(userId, code, at) {
+            await q(`INSERT INTO ${p}codes (user_id, code, created_at) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`, [userId, code, at]);
+            const rows = await q(`SELECT code FROM ${p}codes WHERE user_id = $1`, [userId]);
+            return rows[0] ? String(rows[0].code) : null;
+        },
+        async affiliateByCode(code) {
+            const rows = await q(`SELECT user_id FROM ${p}codes WHERE code = $1`, [code]);
+            return rows[0] ? String(rows[0].user_id) : null;
+        },
+        async attribute(row) {
+            const rows = await q(`INSERT INTO ${p}attributions (user_id, affiliate_id, code, at) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (user_id) DO NOTHING RETURNING user_id`, [row.userId, row.affiliateId, row.code, row.at]);
+            return rows.length > 0;
+        },
+        async getAttribution(userId) {
+            const rows = await q(`SELECT * FROM ${p}attributions WHERE user_id = $1`, [userId]);
+            const r = rows[0];
+            return r ? { userId: String(r.user_id), affiliateId: String(r.affiliate_id), code: String(r.code), at: Number(r.at) } : null;
+        },
+    };
+}