slotlock 0.6.2 → 0.7.0

package/partner-billing.js

@@ -0,0 +1,333 @@
+// Closing a partner's month (RFC 0003 P5, P6): what its accounts used, the invoice lines its
+// contract prices that at, recorded once, the signed usage.period_closed webhook that sends the
+// partner the same numbers first, and the lines added to its next Stripe invoice.
+//
+// - Lines are recorded in slotlock.partner_invoices before anything is sent, and a month's lines
+//   are never priced again: closing a month twice (a retry days later) sends the same numbers, and
+//   only the lines Stripe has not taken yet. Stripe's own idempotency keys last about a day, so they
+//   only guard a retry within one run.
+// - The webhook carries the month's totals by account and metric, the lines, and a SHA-256 of the
+//   canonical rows, so both sides can check they hold the same numbers; `GET /v1/partner/usage`
+//   reads the same counts.
+// - Pylota is the merchant here (a partner is billed as an ordinary business customer), not
+//   Managed Payments, which sells only directly to customers.
+import { createHash } from 'node:crypto';
+import { SLOTLOCK_STRIPE_API_VERSION } from './billing.js';
+import { parseSlotlockPartnerContract } from './partners.js';
+import { createSlotlockWebhookSender, signSlotlockWebhook } from './webhooks.js';
+/**
+ * Price a month with the contract (P6): each account with at least one operation, each 10,000
+ * operations and each 100 bookings an account made above its plan's quota (each account rounded up
+ * on its own), and the minimum's shortfall. No pricing in the contract: no lines.
+ */
+export function priceSlotlockPartnerMonth(contract, accounts) {
+    const pricing = contract.pricing;
+    if (!pricing)
+        return [];
+    const lines = [];
+    const active = accounts.filter((month) => (month.totals.operations ?? 0) > 0).length;
+    if (active > 0 && pricing.activeAccount > 0) {
+        lines.push({
+            line: 'active_accounts',
+            description: `Active accounts (${active} × ${pricing.activeAccount} ${pricing.currency} minor units)`,
+            quantity: active,
+            amount: active * pricing.activeAccount,
+            currency: pricing.currency,
+        });
+    }
+    const over = (metric, per) => accounts.reduce((sum, month) => {
+        const plan = contract.plans[month.plan];
+        const quota = plan ? plan[metric] : Number.POSITIVE_INFINITY;
+        return sum + Math.ceil(Math.max(0, (month.totals[metric] ?? 0) - quota) / per);
+    }, 0);
+    const operationBlocks = over('operations', 10_000);
+    if (operationBlocks > 0 && pricing.operationsOverQuotaPer10k > 0) {
+        lines.push({
+            line: 'operations_over_quota',
+            description: `Operations above the accounts' quotas (${operationBlocks} × 10,000)`,
+            quantity: operationBlocks,
+            amount: operationBlocks * pricing.operationsOverQuotaPer10k,
+            currency: pricing.currency,
+        });
+    }
+    const bookingBlocks = over('bookings', 100);
+    if (bookingBlocks > 0 && pricing.bookingsOverQuotaPer100 > 0) {
+        lines.push({
+            line: 'bookings_over_quota',
+            description: `Bookings above the accounts' quotas (${bookingBlocks} × 100)`,
+            quantity: bookingBlocks,
+            amount: bookingBlocks * pricing.bookingsOverQuotaPer100,
+            currency: pricing.currency,
+        });
+    }
+    const subtotal = lines.reduce((sum, line) => sum + line.amount, 0);
+    if (subtotal < pricing.minimum) {
+        lines.push({
+            line: 'minimum',
+            description: 'Up to the monthly minimum',
+            quantity: 1,
+            amount: pricing.minimum - subtotal,
+            currency: pricing.currency,
+        });
+    }
+    return lines;
+}
+/** The SHA-256 (hex) of a month's canonical rows: `account\tmetric\tcount` lines, sorted, then the invoice lines. */
+export function slotlockPartnerMonthChecksum(accounts, lines) {
+    const usage = accounts
+        .flatMap((month) => Object.entries(month.totals).map(([metric, count]) => `${month.account}\t${metric}\t${count}`))
+        .sort();
+    const priced = lines.map((line) => `${line.line}\t${line.quantity}\t${line.amount}\t${line.currency}`).sort();
+    return createHash('sha256').update([...usage, '', ...priced].join('\n')).digest('hex');
+}
+/** `YYYY-MM`, a month that has ended by `now` (UTC): its first day and the next month's. */
+export function slotlockClosedMonth(month, now) {
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(month)) {
+        throw Object.assign(new Error('Slotlock month must be YYYY-MM'), { code: 'invalid_month' });
+    }
+    const [year, number] = month.split('-').map(Number);
+    const start = Date.UTC(year, number - 1, 1);
+    const next = Date.UTC(year, number, 1);
+    if (next > now) {
+        throw Object.assign(new Error(`Slotlock month ${month} has not ended`), { code: 'month_not_ended' });
+    }
+    const day = (at) => new Date(at).toISOString().slice(0, 10);
+    return { from: day(start), to: day(next - 86_400_000), next: day(next) };
+}
+/** The month before `now` (UTC), `YYYY-MM`: what a run on the 1st closes. */
+export function slotlockPreviousMonth(now) {
+    const date = new Date(now);
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() - 1, 1)).toISOString().slice(0, 7);
+}
+/** Each account's month: what its tenant used, and what an erased one of the same name had used. */
+async function readPartnerMonth(sql, partnerId, range) {
+    const rows = await sql `
+    WITH daily AS (
+      SELECT tenant_ref, day, metric, sum(count) AS count
+        FROM slotlock.usage_daily
+       WHERE day BETWEEN ${range.from}::date AND ${range.to}::date
+         AND tenant_ref IN (SELECT tenant_ref FROM slotlock.partner_accounts WHERE partner_id = ${partnerId})
+       GROUP BY tenant_ref, day, metric
+    )
+    SELECT owned.account, owned.plan, used.metric,
+           CASE WHEN used.metric = 'resources' THEN max(used.count) ELSE sum(used.count) END::text AS count
+      FROM slotlock.partner_accounts owned
+      LEFT JOIN daily used ON used.tenant_ref = owned.tenant_ref
+     WHERE owned.partner_id = ${partnerId}
+     GROUP BY owned.account, owned.plan, used.metric
+    UNION ALL
+    SELECT erased.account, erased.plan, erased.metric, erased.count::text
+      FROM slotlock.partner_erased_usage erased
+     WHERE erased.partner_id = ${partnerId} AND erased.month = ${range.from}::date`;
+    const byAccount = new Map();
+    for (const row of rows) {
+        const month = byAccount.get(row.account) ?? { account: row.account, plan: row.plan, totals: {} };
+        if (row.metric !== null) {
+            const totals = month.totals;
+            const count = Number(row.count ?? 0);
+            // An account erased and made again in the month: both counted, resources at their most.
+            totals[row.metric] = row.metric === 'resources' ? Math.max(totals[row.metric] ?? 0, count) : (totals[row.metric] ?? 0) + count;
+        }
+        byAccount.set(row.account, month);
+    }
+    return canonicalAccounts([...byAccount.values()]);
+}
+/** Accounts by name, each one's metrics by name: the order the webhook body and its checksum use. */
+function canonicalAccounts(accounts) {
+    const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return [...accounts]
+        .sort((a, b) => byName(a.account, b.account))
+        .map((month) => ({
+        account: month.account,
+        plan: month.plan,
+        totals: Object.fromEntries(Object.entries(month.totals).sort(([a], [b]) => byName(a, b))),
+    }));
+}
+/** Stripe's invoice items for the customer that this partner's month already made (a run that stopped after Stripe took them). */
+async function existingInvoiceItems(stripe, customer, partnerId, month) {
+    const send = stripe.fetch ?? fetch;
+    const found = new Map();
+    let after;
+    for (let page = 0; page < 10; page += 1) {
+        const query = new URLSearchParams({ customer, limit: '100', ...(after ? { starting_after: after } : {}) });
+        const response = await send(`${stripe.apiBase ?? 'https://api.stripe.com'}/v1/invoiceitems?${query.toString()}`, {
+            headers: { authorization: `Bearer ${stripe.secretKey}`, 'stripe-version': SLOTLOCK_STRIPE_API_VERSION },
+        }).catch(() => null);
+        if (!response?.ok)
+            throw Object.assign(new Error('Stripe did not list the invoice items'), { code: 'stripe_unavailable' });
+        const listed = (await response.json().catch(() => null));
+        for (const item of listed?.data ?? []) {
+            if (typeof item.id === 'string' &&
+                item.metadata?.slotlock_partner === partnerId &&
+                item.metadata.slotlock_month === month &&
+                typeof item.metadata.slotlock_line === 'string') {
+                found.set(item.metadata.slotlock_line, item.id);
+            }
+        }
+        const last = listed?.data?.at(-1)?.id;
+        if (!listed?.has_more || typeof last !== 'string')
+            break;
+        after = last;
+    }
+    return found;
+}
+/**
+ * Close one partner's month, as the schema owner (`slotlock partner close`). The first run freezes
+ * it: each account's totals (erased accounts' included), the invoice lines the contract prices them
+ * at and their checksum, in one transaction. Every run then sends usage.period_closed with that same
+ * body until the partner's endpoint takes it (a 2xx), and adds to the partner's next Stripe invoice
+ * each line Stripe has not taken, adopting one it took in a run that stopped before recording it.
+ * Nothing is priced or billed twice, however often or concurrently it runs.
+ */
+export async function closeSlotlockPartnerMonth(sql, input) {
+    const now = input.now ?? Date.now();
+    const range = slotlockClosedMonth(input.month, now);
+    const [partner] = await sql `SELECT contract, stripe_customer, webhook_url, webhook_secret FROM slotlock.partners WHERE id = ${input.partnerId}`;
+    if (!partner)
+        throw Object.assign(new Error('Slotlock partner not found'), { code: 'partner_not_found' });
+    // Frozen on the first run, under the partner's month lock, so racing runs freeze it once.
+    let closedNow = false;
+    const frozen = await sql.begin(async (tx) => {
+        await tx `SELECT pg_advisory_xact_lock(hashtextextended(${`slotlock:partner-month:${input.partnerId}:${input.month}`}, 0))`;
+        const [kept] = await tx `
+      SELECT accounts, checksum, webhook_delivered_at IS NOT NULL AS delivered
+        FROM slotlock.partner_month_closes WHERE partner_id = ${input.partnerId} AND month = ${range.from}::date`;
+        // jsonb keeps no key order: put it back, so every run sends the same bytes.
+        if (kept)
+            return { accounts: canonicalAccounts(kept.accounts), checksum: kept.checksum, webhookDelivered: kept.delivered };
+        const accounts = await readPartnerMonth(tx, input.partnerId, range);
+        const priced = priceSlotlockPartnerMonth(parseSlotlockPartnerContract(partner.contract), accounts);
+        for (const line of priced) {
+            await tx `
+        INSERT INTO slotlock.partner_invoices (partner_id, month, line, description, quantity, amount, currency)
+        VALUES (${input.partnerId}, ${range.from}::date, ${line.line}, ${line.description}, ${line.quantity},
+                ${line.amount}, ${line.currency})`;
+        }
+        const checksum = slotlockPartnerMonthChecksum(accounts, priced);
+        await tx `
+      INSERT INTO slotlock.partner_month_closes (partner_id, month, accounts, checksum)
+      VALUES (${input.partnerId}, ${range.from}::date, ${JSON.stringify(accounts)}::text::jsonb, ${checksum})`;
+        closedNow = true;
+        return { accounts, checksum, webhookDelivered: false };
+    });
+    const recorded = await sql `SELECT line, description, quantity::text, amount::text, currency, stripe_item
+      FROM slotlock.partner_invoices
+     WHERE partner_id = ${input.partnerId} AND month = ${range.from}::date
+     ORDER BY line`;
+    const lines = recorded.map((row) => ({
+        line: row.line,
+        description: row.description,
+        quantity: Number(row.quantity),
+        amount: Number(row.amount),
+        currency: row.currency,
+        stripeItem: row.stripe_item,
+    }));
+    // The partner hears the numbers first (P5), signed as any Slotlock webhook, the same body each time.
+    let webhook = 'no_webhook';
+    let webhookStatus;
+    if (frozen.webhookDelivered) {
+        webhook = 'already_delivered';
+    }
+    else if (partner.webhook_url && partner.webhook_secret) {
+        const id = `usage_period_closed_${input.partnerId}_${input.month.replace('-', '_')}`;
+        const timestamp = Math.floor(now / 1_000);
+        const body = JSON.stringify({
+            type: 'usage.period_closed',
+            partner: input.partnerId,
+            month: input.month,
+            from: range.from,
+            to: range.to,
+            accounts: frozen.accounts.map((month) => ({ account: month.account, plan: month.plan, totals: month.totals })),
+            lines: lines.map(({ stripeItem: _, ...line }) => line),
+            checksum: frozen.checksum,
+        });
+        try {
+            const answer = await (input.send ?? createSlotlockWebhookSender())({
+                url: partner.webhook_url,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'webhook-id': id,
+                    'webhook-timestamp': String(timestamp),
+                    'webhook-signature': signSlotlockWebhook({ secret: partner.webhook_secret, id, timestamp, body }),
+                },
+                body,
+            });
+            webhookStatus = answer.status;
+            webhook = answer.status >= 200 && answer.status < 300 ? 'delivered' : 'failed';
+        }
+        catch {
+            webhook = 'failed';
+        }
+        await sql `
+      UPDATE slotlock.partner_month_closes
+         SET webhook_status = ${webhookStatus ?? null},
+             webhook_delivered_at = CASE WHEN ${webhook === 'delivered'} THEN statement_timestamp() ELSE webhook_delivered_at END
+       WHERE partner_id = ${input.partnerId} AND month = ${range.from}::date`;
+    }
+    // Then Stripe (P6): each line it has not taken, once, on the partner's next invoice.
+    let invoiced = 0;
+    const waiting = lines.filter((line) => line.stripeItem === null && line.amount > 0);
+    if (input.stripe && partner.stripe_customer && waiting.length > 0) {
+        const send = input.stripe.fetch ?? fetch;
+        // An item a run made before it stopped is adopted, never made again (idempotency keys last a day).
+        const made = await existingInvoiceItems(input.stripe, partner.stripe_customer, input.partnerId, input.month);
+        for (const line of waiting) {
+            let item = made.get(line.line);
+            if (item === undefined) {
+                const form = new URLSearchParams({
+                    customer: partner.stripe_customer,
+                    amount: String(line.amount),
+                    currency: line.currency,
+                    description: `${input.month}: ${line.description}`,
+                    'metadata[slotlock_partner]': input.partnerId,
+                    'metadata[slotlock_month]': input.month,
+                    'metadata[slotlock_line]': line.line,
+                });
+                const response = await send(`${input.stripe.apiBase ?? 'https://api.stripe.com'}/v1/invoiceitems`, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${input.stripe.secretKey}`,
+                        'content-type': 'application/x-www-form-urlencoded',
+                        'stripe-version': SLOTLOCK_STRIPE_API_VERSION,
+                        'idempotency-key': `slotlock-partner-${input.partnerId}-${input.month}-${line.line}`,
+                    },
+                    body: form.toString(),
+                }).catch(() => null);
+                if (!response?.ok)
+                    continue;
+                item = (await response.json().catch(() => ({}))).id;
+            }
+            if (typeof item !== 'string' || !/^ii_[A-Za-z0-9]{1,250}$/.test(item))
+                continue;
+            await sql `
+        UPDATE slotlock.partner_invoices SET stripe_item = ${item}, sent_at = now()
+         WHERE partner_id = ${input.partnerId} AND month = ${range.from}::date AND line = ${line.line}
+           AND stripe_item IS NULL`;
+            line.stripeItem = item;
+            invoiced += 1;
+        }
+    }
+    return {
+        partner: input.partnerId,
+        month: input.month,
+        accounts: frozen.accounts,
+        lines,
+        checksum: frozen.checksum,
+        closedNow,
+        webhook,
+        ...(webhookStatus !== undefined ? { webhookStatus } : {}),
+        invoiced,
+        pending: lines.filter((line) => line.stripeItem === null && line.amount > 0).length,
+    };
+}
+/**
+ * The `Slotlock-Client` request field (P5), as metrics count it: the name before any `/version`,
+ * when it is one of the deployment's known integrators (SLOTLOCK_KNOWN_CLIENTS), else `other`, and
+ * `none` without the field. Never anything else from the request.
+ */
+export function slotlockClientLabel(field, known) {
+    if (field === null || field.trim() === '')
+        return 'none';
+    const name = field.trim().split('/')[0]?.toLowerCase() ?? '';
+    return known.has(name) ? name : 'other';
+}

package/partner-names.d.ts

@@ -0,0 +1,8 @@
+/** The scope a partner key carries, and the partner API needs. */
+export declare const SLOTLOCK_PARTNER_SCOPE = "partner";
+/** A partner's id: lowercase, 2-40 characters, a letter first. */
+export declare const SLOTLOCK_PARTNER_ID: RegExp;
+/** A partner's id for one of its users: its own, 1-128 letters, digits, dots, dashes or underscores. */
+export declare const SLOTLOCK_PARTNER_ACCOUNT: RegExp;
+/** A contract plan's name. */
+export declare const SLOTLOCK_PARTNER_PLAN: RegExp;

package/partner-names.js

@@ -0,0 +1,10 @@
+// The names partner accounts use (RFC 0003 part 4), with no imports, so the operation schemas
+// (application-api.ts) and the partner store (partners.ts) share them without a cycle.
+/** The scope a partner key carries, and the partner API needs. */
+export const SLOTLOCK_PARTNER_SCOPE = 'partner';
+/** A partner's id: lowercase, 2-40 characters, a letter first. */
+export const SLOTLOCK_PARTNER_ID = /^[a-z][a-z0-9-]{1,39}$/;
+/** A partner's id for one of its users: its own, 1-128 letters, digits, dots, dashes or underscores. */
+export const SLOTLOCK_PARTNER_ACCOUNT = /^[A-Za-z0-9._-]{1,128}$/;
+/** A contract plan's name. */
+export const SLOTLOCK_PARTNER_PLAN = /^[a-z][a-z0-9_]{0,40}$/;

package/partners.d.ts

@@ -0,0 +1,147 @@
+import type { Sql } from 'postgres';
+import { type SlotlockAgentPrincipal } from './agent-server.js';
+import { type SlotlockApiKey, type SlotlockApiKeyScope, type SlotlockApiKeyStore } from './api-keys.js';
+import type { SlotlockSql } from './store.js';
+import { SLOTLOCK_PARTNER_ACCOUNT, SLOTLOCK_PARTNER_ID, SLOTLOCK_PARTNER_PLAN, SLOTLOCK_PARTNER_SCOPE } from './partner-names.js';
+export { SLOTLOCK_PARTNER_ACCOUNT, SLOTLOCK_PARTNER_ID, SLOTLOCK_PARTNER_PLAN, SLOTLOCK_PARTNER_SCOPE };
+/** The tenant a partner's account is. */
+export declare function slotlockPartnerTenantRef(partnerId: string, account: string): string;
+/** What one contract plan allows an account: as a hosted plan's limits and quotas. */
+export interface SlotlockPartnerPlan {
+    resources: number;
+    apiKeys: number;
+    webhookEndpoints: number;
+    operations: number;
+    bookings: number;
+    /** Where use is refused, in percent of the quota (100-1000). */
+    stopPercent: number;
+}
+/**
+ * What a partner is billed (P6), in the currency's minor units: each account with at least one
+ * operation in the month, each 10,000 operations and each 100 bookings an account made above its
+ * plan's quota, and at least `minimum` a month.
+ */
+export interface SlotlockPartnerPricing {
+    currency: string;
+    activeAccount: number;
+    operationsOverQuotaPer10k: number;
+    bookingsOverQuotaPer100: number;
+    minimum: number;
+}
+export interface SlotlockPartnerContract {
+    plans: Readonly<Record<string, SlotlockPartnerPlan>>;
+    /** The scopes an account's key may carry; `read` and `write` unless the contract says. */
+    keyScopes: readonly SlotlockApiKeyScope[];
+    pricing?: SlotlockPartnerPricing;
+    /**
+     * Whether the partner's keys may act for its accounts with `Slotlock-Account` (`act_on_behalf`,
+     * RFC 0003 P3), instead of a key per account. Off unless the contract says.
+     */
+    actOnBehalf?: boolean;
+}
+/**
+ * Read a contract as the owner writes it (snake_case JSON, as the database keeps it), refusing one
+ * the database would not take: `invalid_partner_contract`.
+ */
+export declare function parseSlotlockPartnerContract(value: unknown): SlotlockPartnerContract;
+/** One of the partner's accounts, as the partner API shows it. */
+export interface SlotlockPartnerAccount {
+    account: string;
+    plan: string;
+    status: 'active' | 'suspended';
+    createdAt: Date;
+    updatedAt: Date;
+    /** Resources, archived ones included, and active keys: on a single account's read only. */
+    resources?: number;
+    apiKeys?: number;
+}
+/** A partner's accounts' usage by account, UTC day and metric (P5). */
+export interface SlotlockPartnerUsageRow {
+    account: string;
+    day: string;
+    metric: string;
+    count: number;
+}
+/** The partner a principal acts for: a partner key's, or nothing (never a tenant's key). */
+export declare function slotlockPrincipalPartner(principal: SlotlockAgentPrincipal): string;
+/** What the partner API reads and changes, for one partner at a time. */
+export interface SlotlockPartnerStore {
+    contract(partnerId: string): Promise<SlotlockPartnerContract | null>;
+    putAccount(partnerId: string, account: string, plan: string): Promise<{
+        account: SlotlockPartnerAccount;
+        created: boolean;
+    } | null>;
+    listAccounts(partnerId: string): Promise<SlotlockPartnerAccount[]>;
+    getAccount(partnerId: string, account: string): Promise<SlotlockPartnerAccount | null>;
+    /** The account's tenant, or null when the partner has no such account. */
+    tenantOf(partnerId: string, account: string): Promise<string | null>;
+    /** True when it changed something; null for no such account. */
+    setSuspended(partnerId: string, account: string, suspended: boolean, reason?: string): Promise<boolean | null>;
+    usage(partnerId: string, from: string, to: string, account?: string): Promise<SlotlockPartnerUsageRow[]>;
+    /** Record a partner's comparison of one day's counts (P5 reconciliation). */
+    recordReconciliation(partnerId: string, day: string, accounts: number, mismatched: number, worstPercent: number): Promise<void>;
+    /** The account's keys, made and changed as any tenant's (api-keys.ts). */
+    keys: SlotlockApiKeyStore;
+    /** Erase the account's tenant, with its partner's record of it. */
+    eraseAccount(partnerId: string, account: string): Promise<{
+        erased: boolean;
+        total: number;
+    }>;
+}
+/**
+ * The partner store over the serving role, through SLOTLOCK_PARTNER_FUNCTIONS. `keys` is the API
+ * key store; `eraseTenant` the store's erasure (a tenant's whole data, as `/v1/tenant/erase`).
+ */
+export declare function createSlotlockPartnerStore(sql: SlotlockSql, deps: {
+    keys: SlotlockApiKeyStore;
+    eraseTenant(tenantRef: string): Promise<{
+        total: number;
+    }>;
+}): SlotlockPartnerStore;
+/**
+ * Bearer authentication by partner key: a request with an active partner's unrevoked key is the
+ * principal `partner_key:<id>` with the `partner` scope and its `partnerId`, in a tenant of its own
+ * (`partner:<partner>`) that holds no data. Anything else is not a partner key (null), for the
+ * tenant authenticator to try.
+ */
+export declare function createSlotlockPartnerKeyAuthenticator(sql: SlotlockSql): (request: Request) => Promise<SlotlockAgentPrincipal | null>;
+/** The request field a partner key names one of its accounts in, to act for it (RFC 0003 P3). */
+export declare const SLOTLOCK_ACCOUNT_FIELD = "slotlock-account";
+export interface SlotlockPartner {
+    id: string;
+    name: string;
+    status: 'active' | 'suspended';
+    contract: SlotlockPartnerContract;
+    stripeCustomer: string | null;
+    webhookUrl: string | null;
+    createdAt: Date;
+}
+/** The contract as the database keeps it: snake_case, as the owner writes it. */
+export declare function slotlockPartnerContractJson(contract: SlotlockPartnerContract): Record<string, unknown>;
+/** Create a partner, or change its name and contract (as the schema owner). */
+export declare function putSlotlockPartner(sql: Sql, input: {
+    id: string;
+    name: string;
+    contract: unknown;
+}): Promise<SlotlockPartner>;
+export declare function listSlotlockPartners(sql: Sql): Promise<SlotlockPartner[]>;
+/** Suspend a partner (every account with it) or make it active again. False for no such partner. */
+export declare function setSlotlockPartnerStatus(sql: Sql, id: string, status: 'active' | 'suspended'): Promise<boolean>;
+/** Where the partner is billed (P6) and where usage.period_closed goes (P5), with its secret. */
+export declare function setSlotlockPartnerBilling(sql: Sql, id: string, input: {
+    stripeCustomer?: string | null;
+    webhookUrl?: string | null;
+    webhookSecret?: string | null;
+}): Promise<boolean>;
+/** A key for the partner, shown once: only its SHA-256 is kept. */
+export declare function createSlotlockPartnerKey(sql: Sql, partnerId: string, name: string): Promise<{
+    key: string;
+    id: string;
+    prefix: string;
+}>;
+/** Revoke one of a partner's keys at once. False for no such key. */
+export declare function revokeSlotlockPartnerKey(sql: Sql, partnerId: string, id: string): Promise<boolean>;
+/** The partner API's view of a key it made for one of its accounts. */
+export declare function slotlockPartnerKeyOutput(apiKey: SlotlockApiKey): Record<string, unknown>;
+/** The longest usage range the partner API reads, in days. */
+export declare const SLOTLOCK_PARTNER_USAGE_DAYS = 400;