@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.
Files changed (140) hide show
  1. package/README.md +265 -12
  2. package/dist/{recurrence → date}/calendar.d.ts +30 -2
  3. package/dist/date/calendar.d.ts.map +1 -0
  4. package/dist/{recurrence → date}/calendar.js +42 -3
  5. package/dist/date/calendar.js.map +1 -0
  6. package/dist/date/index.d.ts +17 -0
  7. package/dist/date/index.d.ts.map +1 -0
  8. package/dist/date/index.js +17 -0
  9. package/dist/date/index.js.map +1 -0
  10. package/dist/index.d.ts +15 -1
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +14 -1
  13. package/dist/index.js.map +1 -1
  14. package/dist/isolated/PluginApiError.d.ts +20 -0
  15. package/dist/isolated/PluginApiError.d.ts.map +1 -0
  16. package/dist/isolated/PluginApiError.js +25 -0
  17. package/dist/isolated/PluginApiError.js.map +1 -0
  18. package/dist/isolated/client.d.ts +118 -0
  19. package/dist/isolated/client.d.ts.map +1 -0
  20. package/dist/isolated/client.js +275 -0
  21. package/dist/isolated/client.js.map +1 -0
  22. package/dist/isolated/format.d.ts +25 -0
  23. package/dist/isolated/format.d.ts.map +1 -0
  24. package/dist/isolated/format.js +59 -0
  25. package/dist/isolated/format.js.map +1 -0
  26. package/dist/isolated/index.d.ts +48 -0
  27. package/dist/isolated/index.d.ts.map +1 -0
  28. package/dist/isolated/index.js +45 -0
  29. package/dist/isolated/index.js.map +1 -0
  30. package/dist/isolated/protocol.d.ts +217 -0
  31. package/dist/isolated/protocol.d.ts.map +1 -0
  32. package/dist/isolated/protocol.js +31 -0
  33. package/dist/isolated/protocol.js.map +1 -0
  34. package/dist/isolated/theme.d.ts +24 -0
  35. package/dist/isolated/theme.d.ts.map +1 -0
  36. package/dist/isolated/theme.js +32 -0
  37. package/dist/isolated/theme.js.map +1 -0
  38. package/dist/isolated/validate.d.ts +47 -0
  39. package/dist/isolated/validate.d.ts.map +1 -0
  40. package/dist/isolated/validate.js +260 -0
  41. package/dist/isolated/validate.js.map +1 -0
  42. package/dist/manifest/PERMISSIONS.d.ts +5 -0
  43. package/dist/manifest/PERMISSIONS.d.ts.map +1 -1
  44. package/dist/manifest/PERMISSIONS.js +5 -0
  45. package/dist/manifest/PERMISSIONS.js.map +1 -1
  46. package/dist/manifest/checkRemoteEntry.d.ts +2 -1
  47. package/dist/manifest/checkRemoteEntry.d.ts.map +1 -1
  48. package/dist/manifest/checkRemoteEntry.js +2 -1
  49. package/dist/manifest/checkRemoteEntry.js.map +1 -1
  50. package/dist/manifest/checkRemoteEntryIntegrity.d.ts +27 -0
  51. package/dist/manifest/checkRemoteEntryIntegrity.d.ts.map +1 -0
  52. package/dist/manifest/checkRemoteEntryIntegrity.js +47 -0
  53. package/dist/manifest/checkRemoteEntryIntegrity.js.map +1 -0
  54. package/dist/manifest/index.d.ts +2 -5
  55. package/dist/manifest/index.d.ts.map +1 -1
  56. package/dist/manifest/index.js +2 -5
  57. package/dist/manifest/index.js.map +1 -1
  58. package/dist/manifest/integritySchema.d.ts +28 -0
  59. package/dist/manifest/integritySchema.d.ts.map +1 -0
  60. package/dist/manifest/integritySchema.js +30 -0
  61. package/dist/manifest/integritySchema.js.map +1 -0
  62. package/dist/manifest/parseIntegrity.d.ts +14 -0
  63. package/dist/manifest/parseIntegrity.d.ts.map +1 -0
  64. package/dist/manifest/parseIntegrity.js +16 -0
  65. package/dist/manifest/parseIntegrity.js.map +1 -0
  66. package/dist/manifest/pluginManifestSchema.d.ts +2 -0
  67. package/dist/manifest/pluginManifestSchema.d.ts.map +1 -1
  68. package/dist/manifest/pluginManifestSchema.js +48 -1
  69. package/dist/manifest/pluginManifestSchema.js.map +1 -1
  70. package/dist/manifest/tableGrantSchema.d.ts +6 -1
  71. package/dist/manifest/tableGrantSchema.d.ts.map +1 -1
  72. package/dist/manifest/tableGrantSchema.js +6 -1
  73. package/dist/manifest/tableGrantSchema.js.map +1 -1
  74. package/dist/money/index.d.ts +4 -0
  75. package/dist/money/index.d.ts.map +1 -1
  76. package/dist/money/index.js.map +1 -1
  77. package/dist/recurrence/index.d.ts +8 -0
  78. package/dist/recurrence/index.d.ts.map +1 -1
  79. package/dist/recurrence/index.js +10 -0
  80. package/dist/recurrence/index.js.map +1 -1
  81. package/dist/recurrence/projection.js +1 -1
  82. package/dist/recurrence/projection.js.map +1 -1
  83. package/dist/recurrence/schedule.js +1 -1
  84. package/dist/recurrence/schedule.js.map +1 -1
  85. package/dist/recurrence/scheduled.js +1 -1
  86. package/dist/recurrence/scheduled.js.map +1 -1
  87. package/dist/runtime.d.ts +26 -3
  88. package/dist/runtime.d.ts.map +1 -1
  89. package/dist/runtime.js.map +1 -1
  90. package/dist/server/ConditionForMatching.d.ts +18 -0
  91. package/dist/server/ConditionForMatching.d.ts.map +1 -0
  92. package/dist/server/ConditionForMatching.js +2 -0
  93. package/dist/server/ConditionForMatching.js.map +1 -0
  94. package/dist/server/PluginRouteError.d.ts +27 -0
  95. package/dist/server/PluginRouteError.d.ts.map +1 -0
  96. package/dist/server/PluginRouteError.js +32 -0
  97. package/dist/server/PluginRouteError.js.map +1 -0
  98. package/dist/server/PluginRouteIssue.d.ts +8 -0
  99. package/dist/server/PluginRouteIssue.d.ts.map +1 -0
  100. package/dist/server/PluginRouteIssue.js +2 -0
  101. package/dist/server/PluginRouteIssue.js.map +1 -0
  102. package/dist/server/Query.d.ts +11 -0
  103. package/dist/server/Query.d.ts.map +1 -0
  104. package/dist/server/Query.js +2 -0
  105. package/dist/server/Query.js.map +1 -0
  106. package/dist/server/RegisterRoute.d.ts +24 -0
  107. package/dist/server/RegisterRoute.d.ts.map +1 -0
  108. package/dist/server/RegisterRoute.js +2 -0
  109. package/dist/server/RegisterRoute.js.map +1 -0
  110. package/dist/server/RouteContext.d.ts +12 -0
  111. package/dist/server/RouteContext.d.ts.map +1 -0
  112. package/dist/server/RouteContext.js +2 -0
  113. package/dist/server/RouteContext.js.map +1 -0
  114. package/dist/server/RouteMethod.d.ts +3 -0
  115. package/dist/server/RouteMethod.d.ts.map +1 -0
  116. package/dist/server/RouteMethod.js +2 -0
  117. package/dist/server/RouteMethod.js.map +1 -0
  118. package/dist/server/RuleForMatching.d.ts +16 -0
  119. package/dist/server/RuleForMatching.d.ts.map +1 -0
  120. package/dist/server/RuleForMatching.js +2 -0
  121. package/dist/server/RuleForMatching.js.map +1 -0
  122. package/dist/server/RuleSubject.d.ts +10 -0
  123. package/dist/server/RuleSubject.d.ts.map +1 -0
  124. package/dist/server/RuleSubject.js +2 -0
  125. package/dist/server/RuleSubject.js.map +1 -0
  126. package/dist/server/RunAsPlugin.d.ts +9 -0
  127. package/dist/server/RunAsPlugin.d.ts.map +1 -0
  128. package/dist/server/RunAsPlugin.js +2 -0
  129. package/dist/server/RunAsPlugin.js.map +1 -0
  130. package/dist/server/index.d.ts +30 -0
  131. package/dist/server/index.d.ts.map +1 -0
  132. package/dist/server/index.js +3 -0
  133. package/dist/server/index.js.map +1 -0
  134. package/dist/server/isUuid.d.ts +18 -0
  135. package/dist/server/isUuid.d.ts.map +1 -0
  136. package/dist/server/isUuid.js +26 -0
  137. package/dist/server/isUuid.js.map +1 -0
  138. package/package.json +13 -1
  139. package/dist/recurrence/calendar.d.ts.map +0 -1
  140. 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/recurrence` | Anything (browser or Node) | Recurring-item date maths and projections: `occurrences`, `nextOccurrence`, `scheduledOccurrences`, `nextScheduledOccurrence`, `nextPayday`, `monthlyEquivalent`, `dailyBalances`, `flowTotals`, with per-occurrence overrides (skip, move, change the legs) |
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` | Hosts, tooling, tests (Node) | Everything above, plus the Zod manifest schemas, `parseManifest`, dashboard-range helpers and constants |
34
-
35
- Import from `/runtime` (and `/money` or `/recurrence` if you need them) in plugin UI code.
36
- The package root re-exports the Zod manifest schemas, which add about 85 kB to
37
- a plugin bundle that never uses them.
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, not only by the app. Each plugin
151
- runs under its own database role, which is granted exactly the tables its
152
- manifest lists. A query against any other table is refused.
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
- // the host attaches credentials, so the plugin never sees a token.
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. Internal to the SDK.
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. Internal to the SDK.
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":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,QAAQ,GAAG,2BAA2B,CAAA;AAC5C,MAAM,UAAU,GAAG,UAAU,CAAA;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAK,GAAG,MAAM;IACrD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,UAAU,CAAC,WAAW,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAA;IACpG,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5B,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,UAAU,CAAC,WAAW,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC3F,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,KAAK,GAAG,MAAM;IACvD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,UAAU,CAAA;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,CAAA;IAC1C,OAAO,UAAU,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAA;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IACjE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;AAC7G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAA;AACxD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,KAAa,EAAE,MAAc,EAAE,GAAW;IACvF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,MAAM,CAAA;IACjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAA;IACnC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;IAC3C,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAY;IAChD,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC5B,OAAO,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AAChD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAAc;IACpD,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAChC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC5C,OAAO,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;AACnD,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,WAAW,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAA;AACpH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,SAAiB,EAAE,MAAc,EAAE,OAAe;IAChG,OAAO,CAAC,MAAM,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,SAAS,CAAC,CAAA;AAC9D,CAAC"}
@@ -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, remoteEntrySchema, PERMISSIONS, REMOTE_ENTRY_TYPE, SDK_MAJOR_VERSION, WIDGET_SIZES, WIDGET_SLOTS, federationName, isCompatible, pagePath, parseManifest, pageContributionSchema, pluginManifestSchema, tableGrantSchema, widgetContributionSchema, } from './manifest/index.js';
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,GACzB,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,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"}
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, remoteEntrySchema, PERMISSIONS, REMOTE_ENTRY_TYPE, SDK_MAJOR_VERSION, WIDGET_SIZES, WIDGET_SLOTS, federationName, isCompatible, pagePath, parseManifest, pageContributionSchema, pluginManifestSchema, tableGrantSchema, widgetContributionSchema, } from './manifest/index.js';
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;;;;;;;;GAQG;AACH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,GACzB,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,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"}
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"}