@boost33/shell-data 0.0.0-stage → 0.1.1

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.
@@ -0,0 +1,36 @@
1
+ import { type TokenSplitResult, type ViewerTokenSplitResult } from '@boost33/ledger-client';
2
+ import type { ChromeClaims, ChromeConfig, ChromeTokens } from './types.js';
3
+ /** Reads one acting account's split, by its wallet id (keyed) or the viewer's `b33_ctx` (viewer). */
4
+ export type TokenSplitReader = {
5
+ mode: 'keyed';
6
+ read: (walletId: string) => Promise<TokenSplitResult>;
7
+ } | {
8
+ mode: 'viewer';
9
+ read: (ctx: string) => Promise<ViewerTokenSplitResult>;
10
+ };
11
+ /**
12
+ * The ledger client's base URL, which includes `/api/v1`. Accepts the ledger's
13
+ * origin with or without a trailing `/api/v1` and slashes, and never doubles
14
+ * it: some apps' `BOOST33_LEDGER_URL` already ends in `/api/v1` (Outbound,
15
+ * B33-660), and a doubled path made every token read "unknown".
16
+ */
17
+ export declare const apiUrl: (url: string) => string;
18
+ /**
19
+ * The real reader for this config: `tokenSplit()` with the app's ledger key
20
+ * when it has one, else `tokenSplitForViewer()` with the viewer's own token.
21
+ * Built per call: the client holds no connection.
22
+ */
23
+ export declare function ledgerReader(config: ChromeConfig): TokenSplitReader;
24
+ /**
25
+ * The ledger's split in the chip's terms (B33-1726, from the Hub's toTokenChip):
26
+ * known gives both halves; overdrawn and negative_bucket give the true total
27
+ * and no split; unavailable, account_not_found, an expired viewer token, a
28
+ * throw, or a figure that is not a safe integer give unknown. No acting
29
+ * account, or no wallet, gives none. `nextGrantAt` stays an ISO string:
30
+ * formatting a date is the app's, in its language.
31
+ *
32
+ * Viewer mode reads with the viewer's own `b33_ctx`, so a request with none
33
+ * (only `b33_sid` arrived) is unknown: the session gate refreshes it on the
34
+ * next navigation, and nothing here retries.
35
+ */
36
+ export declare function readTokens(claims: ChromeClaims, ctx: string | null, reader: TokenSplitReader): Promise<ChromeTokens>;
package/dist/tokens.js ADDED
@@ -0,0 +1,92 @@
1
+ import { createLedgerClient, tokenSplitForViewer, } from '@boost33/ledger-client';
2
+ import { actingAccount } from './person.js';
3
+ import { READ_TIMEOUT_MS } from './products.js';
4
+ /**
5
+ * The ledger client's base URL, which includes `/api/v1`. Accepts the ledger's
6
+ * origin with or without a trailing `/api/v1` and slashes, and never doubles
7
+ * it: some apps' `BOOST33_LEDGER_URL` already ends in `/api/v1` (Outbound,
8
+ * B33-660), and a doubled path made every token read "unknown".
9
+ */
10
+ export const apiUrl = (url) => `${url.replace(/\/+$/, '').replace(/\/api\/v1$/, '')}/api/v1`;
11
+ /**
12
+ * The real reader for this config: `tokenSplit()` with the app's ledger key
13
+ * when it has one, else `tokenSplitForViewer()` with the viewer's own token.
14
+ * Built per call: the client holds no connection.
15
+ */
16
+ export function ledgerReader(config) {
17
+ const ledger = config.ledger;
18
+ if (ledger?.url && ledger.key && ledger.app) {
19
+ const { url, key, app } = ledger;
20
+ return {
21
+ mode: 'keyed',
22
+ read: (walletId) => createLedgerClient({ url: apiUrl(url), key, app, readTimeoutMs: READ_TIMEOUT_MS }).tokenSplit(walletId),
23
+ };
24
+ }
25
+ return {
26
+ mode: 'viewer',
27
+ read: (ctx) => tokenSplitForViewer(ctx, { ...(ledger?.url ? { url: apiUrl(ledger.url) } : {}), timeoutMs: READ_TIMEOUT_MS }),
28
+ };
29
+ }
30
+ /** An integer string the chip can draw exactly, or null. */
31
+ function figure(value) {
32
+ const n = Number(value);
33
+ return Number.isSafeInteger(n) ? n : null;
34
+ }
35
+ /**
36
+ * The ledger's split in the chip's terms (B33-1726, from the Hub's toTokenChip):
37
+ * known gives both halves; overdrawn and negative_bucket give the true total
38
+ * and no split; unavailable, account_not_found, an expired viewer token, a
39
+ * throw, or a figure that is not a safe integer give unknown. No acting
40
+ * account, or no wallet, gives none. `nextGrantAt` stays an ISO string:
41
+ * formatting a date is the app's, in its language.
42
+ *
43
+ * Viewer mode reads with the viewer's own `b33_ctx`, so a request with none
44
+ * (only `b33_sid` arrived) is unknown: the session gate refreshes it on the
45
+ * next navigation, and nothing here retries.
46
+ */
47
+ export async function readTokens(claims, ctx, reader) {
48
+ const account = actingAccount(claims);
49
+ if (!account)
50
+ return { kind: 'none' };
51
+ // The claims say this account has no wallet: no chip, and no call, in either mode.
52
+ if (account.walletId === null)
53
+ return { kind: 'none' };
54
+ let result;
55
+ try {
56
+ if (reader.mode === 'keyed') {
57
+ if (!account.walletId)
58
+ return { kind: 'none' };
59
+ result = await reader.read(account.walletId);
60
+ }
61
+ else {
62
+ if (!ctx)
63
+ return { kind: 'unknown' };
64
+ result = await reader.read(ctx);
65
+ }
66
+ }
67
+ catch {
68
+ return { kind: 'unknown' };
69
+ }
70
+ if (!result.ok)
71
+ return { kind: 'unknown' };
72
+ const { split } = result;
73
+ if (split.kind === 'unavailable')
74
+ return split.reason === 'no_wallet' ? { kind: 'none' } : { kind: 'unknown' };
75
+ const granted = figure(split.granted);
76
+ const purchased = figure(split.purchased);
77
+ if (granted === null || purchased === null || !Number.isSafeInteger(granted + purchased))
78
+ return { kind: 'unknown' };
79
+ if (split.kind !== 'known')
80
+ return { kind: 'totalOnly', total: granted + purchased };
81
+ const cycle = result.grantTokensPerCycle === null ? null : figure(result.grantTokensPerCycle);
82
+ const next = result.nextGrantAt !== null && !Number.isNaN(Date.parse(result.nextGrantAt)) ? result.nextGrantAt : null;
83
+ return {
84
+ kind: 'known',
85
+ total: granted + purchased,
86
+ granted,
87
+ purchased,
88
+ grantPerCycle: cycle !== null && cycle > 0 ? cycle : null,
89
+ nextGrantAt: next,
90
+ };
91
+ }
92
+ //# sourceMappingURL=tokens.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,152 @@
1
+ /**
2
+ * The verified session claims, as each app already reads them from `b33_ctx`.
3
+ *
4
+ * Structural on purpose: only the fields read here are named, so an app passes
5
+ * its own claims type unchanged. `design` is deliberately absent: the package
6
+ * never decides which design a person sees. Each app's `isBackdropPreview` is
7
+ * the only reader of that claim, and the chrome is only rendered after it has
8
+ * said "backdrop".
9
+ */
10
+ export type ChromeClaims = {
11
+ email: string;
12
+ name: string | null;
13
+ orgName?: string | null;
14
+ act: string | null;
15
+ accounts: ReadonlyArray<{
16
+ id: string;
17
+ role: 'admin' | 'member';
18
+ products: readonly string[];
19
+ walletId?: string | null;
20
+ }>;
21
+ };
22
+ export type ChromeConfig = {
23
+ /** Identity's origin, e.g. `https://id.boost33.com`. No trailing path. */
24
+ identityUrl: string;
25
+ /** The Hub's origin, e.g. `https://app.boost33.com`. Account rows link here. */
26
+ hubUrl: string;
27
+ /** Defaults to `https://docs.boost33.com`. */
28
+ docsUrl?: string;
29
+ /** Defaults to `support@boost33.com`. */
30
+ supportEmail?: string;
31
+ /**
32
+ * This app's Identity service key, for the profile read. Server env only.
33
+ * Optional: an app with no key (one not in Identity's `APPS`) reads as the
34
+ * viewer only, so `profileName` resolves null and the `name` claim stands.
35
+ * The product list is always read as the viewer and needs no key.
36
+ */
37
+ identityKey?: string;
38
+ /**
39
+ * This app's slug in Identity's `APPS` (boost33-identity src/config/apps.ts),
40
+ * sent as `x-boost33-app` with `identityKey`. Identity's caller slug, NOT the
41
+ * product slug: Outbound is `outbound`, not `boostoutbound`. Identity checks
42
+ * it against the key, so a product slug here fails the profile read.
43
+ */
44
+ appId?: string;
45
+ /**
46
+ * The ledger. With `key` and `app`, the token split is read with this app's
47
+ * ledger key (`tokenSplit`). Without them, or without `ledger` at all, it is
48
+ * read as the viewer with their own `b33_ctx` (`tokenSplitForViewer`): no key,
49
+ * read-only, the wallet taken from the token's acting account. With no `url`
50
+ * the ledger client falls back to `BOOST33_LEDGER_URL`.
51
+ */
52
+ ledger?: {
53
+ /** The ledger's origin. A trailing `/api/v1` is accepted and never doubled. */
54
+ url?: string;
55
+ key?: string;
56
+ app?: string;
57
+ };
58
+ };
59
+ export type ChromePerson = {
60
+ /** The `name` claim. `profileName` may replace it once it resolves. */
61
+ name: string | null;
62
+ email: string;
63
+ /** One or two letters, from the name or else the email. Never empty. */
64
+ initials: string;
65
+ org: {
66
+ name: string;
67
+ } | null;
68
+ role: 'admin' | 'member' | null;
69
+ /** How many other accounts this person can switch to. */
70
+ otherAccounts: number;
71
+ };
72
+ /**
73
+ * One product as the chrome may show it.
74
+ *
75
+ * - `open`: live, and this account has it. `href` is the product.
76
+ * - `soon`: not live yet, or this person has no account. `href` is null.
77
+ * - `ask`: live, but this account does not have it. `href` is a mailto to
78
+ * support, with no subject: a subject would be words, and words are the app's.
79
+ */
80
+ export type ChromeProduct = {
81
+ slug: string;
82
+ name: string;
83
+ /** `name` without a leading "Boost " ("Boost Score" → "Score"), for the rail. */
84
+ shortName: string;
85
+ state: 'open' | 'soon' | 'ask';
86
+ href: string | null;
87
+ };
88
+ export type ChromeProducts = {
89
+ /** Every product except the Wallet, in the order Identity returned them. */
90
+ all: ChromeProduct[];
91
+ /**
92
+ * Slugs pinned on the rail: the first four of `all`. Identity's order, never a
93
+ * list baked in here (CLAUDE.md in @boost33/ui: "the product list is served,
94
+ * never hardcoded"); Identity serving an explicit order is a ticket of its own.
95
+ */
96
+ pinned: string[];
97
+ /** The Wallet, when it is live. Null hides it from the rail. */
98
+ walletHref: string | null;
99
+ /** Where the tokens popover's buy action goes: the Wallet's `/subscribe`. Null when the Wallet is not live. */
100
+ buyTokensHref: string | null;
101
+ /** True when Identity was unreachable and this is the last list that read cleanly. */
102
+ stale: boolean;
103
+ };
104
+ export type ChromeTokens =
105
+ /** Both halves of the balance. `grantPerCycle` and `nextGrantAt` are null when the ledger has none. */
106
+ {
107
+ kind: 'known';
108
+ total: number;
109
+ granted: number;
110
+ purchased: number;
111
+ grantPerCycle: number | null;
112
+ nextGrantAt: string | null;
113
+ }
114
+ /** Overdrawn, or a negative bucket: the true total, and no split to draw. */
115
+ | {
116
+ kind: 'totalOnly';
117
+ total: number;
118
+ }
119
+ /** The ledger could not say: a disabled chip with no popover. */
120
+ | {
121
+ kind: 'unknown';
122
+ }
123
+ /** No account, or an account with no wallet: no chip at all. */
124
+ | {
125
+ kind: 'none';
126
+ };
127
+ /** Every link the chrome draws that does not depend on a read. All absolute. */
128
+ export type ChromeLinks = {
129
+ home: string;
130
+ settings: string;
131
+ profile: string;
132
+ company: string;
133
+ team: string;
134
+ billing: string;
135
+ notifications: string;
136
+ security: string;
137
+ chooseAccount: string;
138
+ signOut: string;
139
+ docs: string;
140
+ support: string;
141
+ };
142
+ export type BackdropChromeData = {
143
+ /** Drawn at once, from the claims. */
144
+ person: ChromePerson;
145
+ /** Identity's display name. Null means keep `person.name`. Never rejects. */
146
+ profileName: Promise<string | null>;
147
+ /** Null when Identity is unreachable and no list has read cleanly yet. Never rejects. */
148
+ products: Promise<ChromeProducts | null>;
149
+ /** Never rejects; failure is `{ kind: 'unknown' }`. */
150
+ tokens: Promise<ChromeTokens>;
151
+ links: ChromeLinks;
152
+ };
package/dist/types.js ADDED
@@ -0,0 +1,11 @@
1
+ /*
2
+ * The shapes the Backdrop chrome in @boost33/ui draws from (B33-1726).
3
+ *
4
+ * `BackdropStandardChrome` takes these as props of the same names, so an app
5
+ * spreads the result of `getBackdropChromeData()` straight onto it. Every
6
+ * field is plain, serialisable data: no words (an app passes its own labels to
7
+ * the chrome), no callbacks, no components. The two packages are agreed on
8
+ * these shapes; changing one is a change to both.
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@boost33/shell-data",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Server-only reads that hand the Backdrop chrome in @boost33/ui exactly the data it draws.",
5
+ "license": "UNLICENSED",
6
+ "type": "module",
7
+ "engines": {
8
+ "node": ">=22"
9
+ },
10
+ "publishConfig": {
11
+ "access": "public"
12
+ },
13
+ "files": [
14
+ "dist",
15
+ "CHANGELOG.md"
16
+ ],
17
+ "sideEffects": false,
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ },
23
+ "./session": {
24
+ "types": "./dist/session.d.ts",
25
+ "import": "./dist/session.js"
26
+ }
27
+ },
28
+ "scripts": {
29
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.drift.json",
30
+ "test": "vitest run",
31
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
32
+ "prepublishOnly": "npm run typecheck && npm run test && npm run build"
33
+ },
34
+ "dependencies": {
35
+ "@boost33/ledger-client": "2.3.0",
36
+ "server-only": "0.0.1"
37
+ },
38
+ "peerDependencies": {
39
+ "jose": ">=6.0.0",
40
+ "next": ">=15.0.0"
41
+ },
42
+ "peerDependenciesMeta": {
43
+ "jose": {
44
+ "optional": true
45
+ },
46
+ "next": {
47
+ "optional": true
48
+ }
49
+ },
50
+ "devDependencies": {
51
+ "@boost33/ui": "0.11.0",
52
+ "@types/node": "^24.0.0",
53
+ "@types/react": "19.3.0",
54
+ "jose": "^6.2.17",
55
+ "next": "^16.4.6",
56
+ "react": "^19.3.1",
57
+ "react-dom": "^19.3.1",
58
+ "typescript": "^5.7.2",
59
+ "vitest": "^4.1.10"
60
+ }
61
+ }