@wickermoney/plugin-sdk 0.4.2 → 0.6.0-rc.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.
- package/README.md +265 -12
- package/dist/{recurrence → date}/calendar.d.ts +30 -2
- package/dist/date/calendar.d.ts.map +1 -0
- package/dist/{recurrence → date}/calendar.js +42 -3
- package/dist/date/calendar.js.map +1 -0
- package/dist/date/index.d.ts +17 -0
- package/dist/date/index.d.ts.map +1 -0
- package/dist/date/index.js +17 -0
- package/dist/date/index.js.map +1 -0
- package/dist/index.d.ts +15 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +14 -1
- package/dist/index.js.map +1 -1
- package/dist/isolated/PluginApiError.d.ts +20 -0
- package/dist/isolated/PluginApiError.d.ts.map +1 -0
- package/dist/isolated/PluginApiError.js +25 -0
- package/dist/isolated/PluginApiError.js.map +1 -0
- package/dist/isolated/client.d.ts +118 -0
- package/dist/isolated/client.d.ts.map +1 -0
- package/dist/isolated/client.js +275 -0
- package/dist/isolated/client.js.map +1 -0
- package/dist/isolated/format.d.ts +25 -0
- package/dist/isolated/format.d.ts.map +1 -0
- package/dist/isolated/format.js +59 -0
- package/dist/isolated/format.js.map +1 -0
- package/dist/isolated/index.d.ts +48 -0
- package/dist/isolated/index.d.ts.map +1 -0
- package/dist/isolated/index.js +45 -0
- package/dist/isolated/index.js.map +1 -0
- package/dist/isolated/protocol.d.ts +217 -0
- package/dist/isolated/protocol.d.ts.map +1 -0
- package/dist/isolated/protocol.js +31 -0
- package/dist/isolated/protocol.js.map +1 -0
- package/dist/isolated/theme.d.ts +24 -0
- package/dist/isolated/theme.d.ts.map +1 -0
- package/dist/isolated/theme.js +32 -0
- package/dist/isolated/theme.js.map +1 -0
- package/dist/isolated/validate.d.ts +47 -0
- package/dist/isolated/validate.d.ts.map +1 -0
- package/dist/isolated/validate.js +260 -0
- package/dist/isolated/validate.js.map +1 -0
- package/dist/manifest/PERMISSIONS.d.ts +5 -0
- package/dist/manifest/PERMISSIONS.d.ts.map +1 -1
- package/dist/manifest/PERMISSIONS.js +5 -0
- package/dist/manifest/PERMISSIONS.js.map +1 -1
- package/dist/manifest/checkRemoteEntry.d.ts +2 -1
- package/dist/manifest/checkRemoteEntry.d.ts.map +1 -1
- package/dist/manifest/checkRemoteEntry.js +2 -1
- package/dist/manifest/checkRemoteEntry.js.map +1 -1
- package/dist/manifest/checkRemoteEntryIntegrity.d.ts +27 -0
- package/dist/manifest/checkRemoteEntryIntegrity.d.ts.map +1 -0
- package/dist/manifest/checkRemoteEntryIntegrity.js +47 -0
- package/dist/manifest/checkRemoteEntryIntegrity.js.map +1 -0
- package/dist/manifest/index.d.ts +2 -5
- package/dist/manifest/index.d.ts.map +1 -1
- package/dist/manifest/index.js +2 -5
- package/dist/manifest/index.js.map +1 -1
- package/dist/manifest/integritySchema.d.ts +28 -0
- package/dist/manifest/integritySchema.d.ts.map +1 -0
- package/dist/manifest/integritySchema.js +30 -0
- package/dist/manifest/integritySchema.js.map +1 -0
- package/dist/manifest/parseIntegrity.d.ts +14 -0
- package/dist/manifest/parseIntegrity.d.ts.map +1 -0
- package/dist/manifest/parseIntegrity.js +16 -0
- package/dist/manifest/parseIntegrity.js.map +1 -0
- package/dist/manifest/pluginManifestSchema.d.ts +2 -0
- package/dist/manifest/pluginManifestSchema.d.ts.map +1 -1
- package/dist/manifest/pluginManifestSchema.js +48 -1
- package/dist/manifest/pluginManifestSchema.js.map +1 -1
- package/dist/manifest/tableGrantSchema.d.ts +6 -1
- package/dist/manifest/tableGrantSchema.d.ts.map +1 -1
- package/dist/manifest/tableGrantSchema.js +6 -1
- package/dist/manifest/tableGrantSchema.js.map +1 -1
- package/dist/money/index.d.ts +4 -0
- package/dist/money/index.d.ts.map +1 -1
- package/dist/money/index.js.map +1 -1
- package/dist/recurrence/index.d.ts +8 -0
- package/dist/recurrence/index.d.ts.map +1 -1
- package/dist/recurrence/index.js +10 -0
- package/dist/recurrence/index.js.map +1 -1
- package/dist/recurrence/projection.js +1 -1
- package/dist/recurrence/projection.js.map +1 -1
- package/dist/recurrence/schedule.js +1 -1
- package/dist/recurrence/schedule.js.map +1 -1
- package/dist/recurrence/scheduled.js +1 -1
- package/dist/recurrence/scheduled.js.map +1 -1
- package/dist/runtime.d.ts +26 -3
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js.map +1 -1
- package/dist/server/ConditionForMatching.d.ts +18 -0
- package/dist/server/ConditionForMatching.d.ts.map +1 -0
- package/dist/server/ConditionForMatching.js +2 -0
- package/dist/server/ConditionForMatching.js.map +1 -0
- package/dist/server/PluginRouteError.d.ts +27 -0
- package/dist/server/PluginRouteError.d.ts.map +1 -0
- package/dist/server/PluginRouteError.js +32 -0
- package/dist/server/PluginRouteError.js.map +1 -0
- package/dist/server/PluginRouteIssue.d.ts +8 -0
- package/dist/server/PluginRouteIssue.d.ts.map +1 -0
- package/dist/server/PluginRouteIssue.js +2 -0
- package/dist/server/PluginRouteIssue.js.map +1 -0
- package/dist/server/Query.d.ts +11 -0
- package/dist/server/Query.d.ts.map +1 -0
- package/dist/server/Query.js +2 -0
- package/dist/server/Query.js.map +1 -0
- package/dist/server/RegisterRoute.d.ts +24 -0
- package/dist/server/RegisterRoute.d.ts.map +1 -0
- package/dist/server/RegisterRoute.js +2 -0
- package/dist/server/RegisterRoute.js.map +1 -0
- package/dist/server/RouteContext.d.ts +12 -0
- package/dist/server/RouteContext.d.ts.map +1 -0
- package/dist/server/RouteContext.js +2 -0
- package/dist/server/RouteContext.js.map +1 -0
- package/dist/server/RouteMethod.d.ts +3 -0
- package/dist/server/RouteMethod.d.ts.map +1 -0
- package/dist/server/RouteMethod.js +2 -0
- package/dist/server/RouteMethod.js.map +1 -0
- package/dist/server/RuleForMatching.d.ts +16 -0
- package/dist/server/RuleForMatching.d.ts.map +1 -0
- package/dist/server/RuleForMatching.js +2 -0
- package/dist/server/RuleForMatching.js.map +1 -0
- package/dist/server/RuleSubject.d.ts +10 -0
- package/dist/server/RuleSubject.d.ts.map +1 -0
- package/dist/server/RuleSubject.js +2 -0
- package/dist/server/RuleSubject.js.map +1 -0
- package/dist/server/RunAsPlugin.d.ts +9 -0
- package/dist/server/RunAsPlugin.d.ts.map +1 -0
- package/dist/server/RunAsPlugin.js +2 -0
- package/dist/server/RunAsPlugin.js.map +1 -0
- package/dist/server/index.d.ts +30 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +3 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/isUuid.d.ts +18 -0
- package/dist/server/isUuid.d.ts.map +1 -0
- package/dist/server/isUuid.js +26 -0
- package/dist/server/isUuid.js.map +1 -0
- package/package.json +13 -1
- package/dist/recurrence/calendar.d.ts.map +0 -1
- package/dist/recurrence/calendar.js.map +0 -1
package/README.md
CHANGED
|
@@ -28,13 +28,54 @@ plugin as a Module Federation singleton.
|
|
|
28
28
|
| Import | Use it for | Contents |
|
|
29
29
|
|---|---|---|
|
|
30
30
|
| `@wickermoney/plugin-sdk/runtime` | Plugin UI code (browser) | Types for the React components a plugin exports (`PluginWidgetProps`, `PluginPageProps`, `PluginContext`, ...), and `adoptPluginStyles` |
|
|
31
|
-
| `@wickermoney/plugin-sdk/
|
|
31
|
+
| `@wickermoney/plugin-sdk/isolated` | Plugin UI code that runs in a sandboxed frame (browser), and the host's broker | The message protocol between a plugin frame and the host, validators for it, and the in-frame client: `connectToHost`, `PluginApiError`, `applyHostTheme`. Experimental |
|
|
32
|
+
| `@wickermoney/plugin-sdk/date` | Anything (browser or Node) | Calendar-date arithmetic on `YYYY-MM-DD` strings: `addDays` and `addMonths` |
|
|
33
|
+
| `@wickermoney/plugin-sdk/recurrence` | Anything (browser or Node) | Recurring-item date maths and projections: `occurrences`, `nextOccurrence`, `scheduledOccurrences`, `nextScheduledOccurrence`, `nextPayday`, `monthlyEquivalent`, `dailyBalances`, `flowTotals`, the calendar helpers `addDays` and `addMonths`, with per-occurrence overrides (skip, move, change the legs) |
|
|
32
34
|
| `@wickermoney/plugin-sdk/money` | Anything (browser or Node) | Exact money arithmetic on decimal strings: `addMoney`, `sumMoney`, `compareMoney`, `equalMoney`, `moneyToUnits`, `divideUnits`, ... |
|
|
33
|
-
| `@wickermoney/plugin-sdk` |
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
35
|
+
| `@wickermoney/plugin-sdk/server` | Bundled plugins' server code, and the host (Node) | The server-side contract: `RouteContext`, `RegisterRoute`, `Query`, `RunAsPlugin`, `PluginRouteError`, `isUuid`, and the category-rule types `RuleForMatching` and `RuleSubject` |
|
|
36
|
+
| `@wickermoney/plugin-sdk` | Hosts, tooling, tests (Node) | Everything above, plus `parseManifest` and the manifest types, dashboard-range helpers and constants |
|
|
37
|
+
|
|
38
|
+
Import from `/runtime` (and `/money` or `/recurrence` if you need them) in plugin UI code,
|
|
39
|
+
and from `/server` in a bundled plugin's server code.
|
|
40
|
+
The package root includes `parseManifest`, which is built on Zod, so importing the
|
|
41
|
+
root adds about 85 kB to a plugin bundle that never uses it. The Zod schemas
|
|
42
|
+
themselves are not exported; validate a manifest with `parseManifest`.
|
|
43
|
+
|
|
44
|
+
## Stability
|
|
45
|
+
|
|
46
|
+
Every entry point has a tier. The tier is also written in each entry point's
|
|
47
|
+
module documentation (`@stable` or `@experimental`).
|
|
48
|
+
|
|
49
|
+
| Import | Tier | What it is for | Who uses it today |
|
|
50
|
+
|---|---|---|---|
|
|
51
|
+
| `@wickermoney/plugin-sdk` (root: manifest, dashboard range) | stable | `parseManifest` and the manifest types, `SDK_MAJOR_VERSION`, remote-entry checks, and the dashboard range helpers | The API and the web app (manifest, range); the Insights and Spending Trends plugins (`monthsInRange`); several plugins import the `PluginContext` and props types from here |
|
|
52
|
+
| `@wickermoney/plugin-sdk/runtime` | stable | The props and context the host hands a plugin's React components, plus `adoptPluginStyles` | The web app and all seven bundled UI plugins |
|
|
53
|
+
| `@wickermoney/plugin-sdk/money` | stable | Exact money arithmetic on decimal strings | The web app, the Budgets, Insights and Spending Trends plugins, and the API's tests |
|
|
54
|
+
| `@wickermoney/plugin-sdk/server` | stable | The server-side contract between the host and a bundled plugin's `register` function | The API, Budgets and Import CSV |
|
|
55
|
+
| `@wickermoney/plugin-sdk/date` | stable | The `addDays` and `addMonths` calendar helpers | The API, the web app and Budgets |
|
|
56
|
+
| `@wickermoney/plugin-sdk/isolated` | experimental | The runtime contract for UI plugins that run in a sandboxed frame: protocol, validators, in-frame client. Stays experimental until the isolation work has shipped and settled | The web app's frame host and broker. The Insights and Spending Trends plugins run in a frame but are written against `/runtime`, unchanged |
|
|
57
|
+
| `@wickermoney/plugin-sdk/recurrence` | experimental | Recurring-item date maths and projections. It still re-exports `addDays` and `addMonths` so older imports work; import them from `/date` | The API and the web app. No plugin uses the projections yet |
|
|
58
|
+
|
|
59
|
+
The root also re-exports the `/date`, `/recurrence`, `/money` and `/server` exports. It does
|
|
60
|
+
not re-export `/isolated`: a frame has no use for the Zod manifest code the root carries. An
|
|
61
|
+
export keeps the tier of the entry point it comes from, however it is
|
|
62
|
+
imported, so `occurrences` is experimental even when imported from the root.
|
|
63
|
+
|
|
64
|
+
What the tiers promise:
|
|
65
|
+
|
|
66
|
+
- **Stable.** A breaking change (a removed or renamed export, a changed
|
|
67
|
+
signature or type, a changed return value or error) is made only with a
|
|
68
|
+
`BREAKING CHANGE:` footer on the commit, an entry under **Breaking** in the
|
|
69
|
+
[CHANGELOG](../../CHANGELOG.md), and a migration note saying what to write
|
|
70
|
+
instead. Additions are not breaking.
|
|
71
|
+
- **Experimental.** May change in any pre-1.0 minor release, including
|
|
72
|
+
removals and renamed or reshaped types. Changes are still recorded in the
|
|
73
|
+
CHANGELOG, but no migration note is promised. Re-check it on each upgrade.
|
|
74
|
+
|
|
75
|
+
Both tiers are covered by the same rule as the rest of the package: until
|
|
76
|
+
`SDK_MAJOR_VERSION` is frozen at 1, the whole contract can still move between
|
|
77
|
+
minor releases. The tiers say how much notice to expect and which parts are
|
|
78
|
+
settled.
|
|
38
79
|
|
|
39
80
|
## Recurring items
|
|
40
81
|
|
|
@@ -76,6 +117,21 @@ scheduledOccurrences(bills, '2026-03-01', '2026-06-01')
|
|
|
76
117
|
// [{ nominalDate: '2026-04-30', date: '2026-05-01', legs }, { nominalDate: '2026-05-31', ... }]
|
|
77
118
|
```
|
|
78
119
|
|
|
120
|
+
The calendar helpers work on the same `YYYY-MM-DD` strings, with no time zone
|
|
121
|
+
involved. `addMonths` clamps to the end of a short month, and each call clamps
|
|
122
|
+
on its own, so add the total to the original date rather than stepping.
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { addDays, addMonths } from '@wickermoney/plugin-sdk/date'
|
|
126
|
+
|
|
127
|
+
addDays('2026-12-31', 1) // '2027-01-01'
|
|
128
|
+
addMonths('2026-08-31', 6) // '2027-02-28' ('2028-02-29' in a leap year)
|
|
129
|
+
addMonths('2026-03-31', -1) // '2026-02-28'
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Both throw `RangeError` for anything that is not a real calendar date or not
|
|
133
|
+
a whole number.
|
|
134
|
+
|
|
79
135
|
## Money
|
|
80
136
|
|
|
81
137
|
Money is `numeric(19,4)` in the database and a decimal string in TypeScript,
|
|
@@ -147,9 +203,14 @@ const result = parseManifest({
|
|
|
147
203
|
if ('error' in result) throw new Error(result.error)
|
|
148
204
|
```
|
|
149
205
|
|
|
150
|
-
`requiredTables` is enforced by PostgreSQL
|
|
151
|
-
runs under its own database role, which is
|
|
152
|
-
manifest lists. A query against any other table
|
|
206
|
+
`requiredTables` is enforced by PostgreSQL for a plugin's **server-side** code.
|
|
207
|
+
Each bundled plugin's server code runs under its own database role, which is
|
|
208
|
+
granted exactly the tables its manifest lists. A query against any other table
|
|
209
|
+
is refused.
|
|
210
|
+
|
|
211
|
+
For your plugin's UI code, the broker and the server hold a plugin that runs in a
|
|
212
|
+
frame to these grants; a plugin that still runs in the app's own page is not held
|
|
213
|
+
to them. See [Trust model](#trust-model).
|
|
153
214
|
|
|
154
215
|
### Widget
|
|
155
216
|
|
|
@@ -157,8 +218,9 @@ manifest lists. A query against any other table is refused.
|
|
|
157
218
|
import type { PluginWidgetProps } from '@wickermoney/plugin-sdk/runtime'
|
|
158
219
|
|
|
159
220
|
export default function RunwayWidget({ ctx, size, range }: PluginWidgetProps) {
|
|
160
|
-
// ctx.api is scoped to your plugin and the tables your manifest grants
|
|
161
|
-
//
|
|
221
|
+
// ctx.api is scoped to your plugin and the tables your manifest grants
|
|
222
|
+
// (a convenience that catches mistakes early, not a sandbox); the host
|
|
223
|
+
// attaches credentials, so well-behaved plugin code never handles a token.
|
|
162
224
|
// Paths are relative to the API root; don't prefix /api/v1 yourself.
|
|
163
225
|
// ...
|
|
164
226
|
return <p>{ctx.formatMoney('1234.5600')}</p>
|
|
@@ -168,6 +230,65 @@ export default function RunwayWidget({ ctx, size, range }: PluginWidgetProps) {
|
|
|
168
230
|
Money crosses the contract as a **decimal string**, never a JavaScript
|
|
169
231
|
`number`. Use `ctx.formatMoney` to display it.
|
|
170
232
|
|
|
233
|
+
## Isolated runtime (experimental)
|
|
234
|
+
|
|
235
|
+
`/runtime` hands a plugin a `PluginContext`, an object of functions. A function cannot
|
|
236
|
+
cross the boundary of a sandboxed frame, so a plugin that runs in one uses
|
|
237
|
+
`/isolated` instead: a small message protocol over a `MessagePort`, and a client that
|
|
238
|
+
rebuilds the same `PluginContext` inside the frame. A component written against
|
|
239
|
+
`PluginWidgetProps` or `PluginPageProps` runs in either place.
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
import { connectToHost } from '@wickermoney/plugin-sdk/isolated'
|
|
243
|
+
|
|
244
|
+
const host = await connectToHost() // hello, port, init; applies the host's theme
|
|
245
|
+
host.observeSize(document.body) // the host sets the frame height from this
|
|
246
|
+
render(<Widget ctx={host.ctx} size={host.getState().size!} />)
|
|
247
|
+
|
|
248
|
+
host.subscribe((change) => { /* theme, locale, props, route, focus-in */ })
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
A manifest marks a plugin as built for this runtime with `isolated: true`. That is a
|
|
252
|
+
declaration of what the plugin was built for, not a grant: it can only move a plugin
|
|
253
|
+
towards isolation, and the host decides which runtime a plugin gets. A plugin the
|
|
254
|
+
image did not ship always gets the frame, whatever the flag says. The flag is
|
|
255
|
+
optional, and an existing manifest without it loads exactly as before.
|
|
256
|
+
|
|
257
|
+
Protocol version 1. After a one-time window handshake (the frame says `wm.hello`; the
|
|
258
|
+
host answers `wm.connect` with a transferred port, or `wm.refuse`), everything travels
|
|
259
|
+
on the port:
|
|
260
|
+
|
|
261
|
+
| Direction | Message | Purpose |
|
|
262
|
+
|---|---|---|
|
|
263
|
+
| frame to host | `ready` | The port is live; the host answers `init` |
|
|
264
|
+
| frame to host | `request` / `cancel` | `GET`, `POST`, `PUT` or `DELETE` of a path relative to the API root, with an optional `cache` mode; `cancel` for an aborted call |
|
|
265
|
+
| frame to host | `navigate` | Go to an in-app path |
|
|
266
|
+
| frame to host | `resize` | The content height in CSS pixels; the host owns the width |
|
|
267
|
+
| frame to host | `focus-out` | Focus left past the last (`next`) or before the first (`previous`) element |
|
|
268
|
+
| frame to host | `notify` | Reserved; a host answers `not_supported` until the `notify` permission exists |
|
|
269
|
+
| host to frame | `init` | Plugin id, widget or page, session, locale, theme, size and range, first path |
|
|
270
|
+
| host to frame | `response` | The JSON value, or an error: `code`, `message`, optional `status` and `issues` |
|
|
271
|
+
| host to frame | `theme`, `locale`, `props`, `route` | Updates after `init` |
|
|
272
|
+
| host to frame | `focus-in` | Move focus to the frame's first or last focusable element |
|
|
273
|
+
|
|
274
|
+
What differs from the in-realm `ctx.api`:
|
|
275
|
+
|
|
276
|
+
- `RequestInit` is narrowed to `signal` and `cache`. Headers and credentials are the
|
|
277
|
+
host's to set; any other option is refused with `invalid_request` rather than
|
|
278
|
+
silently dropped.
|
|
279
|
+
- A failed call rejects with `PluginApiError`, which has the same `status`, `code` and
|
|
280
|
+
`issues` as the host's own `ApiError` (`status` is `0` when there was no HTTP response),
|
|
281
|
+
so `formErrorsFrom` and existing `catch` blocks work unchanged. An aborted call has
|
|
282
|
+
`name === 'AbortError'`.
|
|
283
|
+
- There is no `localStorage`, cookie or network of its own in the frame. A widget frame
|
|
284
|
+
clips overlays, so a widget that needs a dialog should `navigate` to its page, whose
|
|
285
|
+
frame is full height. Protocol 1 has no host-rendered dialog.
|
|
286
|
+
|
|
287
|
+
The host must run `parsePluginMessage` on every message a frame sends and identify the
|
|
288
|
+
frame by the `MessagePort` and `event.source`, never by `event.origin` (which is
|
|
289
|
+
`"null"` for a sandboxed frame). Unknown message types are ignored by both sides, so
|
|
290
|
+
adding one is not a version bump.
|
|
291
|
+
|
|
171
292
|
## Two rules that fail at runtime, not build time
|
|
172
293
|
|
|
173
294
|
1. **The remote entry must be an ES module.** The host loads remotes with a
|
|
@@ -187,11 +308,143 @@ Money crosses the contract as a **decimal string**, never a JavaScript
|
|
|
187
308
|
This is not a style sandbox. Scope your selectors under a class your plugin
|
|
188
309
|
owns.
|
|
189
310
|
|
|
311
|
+
## Trust model
|
|
312
|
+
|
|
313
|
+
Where a plugin's UI runs decides what it can do.
|
|
314
|
+
|
|
315
|
+
| Plugin | UI runs in | What contains it |
|
|
316
|
+
| --- | --- | --- |
|
|
317
|
+
| Bundled, ported (Insights, Spending Trends) | A sandboxed frame | The sandbox and the host's broker (below) |
|
|
318
|
+
| Bundled, not ported yet (Budgets, Import CSV, Upcoming, Forecast, Debt payoff) | **The app's own page** | Nothing: fully trusted, in the host's origin, with the signed-in user's session. `requiredTables`, the `x-wickermoney-plugin` header and the checks in `ctx.api` are developer feedback there, not a boundary |
|
|
319
|
+
| Third-party (a manifest the operator added) | A sandboxed frame, **always** | The sandbox and the broker |
|
|
320
|
+
|
|
321
|
+
Which row a plugin is in is decided by the host, never by the manifest. In-page
|
|
322
|
+
mode is a host-internal list of bundled plugin ids. `isolated: true` can only
|
|
323
|
+
move a plugin towards the frame. A manifest cannot ask for the page, and a
|
|
324
|
+
plugin whose `remoteEntry` is not served by the host has no path into it.
|
|
325
|
+
|
|
326
|
+
### What the frame gives you, and what it takes away
|
|
327
|
+
|
|
328
|
+
In a frame your code has no cookies, `localStorage`, IndexedDB, host DOM, or
|
|
329
|
+
network of its own. It talks to the host over the
|
|
330
|
+
[isolated runtime](#isolated-runtime-experimental), and the host answers a
|
|
331
|
+
request only if it is a `GET` of a core route for a table your manifest lists in
|
|
332
|
+
`requiredTables`, or a call to your own `/p/<id>/` routes (a third-party plugin has none). The server then holds
|
|
333
|
+
the request to a token that carries only those grants. Nothing else is
|
|
334
|
+
reachable, including sign-in, the data export and other plugins.
|
|
335
|
+
|
|
336
|
+
### What a third-party plugin can do
|
|
337
|
+
|
|
338
|
+
- **Read the core aggregates it is granted.** Eight read-only `GET /api/v1/core/*`
|
|
339
|
+
routes, each needing the tables listed in the manifest.
|
|
340
|
+
- **Nothing server-side.** No endpoints, no exporters, no scheduled work and no
|
|
341
|
+
storage of its own (a server half is first-party only, because the per-plugin
|
|
342
|
+
database role is a guardrail and not a sandbox). A manifest that asks for
|
|
343
|
+
`contributes.endpoints` or `contributes.exporters` is refused, with a reason.
|
|
344
|
+
- **No write.** A `write` grant on a core table has no route it can use.
|
|
345
|
+
- **No permissions.** `network:outbound`, `schedule:daily` and `notify` are
|
|
346
|
+
reserved, not implemented, and a manifest that declares one is refused.
|
|
347
|
+
|
|
348
|
+
### Integrity pin
|
|
349
|
+
|
|
350
|
+
A plugin the image did not ship, and any plugin served from another origin,
|
|
351
|
+
must pin its build with the manifest's `integrity` field: Subresource Integrity
|
|
352
|
+
values keyed by path relative to the directory of `remoteEntry`.
|
|
353
|
+
|
|
354
|
+
```json
|
|
355
|
+
"remoteEntry": "https://plugins.example.com/cash-runway/remoteEntry.js",
|
|
356
|
+
"integrity": {
|
|
357
|
+
"remoteEntry.js": "sha384-...",
|
|
358
|
+
"assets/RunwayWidget-1a2b3c.js": "sha384-..."
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
The host has the browser check each listed file before the plugin runs
|
|
363
|
+
(`<link rel=modulepreload integrity=...>`), and a file whose bytes differ is not
|
|
364
|
+
loaded; the widget shows the reason. Limits, because a pin is easy to
|
|
365
|
+
over-trust:
|
|
366
|
+
|
|
367
|
+
- **List every file of the build.** Only listed files are verified. A file the
|
|
368
|
+
entry loads that you did not list loads unchecked. A pin that does not list the
|
|
369
|
+
entry file is refused.
|
|
370
|
+
- **Stylesheets are not covered.**
|
|
371
|
+
- **The hash is only as good as its source.** Take it from the build you
|
|
372
|
+
reviewed, not from the server that will serve it. A manifest fetched from the
|
|
373
|
+
same place as the code proves nothing.
|
|
374
|
+
- **It does not say the code is safe**, only that it is the code you pinned.
|
|
375
|
+
- **The remote origin must send CORS headers**
|
|
376
|
+
(`Access-Control-Allow-Origin`), because the frame fetches in CORS mode.
|
|
377
|
+
- Tested in Chromium 141 only.
|
|
378
|
+
|
|
379
|
+
Generate the values from the built files:
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
openssl dgst -sha384 -binary assets/RunwayWidget-1a2b3c.js | openssl base64 -A | sed 's/^/sha384-/'
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
```powershell
|
|
386
|
+
$hex = (Get-FileHash -Algorithm SHA384 'assets\RunwayWidget-1a2b3c.js').Hash
|
|
387
|
+
'sha384-' + [Convert]::ToBase64String([byte[]]($hex -split '(?<=\G..)(?=.)' | ForEach-Object { [Convert]::ToByte($_, 16) }))
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
### What this does not give you
|
|
391
|
+
|
|
392
|
+
- There is **no install flow, no catalog and no signing**. An operator copies the
|
|
393
|
+
manifest into the directory named by `PLUGIN_MANIFEST_DIR`, lists the origin in
|
|
394
|
+
`PLUGIN_REMOTE_ORIGINS`, restarts the API and switches the plugin on.
|
|
395
|
+
- The sandbox has **known gaps** in Chromium 141: `<link rel=prerender>` and
|
|
396
|
+
WebRTC reach an address the plugin chooses and can carry what it holds (the
|
|
397
|
+
user's email and id, and what its grants allow it to read). Other browsers
|
|
398
|
+
were not tested. Admission control (the operator choosing what to pin) is the
|
|
399
|
+
backstop, so only add a plugin you have read.
|
|
400
|
+
- The broker and token path have not had an independent security review.
|
|
401
|
+
- `requiredTables` is a **declaration** for your UI code, and what the grant
|
|
402
|
+
holds the broker and server to. Declare it honestly.
|
|
403
|
+
|
|
190
404
|
## Server-side code
|
|
191
405
|
|
|
192
406
|
Only bundled plugins may contribute server endpoints (`contributes.endpoints`).
|
|
193
407
|
The host has no sandbox for third-party server code yet. Third-party plugins are
|
|
194
|
-
UI-only and use core endpoints through `ctx.api`.
|
|
408
|
+
UI-only and use core endpoints through `ctx.api`. Bundled plugins are trusted
|
|
409
|
+
as much as the API itself; the one thing that is enforced for them is the
|
|
410
|
+
database: every query runs under the plugin's own PostgreSQL role.
|
|
411
|
+
|
|
412
|
+
`/server` is the contract between the host and a bundled plugin's `register`
|
|
413
|
+
function. It is dependency-free (no Zod) and has no runtime cost beyond two
|
|
414
|
+
small values.
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
import {
|
|
418
|
+
PluginRouteError, isUuid,
|
|
419
|
+
type RegisterRoute, type RunAsPlugin,
|
|
420
|
+
} from '@wickermoney/plugin-sdk/server'
|
|
421
|
+
|
|
422
|
+
export function registerRoutes(deps: { route: RegisterRoute; runAsPlugin: RunAsPlugin }): void {
|
|
423
|
+
deps.route('GET', '/things/:id', async ({ userId, params }) => {
|
|
424
|
+
if (!isUuid(params['id'])) throw new PluginRouteError('id must be a thing id.', 400, 'bad_id')
|
|
425
|
+
return deps.runAsPlugin(userId, (q) => q`SELECT id, name FROM things WHERE id = ${params['id']}`)
|
|
426
|
+
})
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
- **`PluginRouteError(message, statusCode, code, issues?)`** is how a handler
|
|
431
|
+
refuses a request the person can fix. The host answers with that status and
|
|
432
|
+
code and shows `message`, so it must be safe to display. `issues` is a list
|
|
433
|
+
of `{ path, message }` so a form can show each problem by its field. Any
|
|
434
|
+
other thrown error is a bug: it is logged and answered with a generic 500.
|
|
435
|
+
The host recognises an error by its `statusCode` and `code`, so a subclass
|
|
436
|
+
(to add defaults or helpers) works too.
|
|
437
|
+
- **`isUuid(value)`** is the one UUID rule. It accepts the canonical
|
|
438
|
+
hyphenated form in either case with a valid RFC 9562 version (1 to 8) and
|
|
439
|
+
variant, plus the nil and max UUIDs. It refuses braces, `urn:uuid:`, missing
|
|
440
|
+
hyphens and anything that is not a string. Every id PostgreSQL generates
|
|
441
|
+
passes. Check ids with it before they reach a `uuid` column, which would
|
|
442
|
+
otherwise fail as a 500.
|
|
443
|
+
- **`RouteContext`**, **`RegisterRoute`**, **`Query`** and **`RunAsPlugin`**
|
|
444
|
+
are the request input, the route registrar, the tagged-template query runner
|
|
445
|
+
and the transaction wrapper the host provides.
|
|
446
|
+
- **`RuleForMatching`**, **`ConditionForMatching`** and **`RuleSubject`**
|
|
447
|
+
describe the category rules the host loads and matches on a plugin's behalf.
|
|
195
448
|
|
|
196
449
|
## Related
|
|
197
450
|
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @module
|
|
3
|
-
* Calendar-date arithmetic on `YYYY-MM-DD` strings.
|
|
3
|
+
* Calendar-date arithmetic on `YYYY-MM-DD` strings. `addDays` and `addMonths` are
|
|
4
|
+
* public (exported from the `./date` entry point); the rest is internal to the SDK.
|
|
4
5
|
*
|
|
5
6
|
* Dates here are calendar days, not instants: there is no time of day and no
|
|
6
7
|
* time zone, so nothing can shift a day across midnight or a DST change. The
|
|
@@ -63,11 +64,38 @@ export declare function daysInMonth(year: number, month: number): number;
|
|
|
63
64
|
*
|
|
64
65
|
* @param year - Starting year.
|
|
65
66
|
* @param month - Starting month, 1-12.
|
|
66
|
-
* @param months - Whole months to add; may be zero.
|
|
67
|
+
* @param months - Whole months to add; may be zero or negative.
|
|
67
68
|
* @param day - The wanted day of month, 1-31.
|
|
68
69
|
* @returns The clamped date as `YYYY-MM-DD`.
|
|
69
70
|
*/
|
|
70
71
|
export declare function clampedMonthDate(year: number, month: number, months: number, day: number): string;
|
|
72
|
+
/**
|
|
73
|
+
* Adds whole days to a calendar date.
|
|
74
|
+
*
|
|
75
|
+
* Works on day numbers, never on local time, so no time zone or daylight
|
|
76
|
+
* saving change can move the result.
|
|
77
|
+
*
|
|
78
|
+
* @param date - `YYYY-MM-DD`.
|
|
79
|
+
* @param days - Whole days to add; may be zero or negative.
|
|
80
|
+
* @returns The resulting date, `YYYY-MM-DD`.
|
|
81
|
+
* @throws {RangeError} If `date` is not a real calendar date or `days` is not an integer.
|
|
82
|
+
*/
|
|
83
|
+
export declare function addDays(date: string, days: number): string;
|
|
84
|
+
/**
|
|
85
|
+
* Adds whole calendar months to a date. A day past the end of the target
|
|
86
|
+
* month is clamped to that month's last day: Aug 31 plus 6 months is Feb 28,
|
|
87
|
+
* or Feb 29 in a leap year.
|
|
88
|
+
*
|
|
89
|
+
* Each call clamps on its own. Adding months one at a time is not the same as
|
|
90
|
+
* adding them together (Jan 31 + 1 + 1 is Mar 28, Jan 31 + 2 is Mar 31), so
|
|
91
|
+
* add the total to the original date.
|
|
92
|
+
*
|
|
93
|
+
* @param date - `YYYY-MM-DD`.
|
|
94
|
+
* @param months - Whole months to add; may be zero or negative.
|
|
95
|
+
* @returns The resulting date, `YYYY-MM-DD`.
|
|
96
|
+
* @throws {RangeError} If `date` is not a real calendar date or `months` is not an integer.
|
|
97
|
+
*/
|
|
98
|
+
export declare function addMonths(date: string, months: number): string;
|
|
71
99
|
/**
|
|
72
100
|
* Whole months from one year/month to another (`to - from`), ignoring days.
|
|
73
101
|
*
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/date/calendar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAUrG;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,MAAM,CAGjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKjG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAI9D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1G"}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @module
|
|
3
|
-
* Calendar-date arithmetic on `YYYY-MM-DD` strings.
|
|
3
|
+
* Calendar-date arithmetic on `YYYY-MM-DD` strings. `addDays` and `addMonths` are
|
|
4
|
+
* public (exported from the `./date` entry point); the rest is internal to the SDK.
|
|
4
5
|
*
|
|
5
6
|
* Dates here are calendar days, not instants: there is no time of day and no
|
|
6
7
|
* time zone, so nothing can shift a day across midnight or a DST change. The
|
|
@@ -83,16 +84,54 @@ export function daysInMonth(year, month) {
|
|
|
83
84
|
*
|
|
84
85
|
* @param year - Starting year.
|
|
85
86
|
* @param month - Starting month, 1-12.
|
|
86
|
-
* @param months - Whole months to add; may be zero.
|
|
87
|
+
* @param months - Whole months to add; may be zero or negative.
|
|
87
88
|
* @param day - The wanted day of month, 1-31.
|
|
88
89
|
* @returns The clamped date as `YYYY-MM-DD`.
|
|
89
90
|
*/
|
|
90
91
|
export function clampedMonthDate(year, month, months, day) {
|
|
91
92
|
const absolute = year * 12 + (month - 1) + months;
|
|
92
93
|
const y = Math.floor(absolute / 12);
|
|
93
|
-
const m = (absolute % 12) + 1;
|
|
94
|
+
const m = (((absolute % 12) + 12) % 12) + 1;
|
|
94
95
|
return formatDate(y, m, Math.min(day, daysInMonth(y, m)));
|
|
95
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Adds whole days to a calendar date.
|
|
99
|
+
*
|
|
100
|
+
* Works on day numbers, never on local time, so no time zone or daylight
|
|
101
|
+
* saving change can move the result.
|
|
102
|
+
*
|
|
103
|
+
* @param date - `YYYY-MM-DD`.
|
|
104
|
+
* @param days - Whole days to add; may be zero or negative.
|
|
105
|
+
* @returns The resulting date, `YYYY-MM-DD`.
|
|
106
|
+
* @throws {RangeError} If `date` is not a real calendar date or `days` is not an integer.
|
|
107
|
+
*/
|
|
108
|
+
export function addDays(date, days) {
|
|
109
|
+
requireInteger(days, 'days');
|
|
110
|
+
return fromDayNumber(toDayNumber(date) + days);
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Adds whole calendar months to a date. A day past the end of the target
|
|
114
|
+
* month is clamped to that month's last day: Aug 31 plus 6 months is Feb 28,
|
|
115
|
+
* or Feb 29 in a leap year.
|
|
116
|
+
*
|
|
117
|
+
* Each call clamps on its own. Adding months one at a time is not the same as
|
|
118
|
+
* adding them together (Jan 31 + 1 + 1 is Mar 28, Jan 31 + 2 is Mar 31), so
|
|
119
|
+
* add the total to the original date.
|
|
120
|
+
*
|
|
121
|
+
* @param date - `YYYY-MM-DD`.
|
|
122
|
+
* @param months - Whole months to add; may be zero or negative.
|
|
123
|
+
* @returns The resulting date, `YYYY-MM-DD`.
|
|
124
|
+
* @throws {RangeError} If `date` is not a real calendar date or `months` is not an integer.
|
|
125
|
+
*/
|
|
126
|
+
export function addMonths(date, months) {
|
|
127
|
+
requireInteger(months, 'months');
|
|
128
|
+
const { year, month, day } = parseDate(date);
|
|
129
|
+
return clampedMonthDate(year, month, months, day);
|
|
130
|
+
}
|
|
131
|
+
function requireInteger(value, label) {
|
|
132
|
+
if (!Number.isInteger(value))
|
|
133
|
+
throw new RangeError(`Invalid ${label}: ${String(value)} (expected a whole number)`);
|
|
134
|
+
}
|
|
96
135
|
/**
|
|
97
136
|
* Whole months from one year/month to another (`to - from`), ignoring days.
|
|
98
137
|
*
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../../src/date/calendar.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module
|
|
3
|
+
* Calendar-date arithmetic on `YYYY-MM-DD` strings: `addDays` and `addMonths`.
|
|
4
|
+
*
|
|
5
|
+
* Dates here are calendar days, not instants: there is no time of day and no
|
|
6
|
+
* time zone, so nothing can shift a day across midnight or a DST change. Pure
|
|
7
|
+
* and dependency-free, so it is safe in the browser and in Node, and importing
|
|
8
|
+
* it pulls in nothing else from the SDK.
|
|
9
|
+
*
|
|
10
|
+
* Stability: `@stable`. The two helpers are small and their behaviour is
|
|
11
|
+
* settled (month-end clamping, `RangeError` for anything that is not a real
|
|
12
|
+
* calendar date or a whole number).
|
|
13
|
+
*
|
|
14
|
+
* @stable
|
|
15
|
+
*/
|
|
16
|
+
export { addDays, addMonths } from './calendar.js';
|
|
17
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module
|
|
3
|
+
* Calendar-date arithmetic on `YYYY-MM-DD` strings: `addDays` and `addMonths`.
|
|
4
|
+
*
|
|
5
|
+
* Dates here are calendar days, not instants: there is no time of day and no
|
|
6
|
+
* time zone, so nothing can shift a day across midnight or a DST change. Pure
|
|
7
|
+
* and dependency-free, so it is safe in the browser and in Node, and importing
|
|
8
|
+
* it pulls in nothing else from the SDK.
|
|
9
|
+
*
|
|
10
|
+
* Stability: `@stable`. The two helpers are small and their behaviour is
|
|
11
|
+
* settled (month-end clamping, `RangeError` for anything that is not a real
|
|
12
|
+
* calendar date or a whole number).
|
|
13
|
+
*
|
|
14
|
+
* @stable
|
|
15
|
+
*/
|
|
16
|
+
export { addDays, addMonths } from './calendar.js';
|
|
17
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
+
* @module
|
|
2
3
|
* Public surface of the plugin SDK: the contract both the host and every
|
|
3
4
|
* plugin implement.
|
|
4
5
|
*
|
|
@@ -6,15 +7,28 @@
|
|
|
6
7
|
* server; the runtime exports are React types for browser-side plugin code.
|
|
7
8
|
* The two groups are kept apart so a Node process can import the manifest
|
|
8
9
|
* exports without pulling in React.
|
|
10
|
+
*
|
|
11
|
+
* Stability: the manifest, runtime, range, date, money and server exports are
|
|
12
|
+
* `@stable`. The recurrence exports re-exported here are `@experimental`,
|
|
13
|
+
* exactly as they are from `@wickermoney/plugin-sdk/recurrence`: an export
|
|
14
|
+
* keeps the tier of the entry point it comes from, however it is imported.
|
|
15
|
+
*
|
|
16
|
+
* `@wickermoney/plugin-sdk/isolated` (`@experimental`) is deliberately not
|
|
17
|
+
* re-exported here; import it from its own entry point.
|
|
18
|
+
*
|
|
19
|
+
* @stable
|
|
9
20
|
*/
|
|
10
|
-
export { CORE_TABLES, checkRemoteEntry,
|
|
21
|
+
export { CORE_TABLES, checkRemoteEntry, checkRemoteEntryIntegrity, PERMISSIONS, REMOTE_ENTRY_TYPE, SDK_MAJOR_VERSION, WIDGET_SIZES, WIDGET_SLOTS, federationName, isCompatible, pagePath, parseIntegrity, parseManifest, } from './manifest/index.js';
|
|
11
22
|
export type { CoreTableName, ManifestParseResult, PageContribution, Permission, PluginManifest, TableGrant, WidgetContribution, WidgetSize, WidgetSlot, } from './manifest/index.js';
|
|
12
23
|
export { adoptPluginStyles } from './runtime.js';
|
|
13
24
|
export type { PluginApi, PluginContext, PluginModule, PluginPage, PluginPageProps, PluginSession, PluginWidget, PluginWidgetProps, } from './runtime.js';
|
|
14
25
|
export { RANGE_KEYS, DEFAULT_RANGE_KEY, isRangeKey, rangeLabel, resolveRange, monthsInRange, } from './range.js';
|
|
15
26
|
export type { DashboardRange, RangeKey } from './range.js';
|
|
27
|
+
export { addDays, addMonths } from './date/index.js';
|
|
16
28
|
export { DEFAULT_SEMIMONTHLY_DAYS, RECURRENCE_FREQUENCIES, dailyBalances, flowTotals, monthlyEquivalent, nextOccurrence, nextPayday, nextScheduledOccurrence, occurrences, scheduledOccurrences, } from './recurrence/index.js';
|
|
17
29
|
export type { DailyBalance, FlowTotals, OccurrenceOverride, RecurrenceFrequency, RecurrenceSchedule, RecurringItem, RecurringLeg, ScheduledOccurrence, } from './recurrence/index.js';
|
|
18
30
|
export { MONEY_SCALE, MONEY_UNIT, ZERO_MONEY, absMoney, addMoney, compareMoney, divideUnits, editableMoney, equalMoney, isNegativeMoney, isZeroMoney, moneyToUnits, negateMoney, normalizeMoney, subtractMoney, sumMoney, unitsToMoney, } from './money/index.js';
|
|
19
31
|
export type { Money } from './money/index.js';
|
|
32
|
+
export { PluginRouteError, isUuid } from './server/index.js';
|
|
33
|
+
export type { ConditionForMatching, PluginRouteIssue, Query, RegisterRoute, RouteContext, RouteMethod, RuleForMatching, RuleSubject, RunAsPlugin, } from './server/index.js';
|
|
20
34
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,UAAU,GACX,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EACV,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,GACnF,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EACL,wBAAwB,EAAE,sBAAsB,EAChD,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,uBAAuB,EACjG,WAAW,EAAE,oBAAoB,GAClC,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,aAAa,EACpG,YAAY,EAAE,mBAAmB,GAClC,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,WAAW,EAAE,UAAU,EAAE,UAAU,EACnC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EACzF,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAC9F,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC5D,YAAY,EACV,oBAAoB,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EACxG,WAAW,EAAE,WAAW,GACzB,MAAM,mBAAmB,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
+
* @module
|
|
2
3
|
* Public surface of the plugin SDK: the contract both the host and every
|
|
3
4
|
* plugin implement.
|
|
4
5
|
*
|
|
@@ -6,10 +7,22 @@
|
|
|
6
7
|
* server; the runtime exports are React types for browser-side plugin code.
|
|
7
8
|
* The two groups are kept apart so a Node process can import the manifest
|
|
8
9
|
* exports without pulling in React.
|
|
10
|
+
*
|
|
11
|
+
* Stability: the manifest, runtime, range, date, money and server exports are
|
|
12
|
+
* `@stable`. The recurrence exports re-exported here are `@experimental`,
|
|
13
|
+
* exactly as they are from `@wickermoney/plugin-sdk/recurrence`: an export
|
|
14
|
+
* keeps the tier of the entry point it comes from, however it is imported.
|
|
15
|
+
*
|
|
16
|
+
* `@wickermoney/plugin-sdk/isolated` (`@experimental`) is deliberately not
|
|
17
|
+
* re-exported here; import it from its own entry point.
|
|
18
|
+
*
|
|
19
|
+
* @stable
|
|
9
20
|
*/
|
|
10
|
-
export { CORE_TABLES, checkRemoteEntry,
|
|
21
|
+
export { CORE_TABLES, checkRemoteEntry, checkRemoteEntryIntegrity, PERMISSIONS, REMOTE_ENTRY_TYPE, SDK_MAJOR_VERSION, WIDGET_SIZES, WIDGET_SLOTS, federationName, isCompatible, pagePath, parseIntegrity, parseManifest, } from './manifest/index.js';
|
|
11
22
|
export { adoptPluginStyles } from './runtime.js';
|
|
12
23
|
export { RANGE_KEYS, DEFAULT_RANGE_KEY, isRangeKey, rangeLabel, resolveRange, monthsInRange, } from './range.js';
|
|
24
|
+
export { addDays, addMonths } from './date/index.js';
|
|
13
25
|
export { DEFAULT_SEMIMONTHLY_DAYS, RECURRENCE_FREQUENCIES, dailyBalances, flowTotals, monthlyEquivalent, nextOccurrence, nextPayday, nextScheduledOccurrence, occurrences, scheduledOccurrences, } from './recurrence/index.js';
|
|
14
26
|
export { MONEY_SCALE, MONEY_UNIT, ZERO_MONEY, absMoney, addMoney, compareMoney, divideUnits, editableMoney, equalMoney, isNegativeMoney, isZeroMoney, moneyToUnits, negateMoney, normalizeMoney, subtractMoney, sumMoney, unitsToMoney, } from './money/index.js';
|
|
27
|
+
export { PluginRouteError, isUuid } from './server/index.js';
|
|
15
28
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,qBAAqB,CAAA;AAa5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAYhD,OAAO,EACL,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,GACnF,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EACL,wBAAwB,EAAE,sBAAsB,EAChD,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,uBAAuB,EACjG,WAAW,EAAE,oBAAoB,GAClC,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EACL,WAAW,EAAE,UAAU,EAAE,UAAU,EACnC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EACzF,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAC9F,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { PluginApiIssue, PluginErrorPayload } from './protocol.js';
|
|
2
|
+
/**
|
|
3
|
+
* The error a failed `ctx.api` call rejects with inside an isolated frame.
|
|
4
|
+
*
|
|
5
|
+
* The fields match the host's own `ApiError` (`status`, `code`, `issues`), so a
|
|
6
|
+
* plugin's `catch` blocks and ui-kit's `formErrorsFrom` read it the same way in
|
|
7
|
+
* either runtime. `status` is `0` when the failure did not come from an HTTP
|
|
8
|
+
* response (a grant refusal, an abort, a lost connection). An aborted request
|
|
9
|
+
* has `name === 'AbortError'`, like a rejected `fetch`.
|
|
10
|
+
*/
|
|
11
|
+
export declare class PluginApiError extends Error {
|
|
12
|
+
/** The HTTP status of the API response, or `0` when there was none. */
|
|
13
|
+
readonly status: number;
|
|
14
|
+
/** A code to branch on; see `PLUGIN_ERROR_CODES` for the ones the host promises. */
|
|
15
|
+
readonly code: string;
|
|
16
|
+
/** Field-by-field problems; empty when there are none. */
|
|
17
|
+
readonly issues: readonly PluginApiIssue[];
|
|
18
|
+
constructor(payload: PluginErrorPayload);
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=PluginApiError.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"PluginApiError.d.ts","sourceRoot":"","sources":["../../src/isolated/PluginApiError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvE;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;gBAE9B,OAAO,EAAE,kBAAkB;CAOxC"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The error a failed `ctx.api` call rejects with inside an isolated frame.
|
|
3
|
+
*
|
|
4
|
+
* The fields match the host's own `ApiError` (`status`, `code`, `issues`), so a
|
|
5
|
+
* plugin's `catch` blocks and ui-kit's `formErrorsFrom` read it the same way in
|
|
6
|
+
* either runtime. `status` is `0` when the failure did not come from an HTTP
|
|
7
|
+
* response (a grant refusal, an abort, a lost connection). An aborted request
|
|
8
|
+
* has `name === 'AbortError'`, like a rejected `fetch`.
|
|
9
|
+
*/
|
|
10
|
+
export class PluginApiError extends Error {
|
|
11
|
+
/** The HTTP status of the API response, or `0` when there was none. */
|
|
12
|
+
status;
|
|
13
|
+
/** A code to branch on; see `PLUGIN_ERROR_CODES` for the ones the host promises. */
|
|
14
|
+
code;
|
|
15
|
+
/** Field-by-field problems; empty when there are none. */
|
|
16
|
+
issues;
|
|
17
|
+
constructor(payload) {
|
|
18
|
+
super(payload.message);
|
|
19
|
+
this.name = payload.code === 'aborted' ? 'AbortError' : 'PluginApiError';
|
|
20
|
+
this.status = payload.status ?? 0;
|
|
21
|
+
this.code = payload.code;
|
|
22
|
+
this.issues = payload.issues ?? [];
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
//# sourceMappingURL=PluginApiError.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"PluginApiError.js","sourceRoot":"","sources":["../../src/isolated/PluginApiError.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,uEAAuE;IAC9D,MAAM,CAAQ;IACvB,oFAAoF;IAC3E,IAAI,CAAQ;IACrB,0DAA0D;IACjD,MAAM,CAA2B;IAE1C,YAAY,OAA2B;QACrC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAA;QACxE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;QACxB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;IACpC,CAAC;CACF"}
|