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

package/credits/collections/plan.d.ts

@@ -0,0 +1,428 @@
+/**
+ * The org's plan (one document, `_id: "plan"`): what it's on, on what terms,
+ * since when, and anything waived. The terms are copied here, so a contract
+ * is a record like any other, and changing a plan's list doesn't change what
+ * an org agreed to. This, not a payment provider, says what an org has.
+ */
+import { type Infer } from "copilotz";
+export declare const planSchema: {
+    readonly type: "object";
+    readonly properties: {
+        /** Which of the app's plans it came from, or the contract's own name. */
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly terms: {
+            readonly type: "object";
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                };
+                /** What a seat pays each period. */
+                readonly seat: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly price: {
+                            readonly type: "number";
+                        };
+                        readonly currency: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["price", "currency"];
+                };
+                /** Credits (USD): once ever, and each period, flat and per seat. */
+                readonly credits: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly once: {
+                            readonly type: "number";
+                        };
+                        readonly monthly: {
+                            readonly type: "number";
+                        };
+                        readonly perSeat: {
+                            readonly type: "number";
+                        };
+                    };
+                };
+                /** The price list that applies (`resources.priceLists`); none: the app's. */
+                readonly prices: {
+                    readonly type: "string";
+                };
+                /** The month's limit it starts with, per seat; none: the app's. */
+                readonly budget: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly perSeat: {
+                            readonly type: "number";
+                        };
+                    };
+                };
+                /** Which orgs may be on it (`personal`, `team`); none: any. */
+                readonly for: {
+                    readonly type: "string";
+                    readonly enum: readonly ["personal", "team"];
+                };
+                /** The model tier its agents use while the org hasn't chosen one. */
+                readonly models: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["title"];
+        };
+        /** A fixed number of seats (a contract's); none: the org's people, guests apart. */
+        readonly seats: {
+            readonly type: "number";
+        };
+        /** From when its usage counts against its credits. */
+        readonly since: {
+            readonly type: "string";
+        };
+        /** Whether that clock has started: not while limits are off. */
+        readonly counting: {
+            readonly type: "boolean";
+        };
+        /** Where its periods start: the same day each month. */
+        readonly anchor: {
+            readonly type: "string";
+        };
+        /** Who collects for it (`manual`, `stripe`…), which of its accounts, and what it's called there. */
+        readonly channel: {
+            readonly type: "string";
+        };
+        readonly seller: {
+            readonly type: "string";
+        };
+        readonly customer: {
+            readonly type: "string";
+        };
+        readonly subscription: {
+            readonly type: "string";
+        };
+        /** How its payments stand, as its channel last said: `active`, `past_due`, `canceled`. */
+        readonly status: {
+            readonly type: "string";
+        };
+        /** When its channel said so: anything older is out of date. */
+        readonly statusAt: {
+            readonly type: "string";
+        };
+        /** Subscriptions that have ended: news of them, however late, doesn't bring them back. */
+        readonly ended: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        /** Its customer and subscription are from a test mode, so going live forgets them. */
+        readonly sandbox: {
+            readonly type: "boolean";
+        };
+        /** The month's limit (USD); absent: the app's default; null: none. */
+        readonly budget: {
+            readonly type: readonly ["number", "null"];
+        };
+        /** Its usage or seats, not charged. Usage is recorded all the same. */
+        readonly waived: {
+            readonly type: "object";
+            readonly properties: {
+                readonly usage: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly from: {
+                            readonly type: "string";
+                        };
+                        /** When it ends (ISO); none: until lifted. */
+                        readonly until: {
+                            readonly type: "string";
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                        };
+                        readonly by: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["from", "reason"];
+                };
+                readonly seats: {
+                    readonly type: "object";
+                    readonly properties: {
+                        /** Whose; none: every seat. */
+                        readonly people: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly from: {
+                            readonly type: "string";
+                        };
+                        /** When it ends (ISO); none: until lifted. */
+                        readonly until: {
+                            readonly type: "string";
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                        };
+                        readonly by: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["from", "reason"];
+                };
+            };
+        };
+        readonly at: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["name", "terms", "since", "anchor", "at"];
+};
+export type Plan = Infer<typeof planSchema> & {
+    _id: string;
+};
+export declare const billingPlan: {
+    schema: {
+        readonly type: "object";
+        readonly properties: {
+            /** Which of the app's plans it came from, or the contract's own name. */
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly terms: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    /** What a seat pays each period. */
+                    readonly seat: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly price: {
+                                readonly type: "number";
+                            };
+                            readonly currency: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["price", "currency"];
+                    };
+                    /** Credits (USD): once ever, and each period, flat and per seat. */
+                    readonly credits: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly once: {
+                                readonly type: "number";
+                            };
+                            readonly monthly: {
+                                readonly type: "number";
+                            };
+                            readonly perSeat: {
+                                readonly type: "number";
+                            };
+                        };
+                    };
+                    /** The price list that applies (`resources.priceLists`); none: the app's. */
+                    readonly prices: {
+                        readonly type: "string";
+                    };
+                    /** The month's limit it starts with, per seat; none: the app's. */
+                    readonly budget: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly perSeat: {
+                                readonly type: "number";
+                            };
+                        };
+                    };
+                    /** Which orgs may be on it (`personal`, `team`); none: any. */
+                    readonly for: {
+                        readonly type: "string";
+                        readonly enum: readonly ["personal", "team"];
+                    };
+                    /** The model tier its agents use while the org hasn't chosen one. */
+                    readonly models: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["title"];
+            };
+            /** A fixed number of seats (a contract's); none: the org's people, guests apart. */
+            readonly seats: {
+                readonly type: "number";
+            };
+            /** From when its usage counts against its credits. */
+            readonly since: {
+                readonly type: "string";
+            };
+            /** Whether that clock has started: not while limits are off. */
+            readonly counting: {
+                readonly type: "boolean";
+            };
+            /** Where its periods start: the same day each month. */
+            readonly anchor: {
+                readonly type: "string";
+            };
+            /** Who collects for it (`manual`, `stripe`…), which of its accounts, and what it's called there. */
+            readonly channel: {
+                readonly type: "string";
+            };
+            readonly seller: {
+                readonly type: "string";
+            };
+            readonly customer: {
+                readonly type: "string";
+            };
+            readonly subscription: {
+                readonly type: "string";
+            };
+            /** How its payments stand, as its channel last said: `active`, `past_due`, `canceled`. */
+            readonly status: {
+                readonly type: "string";
+            };
+            /** When its channel said so: anything older is out of date. */
+            readonly statusAt: {
+                readonly type: "string";
+            };
+            /** Subscriptions that have ended: news of them, however late, doesn't bring them back. */
+            readonly ended: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            /** Its customer and subscription are from a test mode, so going live forgets them. */
+            readonly sandbox: {
+                readonly type: "boolean";
+            };
+            /** The month's limit (USD); absent: the app's default; null: none. */
+            readonly budget: {
+                readonly type: readonly ["number", "null"];
+            };
+            /** Its usage or seats, not charged. Usage is recorded all the same. */
+            readonly waived: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly usage: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly from: {
+                                readonly type: "string";
+                            };
+                            /** When it ends (ISO); none: until lifted. */
+                            readonly until: {
+                                readonly type: "string";
+                            };
+                            readonly reason: {
+                                readonly type: "string";
+                            };
+                            readonly by: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["from", "reason"];
+                    };
+                    readonly seats: {
+                        readonly type: "object";
+                        readonly properties: {
+                            /** Whose; none: every seat. */
+                            readonly people: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly from: {
+                                readonly type: "string";
+                            };
+                            /** When it ends (ISO); none: until lifted. */
+                            readonly until: {
+                                readonly type: "string";
+                            };
+                            readonly reason: {
+                                readonly type: "string";
+                            };
+                            readonly by: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["from", "reason"];
+                    };
+                };
+            };
+            readonly at: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["name", "terms", "since", "anchor", "at"];
+    };
+    events?: boolean;
+    records?: boolean;
+    durable?: false;
+    indexes?: string[][];
+    private?: string[];
+    queries?: Record<string, import("copilotz").QueryDef<{
+        [x: string]: unknown;
+        budget?: number | null | undefined;
+        waived?: {
+            [x: string]: unknown;
+            seats?: {
+                [x: string]: unknown;
+                by?: string | undefined;
+                until?: string | undefined;
+                people?: string[] | undefined;
+                reason: string;
+                from: string;
+            } | undefined;
+            usage?: {
+                [x: string]: unknown;
+                by?: string | undefined;
+                until?: string | undefined;
+                reason: string;
+                from: string;
+            } | undefined;
+        } | undefined;
+        sandbox?: boolean | undefined;
+        seats?: number | undefined;
+        counting?: boolean | undefined;
+        channel?: string | undefined;
+        seller?: string | undefined;
+        customer?: string | undefined;
+        subscription?: string | undefined;
+        status?: string | undefined;
+        statusAt?: string | undefined;
+        ended?: string[] | undefined;
+        at: string;
+        anchor: string;
+        name: string;
+        terms: {
+            [x: string]: unknown;
+            for?: "personal" | "team" | undefined;
+            seat?: {
+                [x: string]: unknown;
+                price: number;
+                currency: string;
+            } | undefined;
+            credits?: {
+                [x: string]: unknown;
+                once?: number | undefined;
+                monthly?: number | undefined;
+                perSeat?: number | undefined;
+            } | undefined;
+            prices?: string | undefined;
+            budget?: {
+                [x: string]: unknown;
+                perSeat?: number | undefined;
+            } | undefined;
+            models?: string | undefined;
+            title: string;
+        };
+        since: string;
+    } & {
+        _id: string;
+    }>> | undefined;
+    vectors?: string[];
+};

package/credits/collections/plan.js

@@ -0,0 +1,97 @@
+/**
+ * The org's plan (one document, `_id: "plan"`): what it's on, on what terms,
+ * since when, and anything waived. The terms are copied here, so a contract
+ * is a record like any other, and changing a plan's list doesn't change what
+ * an org agreed to. This, not a payment provider, says what an org has.
+ */
+import { defineCollection } from "copilotz";
+const waiver = {
+    type: "object",
+    properties: {
+        from: { type: "string" },
+        /** When it ends (ISO); none: until lifted. */
+        until: { type: "string" },
+        reason: { type: "string" },
+        by: { type: "string" },
+    },
+    required: ["from", "reason"],
+};
+export const planSchema = {
+    type: "object",
+    properties: {
+        /** Which of the app's plans it came from, or the contract's own name. */
+        name: { type: "string" },
+        terms: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                /** What a seat pays each period. */
+                seat: {
+                    type: "object",
+                    properties: { price: { type: "number" }, currency: { type: "string" } },
+                    required: ["price", "currency"],
+                },
+                /** Credits (USD): once ever, and each period, flat and per seat. */
+                credits: {
+                    type: "object",
+                    properties: {
+                        once: { type: "number" },
+                        monthly: { type: "number" },
+                        perSeat: { type: "number" },
+                    },
+                },
+                /** The price list that applies (`resources.priceLists`); none: the app's. */
+                prices: { type: "string" },
+                /** The month's limit it starts with, per seat; none: the app's. */
+                budget: { type: "object", properties: { perSeat: { type: "number" } } },
+                /** Which orgs may be on it (`personal`, `team`); none: any. */
+                for: { type: "string", enum: ["personal", "team"] },
+                /** The model tier its agents use while the org hasn't chosen one. */
+                models: { type: "string" },
+            },
+            required: ["title"],
+        },
+        /** A fixed number of seats (a contract's); none: the org's people, guests apart. */
+        seats: { type: "number" },
+        /** From when its usage counts against its credits. */
+        since: { type: "string" },
+        /** Whether that clock has started: not while limits are off. */
+        counting: { type: "boolean" },
+        /** Where its periods start: the same day each month. */
+        anchor: { type: "string" },
+        /** Who collects for it (`manual`, `stripe`…), which of its accounts, and what it's called there. */
+        channel: { type: "string" },
+        seller: { type: "string" },
+        customer: { type: "string" },
+        subscription: { type: "string" },
+        /** How its payments stand, as its channel last said: `active`, `past_due`, `canceled`. */
+        status: { type: "string" },
+        /** When its channel said so: anything older is out of date. */
+        statusAt: { type: "string" },
+        /** Subscriptions that have ended: news of them, however late, doesn't bring them back. */
+        ended: { type: "array", items: { type: "string" } },
+        /** Its customer and subscription are from a test mode, so going live forgets them. */
+        sandbox: { type: "boolean" },
+        /** The month's limit (USD); absent: the app's default; null: none. */
+        budget: { type: ["number", "null"] },
+        /** Its usage or seats, not charged. Usage is recorded all the same. */
+        waived: {
+            type: "object",
+            properties: {
+                usage: waiver,
+                seats: {
+                    type: "object",
+                    properties: {
+                        ...waiver.properties,
+                        /** Whose; none: every seat. */
+                        people: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["from", "reason"],
+                },
+            },
+        },
+        at: { type: "string" },
+    },
+    required: ["name", "terms", "since", "anchor", "at"],
+};
+export const billingPlan = defineCollection({ schema: planSchema });

package/credits/collections/room.d.ts

@@ -0,0 +1,85 @@
+/**
+ * How much an org can still spend (`_id: "room"`): the answer to "may it?"
+ * without reading the ledger. Kept in the owner's memory, so every executor
+ * sees the same one and writing it commits nothing; a new owner starts
+ * without it and works it out again. Each use takes its price off it.
+ */
+import { type Infer } from "copilotz";
+export declare const roomSchema: {
+    readonly type: "object";
+    readonly properties: {
+        /** Credits left, and the month's budget left (USD); `NO_LIMIT` for none. */
+        readonly credits: {
+            readonly type: "number";
+        };
+        readonly budget: {
+            readonly type: "number";
+        };
+        /** The budget itself (USD), to say so when it's reached. */
+        readonly limit: {
+            readonly type: "number";
+        };
+        /** Below these it's running low. */
+        readonly lowCredits: {
+            readonly type: "number";
+        };
+        readonly lowBudget: {
+            readonly type: "number";
+        };
+        /** Worked out again from then on: when a date changes what it should say. */
+        readonly until: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["credits", "budget", "until"];
+};
+export type Room = Infer<typeof roomSchema> & {
+    _id: string;
+};
+export declare const billingRoom: {
+    schema: {
+        readonly type: "object";
+        readonly properties: {
+            /** Credits left, and the month's budget left (USD); `NO_LIMIT` for none. */
+            readonly credits: {
+                readonly type: "number";
+            };
+            readonly budget: {
+                readonly type: "number";
+            };
+            /** The budget itself (USD), to say so when it's reached. */
+            readonly limit: {
+                readonly type: "number";
+            };
+            /** Below these it's running low. */
+            readonly lowCredits: {
+                readonly type: "number";
+            };
+            readonly lowBudget: {
+                readonly type: "number";
+            };
+            /** Worked out again from then on: when a date changes what it should say. */
+            readonly until: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["credits", "budget", "until"];
+    };
+    events?: boolean;
+    records?: boolean;
+    durable?: false;
+    indexes?: string[][];
+    private?: string[];
+    queries?: Record<string, import("copilotz").QueryDef<{
+        [x: string]: unknown;
+        limit?: number | undefined;
+        lowCredits?: number | undefined;
+        lowBudget?: number | undefined;
+        credits: number;
+        budget: number;
+        until: string;
+    } & {
+        _id: string;
+    }>> | undefined;
+    vectors?: string[];
+};

package/credits/collections/room.js

@@ -0,0 +1,24 @@
+/**
+ * How much an org can still spend (`_id: "room"`): the answer to "may it?"
+ * without reading the ledger. Kept in the owner's memory, so every executor
+ * sees the same one and writing it commits nothing; a new owner starts
+ * without it and works it out again. Each use takes its price off it.
+ */
+import { defineCollection } from "copilotz";
+export const roomSchema = {
+    type: "object",
+    properties: {
+        /** Credits left, and the month's budget left (USD); `NO_LIMIT` for none. */
+        credits: { type: "number" },
+        budget: { type: "number" },
+        /** The budget itself (USD), to say so when it's reached. */
+        limit: { type: "number" },
+        /** Below these it's running low. */
+        lowCredits: { type: "number" },
+        lowBudget: { type: "number" },
+        /** Worked out again from then on: when a date changes what it should say. */
+        until: { type: "string" },
+    },
+    required: ["credits", "budget", "until"],
+};
+export const billingRoom = defineCollection({ durable: false, schema: roomSchema });

package/credits/contract.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The credits plugin's contract: what a way of paying may import, the shapes of
+ * what it tells `billing.apply`, and whether an org's kind fits a plan
+ * (`unfit`, `orgKind`). The rest it reaches by name: `billing.plan` (the org's
+ * plan, started if need be) and `billing.apply` (a payment, or a plan
+ * changed), and its own Actions through `resources.billing.pay`. What model
+ * tier the org's plan gives its agents, others ask through the `planTier`
+ * resource it fills (`billing.tier`).
+ */
+import type { Plan } from "./collections/plan.js";
+export type { PaymentFact, PeriodFact, PlanFact } from "./shared/apply.js";
+export type { Plan } from "./collections/plan.js";
+export type { PlanTerms } from "./shared/settings.js";
+export { orgKind, unfit } from "./shared/settings.js";
+/**
+ * How many seats are charged for: its people, or its fixed number, less those
+ * waived while that lasts. A waiver naming nobody waives every seat.
+ */
+export declare function billableSeats(plan: Pick<Plan, "seats" | "waived">, people: number, now: string): number;

package/credits/contract.js

@@ -0,0 +1,12 @@
+export { orgKind, unfit } from "./shared/settings.js";
+/**
+ * How many seats are charged for: its people, or its fixed number, less those
+ * waived while that lasts. A waiver naming nobody waives every seat.
+ */
+export function billableSeats(plan, people, now) {
+    const total = plan.seats ?? people;
+    const waived = plan.waived?.seats;
+    if (!waived || (waived.until && waived.until <= now))
+        return total;
+    return waived.people?.length ? Math.max(total - waived.people.length, 0) : 0;
+}