@mccaskie-labs/workbench-plans 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +5 -0
- package/README.md +104 -2
- package/dist/cli.d.ts +12 -0
- package/dist/cli.js +141 -0
- package/dist/config.d.ts +29 -0
- package/dist/config.js +174 -0
- package/dist/errors.d.ts +19 -0
- package/dist/errors.js +11 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +10 -0
- package/dist/migration.d.ts +4 -0
- package/dist/migration.js +474 -0
- package/dist/period.d.ts +4 -0
- package/dist/period.js +39 -0
- package/dist/plans.d.ts +58 -0
- package/dist/plans.js +200 -0
- package/dist/signup.d.ts +80 -0
- package/dist/signup.js +238 -0
- package/dist/styles.d.ts +33 -0
- package/dist/styles.js +69 -0
- package/dist/types.d.ts +107 -0
- package/dist/types.js +3 -0
- package/dist/ui.d.ts +34 -0
- package/dist/ui.js +59 -0
- package/dist/words.d.ts +4 -0
- package/dist/words.js +60 -0
- package/package.json +56 -4
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/** One thing an account uses up each month, such as messages read. */
|
|
2
|
+
export interface MeterConfig {
|
|
3
|
+
label: string;
|
|
4
|
+
unit: string;
|
|
5
|
+
/**
|
|
6
|
+
* What one use costs the project at most, in US dollars, through the
|
|
7
|
+
* Gateway (the capability's cost hint). The generator multiplies it by the
|
|
8
|
+
* free allowance to print what "free" costs. Leave it out for a meter that
|
|
9
|
+
* costs nothing.
|
|
10
|
+
*/
|
|
11
|
+
cost_usd?: number;
|
|
12
|
+
}
|
|
13
|
+
export interface PlanConfig {
|
|
14
|
+
label: string;
|
|
15
|
+
/** The features the plan includes, or "all". */
|
|
16
|
+
features: readonly string[] | "all";
|
|
17
|
+
/** The monthly allowance of each meter. A meter left out is 0. */
|
|
18
|
+
meters: Readonly<Record<string, number>>;
|
|
19
|
+
}
|
|
20
|
+
/** The sign-up checks a project can switch on. */
|
|
21
|
+
export type SignupCheck = "email_code" | "turnstile" | "business_identity" | "device_signal" | "phone_code" | "facebook_login";
|
|
22
|
+
export interface SignupConfig {
|
|
23
|
+
checks: readonly SignupCheck[];
|
|
24
|
+
/** How many free accounts one business identity may have; the next is a repeat. Default 1. */
|
|
25
|
+
free_accounts_per_identity?: number;
|
|
26
|
+
/** What happens to a repeat sign-up: held for the admin to check (default), or refused. */
|
|
27
|
+
repeats?: "hold" | "refuse";
|
|
28
|
+
/** The device check: more than `max` sign-ups from one device in `window_days` are repeats. Default 2 in 30 days. */
|
|
29
|
+
device?: {
|
|
30
|
+
max?: number;
|
|
31
|
+
window_days?: number;
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
/** The worst-case check: how many free accounts the project expects, and its Gateway `ai` cap a month. */
|
|
35
|
+
export interface FreeBudget {
|
|
36
|
+
free_accounts: number;
|
|
37
|
+
ai_cap_usd: number;
|
|
38
|
+
}
|
|
39
|
+
export interface PlansConfig {
|
|
40
|
+
format: 1;
|
|
41
|
+
period: "calendar_month";
|
|
42
|
+
/** The month turns over at midnight here (IANA name). */
|
|
43
|
+
time_zone: string;
|
|
44
|
+
meters: Readonly<Record<string, MeterConfig>>;
|
|
45
|
+
features: readonly string[];
|
|
46
|
+
/** In upgrade order: the first is the smallest. */
|
|
47
|
+
plans: Readonly<Record<string, PlanConfig>>;
|
|
48
|
+
default_plan: string;
|
|
49
|
+
signup?: SignupConfig;
|
|
50
|
+
budget?: FreeBudget;
|
|
51
|
+
}
|
|
52
|
+
export type MeterKey<C extends PlansConfig> = keyof C["meters"] & string;
|
|
53
|
+
export type FeatureKey<C extends PlansConfig> = C["features"][number] & string;
|
|
54
|
+
export type PlanKey<C extends PlansConfig> = keyof C["plans"] & string;
|
|
55
|
+
export type RefusalReason = "not_on_plan" | "switched_off" | "allowance_used" | "account_held";
|
|
56
|
+
export type Allowed<P extends string = string> = {
|
|
57
|
+
ok: true;
|
|
58
|
+
useId?: string;
|
|
59
|
+
left?: number;
|
|
60
|
+
} | {
|
|
61
|
+
ok: false;
|
|
62
|
+
reason: RefusalReason;
|
|
63
|
+
resets_at?: string;
|
|
64
|
+
upgrade_to?: P;
|
|
65
|
+
limit?: number;
|
|
66
|
+
};
|
|
67
|
+
/** A use's link to the app's own record (the message, the reply), never a person's words. */
|
|
68
|
+
export type Subject = string;
|
|
69
|
+
export interface UseRequest {
|
|
70
|
+
/** How much to count, default 1. */
|
|
71
|
+
amount?: number;
|
|
72
|
+
subject?: Subject;
|
|
73
|
+
/** The same key twice counts once: pass the request's own id so a retry doesn't count again. */
|
|
74
|
+
idempotencyKey?: string;
|
|
75
|
+
}
|
|
76
|
+
export type FeatureState = "on" | "switched_off" | "not_on_plan";
|
|
77
|
+
export interface MeterStatus {
|
|
78
|
+
meter: string;
|
|
79
|
+
label: string;
|
|
80
|
+
unit: string;
|
|
81
|
+
used: number;
|
|
82
|
+
/** The plan's allowance plus any top-up in force. */
|
|
83
|
+
limit: number;
|
|
84
|
+
/** The top-ups in force, included in `limit`. */
|
|
85
|
+
granted: number;
|
|
86
|
+
left: number;
|
|
87
|
+
}
|
|
88
|
+
export interface HoldMatch {
|
|
89
|
+
/** Which signal matched: email, page, name, phone or device. */
|
|
90
|
+
kind: string;
|
|
91
|
+
/** The other accounts it matched. */
|
|
92
|
+
accounts: string[];
|
|
93
|
+
}
|
|
94
|
+
export interface PlanStatus {
|
|
95
|
+
account: string;
|
|
96
|
+
plan: string;
|
|
97
|
+
plan_label: string;
|
|
98
|
+
status: "active" | "held";
|
|
99
|
+
features: Record<string, FeatureState>;
|
|
100
|
+
meters: MeterStatus[];
|
|
101
|
+
/** This month, as YYYY-MM in the project's time zone. */
|
|
102
|
+
period: string;
|
|
103
|
+
/** When the allowances come back: midnight on the 1st, in the project's time zone. */
|
|
104
|
+
resets_at: string;
|
|
105
|
+
/** Why the account was held, kept after the hold is cleared. */
|
|
106
|
+
hold_matches: HoldMatch[];
|
|
107
|
+
}
|
package/dist/types.js
ADDED
package/dist/ui.d.ts
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { Allowed, PlansConfig, PlanStatus } from "./types.ts";
|
|
2
|
+
export { PLAN_WORDS, PLAN_WORD_KEYS, type PlanWordKey } from "./words.ts";
|
|
3
|
+
/** The project's strings lookup: `t('ui.wbplan.left', { left: 3, limit: 30 })`. Undefined falls back to the English. */
|
|
4
|
+
export type Words = (key: string, params?: Readonly<Record<string, string | number>>) => string | undefined;
|
|
5
|
+
/** "1 Dec" in the project's time zone (fil-PH for tl). */
|
|
6
|
+
export declare function shortDate(iso: string, timeZone: string, lang?: string): string;
|
|
7
|
+
export interface UsageOptions {
|
|
8
|
+
/** The project's strings lookup; English when left out. */
|
|
9
|
+
t?: Words;
|
|
10
|
+
/** For the date: en, tl or taglish. */
|
|
11
|
+
lang?: string;
|
|
12
|
+
/** Where "Switch to …" goes, such as /account/plan. No link when left out. */
|
|
13
|
+
upgradeHref?: string;
|
|
14
|
+
/** The next plan up, to offer on a used-up meter. */
|
|
15
|
+
upgrade?: {
|
|
16
|
+
key: string;
|
|
17
|
+
label: string;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/** The account's usage card: each meter with a bar and what's left, when it resets, and a note while held. */
|
|
21
|
+
export declare function renderUsage(s: PlanStatus, config: PlansConfig, o?: UsageOptions): string;
|
|
22
|
+
export interface LimitOptions {
|
|
23
|
+
t?: Words;
|
|
24
|
+
lang?: string;
|
|
25
|
+
upgradeHref?: string;
|
|
26
|
+
/** The account's plan, for "this month's 30 Free …". */
|
|
27
|
+
plan: string;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The notice for a refusal from use() or can(): "You've used this month's 30
|
|
31
|
+
* free messages read. They come back on 1 Dec, or switch to Basic." Empty for
|
|
32
|
+
* an `ok` answer.
|
|
33
|
+
*/
|
|
34
|
+
export declare function renderLimit(answer: Allowed, meterOrFeature: string, config: PlansConfig, o: LimitOptions): string;
|
package/dist/ui.js
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// '@mccaskie-labs/workbench-plans/ui': the account's usage card and the
|
|
2
|
+
// notice shown when use() or can() says no. Plain HTML strings with a
|
|
3
|
+
// `wb-plan-*` class on every element (PLAN_STYLES), no script.
|
|
4
|
+
import { PLAN_WORDS } from "./words.js";
|
|
5
|
+
export { PLAN_WORDS, PLAN_WORD_KEYS } from "./words.js";
|
|
6
|
+
const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[c]);
|
|
7
|
+
function fill(text, params = {}) {
|
|
8
|
+
return text.replace(/\{(\w+)\}/g, (m, k) => (Object.hasOwn(params, k) ? String(params[k]) : m));
|
|
9
|
+
}
|
|
10
|
+
function word(t, key, params = {}) {
|
|
11
|
+
return t?.(`ui.wbplan.${key}`, params) ?? fill(PLAN_WORDS.en[key], params);
|
|
12
|
+
}
|
|
13
|
+
/** "1 Dec" in the project's time zone (fil-PH for tl). */
|
|
14
|
+
export function shortDate(iso, timeZone, lang = "en") {
|
|
15
|
+
return new Intl.DateTimeFormat(lang === "tl" ? "fil-PH" : "en-GB", { day: "numeric", month: "short", timeZone }).format(new Date(iso));
|
|
16
|
+
}
|
|
17
|
+
/** The account's usage card: each meter with a bar and what's left, when it resets, and a note while held. */
|
|
18
|
+
export function renderUsage(s, config, o = {}) {
|
|
19
|
+
const tz = config.time_zone;
|
|
20
|
+
const rows = s.meters
|
|
21
|
+
.filter((m) => m.limit > 0 || m.used > 0)
|
|
22
|
+
.map((m) => {
|
|
23
|
+
const left = m.left > 0 ? word(o.t, "left", { left: m.left, limit: m.limit }) : word(o.t, "used_up", { limit: m.limit });
|
|
24
|
+
return `<div class="wb-plan-meter${m.left === 0 ? " wb-plan-meter-full" : ""}"><span class="wb-plan-meter-label">${esc(m.label)}</span><progress class="wb-plan-meter-bar" max="${m.limit}" value="${Math.min(m.used, m.limit)}" aria-label="${esc(m.label)}">${m.used} / ${m.limit}</progress><span class="wb-plan-meter-left">${esc(left)}</span></div>`;
|
|
25
|
+
})
|
|
26
|
+
.join("");
|
|
27
|
+
const held = s.status === "held" ? `<p class="wb-plan-held" role="status">${esc(word(o.t, "held"))}</p>` : "";
|
|
28
|
+
const resets = `<p class="wb-plan-resets">${esc(word(o.t, "resets", { date: shortDate(s.resets_at, tz, o.lang) }))}</p>`;
|
|
29
|
+
const anyFull = s.meters.some((m) => m.limit > 0 && m.left === 0);
|
|
30
|
+
const up = anyFull && o.upgrade && o.upgradeHref ? `<a class="wb-plan-upgrade" href="${esc(o.upgradeHref)}">${esc(word(o.t, "upgrade", { upgrade: o.upgrade.label }))}</a>` : "";
|
|
31
|
+
return `<section class="wb-plan-usage"><h2 class="wb-plan-title">${esc(word(o.t, "title", { plan: s.plan_label }))}</h2>${held}${rows}${resets}${up}</section>`;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The notice for a refusal from use() or can(): "You've used this month's 30
|
|
35
|
+
* free messages read. They come back on 1 Dec, or switch to Basic." Empty for
|
|
36
|
+
* an `ok` answer.
|
|
37
|
+
*/
|
|
38
|
+
export function renderLimit(answer, meterOrFeature, config, o) {
|
|
39
|
+
if (answer.ok)
|
|
40
|
+
return "";
|
|
41
|
+
const label = config.meters[meterOrFeature]?.label ?? meterOrFeature.replace(/_/g, " ");
|
|
42
|
+
const plan = config.plans[o.plan]?.label ?? o.plan;
|
|
43
|
+
const upgrade = answer.upgrade_to ? (config.plans[answer.upgrade_to]?.label ?? answer.upgrade_to) : undefined;
|
|
44
|
+
const link = upgrade && o.upgradeHref ? `<a class="wb-plan-upgrade" href="${esc(o.upgradeHref)}">${esc(word(o.t, "upgrade", { upgrade }))}</a>` : "";
|
|
45
|
+
if (answer.reason === "account_held")
|
|
46
|
+
return `<p class="wb-plan-held" role="status">${esc(word(o.t, "held"))}</p>`;
|
|
47
|
+
let text;
|
|
48
|
+
if (answer.reason === "allowance_used") {
|
|
49
|
+
const params = { limit: answer.limit ?? "", plan: plan.toLowerCase(), meter: label.toLowerCase(), date: answer.resets_at ? shortDate(answer.resets_at, config.time_zone, o.lang) : "", upgrade: upgrade ?? "" };
|
|
50
|
+
text = word(o.t, upgrade ? "limit_upgrade" : "limit", params);
|
|
51
|
+
}
|
|
52
|
+
else if (answer.reason === "not_on_plan") {
|
|
53
|
+
text = word(o.t, upgrade ? "not_on_plan_upgrade" : "not_on_plan", { meter: label, plan, upgrade: upgrade ?? "" });
|
|
54
|
+
}
|
|
55
|
+
else {
|
|
56
|
+
text = word(o.t, "switched_off", { meter: label });
|
|
57
|
+
}
|
|
58
|
+
return `<div class="wb-plan-limit" role="status"><p class="wb-plan-limit-text">${esc(text)}</p>${link}</div>`;
|
|
59
|
+
}
|
package/dist/words.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export declare const PLAN_WORD_KEYS: readonly ["title", "left", "used_up", "resets", "limit", "limit_upgrade", "not_on_plan", "not_on_plan_upgrade", "switched_off", "upgrade", "held"];
|
|
2
|
+
export type PlanWordKey = (typeof PLAN_WORD_KEYS)[number];
|
|
3
|
+
/** The words by language, as `ui.wbplan.<key>` would hold them. */
|
|
4
|
+
export declare const PLAN_WORDS: Readonly<Record<"en" | "tl" | "taglish", Readonly<Record<PlanWordKey, string>>>>;
|
package/dist/words.js
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
// The usage card's and notices' words, keyed as the project's strings
|
|
2
|
+
// catalogue keys them (`ui.wbplan.*`), in English, Tagalog and Taglish. A
|
|
3
|
+
// project copies them into its catalogue (or keeps its own) and passes its
|
|
4
|
+
// `t`; a word the catalogue lacks falls back to the English here. The
|
|
5
|
+
// Tagalog and Taglish are starter words: have a fluent reader check them
|
|
6
|
+
// before a client sees them.
|
|
7
|
+
export const PLAN_WORD_KEYS = [
|
|
8
|
+
"title",
|
|
9
|
+
"left",
|
|
10
|
+
"used_up",
|
|
11
|
+
"resets",
|
|
12
|
+
"limit",
|
|
13
|
+
"limit_upgrade",
|
|
14
|
+
"not_on_plan",
|
|
15
|
+
"not_on_plan_upgrade",
|
|
16
|
+
"switched_off",
|
|
17
|
+
"upgrade",
|
|
18
|
+
"held",
|
|
19
|
+
];
|
|
20
|
+
const en = {
|
|
21
|
+
title: "{plan} plan",
|
|
22
|
+
left: "{left} of {limit} left",
|
|
23
|
+
used_up: "All {limit} used",
|
|
24
|
+
resets: "Your allowance comes back on {date}.",
|
|
25
|
+
limit: "You've used this month's {limit} {plan} {meter}. They come back on {date}.",
|
|
26
|
+
limit_upgrade: "You've used this month's {limit} {plan} {meter}. They come back on {date}, or switch to {upgrade}.",
|
|
27
|
+
not_on_plan: "{meter} aren't part of the {plan} plan.",
|
|
28
|
+
not_on_plan_upgrade: "{meter} aren't part of the {plan} plan. Switch to {upgrade} to use them.",
|
|
29
|
+
switched_off: "{meter} are switched off for this account. Ask us if you need them.",
|
|
30
|
+
upgrade: "Switch to {upgrade}",
|
|
31
|
+
held: "We're checking your sign-up, which usually takes a day. You can set up everything meanwhile; we'll email you when it's done.",
|
|
32
|
+
};
|
|
33
|
+
const tl = {
|
|
34
|
+
title: "{plan} na plano",
|
|
35
|
+
left: "{left} sa {limit} ang natitira",
|
|
36
|
+
used_up: "Nagamit na ang lahat ng {limit}",
|
|
37
|
+
resets: "Babalik ang allowance mo sa {date}.",
|
|
38
|
+
limit: "Nagamit mo na ang {limit} na {plan} na {meter} ngayong buwan. Babalik ang mga ito sa {date}.",
|
|
39
|
+
limit_upgrade: "Nagamit mo na ang {limit} na {plan} na {meter} ngayong buwan. Babalik ang mga ito sa {date}, o lumipat sa {upgrade}.",
|
|
40
|
+
not_on_plan: "Hindi kasama ang {meter} sa {plan} na plano.",
|
|
41
|
+
not_on_plan_upgrade: "Hindi kasama ang {meter} sa {plan} na plano. Lumipat sa {upgrade} para magamit ito.",
|
|
42
|
+
switched_off: "Naka-off ang {meter} para sa account na ito. Magtanong sa amin kung kailangan mo.",
|
|
43
|
+
upgrade: "Lumipat sa {upgrade}",
|
|
44
|
+
held: "Sinusuri namin ang sign-up mo, karaniwang isang araw. Puwede mo nang i-set up ang lahat habang naghihintay; mag-e-email kami kapag tapos na.",
|
|
45
|
+
};
|
|
46
|
+
const taglish = {
|
|
47
|
+
title: "{plan} plan",
|
|
48
|
+
left: "{left} of {limit} pa ang natitira",
|
|
49
|
+
used_up: "Nagamit na lahat ng {limit}",
|
|
50
|
+
resets: "Babalik ang allowance mo sa {date}.",
|
|
51
|
+
limit: "Nagamit mo na ang {limit} {plan} {meter} this month. Babalik sila sa {date}.",
|
|
52
|
+
limit_upgrade: "Nagamit mo na ang {limit} {plan} {meter} this month. Babalik sila sa {date}, or switch ka to {upgrade}.",
|
|
53
|
+
not_on_plan: "Hindi kasama ang {meter} sa {plan} plan.",
|
|
54
|
+
not_on_plan_upgrade: "Hindi kasama ang {meter} sa {plan} plan. Switch ka to {upgrade} para magamit.",
|
|
55
|
+
switched_off: "Naka-off ang {meter} for this account. Message us kung kailangan mo.",
|
|
56
|
+
upgrade: "Switch to {upgrade}",
|
|
57
|
+
held: "Chine-check pa namin ang sign-up mo, usually isang araw lang. Puwede mo nang i-set up lahat habang naghihintay; i-email ka namin pag tapos na.",
|
|
58
|
+
};
|
|
59
|
+
/** The words by language, as `ui.wbplan.<key>` would hold them. */
|
|
60
|
+
export const PLAN_WORDS = { en, tl, taglish };
|
package/package.json
CHANGED
|
@@ -1,6 +1,58 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mccaskie-labs/workbench-plans",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Plans and usage limits for Workbench apps: free monthly allowances, per-account feature switches, one use() call that checks and counts atomically, and sign-up checks that hold repeat free sign-ups for review.",
|
|
5
|
+
"license": "UNLICENSED",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/mccaskie-labs/workbench.git",
|
|
10
|
+
"directory": "packages/plans"
|
|
11
|
+
},
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=24"
|
|
14
|
+
},
|
|
15
|
+
"sideEffects": false,
|
|
16
|
+
"exports": {
|
|
17
|
+
".": {
|
|
18
|
+
"types": "./dist/index.d.ts",
|
|
19
|
+
"default": "./dist/index.js"
|
|
20
|
+
},
|
|
21
|
+
"./signup": {
|
|
22
|
+
"types": "./dist/signup.d.ts",
|
|
23
|
+
"default": "./dist/signup.js"
|
|
24
|
+
},
|
|
25
|
+
"./ui": {
|
|
26
|
+
"types": "./dist/ui.d.ts",
|
|
27
|
+
"default": "./dist/ui.js"
|
|
28
|
+
},
|
|
29
|
+
"./styles": {
|
|
30
|
+
"types": "./dist/styles.d.ts",
|
|
31
|
+
"default": "./dist/styles.js"
|
|
32
|
+
},
|
|
33
|
+
"./package.json": "./package.json"
|
|
34
|
+
},
|
|
35
|
+
"bin": {
|
|
36
|
+
"workbench-plans": "./dist/cli.js"
|
|
37
|
+
},
|
|
38
|
+
"files": [
|
|
39
|
+
"dist",
|
|
40
|
+
"README.md",
|
|
41
|
+
"CHANGELOG.md"
|
|
42
|
+
],
|
|
43
|
+
"publishConfig": {
|
|
44
|
+
"access": "public"
|
|
45
|
+
},
|
|
46
|
+
"scripts": {
|
|
47
|
+
"typecheck": "tsc -p tsconfig.check.json && tsc -p test/tsconfig.json",
|
|
48
|
+
"test": "vitest run",
|
|
49
|
+
"test:store": "vitest run --config vitest.db.config.ts",
|
|
50
|
+
"build": "node scripts/build.mjs",
|
|
51
|
+
"prepack": "node scripts/build.mjs"
|
|
52
|
+
},
|
|
53
|
+
"devDependencies": {
|
|
54
|
+
"@types/node": "24.19.2",
|
|
55
|
+
"postgres": "4.1.0",
|
|
56
|
+
"vitest": "^5.1.0"
|
|
57
|
+
}
|
|
58
|
+
}
|