@copilotz/billing 0.0.0-stage → 1.0.0-rc.34

package/credits/mod.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Credits: what an org has to spend, and the check that stops it at its limit.
+ * Built on the usage ledger, whose prices it counts.
+ *
+ * - **The org pays.** Its plan (`billingPlan`), credits (`credit`) and payments
+ *   (`payment`) are its own rows. A plan's terms are data, so a contract is a
+ *   record, not code. Nothing asks a payment provider what an org has.
+ * - **Balance:** credits less what the ledger charged since its plan began,
+ *   walked day by day (shared/walk.ts), so usage from before never counts, and
+ *   credits lapse on their day. Own keys and subscriptions are charged nothing.
+ * - **The check** (`billing.check`, named by the `spending` resource, which
+ *   whatever spends reads): `room` is the smaller of balance and budget left,
+ *   in the owner's memory, so asking costs no database read, and each use takes
+ *   its price off. Memory can only say yes: before anyone's stopped, it's worked
+ *   out again from what's kept.
+ * - **By hand now, by provider later:** staff change plans, give credits, waive
+ *   and record payments (actions/manage.ts); a provider's webhook calls
+ *   `billing.apply` with its own event id, which lands in the same place.
+ * - **`enforce`** off: nothing starts and nobody's stopped; staff can prepare.
+ * - **Who a plan is for** (`for`: personal or team orgs): an org of the other
+ *   kind isn't offered it and can't be moved to it, by anyone. A plan can name
+ *   the model tier its agents use while the org hasn't chosen one (`models`,
+ *   read through `billing.tier`, the `planTier` resource).
+ *
+ *   plugins: [models, usage, credits, …]
+ *   resources: {
+ *     billing: {
+ *       plans: { team: { title: "Team", credits: { perSeat: 10 }, for: "team", models: "advanced" } },
+ *     },
+ *   }
+ */
+import { type Plugin } from "copilotz";
+export type { Credit } from "./collections/credit.js";
+export type { Payment } from "./collections/payment.js";
+export type { Plan } from "./collections/plan.js";
+export type { CreditsSettings, PlanTerms } from "./shared/settings.js";
+export declare const credits: Plugin;
+export default credits;

package/credits/mod.js

@@ -0,0 +1,72 @@
+/**
+ * Credits: what an org has to spend, and the check that stops it at its limit.
+ * Built on the usage ledger, whose prices it counts.
+ *
+ * - **The org pays.** Its plan (`billingPlan`), credits (`credit`) and payments
+ *   (`payment`) are its own rows. A plan's terms are data, so a contract is a
+ *   record, not code. Nothing asks a payment provider what an org has.
+ * - **Balance:** credits less what the ledger charged since its plan began,
+ *   walked day by day (shared/walk.ts), so usage from before never counts, and
+ *   credits lapse on their day. Own keys and subscriptions are charged nothing.
+ * - **The check** (`billing.check`, named by the `spending` resource, which
+ *   whatever spends reads): `room` is the smaller of balance and budget left,
+ *   in the owner's memory, so asking costs no database read, and each use takes
+ *   its price off. Memory can only say yes: before anyone's stopped, it's worked
+ *   out again from what's kept.
+ * - **By hand now, by provider later:** staff change plans, give credits, waive
+ *   and record payments (actions/manage.ts); a provider's webhook calls
+ *   `billing.apply` with its own event id, which lands in the same place.
+ * - **`enforce`** off: nothing starts and nobody's stopped; staff can prepare.
+ * - **Who a plan is for** (`for`: personal or team orgs): an org of the other
+ *   kind isn't offered it and can't be moved to it, by anyone. A plan can name
+ *   the model tier its agents use while the org hasn't chosen one (`models`,
+ *   read through `billing.tier`, the `planTier` resource).
+ *
+ *   plugins: [models, usage, credits, …]
+ *   resources: {
+ *     billing: {
+ *       plans: { team: { title: "Team", credits: { perSeat: 10 }, for: "team", models: "advanced" } },
+ *     },
+ *   }
+ */
+import { definePlugin } from "copilotz";
+import { checkAction, mayAction, priceListAction, spentAction, tierAction, } from "./actions/check.js";
+import { applyAction, budgetAction, grantAction, payAction, planAction, redeemAction, setPlanAction, settleAction, waiveAction, } from "./actions/manage.js";
+import { noticeAction, stateAction } from "./actions/state.js";
+import { credit } from "./collections/credit.js";
+import { payment } from "./collections/payment.js";
+import { billingPlan } from "./collections/plan.js";
+import { billingRoom } from "./collections/room.js";
+import { DEFAULTS } from "./shared/settings.js";
+export const credits = definePlugin({
+    name: "credits",
+    requires: ["usage"],
+    collections: { billingPlan, credit, payment, billingRoom },
+    actions: {
+        "billing.check": checkAction,
+        "billing.may": mayAction,
+        "billing.spent": spentAction,
+        "billing.priceList": priceListAction,
+        "billing.tier": tierAction,
+        "billing.state": stateAction,
+        "billing.notice": noticeAction,
+        "billing.setPlan": setPlanAction,
+        "billing.grant": grantAction,
+        "billing.waive": waiveAction,
+        "billing.pay": payAction,
+        "billing.budget": budgetAction,
+        "billing.redeem": redeemAction,
+        "billing.apply": applyAction,
+        "billing.plan": planAction,
+        "billing.settle": settleAction,
+    },
+    schedules: { "billing.settle": { cron: "20 0 * * *", call: "billing.settle", input: {} } },
+    resources: {
+        billing: DEFAULTS,
+        usage: { priceList: "billing.priceList", spent: "billing.spent" },
+        spending: { check: "billing.check", may: "billing.may" },
+        // Which model tier the org's plan gives its agents, for the tiers plugin.
+        planTier: { action: "billing.tier" },
+    },
+});
+export default credits;

package/credits/shared/apply.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What comes from outside, whoever collected it: a payment, a plan changed, a
+ * period paid for. A person acting by hand and a payment provider's webhook both
+ * land here, so the rest never knows the difference.
+ *
+ * News comes late and out of order, and an org can have had more than one
+ * subscription, so news of a subscription (`of`) changes the org only while that
+ * one is its own, what's older than what it knows changes nothing (`at`), and
+ * one that ended (`ended`) never comes back.
+ */
+import { type Context } from "copilotz";
+import type { Plan } from "../collections/plan.js";
+export type PaymentFact = {
+    channel: string;
+    ref: string;
+    seller?: string;
+    amount: number;
+    currency: string;
+    rate?: number;
+    fee?: number;
+    purpose: "seats" | "credits" | "contract" | "refund";
+    credits?: number;
+    note?: string;
+    by?: string;
+    sandbox?: boolean;
+    at?: string;
+};
+/** Keeps a payment, and the credits it bought (taken back, for a refund). Once per `channel:ref`. */
+export declare function pay(ctx: Context, fact: PaymentFact): Promise<void>;
+export type PlanFact = {
+    /** One of the app's plans, or a contract's own name with its `terms`. */
+    name?: string;
+    terms?: Plan["terms"];
+    seats?: number | null;
+    channel?: string;
+    seller?: string;
+    customer?: string;
+    /** Null: it has none now. */
+    subscription?: string | null;
+    /** Null: nothing to say of its payments, as on a contract. */
+    status?: string | null;
+    /** Where its periods start (now, when its plan changes). */
+    anchor?: string;
+    /** The subscription this is news of, and when it happened. */
+    of?: string;
+    at?: string;
+    /** A subscription that has ended. */
+    ended?: string;
+    sandbox?: boolean;
+};
+/** Changes the org's plan. What it had stays until it lapses. */
+export declare function changePlan(ctx: Context, fact: PlanFact): Promise<void>;
+/** A period someone paid for. */
+export type PeriodFact = {
+    plan: string;
+    /** `YYYY-MM-DD`: its first day, and the first day its credits no longer count. */
+    start: string;
+    expires: string;
+    seats: number;
+    sandbox?: boolean;
+};
+/**
+ * Its credits, as many as it paid for. For a plan a provider collects for, this
+ * is when they come: the money first, so a card that fails gets none.
+ */
+export declare function grantPeriod(ctx: Context, fact: PeriodFact): Promise<void>;

package/credits/shared/apply.js

@@ -0,0 +1,106 @@
+/**
+ * What comes from outside, whoever collected it: a payment, a plan changed, a
+ * period paid for. A person acting by hand and a payment provider's webhook both
+ * land here, so the rest never knows the difference.
+ *
+ * News comes late and out of order, and an org can have had more than one
+ * subscription, so news of a subscription (`of`) changes the org only while that
+ * one is its own, what's older than what it knows changes nothing (`at`), and
+ * one that ended (`ended`) never comes back.
+ */
+import { invalid } from "copilotz";
+import { orgKind, settingsOf, unfit } from "./settings.js";
+import { ensurePlan, forget, termsFor } from "./standing.js";
+const round = (usd) => Math.round(usd * 1e8) / 1e8;
+/** Keeps a payment, and the credits it bought (taken back, for a refund). Once per `channel:ref`. */
+export async function pay(ctx, fact) {
+    const at = fact.at ?? new Date().toISOString();
+    const id = `${fact.channel}:${fact.ref}`;
+    const system = ctx.as();
+    await system.db.collection("payment").insertOne({ ...fact, _id: id, at });
+    if (fact.credits) {
+        const back = fact.credits < 0;
+        await system.db.collection("credit").insertOne({
+            _id: `purchase:${id}`,
+            kind: back ? "adjustment" : "purchase",
+            ...(back ? { takes: "purchase" } : {}),
+            amount: round(fact.credits),
+            at,
+            ...(fact.note ? { note: fact.note } : {}),
+            ...(fact.by ? { by: fact.by } : {}),
+            ...(fact.sandbox ? { sandbox: true } : {}),
+        });
+    }
+    await forget(ctx);
+}
+/** Changes the org's plan. What it had stays until it lapses. */
+export async function changePlan(ctx, fact) {
+    const now = new Date().toISOString();
+    const plan = await ensurePlan(ctx, now);
+    const plans = ctx.as().db.collection("billingPlan");
+    if (fact.ended) {
+        await plans.updateOne({ _id: "plan" }, { $addToSet: { ended: fact.ended } });
+    }
+    const ended = new Set([...(plan.ended ?? []), ...(fact.ended ? [fact.ended] : [])]);
+    // News of a subscription that isn't its own now, or one that's over, leaves it as it is.
+    const elsewhere = fact.of !== undefined && fact.of !== plan.subscription;
+    const back = typeof fact.subscription === "string" && ended.has(fact.subscription);
+    if (elsewhere || back) {
+        await forget(ctx);
+        return;
+    }
+    const stale = !!fact.at && !!plan.statusAt && fact.at < plan.statusAt && !fact.ended;
+    const named = fact.name ? termsFor(ctx, fact.name) : undefined;
+    const terms = fact.terms ?? named;
+    if (fact.name && !terms)
+        throw invalid(`There's no plan "${fact.name}".`);
+    // Whoever moves it, a personal org takes no team's plan, nor a team a person's.
+    const why = terms && fact.name !== plan.name ? unfit(terms, orgKind(ctx)) : undefined;
+    if (why)
+        throw invalid(why);
+    const moved = !!fact.name && fact.name !== plan.name;
+    const unset = {
+        ...(fact.seats === null ? { seats: "" } : {}),
+        ...(fact.subscription === null ? { subscription: "" } : {}),
+        ...(fact.status === null ? { status: "", statusAt: "" } : {}),
+    };
+    await plans.updateOne({ _id: "plan" }, {
+        $set: {
+            ...(fact.name ? { name: fact.name } : {}),
+            ...(terms ? { terms } : {}),
+            ...(fact.channel ? { channel: fact.channel } : {}),
+            ...(fact.seller ? { seller: fact.seller } : {}),
+            ...(fact.customer ? { customer: fact.customer } : {}),
+            ...(fact.subscription ? { subscription: fact.subscription } : {}),
+            ...(fact.status && !stale
+                ? { status: fact.status, ...(fact.at ? { statusAt: fact.at } : {}) }
+                : {}),
+            ...(typeof fact.seats === "number" ? { seats: fact.seats } : {}),
+            ...(fact.anchor || moved ? { anchor: fact.anchor ?? now } : {}),
+            ...(fact.sandbox !== undefined ? { sandbox: fact.sandbox } : {}),
+        },
+        ...(Object.keys(unset).length ? { $unset: unset } : {}),
+    });
+    await forget(ctx);
+}
+/**
+ * Its credits, as many as it paid for. For a plan a provider collects for, this
+ * is when they come: the money first, so a card that fails gets none.
+ */
+export async function grantPeriod(ctx, fact) {
+    const terms = settingsOf(ctx).plans[fact.plan];
+    const credits = terms?.credits;
+    const amount = (credits?.monthly ?? 0) + (credits?.perSeat ?? 0) * fact.seats;
+    if (!amount)
+        return;
+    await ctx.as().db.collection("credit").insertOne({
+        _id: `plan:${fact.plan}:${fact.start}`,
+        kind: "plan",
+        amount,
+        at: new Date().toISOString(),
+        expires: fact.expires,
+        note: terms.title,
+        ...(fact.sandbox ? { sandbox: true } : {}),
+    });
+    await forget(ctx);
+}

package/credits/shared/settings.d.ts

@@ -0,0 +1,70 @@
+/** Credits' settings: the `billing` resource, which an app patches. */
+import type { Resources } from "copilotz";
+/** A plan: the terms an org on it gets. */
+export type PlanTerms = {
+    title: string;
+    seat?: {
+        price: number;
+        currency: string;
+    };
+    credits?: {
+        once?: number;
+        monthly?: number;
+        perSeat?: number;
+    };
+    prices?: string;
+    /** The month's limit it starts with, per seat; none: the app's `budget`. */
+    budget?: {
+        perSeat: number;
+    };
+    /** Which orgs may be on it: a person's own, or a team's; none: any. */
+    for?: "personal" | "team";
+    /** The model tier its orgs' agents use while the org hasn't chosen one (`billing.tier`). */
+    models?: string;
+};
+/** What kind of org this is (`personal` or `team`), where the app serves many. */
+export declare const orgKind: (ctx: {
+    resources: Resources;
+}) => string | undefined;
+/**
+ * Why an org of this kind can't be on a plan, in words, or nothing when it
+ * can: a plan for personal orgs isn't a team's, and the other way round. An
+ * org whose kind isn't known (an app that serves one) can be on any.
+ */
+export declare function unfit(terms: Pick<PlanTerms, "title" | "for">, kind?: string): string | undefined;
+export type CreditsSettings = {
+    /**
+     * Whether limits apply. Off, nothing starts: no plans, no trials, no
+     * balances, and nobody's stopped, though staff can prepare orgs.
+     */
+    enforce: boolean;
+    /** The plans there are, and the one an org starts on. */
+    plans: Record<string, PlanTerms>;
+    start: string;
+    /** The month's limit an org starts with (USD); none: no limit. */
+    budget?: number;
+    /** The share of a budget or of its credits used when it's said to be running low. */
+    warnAt: number;
+    /** What's never stopped, by a call's `purpose`: the app's own upkeep, which follows turns. */
+    free: string[];
+    /** Amounts offered for buying credits (USD), and the least and most. */
+    topUps: number[];
+    topUpMin: number;
+    topUpMax: number;
+    /**
+     * How an org pays, when something lets it (the Actions `stripe` names):
+     * checking out, managing what it pays, and which plans can be sold to it
+     * now (`sellable`: `{}` → plan names; none: every plan with a seat price).
+     */
+    pay?: {
+        checkout: string;
+        portal: string;
+        sellable?: string;
+    };
+    /** Real money: what came from a test mode stops counting. */
+    live?: boolean;
+};
+export declare const DEFAULTS: CreditsSettings;
+export declare const settingsOf: (ctx: {
+    resources: Resources;
+}) => CreditsSettings;

package/credits/shared/settings.js

@@ -0,0 +1,28 @@
+/** What kind of org this is (`personal` or `team`), where the app serves many. */
+export const orgKind = (ctx) => ctx.resources.org?.kind;
+/**
+ * Why an org of this kind can't be on a plan, in words, or nothing when it
+ * can: a plan for personal orgs isn't a team's, and the other way round. An
+ * org whose kind isn't known (an app that serves one) can be on any.
+ */
+export function unfit(terms, kind) {
+    if (!terms.for || !kind || terms.for === kind)
+        return undefined;
+    return terms.for === "team"
+        ? `${terms.title} is for team orgs, and this is a personal one. Make a team org to move to it.`
+        : `${terms.title} is for personal orgs, and this one is a team's.`;
+}
+export const DEFAULTS = {
+    enforce: true,
+    plans: { free: { title: "Free", credits: { once: 5 } } },
+    start: "free",
+    warnAt: 0.8,
+    free: ["history", "memory"],
+    topUps: [10, 25, 50, 100],
+    topUpMin: 5,
+    topUpMax: 2000,
+};
+export const settingsOf = (ctx) => ({
+    ...DEFAULTS,
+    ...ctx.resources.billing,
+});

package/credits/shared/standing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where an org stands: its plan, credits and spending worked out from what's
+ * kept, what's due written, and `room`, the short form every check reads.
+ *
+ * `settle` writes what's come due, and only it does: the trial, this period's
+ * credits, a waiver that ended. Each has an `_id` of its own, so running it
+ * twice changes nothing.
+ */
+import type { Context } from "copilotz";
+import type { Credit } from "../collections/credit.js";
+import type { Plan } from "../collections/plan.js";
+import type { Room } from "../collections/room.js";
+import { type PlanTerms } from "./settings.js";
+import { type Walked } from "./walk.js";
+/** What stands for "no limit" in `room`: taking prices off it never gets near zero. */
+export declare const NO_LIMIT = 1000000000000000;
+export declare const rooms: (ctx: Context) => import("copilotz").Collection<Room>;
+export declare const planOf: (ctx: Context) => Promise<import("copilotz").WithId<Plan> | null>;
+/**
+ * A plan's terms for this org. A trial is one a person: the personal org they
+ * get once. A team's starts without it, and doesn't gain it by falling back.
+ */
+export declare function termsFor(ctx: Context, name: string): PlanTerms | undefined;
+/**
+ * The org's plan, started on the app's first one the first time it's needed.
+ * While limits are off, its clock doesn't start (`counting`).
+ */
+export declare function ensurePlan(ctx: Context, now: string): Promise<Plan>;
+/** People who count as seats: the org's, guests apart. An app without org roles has one. */
+export declare const seatsOf: (ctx: Context, plan: Plan) => Promise<number>;
+/**
+ * A usage waiver's end: what it let through is given back, so it doesn't count
+ * afterwards. Not what was charged, but what the balance lost by it: credits that
+ * would have lapsed anyway aren't given back for good.
+ */
+export declare function endWaiver(ctx: Context, plan: Plan, at: string): Promise<void>;
+/** Writes what's come due. */
+export declare function settle(ctx: Context, now: string): Promise<Plan>;
+export type Standing = {
+    plan: Plan | null;
+    walked: Walked;
+    history: Credit[];
+    /** Spent this month, and the month's limit (none: no limit). */
+    month: {
+        start: string;
+        end: string;
+        spent: number;
+        limit?: number;
+    };
+    /** This period, on a plan with periods. */
+    period?: {
+        start: string;
+        end: string;
+    };
+    waivedUsage: boolean;
+};
+/** Where the org stands now, from what's kept. */
+export declare function standingOf(ctx: Context, now: string): Promise<Standing>;
+/** Settles, works out `room` again, and keeps it. */
+export declare function refresh(ctx: Context, now: string): Promise<Room>;
+/** Something changed what's left: the next check works it out again. */
+export declare const forget: (ctx: Context) => Promise<import("copilotz").DeleteResult>;
+export type Verdict = {
+    ok: true;
+} | {
+    ok: false;
+    why: "credits" | "budget";
+    message: string;
+};
+/** What a check answers for `room`, in the words people see when it stops them. */
+export declare function verdictOf(room: Room): Verdict;