@krak-stack/notifications-admin 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,9 @@
1
+ # @krak-stack/notifications-admin
2
+
3
+ ## 0.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Provide optional React notification contact, campaign, operations and scoped-delivery administration screens, built from shared KrakStack table/form primitives.
8
+ - Provide Effect Atom query and mutation factories, including authorization-key-partitioned staff queries, without prescribing application routing or authorization.
9
+ - Keep the Effect backend in `@krak-stack/notifications`. This package exclusively owns notification administration screens and Atom helpers, reusing shared primitives from the published registry 0.2.2 release without adding registry notification-admin exports or dependencies.
package/README.md CHANGED
@@ -1,3 +1,87 @@
1
- # Temporary Holding Version
1
+ # @krak-stack/notifications-admin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Optional React administration screens and Effect Atom helpers for
4
+ `@krak-stack/notifications`. TanStack Start hosts can mount them in protected web
5
+ routes. The backend remains an independent Effect package: it has no React,
6
+ TanStack or registry dependency.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ bun add @krak-stack/notifications@0.3.0 @krak-stack/notifications-admin@0.1.0 @krak-stack/registry@0.2.2
12
+ ```
13
+
14
+ Install the React, Effect, Effect Atom, Effect browser platform, TanStack, Base UI and icon peer dependencies
15
+ listed in `package.json`. The UI reuses registry's shared DataTable and form
16
+ primitives; registry is not another notification engine. It is not required by
17
+ backend-only consumers of `@krak-stack/notifications`.
18
+
19
+ Import the Tailwind source from the host stylesheet, alongside its existing
20
+ KrakStack theme/base styles:
21
+
22
+ ```css
23
+ @import "@krak-stack/notifications-admin/tailwind.css";
24
+ ```
25
+
26
+ The package does not reset application styles or install a theme. It shares the
27
+ host's `KrakstackProvider` from `@krak-stack/registry/krakstack-provider` for locale
28
+ and component defaults. Language switchers must display `English` and `Français`.
29
+
30
+ ## Imports
31
+
32
+ ```tsx
33
+ import { NotificationContacts } from "@krak-stack/notifications-admin/contacts";
34
+ import { NotificationCampaigns } from "@krak-stack/notifications-admin/campaigns";
35
+ import { NotificationOperations } from "@krak-stack/notifications-admin/operations";
36
+ import { NotificationDeliveries } from "@krak-stack/notifications-admin/deliveries";
37
+ import {
38
+ makeNotificationContactAtoms,
39
+ makeNotificationCampaignAtoms,
40
+ makeNotificationOperationsAtoms,
41
+ makeNotificationDeliveryAtoms,
42
+ } from "@krak-stack/notifications-admin/atoms";
43
+ ```
44
+
45
+ The root entry point exports the controlled views and their prop/message types.
46
+ `/atoms` is separate so custom host data loading does not require using the bundled
47
+ factories. The existing `Send*` names remain aliases for compatibility.
48
+
49
+ ## Host integration
50
+
51
+ - Protect the page with the host's existing authentication and authorization.
52
+ These components confer no permissions and create no routes.
53
+ - Mount the Effect backend groups from `@krak-stack/notifications/admin/*` with
54
+ their mandatory host middleware. Hiding a tab is not API authorization.
55
+ - Supply data, mutation callbacks, messages and controlled table state to the
56
+ views. Shared server-backed tables apply search, filtering, sorting and pagination
57
+ to the full authorized dataset, not just loaded rows.
58
+ - Supply English and French messages using the host's Paraglide integration. The
59
+ package does not embed the KrakStack site's generated translations.
60
+ - Use the Effect Atom factories for the existing protected API contracts, or
61
+ supply host-owned atoms/HttpClient layers when authentication or CSRF transport
62
+ requires customization. Default factories use FetchHttpClient and same-origin
63
+ browser credentials; they do not store provider credentials or auth tokens.
64
+ - For staff delivery reads, provide a non-secret `authorizationKey`. Recreate
65
+ factories when the session or grants change; unmount on sign-out. This key
66
+ partitions caches and is not authorization evidence. The host must clear/hide
67
+ retained data on authorization failures and prevent shared HTTP caching.
68
+ - Dangerous mutations remain authoritative. Removing a suppression does not
69
+ subscribe, republish or resend; an audit reason and reviewed row version remain
70
+ required by the backend.
71
+
72
+ The bilingual [host console example](https://github.com/krakcons/krakstack/blob/main/src/agent-examples/send/console.tsx)
73
+ shows complete composition with Effect Atom, query retention, explicit mutation
74
+ invalidation, inspection dialogs and authorization-revocation clearing. It is an
75
+ example, not a public route or a mandatory router integration.
76
+
77
+ ## Package boundary
78
+
79
+ Notification administration screens and Atom helpers are available exclusively
80
+ from this package, not registry exports or shadcn registry items. Registry supplies
81
+ 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
84
+ remain unchanged.
85
+
86
+ See the backend's [administration guide](https://github.com/krakcons/krakstack/blob/main/packages/notifications/ADMIN.md)
87
+ for grants, feedback coverage, consent and suppression semantics.
@@ -0,0 +1,10 @@
1
+ export * from "./contact.atom.js";
2
+ export * from "./campaign.atom.js";
3
+ export * from "./operations.atom.js";
4
+ export * from "./delivery.atom.js";
5
+ import { makeSendContactAtoms } from "./contact.atom.js";
6
+ import { makeSendCampaignAtoms } from "./campaign.atom.js";
7
+ import { makeSendOperationsAtoms } from "./operations.atom.js";
8
+ export declare const makeNotificationContactAtoms: typeof makeSendContactAtoms;
9
+ export declare const makeNotificationCampaignAtoms: typeof makeSendCampaignAtoms;
10
+ export declare const makeNotificationOperationsAtoms: typeof makeSendOperationsAtoms;
package/dist/atoms.js ADDED
@@ -0,0 +1,328 @@
1
+ // src/contact.atom.ts
2
+ import { Atom, AtomHttpApi, AsyncResult } from "effect/reactivity";
3
+ import { Schema } from "effect";
4
+ import { FetchHttpClient } from "effect/http";
5
+ import { SendAdminApi } from "@krak-stack/notifications/admin/api";
6
+ import {
7
+ TableState,
8
+ initialTableState
9
+ } from "@krak-stack/notifications/admin/table.schema";
10
+ import {
11
+ SendId
12
+ } from "@krak-stack/notifications/admin/schema";
13
+ var TableCodec = Schema.fromJsonString(TableState);
14
+ var makeSendContactAtoms = (baseUrl) => {
15
+
16
+ class SendClient extends AtomHttpApi.Service()("example/SendClient", {
17
+ api: SendAdminApi,
18
+ baseUrl,
19
+ httpClient: FetchHttpClient.layer
20
+ }) {
21
+ }
22
+ const contacts = Atom.family((after) => Atom.optimistic(Atom.map(SendClient.query("send", "contactsTable", {
23
+ query: {
24
+ table: after ? Schema.decodeSync(TableCodec)(after) : initialTableState
25
+ },
26
+ timeToLive: "30 seconds",
27
+ reactivityKeys: ["kraksend.contacts"]
28
+ }), (result) => AsyncResult.map(result, (page) => ({ ...page, nextCursor: null })))));
29
+ const createMutation = SendClient.mutation("send", "createContact");
30
+ const create = Atom.fn((payload, get) => get.setResult(createMutation, {
31
+ payload,
32
+ reactivityKeys: ["kraksend.contacts"]
33
+ }));
34
+ const consentMutation = SendClient.mutation("send", "recordEmailConsent");
35
+ const withdraw = Atom.family((after) => Atom.optimisticFn(contacts(after), {
36
+ reducer: (state, input) => AsyncResult.map(state, (page) => ({
37
+ ...page,
38
+ items: page.items.map((contact) => contact.id === input.contactId ? { ...contact, emailConsent: "unsubscribed" } : contact)
39
+ })),
40
+ fn: Atom.fn((input, get) => get.setResult(consentMutation, {
41
+ params: { id: input.contactId },
42
+ payload: {
43
+ requestId: input.requestId,
44
+ status: "unsubscribed",
45
+ noticeVersion: "admin-withdrawal-v1"
46
+ },
47
+ reactivityKeys: ["kraksend.contacts"]
48
+ }))
49
+ }));
50
+ const contact = Atom.family((id) => Atom.optimistic(SendClient.query("send", "getContact", {
51
+ params: { id },
52
+ reactivityKeys: ["kraksend.contacts"],
53
+ timeToLive: "10 seconds"
54
+ })));
55
+ const HistoryKey = Schema.fromJsonString(Schema.Struct({ id: SendId, table: TableState }).annotate({
56
+ identifier: "SendContactHistoryKey"
57
+ }));
58
+ const historyQuery = Atom.family((key) => {
59
+ const { id, table } = Schema.decodeSync(HistoryKey)(key);
60
+ return Atom.optimistic(Atom.map(SendClient.query("send", "consentTable", {
61
+ params: { id },
62
+ query: { table },
63
+ reactivityKeys: ["kraksend.contacts"],
64
+ timeToLive: "10 seconds"
65
+ }), (result) => AsyncResult.map(result, (page) => ({ ...page, nextCursor: null }))));
66
+ });
67
+ const history = (id, table = initialTableState) => historyQuery(Schema.encodeSync(HistoryKey)({ id, table }));
68
+ return { contacts, contact, history, create, withdraw };
69
+ };
70
+ // src/campaign.atom.ts
71
+ import { Atom as Atom2, AtomHttpApi as AtomHttpApi2, AsyncResult as AsyncResult2 } from "effect/reactivity";
72
+ import { FetchHttpClient as FetchHttpClient2 } from "effect/http";
73
+ import { SendCampaignApi } from "@krak-stack/notifications/admin/campaign.api";
74
+ import { Schema as Schema2 } from "effect";
75
+ import {
76
+ TableState as TableState2,
77
+ initialTableState as initialTableState2
78
+ } from "@krak-stack/notifications/admin/table.schema";
79
+ var makeSendCampaignAtoms = (baseUrl) => {
80
+
81
+ class Client extends AtomHttpApi2.Service()("example/SendCampaignClient", {
82
+ api: SendCampaignApi,
83
+ baseUrl,
84
+ httpClient: FetchHttpClient2.layer
85
+ }) {
86
+ }
87
+ const key = "kraksend.campaigns";
88
+ const campaigns = Atom2.family((after) => Atom2.optimistic(Atom2.map(Client.query("sendCampaigns", "table", {
89
+ query: {
90
+ table: after ? Schema2.decodeSync(Schema2.fromJsonString(TableState2))(after) : initialTableState2
91
+ },
92
+ timeToLive: "10 seconds",
93
+ reactivityKeys: [key]
94
+ }), (result) => AsyncResult2.map(result, (page) => ({ ...page, nextCursor: null })))));
95
+ const campaign = Atom2.family((id) => Atom2.optimistic(Client.query("sendCampaigns", "get", {
96
+ params: { id },
97
+ timeToLive: "10 seconds",
98
+ reactivityKeys: [key]
99
+ })));
100
+ const report = Atom2.family((id) => Atom2.optimistic(Client.query("sendCampaigns", "report", {
101
+ params: { id },
102
+ timeToLive: "10 seconds",
103
+ reactivityKeys: [key]
104
+ })));
105
+ const createMutation = Client.mutation("sendCampaigns", "create");
106
+ const scheduleMutation = Client.mutation("sendCampaigns", "schedule");
107
+ const transitionMutation = Client.mutation("sendCampaigns", "transition");
108
+ const create = Atom2.fn((payload, get) => get.setResult(createMutation, { payload, reactivityKeys: [key] }));
109
+ const schedule = Atom2.fn((input, get) => get.setResult(scheduleMutation, {
110
+ params: { id: input.id },
111
+ payload: { scheduledFor: input.scheduledFor },
112
+ reactivityKeys: [key]
113
+ }));
114
+ const cancel = Atom2.fn((id, get) => get.setResult(transitionMutation, {
115
+ params: { id },
116
+ payload: { action: "cancel" },
117
+ reactivityKeys: [key]
118
+ }));
119
+ const transition = Atom2.family((id) => Atom2.optimisticFn(campaign(id), {
120
+ reducer: (state, action) => AsyncResult2.map(state, (value) => ({
121
+ ...value,
122
+ status: action === "pause" ? "paused" : "scheduled"
123
+ })),
124
+ fn: Atom2.fn((action, get) => get.setResult(transitionMutation, {
125
+ params: { id },
126
+ payload: { action },
127
+ reactivityKeys: [key]
128
+ }))
129
+ }));
130
+ return { campaigns, campaign, report, create, schedule, cancel, transition };
131
+ };
132
+ // src/operations.atom.ts
133
+ import { Schema as Schema3 } from "effect";
134
+ import { Atom as Atom3, AtomHttpApi as AtomHttpApi3, AsyncResult as AsyncResult3 } from "effect/reactivity";
135
+ import { FetchHttpClient as FetchHttpClient3 } from "effect/http";
136
+ import { SendOperationsApi } from "@krak-stack/notifications/admin/operations.api";
137
+ import * as S from "@krak-stack/notifications/admin/operations.schema";
138
+ import { TableState as TableState3 } from "@krak-stack/notifications/admin/table.schema";
139
+ var OperationsQueryKey = Schema3.Struct({
140
+ view: S.OperationsView,
141
+ filters: S.OperationsFilters,
142
+ table: TableState3
143
+ }).annotate({ identifier: "SendOperationsQueryKey" });
144
+ var KeyCodec = Schema3.fromJsonString(OperationsQueryKey);
145
+ var operationsQueryKey = Schema3.encodeSync(KeyCodec);
146
+ var retain = (source, map) => ({
147
+ atom: Atom3.map(Atom3.optimistic(source), (result) => AsyncResult3.map(result, map)),
148
+ refresh: source
149
+ });
150
+ var makeSendOperationsAtoms = (baseUrl) => {
151
+
152
+ class Client extends AtomHttpApi3.Service()("example/SendOperationsClient", { api: SendOperationsApi, baseUrl, httpClient: FetchHttpClient3.layer }) {
153
+ }
154
+ const reactivityKeys = ["kraksend.operations"];
155
+ const query = Atom3.family((key) => {
156
+ const { view, filters: f, table } = Schema3.decodeSync(KeyCodec)(key);
157
+ switch (view) {
158
+ case "overview":
159
+ return retain(Client.query("sendOperations", "overview", {
160
+ query: { since: f.since, until: f.until },
161
+ reactivityKeys,
162
+ timeToLive: "10 seconds"
163
+ }), (overview) => ({ overview }));
164
+ case "activity":
165
+ return retain(Client.query("sendOperations", "activityTable", {
166
+ query: {
167
+ table,
168
+ campaignId: f.campaignId,
169
+ contactId: f.contactId
170
+ },
171
+ reactivityKeys,
172
+ timeToLive: "10 seconds"
173
+ }), (page) => ({
174
+ total: page.total,
175
+ activity: { ...page, nextCursor: null }
176
+ }));
177
+ case "feedback":
178
+ return retain(Client.query("sendOperations", "feedbackTable", {
179
+ query: {
180
+ table,
181
+ deliveryId: f.deliveryId
182
+ },
183
+ reactivityKeys,
184
+ timeToLive: "10 seconds"
185
+ }), (page) => ({
186
+ total: page.total,
187
+ feedback: { ...page, nextCursor: null }
188
+ }));
189
+ case "suppressions":
190
+ return retain(Client.query("sendOperations", "suppressionsTable", {
191
+ query: { table },
192
+ reactivityKeys,
193
+ timeToLive: "10 seconds"
194
+ }), (page) => ({
195
+ total: page.total,
196
+ suppressions: { ...page, nextCursor: null }
197
+ }));
198
+ case "audit":
199
+ return retain(Client.query("sendOperations", "auditTable", {
200
+ query: { table },
201
+ reactivityKeys,
202
+ timeToLive: "10 seconds"
203
+ }), (page) => ({
204
+ total: page.total,
205
+ audit: { ...page, nextCursor: null }
206
+ }));
207
+ case "recipients":
208
+ return f.campaignId ? retain(Client.query("sendOperations", "recipientsTable", {
209
+ query: {
210
+ table,
211
+ campaignId: f.campaignId
212
+ },
213
+ reactivityKeys,
214
+ timeToLive: "10 seconds"
215
+ }), (page) => ({
216
+ total: page.total,
217
+ recipients: { ...page, nextCursor: null }
218
+ })) : {
219
+ atom: Atom3.make(AsyncResult3.success({})),
220
+ refresh: Atom3.make(undefined)
221
+ };
222
+ }
223
+ });
224
+ const inspection = Atom3.family((id) => Atom3.optimistic(Client.query("sendOperations", "inspect", {
225
+ params: { id },
226
+ reactivityKeys,
227
+ timeToLive: "10 seconds"
228
+ })));
229
+ const addMutation = Client.mutation("sendOperations", "addSuppression");
230
+ const removeMutation = Client.mutation("sendOperations", "removeSuppression");
231
+ const add = Atom3.fn((payload, get) => get.setResult(addMutation, {
232
+ payload,
233
+ reactivityKeys: [...reactivityKeys, "kraksend.campaigns"]
234
+ }));
235
+ const remove = Atom3.fn((input, get) => get.setResult(removeMutation, {
236
+ params: { id: input.id },
237
+ payload: input.payload,
238
+ reactivityKeys: [...reactivityKeys, "kraksend.campaigns"]
239
+ }));
240
+ return { query, inspection, add, remove };
241
+ };
242
+ // src/delivery.atom.ts
243
+ import { Schema as Schema4 } from "effect";
244
+ import { Atom as Atom4, AtomHttpApi as AtomHttpApi4, AsyncResult as AsyncResult4 } from "effect/reactivity";
245
+ import { FetchHttpClient as FetchHttpClient4 } from "effect/http";
246
+ import { DeliveryAdminApi } from "@krak-stack/notifications/admin/delivery.api";
247
+ import {
248
+ DeliverySelection
249
+ } from "@krak-stack/notifications/admin/delivery.schema";
250
+ import { NotificationScope } from "@krak-stack/notifications/schema";
251
+ import { TableState as TableState4 } from "@krak-stack/notifications/admin/table.schema";
252
+ var Key = Schema4.Struct({
253
+ view: Schema4.Literals(["overview", "activity"]),
254
+ source: DeliverySelection.fields.source,
255
+ scope: Schema4.optional(NotificationScope),
256
+ table: TableState4
257
+ }).annotate({ identifier: "StaffDeliveryQueryKey" });
258
+ var Codec = Schema4.fromJsonString(Key);
259
+ var deliveryQueryKey = Schema4.encodeSync(Codec);
260
+ var InspectionKey = Schema4.fromJsonString(Schema4.Struct({ id: Schema4.String, queryKey: Schema4.String }).annotate({
261
+ identifier: "StaffDeliveryInspectionKey"
262
+ }));
263
+ var deliveryInspectionKey = Schema4.encodeSync(InspectionKey);
264
+ var makeNotificationDeliveryAtoms = (options) => {
265
+
266
+ class Client extends AtomHttpApi4.Service()(`host/NotificationDeliveryAdmin/${options.authorizationKey}`, {
267
+ api: DeliveryAdminApi,
268
+ baseUrl: options.baseUrl,
269
+ httpClient: FetchHttpClient4.layer
270
+ }) {
271
+ }
272
+ const reactivityKeys = [`notification.staff.${options.authorizationKey}`];
273
+ const query = Atom4.family((key) => {
274
+ const { table, view, ...selection } = Schema4.decodeSync(Codec)(key);
275
+ const common = { reactivityKeys, timeToLive: "10 seconds" };
276
+ if (view === "overview") {
277
+ const atom = Client.query("notificationDeliveries", "overview", {
278
+ query: selection,
279
+ ...common
280
+ });
281
+ return {
282
+ atom: Atom4.map(Atom4.optimistic(atom), (result) => AsyncResult4.map(result, (overview) => ({ overview }))),
283
+ refresh: atom
284
+ };
285
+ }
286
+ const atom = Client.query("notificationDeliveries", "activityTable", {
287
+ query: { ...selection, table },
288
+ ...common
289
+ });
290
+ return {
291
+ atom: Atom4.map(Atom4.optimistic(atom), (result) => AsyncResult4.map(result, (activity) => ({ activity }))),
292
+ refresh: atom
293
+ };
294
+ });
295
+ const inspection = Atom4.family((key) => {
296
+ const { id, queryKey } = Schema4.decodeSync(InspectionKey)(key);
297
+ const selection = Schema4.decodeSync(Codec)(queryKey);
298
+ return Atom4.optimistic(Client.query("notificationDeliveries", "inspect", {
299
+ params: { id },
300
+ query: { source: selection.source, scope: selection.scope },
301
+ reactivityKeys,
302
+ timeToLive: "10 seconds"
303
+ }));
304
+ });
305
+ return {
306
+ query,
307
+ inspection,
308
+ authorizationKey: options.authorizationKey,
309
+ scope: options.scope
310
+ };
311
+ };
312
+ // src/atoms.ts
313
+ var makeNotificationContactAtoms = makeSendContactAtoms;
314
+ var makeNotificationCampaignAtoms = makeSendCampaignAtoms;
315
+ var makeNotificationOperationsAtoms = makeSendOperationsAtoms;
316
+ export {
317
+ OperationsQueryKey,
318
+ deliveryInspectionKey,
319
+ deliveryQueryKey,
320
+ makeNotificationCampaignAtoms,
321
+ makeNotificationContactAtoms,
322
+ makeNotificationDeliveryAtoms,
323
+ makeNotificationOperationsAtoms,
324
+ makeSendCampaignAtoms,
325
+ makeSendContactAtoms,
326
+ makeSendOperationsAtoms,
327
+ operationsQueryKey
328
+ };