@profullstack/affiliates 0.0.0-stage → 0.2.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,249 @@
-# 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`), Postgres (anything
+with a node-postgres style `query`) and Supabase (a supabase-js client, through `rpc()` only). SQL
+stores create their own tables (prefix `aff_`); the Supabase store ships its schema as a migration.
+
+```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 })));
+```
+
+## On Supabase
+
+For apps that only have a supabase-js client (service role key, no direct `DATABASE_URL`). Every
+operation is one `client.rpc()` call to a Postgres function, so the scarce parts are atomic in the
+database, not read-modify-write in JS: the quota check and insert run under a per-inviter advisory
+lock (the same logic as `postgresStore`'s `aff_insert_invite()`), redemption is
+`UPDATE ... WHERE used_by IS NULL`, and attribution is `INSERT ... ON CONFLICT DO NOTHING`.
+`@supabase/supabase-js` is not a dependency; anything with `rpc(fn, args) -> { data, error }` works.
+
+1. Add the migration (tables, RLS on with no policies, `SECURITY DEFINER` functions with a pinned
+   `search_path`, executable only by `service_role`):
+
+   ```sh
+   cp node_modules/@profullstack/affiliates/migrations/supabase.sql supabase/migrations/20261026000000_affiliates.sql
+   # other prefix: node -e "import('@profullstack/affiliates').then(m => process.stdout.write(m.supabaseMigrationSql('gc_')))" > ...
+   ```
+
+2. Use a service-role client on the server only:
+
+   ```ts
+   // lib/affiliates.ts  (server only)
+   import { createClient } from '@supabase/supabase-js';
+   import { Affiliates, supabaseStore } from '@profullstack/affiliates';
+   let aff: Affiliates | undefined;
+   export const getAffiliates = () => (aff ??= new Affiliates(supabaseStore(createClient(
+     process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!, { auth: { persistSession: false } }))));
+
+   // app/auth/callback/route.ts, after exchangeCodeForSession() gave you `user`
+   import { refFromRequest } from '@profullstack/affiliates';
+   const ref = refFromRequest(request);                                   // ?ref= or the referral_code cookie
+   if (ref) await getAffiliates().attribute(ref, user.id);                // { external: true } = not ours, see below
+   ```
+
+   Build the client lazily (as above), not at module top level: Next.js inlines `process.env.X` at
+   build time, and a secret that is only present at runtime would compile in as `undefined`.
+
+The tables are the same as `postgresStore`'s, so a script with a direct Postgres URL can use
+`postgresStore` on the same data. `supabaseStore(client, { prefix })` must match the prefix the
+migration was generated with. The anon and authenticated keys can neither read the tables nor call
+the functions.
+
+## Already using @profullstack/referrals
+
+Sites that already ship `@profullstack/referrals` keep it: its tables, its `trackReferralCode`
+middleware and its single `referral_code` cookie. Affiliates reads that cookie instead of setting
+its own, so one sign-up is never counted twice.
+
+- **Do not set a second cookie.** In the signup or auth callback, take the code with
+  `refFromRequest(request)` (it reads `?ref=` and then `REF_COOKIE`, which is `'referral_code'`, the
+  name `@profullstack/referrals/next` sets) and pass it to `aff.attribute(code, newUserId)`.
+- **Codes that are theirs come back `{ ok: false, external: true }`** and nothing is recorded; hand
+  them to the existing referrals flow (`applyReferral`, the site's own usage table). Our codes come
+  back `{ ok: true, affiliateId }`. Unknown codes come back `{ ok: false }`.
+- How "theirs" is decided: `supabaseStore` checks the `referral_codes` table from
+  `20260602000000_referrals.sql` when it exists. Other stores take
+  `new Affiliates(store, { externalCodes })`, where `externalCodes` is your @profullstack/referrals
+  `ReferralStore` (its `getCode` is used) or a function `(code) => boolean | Promise<boolean>`.
+
+```ts
+const code = refFromRequest(request);
+if (code) {
+  const r = await aff.attribute(code, user.id);
+  if (r.external) await applyReferral({ code, newUserId: user.id, amountCents, store: referralStore });
+}
+```
+
+## 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 function supabaseStore(
+  client: { rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{ data: any; error: any }> },
+  opts?: { prefix?: string },
+): AffiliateStore;
+export function supabaseMigrationSql(prefix?: string): string;   // = migrations/supabase.sql for 'aff_'
+
+export const REF_COOKIE = 'referral_code';                        // @profullstack/referrals' cookie
+export const REF_PARAM = 'ref';
+export function refFromRequest(
+  req: Request | { headers: Headers; url: string },
+  opts?: { param?: string; cookieName?: string },
+): string | null;                                                 // ?ref= first, then the cookie
+
+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
+    externalCodes?: ReferralStore | ((code: string) => boolean | Promise<boolean>);
+  });
+  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; external?: boolean }>;
+  isExternalCode(code: string): Promise<boolean>;
+  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. A code that is not
+  ours but belongs to the site's @profullstack/referrals setup returns `{ ok: false, external: true }`.
+
+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 + supabaseStore over rpc()
+# adds real PostgREST too (see .github/workflows and test/setup-postgrest.ts):
+#   AFFILIATES_TEST_POSTGREST_URL=http://127.0.0.1:3000 AFFILIATES_TEST_POSTGREST_JWT_SECRET=... npm test
+npm run gen:migration    # rewrite migrations/supabase.sql after changing supabaseMigrationSql()
+npm run build            # tsc to dist/
+```
+
+MIT, Profullstack, Inc.

package/dist/affiliates.d.ts

@@ -0,0 +1,101 @@
+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';
+};
+/** Result of `attribute`. `external: true` means the code belongs to the site's other referral system. */
+export type AttributeResult = {
+    ok: boolean;
+    affiliateId?: string;
+    external?: boolean;
+};
+/** A check for codes owned by another referral system: a function, or an @profullstack/referrals ReferralStore. */
+export type ExternalCodes = ((code: string) => boolean | Promise<boolean>) | {
+    getCode(code: string): Promise<unknown | null>;
+};
+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;
+    /**
+     * Codes that belong to an existing referral system (sites already on @profullstack/referrals).
+     * When `attribute()` gets a code that is not ours and this says it is theirs, it returns
+     * `{ ok: false, external: true }` and records nothing, so the existing flow handles it.
+     * Default: the store's `isExternalCode` when it has one (supabaseStore checks `referral_codes`).
+     */
+    externalCodes?: ExternalCodes;
+}
+/** 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;
+    private readonly externalCodes;
+    constructor(store: AffiliateStore, opts?: AffiliatesOptions);
+    /** True when `code` belongs to the site's other referral system (see `externalCodes`). */
+    isExternalCode(code: string): Promise<boolean>;
+    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.
+     * A code that is not ours but belongs to the site's existing referral system returns
+     * `{ ok: false, external: true }` and records nothing.
+     */
+    attribute(code: string, newUserId: string): Promise<AttributeResult>;
+    /** 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,180 @@
+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;
+    externalCodes;
+    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;
+        this.externalCodes = opts.externalCodes;
+    }
+    /** True when `code` belongs to the site's other referral system (see `externalCodes`). */
+    async isExternalCode(code) {
+        const raw = String(code ?? '').trim();
+        if (!raw)
+            return false;
+        const ext = this.externalCodes;
+        if (typeof ext === 'function')
+            return Boolean(await ext(raw));
+        // @profullstack/referrals looks codes up upper-cased and trimmed (validateCode)
+        if (ext)
+            return (await ext.getCode(raw.toUpperCase())) != null;
+        if (this.store.isExternalCode)
+            return this.store.isExternalCode(raw);
+        return false;
+    }
+    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.
+     * A code that is not ours but belongs to the site's existing referral system returns
+     * `{ ok: false, external: true }` and records nothing.
+     */
+    async attribute(code, newUserId) {
+        if (!code || !newUserId)
+            return { ok: false };
+        const norm = normalizeCode(code);
+        const affiliateId = norm ? await this.store.affiliateByCode(norm) : null;
+        if (!affiliateId)
+            return (await this.isExternalCode(code)) ? { ok: false, external: true } : { ok: false };
+        if (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 {};