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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Copilotz Contributors
+
+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,49 @@
-# Temporary Holding Version
+# @copilotz/billing
 
-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.
+What an org has to spend, and paying for it, for [Copilotz](https://github.com/copilotzhq/copilotz):
+plans, credits and budgets on Copilotz's usage ledger, and Stripe as one way to pay.
+
+```sh
+npm install @copilotz/billing copilotz          # Node 24+, Bun
+deno add jsr:@copilotz/billing jsr:@copilotz/copilotz
+```
+
+It goes with Copilotz at the same version (they're released together): `@copilotz/billing@x.y.z`
+with `copilotz@x.y.z`.
+
+```ts
+import { usage } from "copilotz/plugins/billing";
+import { credits, stripe, stripeWebhook } from "@copilotz/billing";
+
+const runtime = await createRuntime({
+  store,
+  plugins: [models, chat, ...access, usage, credits, stripe, stripeWebhook, app],
+});
+```
+
+```ts
+// In the browser: the org page's Billing, and the note above where you type.
+import { creditsWeb } from "@copilotz/billing/web";
+```
+
+| Import                       | What it has                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `@copilotz/billing`          | `credits`, `stripe`, `stripeWebhook`                                                 |
+| `@copilotz/billing/web`      | `creditsWeb`                                                                         |
+| `@copilotz/billing/contract` | what a way of paying tells `billing.apply` (`PaymentFact`…), a plan's terms, `unfit` |
+
+- **`credits`**: 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. Its balance is its
+  credits less what the ledger charged since its plan began, and the check (`billing.check`, named
+  by the `spending` resource that whatever spends reads) stops it at its limit. Staff change plans,
+  give credits, waive and record payments by hand; a provider's webhook calls `billing.apply`. The
+  ledger itself, `usage`, stays Copilotz's (`copilotz/plugins/billing`): metering every use is.
+- **`stripe`**: Checkout and the customer portal are Stripe's pages, so no card reaches the app;
+  what was paid lands by a signed webhook (`stripeWebhook`, `POST /__stripe/<seller>`, in the
+  runtime of the app's one address: the directory's, with many orgs).
+
+Through 1.0.0-rc.32 these were `credits`, `stripe` and `stripeWebhook` in
+`copilotz/plugins/billing`, and `creditsWeb` in `copilotz/plugins/billing/web`. Their names
+(collections, Actions, events, Views, routes, resources) are the same, so an app's data stays as it
+is: only its imports change. See
+[design/plugins.md](https://github.com/copilotzhq/copilotz/blob/main/design/plugins.md).

package/contract.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Billing's contract (`@copilotz/billing/contract`): credits', what a payment
+ * provider tells it (`PaymentFact`, `PeriodFact`, `PlanFact`), a plan's terms
+ * and how they're read, for plugins built on it. The rest is reached by name,
+ * through the runtime (`billing.apply`, `billing.state`…).
+ */
+export * from "./credits/contract.js";

package/contract.js

@@ -0,0 +1,7 @@
+/**
+ * Billing's contract (`@copilotz/billing/contract`): credits', what a payment
+ * provider tells it (`PaymentFact`, `PeriodFact`, `PlanFact`), a plan's terms
+ * and how they're read, for plugins built on it. The rest is reached by name,
+ * through the runtime (`billing.apply`, `billing.state`…).
+ */
+export * from "./credits/contract.js";

package/credits/actions/check.d.ts

@@ -0,0 +1,5 @@
+export declare const checkAction: import("copilotz").ActionDef;
+export declare const mayAction: import("copilotz").ActionDef;
+export declare const spentAction: import("copilotz").ActionDef;
+export declare const priceListAction: import("copilotz").ActionDef;
+export declare const tierAction: import("copilotz").ActionDef;

package/credits/actions/check.js

@@ -0,0 +1,97 @@
+/**
+ * The check, for whatever's about to spend (the `spending` resource names
+ * these). All answer `{ ok }`, or `{ ok: false, why, message }`.
+ *
+ * - `billing.check` `{ purpose? }`: before a model call, a wake, a build. It
+ *   reads `room`, which costs no database read. Memory can only say yes: when
+ *   `room` is spent, or stale, what's due is written and it's worked out
+ *   again from what's kept before anyone's stopped.
+ * - `billing.may` `{}`: the same, for a read (the sizes on offer), which can't
+ *   write: without a fresh `room` it says yes, and the real thing decides.
+ * - `billing.spent` `{ price }`: the ledger, as it records a use: its price
+ *   comes off `room`, in memory, before the record goes.
+ * - `billing.priceList` `{}`: the list the org's plan names, for rating.
+ * - `billing.tier` `{}`: the model tier the org's plan gives its agents (the
+ *   `planTier` resource), or null: the plan it's on, or the one it would start
+ *   on. A plan's terms are copied when an org moves to it; terms kept from
+ *   before plans named a tier say what the app's plan of that name says now.
+ */
+import { defineAction } from "copilotz";
+import { settingsOf } from "../shared/settings.js";
+import { planOf, refresh, rooms, verdictOf } from "../shared/standing.js";
+const OK = { ok: true };
+export const checkAction = defineAction({
+    description: "Whether the org can spend now, and why not",
+    record: false,
+    input: {
+        type: "object",
+        properties: { purpose: { type: "string" } },
+        additionalProperties: false,
+    },
+    run: async (ctx, input) => {
+        const set = settingsOf(ctx);
+        if (!set.enforce || (input.purpose && set.free.includes(input.purpose)))
+            return OK;
+        const now = new Date().toISOString();
+        const room = await rooms(ctx).findOne({ _id: "room" });
+        if (room && now < room.until && verdictOf(room).ok)
+            return OK;
+        try {
+            return verdictOf(await refresh(ctx, now));
+        }
+        catch (error) {
+            // Called from a read, which can't write: what's there answers, and nothing there says yes.
+            if (error.message === "Queries are read-only")
+                return room ? verdictOf(room) : OK;
+            throw error;
+        }
+    },
+});
+export const mayAction = defineAction({
+    description: "Whether the org can spend now, as far as a read can tell",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    run: async (ctx) => {
+        if (!settingsOf(ctx).enforce)
+            return OK;
+        const room = await rooms(ctx).findOne({ _id: "room" });
+        return room && new Date().toISOString() < room.until ? verdictOf(room) : OK;
+    },
+});
+export const spentAction = defineAction({
+    description: "Takes a use's price off what the org can still spend",
+    record: false,
+    input: {
+        type: "object",
+        properties: { price: { type: "number" } },
+        required: ["price"],
+        additionalProperties: false,
+    },
+    run: async (ctx, input) => {
+        if (!settingsOf(ctx).enforce)
+            return;
+        await rooms(ctx).updateOne({ _id: "room" }, {
+            $inc: { credits: -input.price, budget: -input.price },
+        }).catch((error) => {
+            // A use recorded from a read: its record goes, and the next working-out counts it.
+            if (error.message !== "Queries are read-only")
+                throw error;
+        });
+    },
+});
+export const priceListAction = defineAction({
+    description: "The price list the org's plan names",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    run: async (ctx) => (await planOf(ctx))?.terms.prices ?? null,
+});
+export const tierAction = defineAction({
+    description: "The model tier the org's plan gives its agents",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    run: async (ctx) => {
+        const set = settingsOf(ctx);
+        const plan = await planOf(ctx);
+        return plan?.terms.models ?? set.plans[plan?.name ?? set.start]?.models ?? null;
+    },
+});

package/credits/actions/manage.d.ts

@@ -0,0 +1,9 @@
+export declare const setPlanAction: import("copilotz").ActionDef;
+export declare const grantAction: import("copilotz").ActionDef;
+export declare const waiveAction: import("copilotz").ActionDef;
+export declare const payAction: import("copilotz").ActionDef;
+export declare const budgetAction: import("copilotz").ActionDef;
+export declare const redeemAction: import("copilotz").ActionDef;
+export declare const applyAction: import("copilotz").ActionDef;
+export declare const planAction: import("copilotz").ActionDef;
+export declare const settleAction: import("copilotz").ActionDef;

package/credits/actions/manage.js

@@ -0,0 +1,266 @@
+/**
+ * Changing what an org has, each in person (never a key or an agent).
+ *
+ * Platform staff: `billing.setPlan`, `billing.grant` (gift credits, or take
+ * some away), `billing.waive` (usage or seats, for a while or until lifted),
+ * `billing.pay` (money that came in by hand). Recorded, so the log keeps who
+ * did what. The org's owners and admins: `billing.budget` (its month's limit)
+ * and `billing.redeem` (a gift code).
+ *
+ * `billing.apply`: for trusted code, what a payment provider says, called with
+ * the provider's own id for it (`{ id: "stripe:evt_…" }`), so the same news
+ * twice answers from the log.
+ */
+import { defineAction, failure, forbidden, inPerson, invalid, personOf, } from "copilotz";
+import { runsOrg } from "copilotz/plugins/access/contract";
+import { changePlan, grantPeriod, pay, } from "../shared/apply.js";
+import { settingsOf } from "../shared/settings.js";
+import { endWaiver, ensurePlan, forget, planOf, refresh } from "../shared/standing.js";
+const DAY = "^\\d{4}-\\d{2}-\\d{2}$";
+const staffOnly = (ctx) => {
+    if (ctx.actor?.staff !== true)
+        throw forbidden("Only platform staff do this.");
+};
+async function runsIt(ctx) {
+    if (ctx.actor?.staff === true)
+        return;
+    const me = await ctx.call("org.me", {});
+    if (!runsOrg(me.role))
+        throw forbidden("Only the org's owners and admins do this.");
+}
+const by = (ctx) => personOf(ctx.actor) ?? ctx.actor?.id;
+const plans = (ctx) => ctx.as().db.collection("billingPlan");
+const termsSchema = { type: "object" };
+export const setPlanAction = defineAction({
+    description: "Puts the org on a plan, or a contract of its own terms",
+    input: {
+        type: "object",
+        properties: {
+            name: { type: "string", minLength: 1 },
+            terms: termsSchema,
+            seats: { type: ["integer", "null"], minimum: 0 },
+            channel: { type: "string" },
+            note: { type: "string" },
+        },
+        required: ["name"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        staffOnly(ctx);
+        const { note: _note, ...fact } = input;
+        // By hand now, whatever collected before: what it said of its payments no longer applies.
+        await changePlan(ctx, {
+            channel: "manual",
+            status: null,
+            subscription: null,
+            ...fact,
+        });
+        return {};
+    },
+});
+export const grantAction = defineAction({
+    description: "Gives the org credits, or takes some away",
+    input: {
+        type: "object",
+        properties: {
+            amount: { type: "number" },
+            reason: { type: "string", minLength: 1 },
+            expires: { type: "string", pattern: DAY },
+        },
+        required: ["amount", "reason"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        staffOnly(ctx);
+        if (!input.amount)
+            throw invalid("Say how much.");
+        const now = new Date().toISOString();
+        await ensurePlan(ctx, now);
+        const id = await ctx.as().db.collection("credit").insertOne({
+            _id: `grant:${crypto.randomUUID()}`,
+            kind: input.amount > 0 ? "gift" : "adjustment",
+            amount: input.amount,
+            at: now,
+            reason: input.reason,
+            ...(input.expires ? { expires: input.expires } : {}),
+            ...(by(ctx) ? { by: by(ctx) } : {}),
+        });
+        await forget(ctx);
+        return { credit: id.insertedId };
+    },
+});
+export const waiveAction = defineAction({
+    description: "Waives the org's usage or seats, or lifts that",
+    input: {
+        type: "object",
+        properties: {
+            what: { type: "string", enum: ["usage", "seats"] },
+            /** To stop waiving it. */
+            lift: { type: "boolean" },
+            reason: { type: "string", minLength: 1 },
+            until: { type: "string" },
+            people: { type: "array", items: { type: "string" } },
+        },
+        required: ["what"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        staffOnly(ctx);
+        const now = new Date().toISOString();
+        const plan = await ensurePlan(ctx, now);
+        if (input.lift) {
+            if (input.what === "usage")
+                await endWaiver(ctx, plan, now);
+            else
+                await plans(ctx).updateOne({ _id: "plan" }, { $unset: { "waived.seats": "" } });
+        }
+        else {
+            if (!input.reason)
+                throw invalid("Say why it's waived.");
+            if (input.until && input.until <= now)
+                throw invalid("That's already past.");
+            // Waiving usage again keeps when it began, so all of it is given back when it ends.
+            const from = plan.waived?.[input.what]?.from ?? now;
+            await plans(ctx).updateOne({ _id: "plan" }, {
+                $set: {
+                    waived: {
+                        ...plan.waived,
+                        [input.what]: {
+                            from,
+                            reason: input.reason,
+                            ...(input.until ? { until: input.until } : {}),
+                            ...(by(ctx) ? { by: by(ctx) } : {}),
+                            ...(input.what === "seats" && input.people?.length ? { people: input.people } : {}),
+                        },
+                    },
+                },
+            });
+        }
+        await forget(ctx);
+        return {};
+    },
+});
+const paymentProperties = {
+    ref: { type: "string", minLength: 1 },
+    amount: { type: "number" },
+    currency: { type: "string", minLength: 3, maxLength: 3 },
+    rate: { type: "number", exclusiveMinimum: 0 },
+    fee: { type: "number", minimum: 0 },
+    purpose: { type: "string", enum: ["seats", "credits", "contract", "refund"] },
+    credits: { type: "number" },
+    note: { type: "string" },
+};
+export const payAction = defineAction({
+    description: "Keeps money that came in by hand, and the credits it bought",
+    input: {
+        type: "object",
+        properties: paymentProperties,
+        required: ["ref", "amount", "currency", "purpose"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        staffOnly(ctx);
+        await ensurePlan(ctx, new Date().toISOString());
+        await pay(ctx, {
+            channel: "manual",
+            ...input,
+            currency: input.currency.toLowerCase(),
+            ...(by(ctx) ? { by: by(ctx) } : {}),
+        });
+        return {};
+    },
+});
+export const budgetAction = defineAction({
+    description: "Sets the org's limit for a month, or removes it",
+    input: {
+        type: "object",
+        properties: { usd: { type: ["number", "null"], minimum: 0 } },
+        required: ["usd"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        await runsIt(ctx);
+        await ensurePlan(ctx, new Date().toISOString());
+        await plans(ctx).updateOne({ _id: "plan" }, { $set: { budget: input.usd } });
+        await forget(ctx);
+        return { budget: input.usd };
+    },
+});
+export const redeemAction = defineAction({
+    description: "Adds a gift code's credits to the org",
+    // A code is in no event.
+    record: false,
+    input: {
+        type: "object",
+        properties: { code: { type: "string", minLength: 1, maxLength: 80 } },
+        required: ["code"],
+        additionalProperties: false,
+    },
+    allow: inPerson,
+    run: async (ctx, input) => {
+        await runsIt(ctx);
+        const port = ctx.resources.directory;
+        if (!port?.claimCode)
+            throw failure("no_codes", "This app doesn't take gift codes.");
+        const person = by(ctx) ?? "";
+        const claimed = await port.claimCode(input.code, person);
+        const now = new Date().toISOString();
+        await ensurePlan(ctx, now);
+        // Claiming again for this org is the same code: the same `_id`, so it lands once.
+        await ctx.as().db.collection("credit").insertOne({
+            _id: `gift:${claimed.id}`,
+            kind: "gift",
+            amount: claimed.amount,
+            at: now,
+            ...(claimed.expires ? { expires: claimed.expires } : {}),
+            ...(claimed.note ? { note: claimed.note } : {}),
+            ...(person ? { by: person } : {}),
+        });
+        await forget(ctx);
+        return { amount: claimed.amount, ...(claimed.expires ? { expires: claimed.expires } : {}) };
+    },
+});
+export const applyAction = defineAction({
+    description: "What a payment provider says: a payment, or a plan changed",
+    input: {
+        type: "object",
+        properties: {
+            payment: { type: "object" },
+            plan: { type: "object" },
+            period: { type: "object" },
+        },
+        additionalProperties: false,
+    },
+    run: async (ctx, input) => {
+        await ensurePlan(ctx, new Date().toISOString());
+        if (input.plan)
+            await changePlan(ctx, input.plan);
+        if (input.payment)
+            await pay(ctx, input.payment);
+        if (input.period)
+            await grantPeriod(ctx, input.period);
+        return {};
+    },
+});
+export const planAction = defineAction({
+    description: "The org's plan, started if it hasn't one",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    run: (ctx) => ensurePlan(ctx, new Date().toISOString()),
+});
+export const settleAction = defineAction({
+    description: "Writes what's come due: the trial, this period's credits, a waiver that ended",
+    input: { type: "object", additionalProperties: false },
+    run: async (ctx) => {
+        // Nothing starts for an org until something needs it, nor with limits off.
+        if (!settingsOf(ctx).enforce || !await planOf(ctx))
+            return {};
+        await refresh(ctx, ctx.scheduled?.at ?? new Date().toISOString());
+        return {};
+    },
+});

package/credits/actions/state.d.ts

@@ -0,0 +1,2 @@
+export declare const stateAction: import("copilotz").ActionDef;
+export declare const noticeAction: import("copilotz").ActionDef;

package/credits/actions/state.js

@@ -0,0 +1,172 @@
+/**
+ * What people see of where the org stands.
+ *
+ * - `billing.state` `{}`: for the Billing section. Its people see whether work
+ *   can go on and why not; its owners and admins, the plan, balance, month,
+ *   credits and payments, and the plans it can move to (`pay.plans`: those for
+ *   its kind of org that its way of paying sells it now, its own kind's first;
+ *   `pay.elsewhere`, those only another kind of org can have); platform staff,
+ *   also the plans there are to set.
+ *   With limits off (`enforce`), only staff see anything, and nothing starts.
+ * - `billing.notice` `{}`: what to say above the composer, if anything: that
+ *   the org can't spend (to everyone), or is running low (to those who can act
+ *   on it).
+ *
+ * Both only read and settle what's due, so neither is recorded.
+ */
+import { defineAction, people } from "copilotz";
+import { runsOrg } from "copilotz/plugins/access/contract";
+import { billableSeats } from "../contract.js";
+import { orgKind, settingsOf, unfit, } from "../shared/settings.js";
+import { NO_LIMIT, refresh, rooms, seatsOf, standingOf, verdictOf } from "../shared/standing.js";
+/** A waiver as who runs the org sees it: what, and until when; why and who are staff's. */
+const withoutWhy = (waived) => Object.fromEntries(Object.entries(waived).map(([what, w]) => {
+    const { reason: _reason, by: _by, ...shown } = w;
+    return [what, shown];
+}));
+/** A plan as it's offered: what it is, costs and gives, and who it's for. */
+const offer = ([name, terms]) => ({
+    name,
+    title: terms.title,
+    seat: terms.seat,
+    credits: terms.credits,
+    ...(terms.for ? { for: terms.for } : {}),
+});
+/**
+ * The plans an org can move to by itself: those a seat's price is known for,
+ * that its way of paying can sell it now, for its kind of org (its own kind's
+ * first); and apart, those only another kind of org can have.
+ */
+async function offersOf(ctx, set) {
+    const kind = orgKind(ctx);
+    const sold = set.pay?.sellable
+        ? new Set(await ctx.call(set.pay.sellable, {}))
+        : undefined;
+    const priced = Object.entries(set.plans)
+        .filter(([name, terms]) => terms.seat && (!sold || sold.has(name)));
+    const fits = priced.filter(([, terms]) => !unfit(terms, kind))
+        .sort(([, a], [, b]) => Number(b.for === kind) - Number(a.for === kind));
+    const elsewhere = priced.filter(([, terms]) => unfit(terms, kind));
+    return {
+        plans: fits.map(offer),
+        ...(elsewhere.length ? { elsewhere: elsewhere.map(offer) } : {}),
+    };
+}
+async function sight(ctx) {
+    const me = await ctx.call("org.me", {})
+        .catch(() => undefined);
+    const staff = me?.staff === true || ctx.actor?.staff === true;
+    return { staff, runs: staff || runsOrg(me?.role) };
+}
+export const stateAction = defineAction({
+    description: "Where the org stands: whether it can spend; its plan and credits for who runs it",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    allow: people,
+    run: async (ctx) => {
+        const { staff, runs } = await sight(ctx);
+        const set = settingsOf(ctx);
+        const now = new Date().toISOString();
+        if (!set.enforce && !staff)
+            return { on: false, runs, staff };
+        const room = set.enforce ? await refresh(ctx, now) : undefined;
+        const verdict = room ? verdictOf(room) : { ok: true };
+        if (!runs)
+            return { on: true, runs, staff, ...verdict };
+        const s = await standingOf(ctx, now);
+        const seats = s.plan ? await seatsOf(ctx, s.plan) : undefined;
+        const payments = await ctx.as().db.collection("payment").find({}, {
+            sort: { at: -1 },
+            limit: 50,
+        });
+        const lowOn = !room
+            ? undefined
+            : room.lowCredits !== undefined && room.credits < room.lowCredits
+                ? "credits"
+                : room.lowBudget !== undefined && room.budget < room.lowBudget
+                    ? "budget"
+                    : undefined;
+        return {
+            on: set.enforce,
+            runs,
+            staff,
+            ...verdict,
+            low: !!lowOn,
+            ...(lowOn ? { lowOn } : {}),
+            plan: s.plan && {
+                name: s.plan.name,
+                terms: s.plan.terms,
+                since: s.plan.since,
+                channel: s.plan.channel,
+                ...(s.plan.status ? { status: s.plan.status } : {}),
+                ...(s.plan.customer ? { customer: s.plan.customer } : {}),
+                ...(s.plan.subscription ? { subscription: s.plan.subscription } : {}),
+                ...(typeof s.plan.seats === "number" ? { fixedSeats: s.plan.seats } : {}),
+                ...(s.plan.waived ? { waived: staff ? s.plan.waived : withoutWhy(s.plan.waived) } : {}),
+            },
+            ...(seats !== undefined ? { seats, billedSeats: billableSeats(s.plan, seats, now) } : {}),
+            ...(s.period ? { period: s.period } : {}),
+            balance: s.walked.balance,
+            buckets: s.walked.buckets,
+            debt: s.walked.debt,
+            waived: s.waivedUsage,
+            month: s.month,
+            // Why it was given, and by whom, for staff; those who run the org, what it is.
+            history: s.history.slice(0, 100).map(({ by: who, reason, ...credit }) => staff
+                ? {
+                    ...credit,
+                    ...(credit.note ?? reason ? { note: credit.note ?? reason } : {}),
+                    ...(who ? { by: who } : {}),
+                }
+                : credit),
+            // What it was and came to, for who runs the org; what a channel kept, and who, for staff.
+            payments: staff ? payments : payments.map((p) => ({
+                _id: p._id,
+                channel: p.channel,
+                ref: p.ref,
+                amount: p.amount,
+                currency: p.currency,
+                purpose: p.purpose,
+                ...(p.credits !== undefined ? { credits: p.credits } : {}),
+                ...(p.note ? { note: p.note } : {}),
+                at: p.at,
+            })),
+            pay: set.pay
+                ? {
+                    topUps: set.topUps,
+                    min: set.topUpMin,
+                    max: set.topUpMax,
+                    ...await offersOf(ctx, set),
+                    manage: !!s.plan?.customer,
+                }
+                : null,
+            ...(staff ? { plans: set.plans } : {}),
+        };
+    },
+});
+export const noticeAction = defineAction({
+    description: "What to say above the composer about what the org can spend, if anything",
+    record: false,
+    input: { type: "object", additionalProperties: false },
+    allow: people,
+    run: async (ctx) => {
+        if (!settingsOf(ctx).enforce)
+            return null;
+        const now = new Date().toISOString();
+        const kept = await rooms(ctx).findOne({ _id: "room" });
+        const room = kept && now < kept.until ? kept : await refresh(ctx, now);
+        const { runs } = await sight(ctx);
+        const verdict = verdictOf(room);
+        if (!verdict.ok)
+            return { tone: "stop", why: verdict.why, text: verdict.message, runs };
+        if (!runs)
+            return null;
+        if (room.lowCredits !== undefined && room.credits < room.lowCredits) {
+            return { tone: "low", why: "credits", left: Math.max(room.credits, 0), runs };
+        }
+        if (room.lowBudget !== undefined && room.budget < room.lowBudget && room.budget < NO_LIMIT) {
+            return { tone: "low", why: "budget", left: Math.max(room.budget, 0), runs };
+        }
+        return null;
+    },
+});