@krak-stack/notifications-admin 0.1.0 → 0.2.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/CHANGELOG.md CHANGED
@@ -1,5 +1,30 @@
1
1
  # @krak-stack/notifications-admin
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 14f7065: Expose focused delivery overview, activity, detail and attempt-history modules,
8
+ plus standalone feedback, suppression and suppression-audit views. Retain existing
9
+ screens with optional host navigation, selectable operations views and typed table
10
+ customization with stable table identities.
11
+
12
+ Add an optional query lifecycle hook for polling, retained pagination totals and
13
+ failed-read clearing. Apply configured delivery scope consistently, isolate
14
+ operations caches by host/session, support host HttpClient layers, and accept
15
+ notifications 0.3.x/0.4.x and registry 0.2.x/0.10.x to avoid unnecessary nested peer
16
+ copies. Existing screen exports and legacy operations factory
17
+ calls remain supported.
18
+
19
+ - Updated dependencies [8d013ab]
20
+ - @krak-stack/notifications@0.4.1
21
+
22
+ ## 0.2.0
23
+
24
+ ### Minor Changes
25
+
26
+ - Add an optional NotificationPresentationProvider for host-owned table defaults and named inspection references. Delivery and operations screens retain their existing controlled data, actions, authorization boundaries and backwards-compatible default rendering.
27
+
3
28
  ## 0.1.0
4
29
 
5
30
  ### Minor Changes
package/README.md CHANGED
@@ -8,7 +8,7 @@ TanStack or registry dependency.
8
8
  ## Install
9
9
 
10
10
  ```sh
11
- bun add @krak-stack/notifications@0.3.0 @krak-stack/notifications-admin@0.1.0 @krak-stack/registry@0.2.2
11
+ bun add @krak-stack/notifications @krak-stack/notifications-admin @krak-stack/registry
12
12
  ```
13
13
 
14
14
  Install the React, Effect, Effect Atom, Effect browser platform, TanStack, Base UI and icon peer dependencies
@@ -26,6 +26,9 @@ KrakStack theme/base styles:
26
26
  The package does not reset application styles or install a theme. It shares the
27
27
  host's `KrakstackProvider` from `@krak-stack/registry/krakstack-provider` for locale
28
28
  and component defaults. Language switchers must display `English` and `Français`.
29
+ Supported backend lines are notifications `0.3.x` and `0.4.x`; supported registry
30
+ lines are `0.2.x` (from `0.2.2`) and `0.10.x` (from `0.10.3`). Use one shared
31
+ registry instance so tables, forms and the host see the same locale context.
29
32
 
30
33
  ## Imports
31
34
 
@@ -46,8 +49,193 @@ The root entry point exports the controlled views and their prop/message types.
46
49
  `/atoms` is separate so custom host data loading does not require using the bundled
47
50
  factories. The existing `Send*` names remain aliases for compatibility.
48
51
 
52
+ ## Compose sections instead of copying screens
53
+
54
+ The existing `NotificationDeliveries` and `NotificationOperations` screens remain
55
+ available with their original defaults. Focused sections can instead be placed in
56
+ host-owned layouts, navigation, dialogs, drawers or routes:
57
+
58
+ | Import | Focused interface |
59
+ | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
60
+ | `/deliveries`: `NotificationDeliveryOverview` | Messages, overview, loading/error; optional metric groups and `variant: "cards" \| "rows"` |
61
+ | `/deliveries`: `NotificationDeliveryActivity` | Messages, activity page, controlled table state/total, inspect and optional refresh callbacks |
62
+ | `/deliveries`: `NotificationDeliveryDetails` | Messages, inspection, loading/error and optional contact/campaign navigation; no dialog shell |
63
+ | `/deliveries`: `NotificationAttemptHistory` | Common messages and attempts; no screen callbacks |
64
+ | `/operations`: `NotificationFeedbackTable` | Messages, feedback items, table state and inspection callback |
65
+ | `/operations`: `NotificationSuppressions` | Messages, suppression items, table state and optional block/unblock callbacks |
66
+ | `/operations`: `NotificationSuppressionAudit` | Messages, audit items and table state; no mutation callbacks |
67
+
68
+ Each module exports its corresponding `*Props` and focused `*Messages` types.
69
+ Standalone modules require only their own labels, not every full-console
70
+ translation; existing complete message objects remain accepted. No module fetches records,
71
+ infers permissions, installs routes or resolves product identities.
72
+ `NotificationSuppressions` is read-only when mutation callbacks are omitted.
73
+ When provided, its existing confirmation form still requires an audit reason,
74
+ uses the reviewed row version and retains its idempotency key across retries.
75
+
76
+ ```tsx
77
+ import {
78
+ NotificationDeliveryOverview,
79
+ NotificationDeliveryActivity,
80
+ NotificationDeliveryDetails,
81
+ } from "@krak-stack/notifications-admin/deliveries";
82
+
83
+ // The host owns messages, state, queries, navigation and the dialog shell.
84
+ <main>
85
+ <NotificationDeliveryOverview
86
+ messages={messages}
87
+ overview={overview}
88
+ pending={pending}
89
+ error={error}
90
+ variant="rows"
91
+ groups={[
92
+ { metrics: ["total", "accepted", "failed"] },
93
+ {
94
+ label: messages.feedbackCovered,
95
+ metrics: ["feedbackCovered", "feedbackUnavailable", "confirmed"],
96
+ },
97
+ ]}
98
+ />
99
+ <NotificationDeliveryActivity
100
+ messages={messages}
101
+ activity={activity}
102
+ table={table}
103
+ total={total}
104
+ onTable={setTable}
105
+ onInspect={setSelected}
106
+ pending={pending}
107
+ error={error}
108
+ />
109
+ {/* Mount inside the host's accessible dialog/drawer when a row is selected. */}
110
+ {selected && (
111
+ <NotificationDeliveryDetails
112
+ messages={messages}
113
+ inspection={inspection}
114
+ error={inspectionError}
115
+ />
116
+ )}
117
+ </main>;
118
+ ```
119
+
120
+ Keep the activity module mounted behind inspection to preserve its local column
121
+ settings and controlled page/filter state. The full delivery screen already does
122
+ this. `messages.sections` optionally supplies localized summary/sending section
123
+ headings; existing message objects work unchanged. Dates and metric counts use the
124
+ host's shared registry locale.
125
+
126
+ For the default screens, set `navigation={false}` and/or `header={false}` when the
127
+ host owns those elements. `NotificationDeliveries` also accepts
128
+ `sourcePicker={false}`; its controlled `source` still selects the data.
129
+ `NotificationOperations` accepts, for example,
130
+ `views={["suppressions", "feedback", "audit"]}`. An excluded current view renders
131
+ no content; the host selects a valid initial view. These options are presentation,
132
+ **not authorization**. Protect every mounted backend capability independently.
133
+
134
+ ### Typed tables and stable identities
135
+
136
+ Standalone tables and the full delivery screen accept `tableOptions`:
137
+
138
+ ```tsx
139
+ <NotificationDeliveryActivity
140
+ {...activityProps}
141
+ tableOptions={{
142
+ initialState: { columnVisibility: { source: false, provider: false } },
143
+ columns: (defaults) =>
144
+ defaults
145
+ .filter((column) => column.field !== "eventKey")
146
+ .map((column) =>
147
+ column.field === "organizationId"
148
+ ? {
149
+ ...column,
150
+ sortable: false,
151
+ filterable: false,
152
+ searchable: false,
153
+ valueGetter: ({ data }) =>
154
+ organizationNames.get(data.organizationId ?? ""),
155
+ cellRenderer: ({ data }) =>
156
+ renderOrganization(data.organizationId),
157
+ }
158
+ : column,
159
+ ),
160
+ }}
161
+ />
162
+ ```
163
+
164
+ Return columns in the desired order, omit unwanted columns, or override typed
165
+ renderers/value getters. Keep IDs in records and callbacks. Use `valueGetter` for
166
+ display/export labels as well as `cellRenderer`; a renderer alone does not change
167
+ exported values. A display override does not add server-side sorting, searching or
168
+ filtering by resolved names: leave those capabilities disabled unless the backend
169
+ contract supports them. Hidden columns are not a security mechanism.
170
+
171
+ The presentation provider's `Table` additionally receives optional
172
+ `notificationTable` metadata. Stable values are `delivery-activity`,
173
+ `delivery-attempts`, `operations-activity`, `feedback`, `suppressions`,
174
+ `suppression-audit`, `campaign-recipients` and `operations-attempts`.
175
+ Hosts can select table defaults by identity rather than guessing from column
176
+ names. Existing `Table={DataTable}` adapters still work. Public table prop,
177
+ renderer, identity and customization types are exported from `/presentation`.
178
+
179
+ ### Optional query lifecycle hook
180
+
181
+ `useNotificationQuery` from `/hooks` works with the package atom resources or an
182
+ equivalent host resource:
183
+
184
+ ```tsx
185
+ const { data, total, pending, failed, refresh } = useNotificationQuery(
186
+ resource,
187
+ {
188
+ retentionKey: JSON.stringify([authorizationKey, scope, source, view]),
189
+ total: (data) => data.activity?.total,
190
+ refreshIntervalMillis: 15_000,
191
+ },
192
+ );
193
+ ```
194
+
195
+ The resource supplies `atom` and `refresh`. The hook retains the authoritative
196
+ total while another page/filter loads, preventing premature page clamping. It hides
197
+ `data` and resets the retained total on a failed read, even if the result contains
198
+ previous successful data. Changing `retentionKey` resets the retained count.
199
+ Include session/grant identity, scope, source and view in that key; page/search
200
+ changes normally share it. This key does not authorize reads or partition the
201
+ underlying query cache. Recreate factories and remount authorized content when
202
+ sessions/grants change. Use the hook's guarded `data`, not a retained value
203
+ extracted manually from its diagnostic `result`.
204
+
205
+ Polling is opt-in, stops when disabled/unmounted and refreshes only the subscribed
206
+ resource. The hook does not infer whether an error is safe to display stale data
207
+ for: all failures hide data. Pass a localized host error message to the controlled
208
+ view when `failed` is true.
209
+
210
+ ### Atom transport, scope and session identity
211
+
212
+ Delivery atoms accept `{ baseUrl, authorizationKey, scope?, httpClient? }`.
213
+ A configured exact `scope` now applies to overview, activity and inspection even
214
+ when omitted from a query key. Conflicting explicit scopes fail before dispatch;
215
+ use another factory for another configured scope. With no configured scope,
216
+ selection remains query-owned and subject to backend grants.
217
+
218
+ Operations atoms accept `{ baseUrl, authorizationKey, httpClient? }` as well as
219
+ the existing base-URL string. The object form makes session/grant identity explicit;
220
+ the string form generates a fresh non-secret cache identity per construction.
221
+ Keep either factory stable while mounted; do not construct it on every render.
222
+ The host/base URL and authorization key partition client and refresh identities.
223
+
224
+ `httpClient` is an optional fully provided Effect `HttpClient` layer for host
225
+ cookie/CSRF behavior. Defaults remain `FetchHttpClient.layer`. These factories do
226
+ not store credentials in query keys. Block/unblock mutations remain authoritative,
227
+ not optimistic restorations of deliverability.
228
+
49
229
  ## Host integration
50
230
 
231
+ Hosts can wrap delivery and operations views with `NotificationPresentationProvider`
232
+ from `@krak-stack/notifications-admin/presentation`. Supply `Table` (the registry
233
+ DataTable interface) to share application table defaults, columns and safe exports.
234
+ Optional `renderReference(kind, id)` resolves inspection references to host-owned
235
+ names or links. These hooks are useful to both product admin workspaces and
236
+ embedded sending consoles. They contain no product labels, record lookups,
237
+ authentication or policy. Default rendering remains backwards compatible.
238
+
51
239
  - Protect the page with the host's existing authentication and authorization.
52
240
  These components confer no permissions and create no routes.
53
241
  - Mount the Effect backend groups from `@krak-stack/notifications/admin/*` with
@@ -79,8 +267,8 @@ example, not a public route or a mandatory router integration.
79
267
  Notification administration screens and Atom helpers are available exclusively
80
268
  from this package, not registry exports or shadcn registry items. Registry supplies
81
269
  only the shared primitives used by these screens and does not depend on either
82
- notification SDK. Its published 0.2.2 release is supported; no new registry release
83
- is required. Already published packages and legacy notification engine exports
270
+ notification SDK. Existing supported registry releases work; no new registry
271
+ release is required. Already published packages and legacy notification engine exports
84
272
  remain unchanged.
85
273
 
86
274
  See the backend's [administration guide](https://github.com/krakcons/krakstack/blob/main/packages/notifications/ADMIN.md)
package/dist/atoms.d.ts CHANGED
@@ -2,6 +2,7 @@ export * from "./contact.atom.js";
2
2
  export * from "./campaign.atom.js";
3
3
  export * from "./operations.atom.js";
4
4
  export * from "./delivery.atom.js";
5
+ export type { NotificationAdminClientOptions } from "./client-options.js";
5
6
  import { makeSendContactAtoms } from "./contact.atom.js";
6
7
  import { makeSendCampaignAtoms } from "./campaign.atom.js";
7
8
  import { makeSendOperationsAtoms } from "./operations.atom.js";
package/dist/atoms.js CHANGED
@@ -147,11 +147,18 @@ var retain = (source, map) => ({
147
147
  atom: Atom3.map(Atom3.optimistic(source), (result) => AsyncResult3.map(result, map)),
148
148
  refresh: source
149
149
  });
150
- var makeSendOperationsAtoms = (baseUrl) => {
150
+ var makeSendOperationsAtoms = (input) => {
151
+ const options = Schema3.is(Schema3.String)(input) ? { baseUrl: input, authorizationKey: crypto.randomUUID() } : input;
152
+ const authorizationKey = Schema3.decodeSync(Schema3.NonEmptyString)(options.authorizationKey);
153
+ const identity = JSON.stringify([options.baseUrl, authorizationKey]);
151
154
 
152
- class Client extends AtomHttpApi3.Service()("example/SendOperationsClient", { api: SendOperationsApi, baseUrl, httpClient: FetchHttpClient3.layer }) {
155
+ class Client extends AtomHttpApi3.Service()(`host/NotificationOperations/${identity}`, {
156
+ api: SendOperationsApi,
157
+ baseUrl: options.baseUrl,
158
+ httpClient: options.httpClient ?? FetchHttpClient3.layer
159
+ }) {
153
160
  }
154
- const reactivityKeys = ["kraksend.operations"];
161
+ const reactivityKeys = [`notification.operations.${identity}`];
155
162
  const query = Atom3.family((key) => {
156
163
  const { view, filters: f, table } = Schema3.decodeSync(KeyCodec)(key);
157
164
  switch (view) {
@@ -237,7 +244,7 @@ var makeSendOperationsAtoms = (baseUrl) => {
237
244
  payload: input.payload,
238
245
  reactivityKeys: [...reactivityKeys, "kraksend.campaigns"]
239
246
  }));
240
- return { query, inspection, add, remove };
247
+ return { query, inspection, add, remove, authorizationKey };
241
248
  };
242
249
  // src/delivery.atom.ts
243
250
  import { Schema as Schema4 } from "effect";
@@ -262,20 +269,32 @@ var InspectionKey = Schema4.fromJsonString(Schema4.Struct({ id: Schema4.String,
262
269
  }));
263
270
  var deliveryInspectionKey = Schema4.encodeSync(InspectionKey);
264
271
  var makeNotificationDeliveryAtoms = (options) => {
272
+ const scope = options.scope === undefined ? undefined : Schema4.decodeSync(NotificationScope)(options.scope);
273
+ const authorizationKey = Schema4.decodeSync(Schema4.NonEmptyString)(options.authorizationKey);
274
+ const identity = JSON.stringify([
275
+ options.baseUrl,
276
+ authorizationKey,
277
+ scope ?? null
278
+ ]);
279
+ const selection = (key) => {
280
+ const selected = Schema4.decodeSync(Key.check(Schema4.makeFilter((selected) => scope === undefined || selected.scope === undefined || scope.recipientUserId === selected.scope.recipientUserId && scope.organizationId === selected.scope.organizationId && scope.workspaceId === selected.scope.workspaceId || "Query scope conflicts with the configured delivery scope")).annotate({ identifier: "ScopedStaffDeliveryQueryKey" }))(Schema4.decodeSync(Codec)(key));
281
+ return { source: selected.source, scope: scope ?? selected.scope };
282
+ };
265
283
 
266
- class Client extends AtomHttpApi4.Service()(`host/NotificationDeliveryAdmin/${options.authorizationKey}`, {
284
+ class Client extends AtomHttpApi4.Service()(`host/NotificationDeliveryAdmin/${identity}`, {
267
285
  api: DeliveryAdminApi,
268
286
  baseUrl: options.baseUrl,
269
- httpClient: FetchHttpClient4.layer
287
+ httpClient: options.httpClient ?? FetchHttpClient4.layer
270
288
  }) {
271
289
  }
272
- const reactivityKeys = [`notification.staff.${options.authorizationKey}`];
290
+ const reactivityKeys = [`notification.staff.${identity}`];
273
291
  const query = Atom4.family((key) => {
274
- const { table, view, ...selection } = Schema4.decodeSync(Codec)(key);
292
+ const { table, view } = Schema4.decodeSync(Codec)(key);
293
+ const selected = selection(key);
275
294
  const common = { reactivityKeys, timeToLive: "10 seconds" };
276
295
  if (view === "overview") {
277
296
  const atom = Client.query("notificationDeliveries", "overview", {
278
- query: selection,
297
+ query: selected,
279
298
  ...common
280
299
  });
281
300
  return {
@@ -284,7 +303,7 @@ var makeNotificationDeliveryAtoms = (options) => {
284
303
  };
285
304
  }
286
305
  const atom = Client.query("notificationDeliveries", "activityTable", {
287
- query: { ...selection, table },
306
+ query: { ...selected, table },
288
307
  ...common
289
308
  });
290
309
  return {
@@ -294,10 +313,10 @@ var makeNotificationDeliveryAtoms = (options) => {
294
313
  });
295
314
  const inspection = Atom4.family((key) => {
296
315
  const { id, queryKey } = Schema4.decodeSync(InspectionKey)(key);
297
- const selection = Schema4.decodeSync(Codec)(queryKey);
316
+ const selected = selection(queryKey);
298
317
  return Atom4.optimistic(Client.query("notificationDeliveries", "inspect", {
299
318
  params: { id },
300
- query: { source: selection.source, scope: selection.scope },
319
+ query: selected,
301
320
  reactivityKeys,
302
321
  timeToLive: "10 seconds"
303
322
  }));
@@ -305,8 +324,8 @@ var makeNotificationDeliveryAtoms = (options) => {
305
324
  return {
306
325
  query,
307
326
  inspection,
308
- authorizationKey: options.authorizationKey,
309
- scope: options.scope
327
+ authorizationKey,
328
+ scope
310
329
  };
311
330
  };
312
331
  // src/atoms.ts