@profullstack/affiliates 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc. (moshcoder)
+
+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

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @profullstack/affiliates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scarce invite codes plus open affiliate links, for every Profullstack property.
+
+- **Invite codes** are scarce on purpose. Each user gets a small quota (default 3). Each code
+  works once, expires (default 30 days), cannot be redeemed by the person who made it, and records
+  who invited whom. Codes look like `INV-7K3M-QX9D-2F8H` (60 random bits, Crockford base32) and are
+  stored only as sha256 hashes, so a database leak does not leak working codes.
+- **Affiliate codes** are open: one stable public code per user, unlimited use, first-touch
+  attribution that is never overwritten.
+- **Commission math** is not reimplemented here. It comes from
+  [`@profullstack/referrals`](https://www.npmjs.com/package/@profullstack/referrals)
+  (`calculateReferral`, `DEFAULT_SPLIT` = 60% affiliate, 20% customer discount), and its
+  `buildReferralUrl` / `extractCode` are re-exported.
+
+Stores: in-memory, SQLite (`bun:sqlite`, `node:sqlite`, `better-sqlite3`) and Postgres (anything
+with a node-postgres style `query`). SQL stores create their own tables (prefix `aff_`).
+
+```sh
+npm i @profullstack/affiliates
+```
+
+## Quick start
+
+```ts
+import { Database } from 'bun:sqlite';               // or: import { DatabaseSync } from 'node:sqlite'
+import { Affiliates, sqliteStore, buildReferralUrl, extractCode } from '@profullstack/affiliates';
+
+const aff = new Affiliates(sqliteStore(new Database('app.db')));
+
+// invites: scarce, single use
+const invite = await aff.createInvite('user_alice', 'for Carol');
+invite.code;                                          // 'INV-7K3M-QX9D-2F8H' (shown once, only the hash is stored)
+await aff.quota('user_alice');                        // { total: 3, used: 1, left: 2 }
+await aff.redeemInvite(invite.code, 'user_carol');    // { ok: true, inviterId: 'user_alice', inviteId: '...' }
+await aff.redeemInvite(invite.code, 'user_dave');     // { ok: false, reason: 'used' }
+await aff.invitedBy('user_carol');                    // 'user_alice'
+await aff.setQuota('user_alice', 10);                 // admin: hand out more
+
+// affiliate links: open, unlimited, first touch wins
+const code = await aff.affiliateCode('user_alice');   // 'E6KETYBK' (stable)
+const link = buildReferralUrl('https://example.com/signup', code);  // ...?ref=E6KETYBK
+await aff.attribute(extractCode(link)!, 'user_erin'); // { ok: true, affiliateId: 'user_alice' }
+aff.commission(10_000);                               // { discountCents: 2000, commissionCents: 6000 }
+```
+
+Postgres:
+
+```ts
+import pg from 'pg';
+import { Affiliates, postgresStore } from '@profullstack/affiliates';
+const aff = new Affiliates(postgresStore(new pg.Pool({ connectionString: process.env.DATABASE_URL })));
+```
+
+## Invite-only signup in 5 lines
+
+```ts
+const aff = new Affiliates(sqliteStore(db));
+const r = await aff.redeemInvite(body.inviteCode, newUserId);    // in your signup handler, before creating the account
+if (!r.ok) return new Response(`Invite ${r.reason}`, { status: 403 });
+await createUser(newUserId, { invitedBy: r.inviterId });
+// later, on the user's settings page: const { code } = await aff.createInvite(userId);
+```
+
+Allocate the user id before redeeming (or redeem inside the same transaction you create the user in)
+so a failed account creation does not silently burn the invite. If it does, `setQuota` the inviter
+one more.
+
+## API
+
+```ts
+export type Invite = {
+  code: string;            // plaintext, only on create
+  id: string;
+  inviterId: string;
+  createdAt: number;       // ms
+  expiresAt: number | null;
+  usedBy: string | null;
+  usedAt: number | null;
+  note: string;
+};
+export type RedeemInviteResult =
+  | { ok: true; inviterId: string; inviteId: string }
+  | { ok: false; reason: 'invalid' | 'expired' | 'used' | 'self' | 'revoked' };
+
+export interface AffiliateStore { /* see src/store.ts: quota, invite, claim, attribution primitives */ }
+export function memoryStore(): AffiliateStore;
+export function sqliteStore(db: SqliteLike, opts?: { prefix?: string }): AffiliateStore;
+export function postgresStore(
+  pool: { query(sql: string, params?: unknown[]): Promise<{ rows: any[] }> },
+  opts?: { prefix?: string },
+): AffiliateStore;
+
+export class Affiliates {
+  constructor(store: AffiliateStore, opts?: {
+    now?: () => number;              // clock, default Date.now
+    defaultQuota?: number;           // default 3
+    inviteTtlMs?: number | null;     // default 30 days, null = never expires
+    split?: ReferralSplit;           // default DEFAULT_SPLIT from @profullstack/referrals
+  });
+  quota(userId: string): Promise<{ total: number; used: number; left: number }>;
+  setQuota(userId: string, total: number): Promise<void>;
+  createInvite(inviterId: string, note?: string): Promise<Invite>;   // throws Error('no invites left')
+  redeemInvite(code: string, newUserId: string): Promise<RedeemInviteResult>;
+  invitedBy(userId: string): Promise<string | null>;
+  invitees(inviterId: string): Promise<{ userId: string; at: number }[]>;
+  invites(inviterId: string): Promise<Omit<Invite, 'code'>[]>;       // newest first; also carries revokedAt
+  revokeInvite(inviteId: string): Promise<void>;
+  affiliateCode(userId: string): Promise<string>;
+  attribute(code: string, newUserId: string): Promise<{ ok: boolean; affiliateId?: string }>;
+  affiliateOf(userId: string): Promise<string | null>;
+  commission(amountCents: number): { discountCents: number; commissionCents: number };
+}
+export { buildReferralUrl, extractCode, calculateReferral, DEFAULT_SPLIT } from '@profullstack/referrals';
+export function normalizeCode(input: string): string;
+```
+
+Semantics worth knowing:
+
+- **Quota** counts every invite a user created except ones revoked before use, so revoking an unused
+  invite refunds the slot. `setQuota` sets the total, not an increment.
+- **Single use** is enforced in the store with `UPDATE ... WHERE used_by IS NULL AND revoked_at IS NULL`;
+  under any number of concurrent redeems exactly one wins and the rest get `used`.
+- **Quota under concurrency**: SQLite serializes writers, and on Postgres the check and insert run in
+  a small `aff_insert_invite()` function under a per-inviter advisory lock, so parallel
+  `createInvite` calls cannot overshoot.
+- **Redeem order**: `invalid`, `revoked`, `used`, `self`, `expired`. A self-redeem does not burn the
+  invite. If a user redeems two different invites, `invitedBy` returns the first inviter.
+- **normalizeCode** uppercases, drops spaces and punctuation, and maps the Crockford look-alikes
+  `O` to `0` and `I`/`L` to `1`. Invite codes come back as `INV-XXXX-XXXX-XXXX` (the `INV` prefix is
+  optional on input), so `inv 7k3m qx9d 2f8h` redeems.
+- **Affiliate attribution** is first touch: a second `attribute` for the same user returns
+  `{ ok: false, affiliateId: <the original> }`. Users cannot attribute themselves.
+
+Tables (prefix configurable): `aff_invites`, `aff_quotas`, `aff_codes`, `aff_attributions`.
+
+## CLI
+
+```sh
+npx @profullstack/affiliates --db app.db invite create user_alice --note "for Carol"
+affiliates --db app.db invite list user_alice
+affiliates --db app.db invite revoke <inviteId>
+affiliates --db app.db invite redeem INV-7K3M-QX9D-2F8H user_carol
+affiliates --db app.db quota set user_alice 10
+affiliates --db app.db quota get user_alice
+affiliates --db app.db invitedby user_carol
+affiliates --db app.db invitees user_alice
+affiliates --db app.db code user_alice
+affiliates --db app.db --json commission 10000
+```
+
+Works on a SQLite file through `node:sqlite` under Node (22.13+) and `bun:sqlite` under Bun. Every
+command takes `--json`. Other options: `--prefix`, `--default-quota`, `--ttl-days` (0 = no expiry).
+`--db` defaults to `$AFFILIATES_DB`, then `./affiliates.db`.
+
+## Development
+
+```sh
+npm test                 # node --experimental-strip-types --test (memory + node:sqlite)
+AFFILIATES_TEST_PG_URL=postgres://postgres:x@127.0.0.1:55432/postgres npm test   # adds real Postgres
+npm run build            # tsc to dist/
+```
+
+MIT, Profullstack, Inc.

package/dist/affiliates.d.ts

@@ -0,0 +1,80 @@
+import { type ReferralSplit } from '@profullstack/referrals';
+import type { AffiliateStore } from './store.js';
+export type Invite = {
+    /** Plaintext code. Only returned by createInvite; never stored. */
+    code: string;
+    id: string;
+    inviterId: string;
+    createdAt: number;
+    expiresAt: number | null;
+    usedBy: string | null;
+    usedAt: number | null;
+    note: string;
+};
+export type RedeemInviteResult = {
+    ok: true;
+    inviterId: string;
+    inviteId: string;
+} | {
+    ok: false;
+    reason: 'invalid' | 'expired' | 'used' | 'self' | 'revoked';
+};
+export interface AffiliatesOptions {
+    /** Clock in ms. Default Date.now. */
+    now?: () => number;
+    /** Invites each user may create unless setQuota says otherwise. Default 3. */
+    defaultQuota?: number;
+    /** Invite lifetime in ms; null for no expiry. Default 30 days. */
+    inviteTtlMs?: number | null;
+    /** Commission split passed to @profullstack/referrals. Default DEFAULT_SPLIT (60% affiliate, 20% customer). */
+    split?: ReferralSplit;
+}
+/** Scarce invite codes plus open affiliate links over any AffiliateStore. */
+export declare class Affiliates {
+    readonly store: AffiliateStore;
+    readonly now: () => number;
+    readonly defaultQuota: number;
+    readonly inviteTtlMs: number | null;
+    readonly split: ReferralSplit;
+    constructor(store: AffiliateStore, opts?: AffiliatesOptions);
+    private total;
+    /** Invites a user may create, has created (revoked-before-use ones are refunded), and has left. */
+    quota(userId: string): Promise<{
+        total: number;
+        used: number;
+        left: number;
+    }>;
+    /** Admin: set a user's invite allowance (total, not additional). */
+    setQuota(userId: string, total: number): Promise<void>;
+    /** Mint one invite. Throws Error('no invites left') when the quota is spent. */
+    createInvite(inviterId: string, note?: string): Promise<Invite>;
+    /** Spend an invite on a new user. Single use; the inviter cannot redeem their own. */
+    redeemInvite(code: string, newUserId: string): Promise<RedeemInviteResult>;
+    /** Who invited this user (first redeemed invite), or null. */
+    invitedBy(userId: string): Promise<string | null>;
+    /** Users who joined on this inviter's invites, oldest first. */
+    invitees(inviterId: string): Promise<{
+        userId: string;
+        at: number;
+    }[]>;
+    /** Invites this user created, newest first, without codes (only hashes are stored). Includes revokedAt. */
+    invites(inviterId: string): Promise<(Omit<Invite, 'code'> & {
+        revokedAt: number | null;
+    })[]>;
+    /** Revoke an unused invite; it stops working and its quota slot is refunded. */
+    revokeInvite(inviteId: string): Promise<void>;
+    /** The user's public affiliate code: stable, created on first call, unlimited use. */
+    affiliateCode(userId: string): Promise<string>;
+    /** First-touch attribution of a new user to the affiliate who owns `code`. Never overwrites. */
+    attribute(code: string, newUserId: string): Promise<{
+        ok: boolean;
+        affiliateId?: string;
+    }>;
+    /** The affiliate a user is attributed to, or null. */
+    affiliateOf(userId: string): Promise<string | null>;
+    /** Discount for the new customer and commission for the affiliate, via @profullstack/referrals. */
+    commission(amountCents: number): {
+        discountCents: number;
+        commissionCents: number;
+    };
+}

package/dist/affiliates.js

@@ -0,0 +1,157 @@
+import { calculateReferral, DEFAULT_SPLIT } from '@profullstack/referrals';
+import { generateAffiliateCode, generateInviteCode, hashCode, newId, normalizeCode } from "./codes.js";
+const DAY = 24 * 60 * 60 * 1000;
+function publicInvite(r) {
+    return {
+        id: r.id,
+        inviterId: r.inviterId,
+        createdAt: r.createdAt,
+        expiresAt: r.expiresAt,
+        usedBy: r.usedBy,
+        usedAt: r.usedAt,
+        note: r.note,
+        revokedAt: r.revokedAt,
+    };
+}
+/** Scarce invite codes plus open affiliate links over any AffiliateStore. */
+export class Affiliates {
+    store;
+    now;
+    defaultQuota;
+    inviteTtlMs;
+    split;
+    constructor(store, opts = {}) {
+        this.store = store;
+        this.now = opts.now ?? Date.now;
+        this.defaultQuota = opts.defaultQuota ?? 3;
+        this.inviteTtlMs = opts.inviteTtlMs === undefined ? 30 * DAY : opts.inviteTtlMs;
+        this.split = opts.split ?? DEFAULT_SPLIT;
+    }
+    async total(userId) {
+        const q = await this.store.getQuota(userId);
+        return q ?? this.defaultQuota;
+    }
+    /** Invites a user may create, has created (revoked-before-use ones are refunded), and has left. */
+    async quota(userId) {
+        const [total, used] = await Promise.all([this.total(userId), this.store.countInvites(userId)]);
+        return { total, used, left: Math.max(0, total - used) };
+    }
+    /** Admin: set a user's invite allowance (total, not additional). */
+    async setQuota(userId, total) {
+        if (!Number.isInteger(total) || total < 0)
+            throw new Error('quota must be a non-negative integer');
+        await this.store.setQuota(userId, total);
+    }
+    /** Mint one invite. Throws Error('no invites left') when the quota is spent. */
+    async createInvite(inviterId, note = '') {
+        if (!inviterId)
+            throw new Error('inviterId required');
+        const limit = await this.total(inviterId);
+        const createdAt = this.now();
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const code = generateInviteCode();
+            const row = {
+                id: newId(),
+                codeHash: hashCode(code),
+                inviterId,
+                createdAt,
+                expiresAt: this.inviteTtlMs === null ? null : createdAt + this.inviteTtlMs,
+                usedBy: null,
+                usedAt: null,
+                note: String(note ?? ''),
+                revokedAt: null,
+            };
+            let inserted;
+            try {
+                inserted = await this.store.insertInvite(row, limit);
+            }
+            catch (err) {
+                // 60-bit code collision: astronomically unlikely, retry with a fresh code
+                if (/unique|collision|constraint/i.test(String(err?.message)))
+                    continue;
+                throw err;
+            }
+            if (!inserted)
+                throw new Error('no invites left');
+            const { revokedAt: _r, ...pub } = publicInvite(row);
+            return { code, ...pub };
+        }
+        throw new Error('could not mint a unique invite code');
+    }
+    /** Spend an invite on a new user. Single use; the inviter cannot redeem their own. */
+    async redeemInvite(code, newUserId) {
+        if (!code || !newUserId)
+            return { ok: false, reason: 'invalid' };
+        const row = await this.store.getInviteByHash(hashCode(code));
+        if (!row)
+            return { ok: false, reason: 'invalid' };
+        if (row.revokedAt !== null)
+            return { ok: false, reason: 'revoked' };
+        if (row.usedBy !== null)
+            return { ok: false, reason: 'used' };
+        if (row.inviterId === newUserId)
+            return { ok: false, reason: 'self' };
+        const at = this.now();
+        if (row.expiresAt !== null && at >= row.expiresAt)
+            return { ok: false, reason: 'expired' };
+        const won = await this.store.claimInvite(row.id, newUserId, at);
+        if (!won) {
+            const again = await this.store.getInvite(row.id);
+            return { ok: false, reason: again && again.revokedAt !== null && again.usedBy === null ? 'revoked' : 'used' };
+        }
+        return { ok: true, inviterId: row.inviterId, inviteId: row.id };
+    }
+    /** Who invited this user (first redeemed invite), or null. */
+    invitedBy(userId) {
+        return this.store.invitedBy(userId);
+    }
+    /** Users who joined on this inviter's invites, oldest first. */
+    invitees(inviterId) {
+        return this.store.invitees(inviterId);
+    }
+    /** Invites this user created, newest first, without codes (only hashes are stored). Includes revokedAt. */
+    async invites(inviterId) {
+        return (await this.store.listInvites(inviterId)).map(publicInvite);
+    }
+    /** Revoke an unused invite; it stops working and its quota slot is refunded. */
+    async revokeInvite(inviteId) {
+        await this.store.revokeInvite(inviteId, this.now());
+    }
+    /** The user's public affiliate code: stable, created on first call, unlimited use. */
+    async affiliateCode(userId) {
+        if (!userId)
+            throw new Error('userId required');
+        const existing = await this.store.getAffiliateCode(userId);
+        if (existing)
+            return existing;
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const got = await this.store.putAffiliateCode(userId, generateAffiliateCode(), this.now());
+            if (got)
+                return got;
+        }
+        throw new Error('could not mint a unique affiliate code');
+    }
+    /** First-touch attribution of a new user to the affiliate who owns `code`. Never overwrites. */
+    async attribute(code, newUserId) {
+        if (!code || !newUserId)
+            return { ok: false };
+        const norm = normalizeCode(code);
+        const affiliateId = await this.store.affiliateByCode(norm);
+        if (!affiliateId || affiliateId === newUserId)
+            return { ok: false };
+        const inserted = await this.store.attribute({ userId: newUserId, affiliateId, code: norm, at: this.now() });
+        if (inserted)
+            return { ok: true, affiliateId };
+        const prior = await this.store.getAttribution(newUserId);
+        return { ok: false, ...(prior ? { affiliateId: prior.affiliateId } : {}) };
+    }
+    /** The affiliate a user is attributed to, or null. */
+    async affiliateOf(userId) {
+        return (await this.store.getAttribution(userId))?.affiliateId ?? null;
+    }
+    /** Discount for the new customer and commission for the affiliate, via @profullstack/referrals. */
+    commission(amountCents) {
+        const r = calculateReferral(amountCents, this.split);
+        return { discountCents: r.discountCents, commissionCents: r.commissionCents };
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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,12 @@
+export { Affiliates } from './affiliates.js';
+export type { Invite, RedeemInviteResult, AffiliatesOptions } 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 { 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,6 @@
+export { Affiliates } from "./affiliates.js";
+export { memoryStore } from "./memory.js";
+export { sqliteStore } from "./sqlite.js";
+export { postgresStore } from "./postgres.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/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;
+        },
+    };
+}

package/dist/sqlite.d.ts

@@ -0,0 +1,26 @@
+import { type SqlStoreOptions } from './sql.js';
+import type { AffiliateStore } from './store.js';
+interface SqliteStatement {
+    all(...params: any[]): any;
+    get?(...params: any[]): any;
+    run?(...params: any[]): any;
+}
+/**
+ * A synchronous SQLite handle: bun:sqlite `Database` (query/prepare + exec),
+ * better-sqlite3 `Database` (prepare + exec) or node:sqlite `DatabaseSync` (prepare + exec).
+ */
+export type SqliteLike = {
+    query(sql: string): SqliteStatement;
+    exec(sql: string): unknown;
+} | {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): unknown;
+};
+/** Rewrite $1..$n to positional `?`, expanding params in order of appearance. */
+export declare function toPositional(sql: string, params: unknown[]): {
+    sql: string;
+    params: unknown[];
+};
+/** Store on a synchronous SQLite handle. Creates its tables (prefix `aff_`) on first use. */
+export declare function sqliteStore(db: SqliteLike, opts?: SqlStoreOptions): AffiliateStore;
+export {};

package/dist/sqlite.js

@@ -0,0 +1,30 @@
+import { sqlStore } from "./sql.js";
+/** Rewrite $1..$n to positional `?`, expanding params in order of appearance. */
+export function toPositional(sql, params) {
+    const out = [];
+    const text = sql.replace(/\$(\d+)/g, (_m, n) => {
+        out.push(params[Number(n) - 1]);
+        return '?';
+    });
+    return { sql: text, params: out.map((v) => (v === undefined ? null : v)) };
+}
+/** Store on a synchronous SQLite handle. Creates its tables (prefix `aff_`) on first use. */
+export function sqliteStore(db, opts = {}) {
+    const anyDb = db;
+    const prep = typeof anyDb.query === 'function' ? (sql) => anyDb.query(sql) : (sql) => anyDb.prepare(sql);
+    return sqlStore(async (sql, params) => {
+        const { sql: text, params: args } = toPositional(sql, params);
+        if (args.length === 0 && /^\s*CREATE\s/i.test(text)) {
+            anyDb.exec(text);
+            return [];
+        }
+        const st = prep(text);
+        if (st.reader === false && st.run) {
+            // better-sqlite3 refuses .all() on statements that return no rows
+            st.run(...args);
+            return [];
+        }
+        const rows = st.all(...args);
+        return Array.isArray(rows) ? rows : [];
+    }, opts);
+}

package/dist/store.d.ts

@@ -0,0 +1,56 @@
+/** One invite as persisted. The plaintext code is never stored, only its sha256. */
+export interface InviteRow {
+    id: string;
+    codeHash: string;
+    inviterId: string;
+    createdAt: number;
+    expiresAt: number | null;
+    usedBy: string | null;
+    usedAt: number | null;
+    note: string;
+    revokedAt: number | null;
+}
+export interface AttributionRow {
+    userId: string;
+    affiliateId: string;
+    code: string;
+    at: number;
+}
+/**
+ * Persistence contract. Every method is async so SQL and remote stores fit.
+ * The two methods that guard scarcity must be atomic in the store itself:
+ * `insertInvite` (quota check + insert) and `claimInvite` (single use).
+ *
+ * "Counted" invites are the ones that use up quota: every invite except one
+ * revoked before it was used.
+ */
+export interface AffiliateStore {
+    /** Custom quota for a user, or null when the default applies. */
+    getQuota(userId: string): Promise<number | null>;
+    setQuota(userId: string, total: number): Promise<void>;
+    /** Number of counted invites created by this user. */
+    countInvites(inviterId: string): Promise<number>;
+    /** Insert only if the inviter has fewer than `limit` counted invites. Returns false when over quota. */
+    insertInvite(row: InviteRow, limit: number): Promise<boolean>;
+    getInviteByHash(codeHash: string): Promise<InviteRow | null>;
+    getInvite(id: string): Promise<InviteRow | null>;
+    /** Atomic single use: sets used_by/used_at only where used_by IS NULL and not revoked. True if this call won. */
+    claimInvite(id: string, userId: string, at: number): Promise<boolean>;
+    revokeInvite(id: string, at: number): Promise<void>;
+    /** All invites created by the user, newest first. */
+    listInvites(inviterId: string): Promise<InviteRow[]>;
+    /** Inviter of the earliest invite this user redeemed. */
+    invitedBy(userId: string): Promise<string | null>;
+    /** Users who redeemed this inviter's invites, oldest first. */
+    invitees(inviterId: string): Promise<{
+        userId: string;
+        at: number;
+    }[]>;
+    getAffiliateCode(userId: string): Promise<string | null>;
+    /** Insert if the user has none yet. Returns the user's code after the call (existing one wins), or null if `code` collided with another user's. */
+    putAffiliateCode(userId: string, code: string, at: number): Promise<string | null>;
+    affiliateByCode(code: string): Promise<string | null>;
+    /** First touch: insert only if the user has no attribution. True if inserted. */
+    attribute(row: AttributionRow): Promise<boolean>;
+    getAttribution(userId: string): Promise<AttributionRow | null>;
+}

package/dist/store.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@profullstack/affiliates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Scarce invite codes (per-user quota, single use, who-invited-whom) plus open affiliate links with first-touch attribution. Commission math from @profullstack/referrals. Memory, SQLite (bun:sqlite, node:sqlite, better-sqlite3) and Postgres stores, plus a CLI.",
+  "keywords": [
+    "invite",
+    "invite-codes",
+    "invite-only",
+    "affiliate",
+    "referral",
+    "attribution",
+    "sqlite",
+    "postgres",
+    "profullstack"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/affiliates.git"
+  },
+  "homepage": "https://github.com/profullstack/affiliates#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "affiliates": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && sed -i -E \"s#(from '\\./[a-z-]+)\\.ts'#\\1.js'#\" dist/*.d.ts && chmod +x dist/cli.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --experimental-strip-types --no-warnings --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@profullstack/referrals": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}