slotlock 0.6.2 → 0.7.0

package/partners.js

@@ -0,0 +1,375 @@
+import { SlotlockAgentOperationError } from './agent-server.js';
+import { SLOTLOCK_API_KEY_SCOPES, generateSlotlockPartnerKey, isSlotlockPartnerKey, slotlockApiKeyDigest, slotlockBearerCredential, } from './api-keys.js';
+import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_USAGE_RETENTION_DAYS } from './ddl.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 function slotlockPartnerTenantRef(partnerId, account) {
+    return `partner:${partnerId}:${account}`;
+}
+function contractError(message) {
+    return Object.assign(new Error(`Slotlock partner contract: ${message}`), {
+        code: 'invalid_partner_contract',
+    });
+}
+const whole = (value, min, max) => Number.isSafeInteger(value) && value >= min && value <= max;
+/**
+ * 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 function parseSlotlockPartnerContract(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw contractError('must be an object');
+    const given = value;
+    const plansGiven = given.plans;
+    if (typeof plansGiven !== 'object' || plansGiven === null || Array.isArray(plansGiven)) {
+        throw contractError('plans must be an object of plans by name');
+    }
+    const entries = Object.entries(plansGiven);
+    if (entries.length === 0 || entries.length > 20)
+        throw contractError('needs 1-20 plans');
+    const plans = {};
+    for (const [name, plan] of entries) {
+        if (!SLOTLOCK_PARTNER_PLAN.test(name))
+            throw contractError(`plan name ${JSON.stringify(name)} is not a plan name`);
+        const fields = (plan ?? {});
+        const limits = {
+            resources: fields.resources,
+            apiKeys: fields.api_keys,
+            webhookEndpoints: fields.webhook_endpoints,
+            operations: fields.operations,
+            bookings: fields.bookings,
+            stopPercent: fields.stop_percent ?? 100,
+        };
+        if (!whole(limits.resources, 1, 100_000) ||
+            !whole(limits.apiKeys, 1, SLOTLOCK_API_KEY_ACTIVE_LIMIT) ||
+            !whole(limits.webhookEndpoints, 1, 1_000) ||
+            !whole(limits.operations, 1, 1_000_000_000_000) ||
+            !whole(limits.bookings, 1, 1_000_000_000_000) ||
+            !whole(limits.stopPercent, 100, 1_000)) {
+            throw contractError(`plan ${name} needs resources (1-100,000), api_keys (1-${SLOTLOCK_API_KEY_ACTIVE_LIMIT}), webhook_endpoints (1-1,000), operations and bookings (whole, at least 1) and stop_percent (100-1,000)`);
+        }
+        plans[name] = limits;
+    }
+    const scopesGiven = given.key_scopes ?? ['read', 'write'];
+    if (!Array.isArray(scopesGiven) ||
+        scopesGiven.length === 0 ||
+        scopesGiven.some((scope) => !SLOTLOCK_API_KEY_SCOPES.includes(scope))) {
+        throw contractError(`key_scopes must list some of ${SLOTLOCK_API_KEY_SCOPES.join(', ')}`);
+    }
+    const contract = {
+        plans,
+        keyScopes: SLOTLOCK_API_KEY_SCOPES.filter((scope) => scopesGiven.includes(scope)),
+    };
+    if (given.act_on_behalf !== undefined) {
+        if (typeof given.act_on_behalf !== 'boolean')
+            throw contractError('act_on_behalf must be true or false');
+        if (given.act_on_behalf)
+            contract.actOnBehalf = true;
+    }
+    if (given.pricing !== undefined) {
+        const pricing = (given.pricing ?? {});
+        const parsed = {
+            currency: pricing.currency,
+            activeAccount: pricing.active_account ?? 0,
+            operationsOverQuotaPer10k: pricing.operations_over_quota_per_10k ?? 0,
+            bookingsOverQuotaPer100: pricing.bookings_over_quota_per_100 ?? 0,
+            minimum: pricing.minimum ?? 0,
+        };
+        if (typeof parsed.currency !== 'string' ||
+            !/^[a-z]{3}$/.test(parsed.currency) ||
+            !whole(parsed.activeAccount, 0, 100_000_000) ||
+            !whole(parsed.operationsOverQuotaPer10k, 0, 100_000_000) ||
+            !whole(parsed.bookingsOverQuotaPer100, 0, 100_000_000) ||
+            !whole(parsed.minimum, 0, 1_000_000_000)) {
+            throw contractError('pricing needs a currency (ISO 4217, lowercase) and whole amounts in its minor units: active_account, operations_over_quota_per_10k, bookings_over_quota_per_100, minimum');
+        }
+        contract.pricing = parsed;
+    }
+    return contract;
+}
+const partnerRefusal = (code, status, message) => new SlotlockAgentOperationError(code, status, message ? { message } : undefined);
+/** The partner a principal acts for: a partner key's, or nothing (never a tenant's key). */
+export function slotlockPrincipalPartner(principal) {
+    const partner = principal.partnerId;
+    if (typeof partner !== 'string' ||
+        !SLOTLOCK_PARTNER_ID.test(partner) ||
+        !Array.isArray(principal.scopes) ||
+        !principal.scopes.includes(SLOTLOCK_PARTNER_SCOPE)) {
+        throw partnerRefusal('forbidden', 403);
+    }
+    return partner;
+}
+const toAccount = (row) => ({
+    account: row.account,
+    plan: row.plan,
+    status: row.suspended ? 'suspended' : 'active',
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...(row.resources !== undefined ? { resources: Number(row.resources) } : {}),
+    ...(row.api_keys !== undefined ? { apiKeys: Number(row.api_keys) } : {}),
+});
+/**
+ * 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 function createSlotlockPartnerStore(sql, deps) {
+    const tenantOf = async (partnerId, account) => {
+        if (!SLOTLOCK_PARTNER_ID.test(partnerId) || !SLOTLOCK_PARTNER_ACCOUNT.test(account))
+            return null;
+        const [row] = await sql `
+      SELECT tenant_ref FROM slotlock.get_partner_account(${partnerId}::text, ${account}::text)`;
+        return row?.tenant_ref ?? null;
+    };
+    return {
+        async contract(partnerId) {
+            if (!SLOTLOCK_PARTNER_ID.test(partnerId))
+                return null;
+            const [row] = await sql `
+        SELECT slotlock.partner_contract(${partnerId}::text) AS contract`;
+            return row?.contract ? parseSlotlockPartnerContract(row.contract) : null;
+        },
+        async putAccount(partnerId, account, plan) {
+            try {
+                const [row] = await sql `
+          SELECT put.account, put.plan, false AS suspended, put.created_at, put.updated_at, put.created
+            FROM slotlock.put_partner_account(${partnerId}::text, ${account}::text, ${plan}::text) put`;
+                if (!row)
+                    return null;
+                const found = await this.getAccount(partnerId, account);
+                return { account: found ?? toAccount(row), created: row.created };
+            }
+            catch (error) {
+                const hint = error.hint;
+                if (hint === 'invalid_partner_plan' || hint === 'invalid_partner_account') {
+                    throw partnerRefusal(hint, 400);
+                }
+                throw error;
+            }
+        },
+        async listAccounts(partnerId) {
+            const rows = await sql `
+        SELECT account, plan, suspended, created_at, updated_at
+          FROM slotlock.list_partner_accounts(${partnerId}::text)`;
+            return rows.map(toAccount);
+        },
+        async getAccount(partnerId, account) {
+            if (!SLOTLOCK_PARTNER_ACCOUNT.test(account))
+                return null;
+            const [row] = await sql `
+        SELECT account, plan, suspended, created_at, updated_at, resources::text, api_keys::text
+          FROM slotlock.get_partner_account(${partnerId}::text, ${account}::text)`;
+            return row ? toAccount(row) : null;
+        },
+        tenantOf,
+        async setSuspended(partnerId, account, suspended, reason) {
+            if (!SLOTLOCK_PARTNER_ACCOUNT.test(account))
+                return null;
+            const [row] = await sql `
+        SELECT slotlock.set_partner_account_suspended(
+          ${partnerId}::text, ${account}::text, ${suspended}::boolean, ${reason ?? null}::text) AS changed`;
+            return row?.changed ?? null;
+        },
+        async usage(partnerId, from, to, account) {
+            const rows = await sql `
+        SELECT account, day::text, metric, count::text
+          FROM slotlock.partner_usage(${partnerId}::text, ${from}::date, ${to}::date, ${account ?? null}::text)`;
+            return rows.map((row) => ({ account: row.account, day: row.day, metric: row.metric, count: Number(row.count) }));
+        },
+        async recordReconciliation(partnerId, day, accounts, mismatched, worstPercent) {
+            await sql `SELECT slotlock.record_partner_reconciliation(${partnerId}::text, ${day}::date,
+        ${accounts}::integer, ${mismatched}::integer, ${worstPercent}::numeric)`;
+        },
+        keys: deps.keys,
+        async eraseAccount(partnerId, account) {
+            const tenantRef = await tenantOf(partnerId, account);
+            if (!tenantRef)
+                return { erased: false, total: 0 };
+            const erased = await deps.eraseTenant(tenantRef);
+            return { erased: true, total: erased.total };
+        },
+    };
+}
+/**
+ * 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 function createSlotlockPartnerKeyAuthenticator(sql) {
+    const contracts = new Map();
+    return async (request) => {
+        const presented = slotlockBearerCredential(request);
+        if (presented === undefined || !isSlotlockPartnerKey(presented))
+            return null;
+        const account = request.headers.get(SLOTLOCK_ACCOUNT_FIELD);
+        // A malformed account is refused before the key is looked up, as a malformed key is.
+        if (account !== null && !SLOTLOCK_PARTNER_ACCOUNT.test(account))
+            return null;
+        // One statement: the key, and with Slotlock-Account its partner's contract and the account's tenant.
+        const [row] = await sql `
+      SELECT authenticated.key_id::text, authenticated.partner_id,
+             CASE WHEN ${account}::text IS NULL THEN NULL
+                  ELSE slotlock.partner_contract(authenticated.partner_id)::text END AS contract,
+             CASE WHEN ${account}::text IS NULL THEN NULL
+                  ELSE slotlock.partner_account_tenant(authenticated.partner_id, ${account}::text) END AS tenant_ref
+        FROM slotlock.authenticate_partner_key(${slotlockApiKeyDigest(presented)}::bytea) authenticated`;
+        if (!row)
+            return null;
+        if (account === null) {
+            return {
+                subject: `partner_key:${row.key_id}`,
+                tenantRef: `partner:${row.partner_id}`,
+                scopes: [SLOTLOCK_PARTNER_SCOPE],
+                partnerId: row.partner_id,
+            };
+        }
+        // Acting for one of its accounts (RFC 0003 P3): only where the contract allows it, only for an
+        // account the partner has, and with no more than the contract lets its accounts' keys carry.
+        if (!row.contract || !row.tenant_ref)
+            return null;
+        const contract = parsedContract(row.contract);
+        if (!contract?.actOnBehalf)
+            return null;
+        return {
+            subject: `partner_key:${row.key_id}`,
+            tenantRef: row.tenant_ref,
+            scopes: [...contract.keyScopes],
+            onBehalfOf: row.partner_id,
+        };
+    };
+    /** Contracts read, by their JSON text: parsed once while unchanged (at most 1,000 kept). */
+    function parsedContract(text) {
+        const kept = contracts.get(text);
+        if (kept !== undefined)
+            return kept;
+        let contract;
+        try {
+            contract = parseSlotlockPartnerContract(JSON.parse(text));
+        }
+        catch {
+            contract = null;
+        }
+        if (contracts.size >= 1_000)
+            contracts.delete(contracts.keys().next().value);
+        contracts.set(text, contract);
+        return contract;
+    }
+}
+/** The request field a partner key names one of its accounts in, to act for it (RFC 0003 P3). */
+export const SLOTLOCK_ACCOUNT_FIELD = 'slotlock-account';
+const toPartner = (row) => ({
+    id: row.id,
+    name: row.name,
+    status: row.status,
+    contract: parseSlotlockPartnerContract(row.contract),
+    stripeCustomer: row.stripe_customer,
+    webhookUrl: row.webhook_url,
+    createdAt: row.created_at,
+});
+/** The contract as the database keeps it: snake_case, as the owner writes it. */
+export function slotlockPartnerContractJson(contract) {
+    return {
+        plans: Object.fromEntries(Object.entries(contract.plans).map(([name, plan]) => [
+            name,
+            {
+                resources: plan.resources,
+                api_keys: plan.apiKeys,
+                webhook_endpoints: plan.webhookEndpoints,
+                operations: plan.operations,
+                bookings: plan.bookings,
+                stop_percent: plan.stopPercent,
+            },
+        ])),
+        key_scopes: [...contract.keyScopes],
+        ...(contract.actOnBehalf ? { act_on_behalf: true } : {}),
+        ...(contract.pricing
+            ? {
+                pricing: {
+                    currency: contract.pricing.currency,
+                    active_account: contract.pricing.activeAccount,
+                    operations_over_quota_per_10k: contract.pricing.operationsOverQuotaPer10k,
+                    bookings_over_quota_per_100: contract.pricing.bookingsOverQuotaPer100,
+                    minimum: contract.pricing.minimum,
+                },
+            }
+            : {}),
+    };
+}
+/** Create a partner, or change its name and contract (as the schema owner). */
+export async function putSlotlockPartner(sql, input) {
+    if (!SLOTLOCK_PARTNER_ID.test(input.id)) {
+        throw Object.assign(new Error('Slotlock partner id must be 2-40 lowercase letters, digits or dashes, a letter first'), {
+            code: 'invalid_partner',
+        });
+    }
+    const contract = slotlockPartnerContractJson(parseSlotlockPartnerContract(input.contract));
+    const [row] = await sql `
+    INSERT INTO slotlock.partners (id, name, contract)
+    VALUES (${input.id}, ${input.name}, ${JSON.stringify(contract)}::text::jsonb)
+    ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, contract = EXCLUDED.contract
+    RETURNING id, name, status, contract, stripe_customer, webhook_url, created_at`;
+    return toPartner(row);
+}
+export async function listSlotlockPartners(sql) {
+    const rows = await sql `
+    SELECT id, name, status, contract, stripe_customer, webhook_url, created_at
+      FROM slotlock.partners ORDER BY id`;
+    return rows.map(toPartner);
+}
+/** Suspend a partner (every account with it) or make it active again. False for no such partner. */
+export async function setSlotlockPartnerStatus(sql, id, status) {
+    const rows = await sql `UPDATE slotlock.partners SET status = ${status} WHERE id = ${id} RETURNING id`;
+    return rows.length > 0;
+}
+/** Where the partner is billed (P6) and where usage.period_closed goes (P5), with its secret. */
+export async function setSlotlockPartnerBilling(sql, id, input) {
+    const rows = await sql `
+    UPDATE slotlock.partners
+       SET stripe_customer = CASE WHEN ${input.stripeCustomer !== undefined} THEN ${input.stripeCustomer ?? null} ELSE stripe_customer END,
+           webhook_url = CASE WHEN ${input.webhookUrl !== undefined} THEN ${input.webhookUrl ?? null} ELSE webhook_url END,
+           webhook_secret = CASE WHEN ${input.webhookSecret !== undefined} THEN ${input.webhookSecret ?? null} ELSE webhook_secret END
+     WHERE id = ${id} RETURNING id`;
+    return rows.length > 0;
+}
+/** A key for the partner, shown once: only its SHA-256 is kept. */
+export async function createSlotlockPartnerKey(sql, partnerId, name) {
+    const { key, prefix, digest } = generateSlotlockPartnerKey();
+    const [row] = await sql `
+    INSERT INTO slotlock.partner_keys (partner_id, name, prefix, secret_hash)
+    VALUES (${partnerId}, ${name}, ${prefix}, ${digest})
+    RETURNING id::text`;
+    return { key, id: row.id, prefix };
+}
+/** Revoke one of a partner's keys at once. False for no such key. */
+export async function revokeSlotlockPartnerKey(sql, partnerId, id) {
+    const rows = await sql `
+    UPDATE slotlock.partner_keys SET revoked_at = COALESCE(revoked_at, now())
+     WHERE partner_id = ${partnerId} AND id = ${id}::uuid RETURNING id`;
+    return rows.length > 0;
+}
+/** The partner API's view of a key it made for one of its accounts. */
+export function slotlockPartnerKeyOutput(apiKey) {
+    return {
+        id: apiKey.id,
+        name: apiKey.name,
+        prefix: apiKey.prefix,
+        scopes: apiKey.scopes,
+        created_at: apiKey.createdAt.toISOString(),
+        expires_at: apiKey.expiresAt?.toISOString() ?? null,
+        last_used_at: apiKey.lastUsedAt?.toISOString() ?? null,
+        revoked_at: apiKey.revokedAt?.toISOString() ?? null,
+        limits: apiKey.limits
+            ? {
+                ...(apiKey.limits.maxHolds !== undefined ? { max_holds: apiKey.limits.maxHolds } : {}),
+                ...(apiKey.limits.maxHeldHours !== undefined ? { max_held_hours: apiKey.limits.maxHeldHours } : {}),
+                ...(apiKey.limits.requestsPerMinute !== undefined
+                    ? { requests_per_minute: apiKey.limits.requestsPerMinute }
+                    : {}),
+                ...(apiKey.limits.requiresApproval ? { requires_approval: true } : {}),
+            }
+            : null,
+    };
+}
+/** The longest usage range the partner API reads, in days. */
+export const SLOTLOCK_PARTNER_USAGE_DAYS = SLOTLOCK_USAGE_RETENTION_DAYS;

package/plans.d.ts

@@ -0,0 +1,92 @@
+import type { SlotlockSql } from './store.js';
+/**
+ * The plans hosted Slotlock sells. Custom runs on the customer's own servers and needs no row. Team
+ * is an organization's (Teams on Cloud): five times Developer's resources, more webhook endpoints,
+ * and four times its monthly quotas, shared by its members.
+ */
+export type SlotlockPlan = 'free' | 'developer' | 'team';
+/** Where the tenant's billing stands. A `canceled` or long-unpaid tenant is on the Free limits. */
+export type SlotlockPlanStatus = 'active' | 'past_due' | 'canceled';
+/** What a plan allows a tenant to hold at once. */
+export interface SlotlockPlanLimits {
+    /** Resources, archived ones included (the store's own count). */
+    resources: number;
+    /** Active API keys. */
+    apiKeys: number;
+    /** Webhook endpoints. */
+    webhookEndpoints: number;
+}
+export declare const SLOTLOCK_PLAN_LIMITS: Readonly<Record<SlotlockPlan, Readonly<SlotlockPlanLimits>>>;
+/**
+ * What a plan allows a tenant to use each UTC calendar month (quotas.ts, with SLOTLOCK_QUOTAS=on).
+ * They are the plan's, not stored per tenant: the Terms give 30 days' notice of a change, and the
+ * release that makes it applies it to every tenant on the plan.
+ */
+export interface SlotlockPlanQuotas {
+    /** Operations its API keys and the assistant run (MCP, A2A and REST, the application API too). */
+    operations: number;
+    /** Bookings made: reservations, events (a whole series is one) and holds confirmed. */
+    bookings: number;
+    /** Where use is refused, in percent of the quota: 100 stops at it, 110 allows a tenth more. */
+    stopPercent: number;
+}
+export declare const SLOTLOCK_PLAN_QUOTAS: Readonly<Record<SlotlockPlan, Readonly<SlotlockPlanQuotas>>>;
+/** A tenant's plan as the database holds it. */
+export interface SlotlockTenantPlan {
+    plan: SlotlockPlan;
+    status: SlotlockPlanStatus;
+    limits: SlotlockPlanLimits;
+    stripeCustomer: string | null;
+    stripeSubscription: string | null;
+    currentPeriodEnd: Date | null;
+}
+/**
+ * The monthly quotas the tenant is held to (quotas.ts): its own (a partner's account, on its
+ * contract plan's numbers, RFC 0003 P4), else its plan's, else null (no plan, or one with none).
+ */
+export declare function readSlotlockTenantQuotas(sql: SlotlockSql, tenantRef: string, 
+/**
+ * Metered overage (SLOTLOCK_OVERAGE=on, overage.ts): a paying Developer tenant is refused only past
+ * this percent of its quota, and what it uses above the quota is billed.
+ */
+options?: {
+    overageStopPercent?: number;
+}): Promise<SlotlockPlanQuotas | null>;
+/** The tenant's plan, or null when it has none (no plan limits apply). */
+export declare function readSlotlockTenantPlan(sql: SlotlockSql, tenantRef: string): Promise<SlotlockTenantPlan | null>;
+/** Sets the tenant's plan, with the limits that plan allows. */
+export declare function setSlotlockTenantPlan(sql: SlotlockSql, input: {
+    tenantRef: string;
+    plan: SlotlockPlan;
+    status: SlotlockPlanStatus;
+    stripeCustomer?: string | null;
+    stripeSubscription?: string | null;
+    currentPeriodEnd?: Date | null;
+}): Promise<void>;
+/** The plan every tenant without one of its own is on, from `appliesFrom`. */
+export interface SlotlockPlanDefault {
+    plan: SlotlockPlan;
+    limits: SlotlockPlanLimits;
+    appliesFrom: Date;
+}
+/** The deployment's default plan, or null when it has none. */
+export declare function readSlotlockPlanDefault(sql: SlotlockSql): Promise<SlotlockPlanDefault | null>;
+/**
+ * Sets the default plan, with the limits that plan allows, or removes it (null). Only the deployment
+ * role may: another is refused EXECUTE (`plan_default_not_permitted`).
+ */
+export declare function setSlotlockPlanDefault(sql: SlotlockSql, input: {
+    plan: SlotlockPlan;
+    appliesFrom: Date;
+} | null): Promise<void>;
+/**
+ * Puts a new tenant on the default plan at once, while the default does not yet apply to every
+ * tenant: one with no API key, nothing in its feed and no webhook. True when it did. The dashboard
+ * calls it before a tenant adds a key, resource or webhook endpoint.
+ */
+export declare function enrolSlotlockTenantPlan(sql: SlotlockSql, tenantRef: string): Promise<boolean>;
+/**
+ * Reading a tenant's plan needs EXECUTE on slotlock.tenant_plan(text), which `slotlock migrate` (or
+ * grantApplicationRole) grants: a role without it is told so (`application_role_not_granted`).
+ */
+export declare function slotlockPlanReadRefusal(error: unknown, signature?: string): unknown;

package/plans.js

@@ -0,0 +1,115 @@
+export const SLOTLOCK_PLAN_LIMITS = Object.freeze({
+    free: Object.freeze({ resources: 10, apiKeys: 10, webhookEndpoints: 2 }),
+    developer: Object.freeze({ resources: 100, apiKeys: 100, webhookEndpoints: 10 }),
+    team: Object.freeze({ resources: 500, apiKeys: 100, webhookEndpoints: 25 }),
+});
+export const SLOTLOCK_PLAN_QUOTAS = Object.freeze({
+    free: Object.freeze({ operations: 25_000, bookings: 1_000, stopPercent: 100 }),
+    developer: Object.freeze({ operations: 500_000, bookings: 25_000, stopPercent: 110 }),
+    team: Object.freeze({ operations: 2_000_000, bookings: 100_000, stopPercent: 110 }),
+});
+/**
+ * The monthly quotas the tenant is held to (quotas.ts): its own (a partner's account, on its
+ * contract plan's numbers, RFC 0003 P4), else its plan's, else null (no plan, or one with none).
+ */
+export async function readSlotlockTenantQuotas(sql, tenantRef, 
+/**
+ * Metered overage (SLOTLOCK_OVERAGE=on, overage.ts): a paying Developer tenant is refused only past
+ * this percent of its quota, and what it uses above the quota is billed.
+ */
+options = {}) {
+    const [row] = await sql `SELECT quotas.plan, quotas.operations::text, quotas.bookings::text, quotas.stop_percent,
+           (SELECT given.stripe_subscription IS NOT NULL AND given.status <> 'canceled'
+              FROM slotlock.tenant_plan(${tenantRef}::text) given) AS paid
+      FROM slotlock.tenant_plan_quotas(${tenantRef}::text) quotas`;
+    if (!row)
+        return null;
+    if (row.operations !== null && row.bookings !== null && row.stop_percent !== null) {
+        return { operations: Number(row.operations), bookings: Number(row.bookings), stopPercent: row.stop_percent };
+    }
+    if (!Object.hasOwn(SLOTLOCK_PLAN_QUOTAS, row.plan))
+        return null;
+    const quotas = SLOTLOCK_PLAN_QUOTAS[row.plan];
+    if (options.overageStopPercent !== undefined && row.plan === 'developer' && row.paid === true) {
+        return { ...quotas, stopPercent: Math.max(quotas.stopPercent, options.overageStopPercent) };
+    }
+    return quotas;
+}
+/** The tenant's plan, or null when it has none (no plan limits apply). */
+export async function readSlotlockTenantPlan(sql, tenantRef) {
+    const [row] = await sql `SELECT * FROM slotlock.tenant_plan(${tenantRef}::text)`;
+    if (!row)
+        return null;
+    return {
+        plan: row.plan,
+        status: row.status,
+        limits: {
+            resources: row.max_resources,
+            apiKeys: row.max_api_keys,
+            webhookEndpoints: row.max_webhook_endpoints,
+        },
+        stripeCustomer: row.stripe_customer,
+        stripeSubscription: row.stripe_subscription,
+        currentPeriodEnd: row.current_period_end,
+    };
+}
+/** Sets the tenant's plan, with the limits that plan allows. */
+export async function setSlotlockTenantPlan(sql, input) {
+    const limits = SLOTLOCK_PLAN_LIMITS[input.plan];
+    await sql `SELECT slotlock.set_tenant_plan(
+    ${input.tenantRef}::text, ${input.plan}::text, ${input.status}::text,
+    ${limits.resources}::integer, ${limits.apiKeys}::integer, ${limits.webhookEndpoints}::integer,
+    ${input.stripeCustomer ?? null}::text, ${input.stripeSubscription ?? null}::text,
+    ${input.currentPeriodEnd ?? null}::timestamptz)`;
+}
+/** The deployment's default plan, or null when it has none. */
+export async function readSlotlockPlanDefault(sql) {
+    const [row] = await sql `SELECT * FROM slotlock.plan_default()`;
+    if (!row)
+        return null;
+    return {
+        plan: row.plan,
+        limits: {
+            resources: row.max_resources,
+            apiKeys: row.max_api_keys,
+            webhookEndpoints: row.max_webhook_endpoints,
+        },
+        appliesFrom: row.applies_from,
+    };
+}
+/**
+ * Sets the default plan, with the limits that plan allows, or removes it (null). Only the deployment
+ * role may: another is refused EXECUTE (`plan_default_not_permitted`).
+ */
+export async function setSlotlockPlanDefault(sql, input) {
+    const limits = input ? SLOTLOCK_PLAN_LIMITS[input.plan] : null;
+    await sql `SELECT slotlock.set_plan_default(
+    ${input?.plan ?? null}::text, ${limits?.resources ?? null}::integer,
+    ${limits?.apiKeys ?? null}::integer, ${limits?.webhookEndpoints ?? null}::integer,
+    ${input?.appliesFrom ?? null}::timestamptz)`.catch((error) => {
+        if (error?.code !== '42501')
+            throw error;
+        throw Object.assign(new Error('Slotlock sets the default plan only as the deployment role', { cause: error }), { code: 'plan_default_not_permitted' });
+    });
+}
+/**
+ * Puts a new tenant on the default plan at once, while the default does not yet apply to every
+ * tenant: one with no API key, nothing in its feed and no webhook. True when it did. The dashboard
+ * calls it before a tenant adds a key, resource or webhook endpoint.
+ */
+export async function enrolSlotlockTenantPlan(sql, tenantRef) {
+    const [row] = await sql `
+    SELECT slotlock.enrol_tenant_plan(${tenantRef}::text) AS enrolled`.catch((error) => {
+        throw slotlockPlanReadRefusal(error, 'slotlock.enrol_tenant_plan(text)');
+    });
+    return row?.enrolled === true;
+}
+/**
+ * Reading a tenant's plan needs EXECUTE on slotlock.tenant_plan(text), which `slotlock migrate` (or
+ * grantApplicationRole) grants: a role without it is told so (`application_role_not_granted`).
+ */
+export function slotlockPlanReadRefusal(error, signature = 'slotlock.tenant_plan(text)') {
+    if (error?.code !== '42501')
+        return error;
+    return Object.assign(new Error(`Slotlock serving role may not run ${signature}: grant it what this release needs with grantApplicationRole (\`slotlock migrate\` does), once per release`, { cause: error }), { code: 'application_role_not_granted' });
+}