@marktiderman/genesis-notifications 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Tiderman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# @marktiderman/genesis-notifications
 
-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.
+One notifier for every part of a Genesis app. A domain package (chat, forms,
+sites, support) decides **who** is told and **what**: the candidates, its own
+mutes and mentions, who may see what. The notifier decides **how and when**:
+
+- the channel: the in-app feed, Expo push, email;
+- quiet hours, read in the person's time zone and right across daylight saving;
+- preferences by category and channel, with tenant defaults, and `critical` types always on;
+- delay-then-skip-if-read for email;
+- dedupe, retries, delivery receipts, and pruning dead push tokens.
+
+It never reads a domain's tables. The contract, the tables and a worked example
+for a domain are in [docs/NOTIFICATIONS.md](../../docs/NOTIFICATIONS.md).
+
+## Entry points
+
+| Import | What |
+|---|---|
+| `@marktiderman/genesis-notifications` (`/core`) | `defineNotifications`, the shared types, `MESSAGE_ACTIONS`, `GENESIS_TEST_TYPE`. No dependencies. |
+| `/runner` | `createRunner`: the one outbox runner (claim, send in groups, settle, `maxDeferrals`, jitter, `disable` on 410). genesis-forms' destinations run on it too. No dependencies. |
+| `/server` | `notify()`, `syncNotificationTypes`, `createNotificationRunner`, `createNotificationsHandler`, `expoPushProvider`, `resendProvider`, `resolveSecretLink`, `checkSenderDomain`, unsubscribe tokens, webhook verification. Service role only. |
+| `/email` | React Email: `BrandLayout`, `EmailText`, `EmailButton`, `reactEmailTemplate`, `brandedDefaultTemplate`. |
+| `/supabase` | `NOTIFICATIONS_MIGRATIONS` and `notificationsClient(supabase)`, the browser and phone side under row level security. |
+| `/react` | `NotificationsProvider`, `useNotifications`, `useUnreadCount`, `usePreferences`. |
+| `/web` | `NotificationBell`, `NotificationFeed`, `PreferencesMatrix`, and for admins `DeliveryLog`, `SuppressionList`, `SendTestNotification`, all on genesis-ui. |
+| `/native` | `NotificationsFeed` (on genesis-ui-native's `NotificationsPage`), `ChannelPreferences`, `NotificationPreferences`, `notificationsPushBackend`, `pushOptionsFrom`, `notificationAction`. |
+| `/blocks` | `notificationsBlock`: routes, nav, a Settings row, the migration and the privacy notes. |
+
+The package ships `migrations/0001_genesis_notifications.sql` with its pgTAP
+test, and the `functions/genesis-notifications` Edge Function template.
+
+## Set up
+
+1. Copy the migration into `supabase/migrations/` under a new timestamped name and its test into
+   `supabase/tests/database/`. It needs Vault (every Supabase project has it) for the key that
+   encrypts one-time secrets.
+2. Say who is an admin, in a migration of your own after it:
+
+   ```sql
+   create or replace function private.genesis_notifications_admin(p_user uuid, p_tenant uuid)
+   returns boolean language sql stable security definer set search_path = '' as $$
+     -- Your own rule: here, a tenant's owners and admins see that tenant (p_tenant null, the
+     -- whole app and the suppression list, is nobody's).
+     select p_tenant is not null and exists (
+       select 1 from public.memberships m
+       where m.user_id = p_user and m.tenant_id = p_tenant and m.role in ('owner', 'admin'))
+   $$;
+   ```
+
+   Row level security calls it as the signed-in person, so it stays executable by
+   `authenticated`; never grant it to `anon` or `public`. Until you replace it nobody is an admin.
+3. Define your types once and import the list everywhere (app, server, function):
+
+   ```ts
+   import { defineNotifications, MESSAGE_ACTIONS, GENESIS_TEST_CATEGORY, GENESIS_TEST_TYPE } from "@marktiderman/genesis-notifications";
+
+   export const notifications = defineNotifications({
+     categories: { messages: { label: "Messages", android: { importance: "high" } }, ...GENESIS_TEST_CATEGORY },
+     actions: { message: MESSAGE_ACTIONS },
+     types: {
+       "chat.message": {
+         category: "messages",
+         channels: { in_app: true, push: true, email: true },
+         emailDelaySeconds: 600,
+         actions: "message",
+         render: (d) => ({ title: String(d.sender_name), body: String(d.preview), url: `/messages/${d.conversation_id}` }),
+       },
+       ...GENESIS_TEST_TYPE,
+     },
+   });
+   ```
+
+4. Mirror it on deploy: `await syncNotificationTypes(admin, notifications)` (types left out are
+   retired, never deleted).
+5. Deploy `functions/genesis-notifications` (`--no-verify-jwt`), and schedule `POST …/run`
+   every minute and `POST …/receipts` every 15 minutes with
+   `Authorization: Bearer <GENESIS_NOTIFICATIONS_CRON_SECRET>`, and
+   `select public.genesis_notifications_prune()` daily. Point Resend's webhook (bounced,
+   complained, delivered) at `…/webhooks/resend`.
+6. In the app, wrap the signed-in screens:
+
+   ```tsx
+   <NotificationsProvider client={supabase} registry={notifications} userId={session?.user.id ?? null}>
+   ```
+
+   On native, give the push block this package's backend and the registry's categories:
+   `createPush({ backend: notificationsPushBackend(supabase), ...pushOptionsFrom(notifications), randomUUID: Crypto.randomUUID, … })`.
+
+## Sending
+
+```ts
+import { notify } from "@marktiderman/genesis-notifications/server";
+
+await notify(admin, {
+  type: "chat.message",
+  recipients: memberIds,                    // user ids, or { email, name, ref } for people with no login
+  data: { conversation_id, sender_name, preview },
+  idempotencyKey: `push:${messageId}`,       // per recipient, type and tenant: the same key again sends nothing more
+  threadKey: conversationId,                // groups them on the lock screen
+  collapseKey: `conversation:${conversationId}`, // a newer one replaces an unsent older one
+  badge: unreadCount,                        // the caller counts
+  tenantId,
+}, { registry: notifications });
+```
+
+`genesis_notify` (the SQL function under it, service role only) can be called with the same
+arguments from a domain's own SQL.
+
+To take back what hasn't gone out (a release rolled back, an event undone):
+
+```ts
+await cancelNotification(admin, { type: "release.published", idempotencyKey: `release:${releaseId}`, tenantId, archive: true });
+```
+
+Every pending send job made with that type, tenant and key (for everyone, or only `recipients`)
+becomes `cancelled` and is never claimed; one being sent at that moment ends cancelled unless
+that attempt goes out (it is never retried); a job already sent is left alone; `archive: true`
+archives the feed rows too (`genesis_notifications_cancel` in SQL). Another tenant's
+notifications with the same key are never touched.
+
+### Rules the notifier keeps
+
+- **Secrets never go in `data`, or in a push.** `genesis_notify` (and `notify()` before it)
+  refuses any key ending in `token`, `code`, `secret`, `key`, `otp` or `password` (and
+  `signature`, `sig`, `invite_link` and the like), and any link, absolute or relative, with a
+  query or fragment parameter named that way (`/accept?inviteCode=`, `#access_token=`). This is
+  a backstop, not a guarantee: it catches the usual names, so keep secrets out by design, and
+  rename a display value it trips on (`country_code` → `country`). Store a reference
+  (`{ response_id }`) and mark the type `secretLink: true`; the runner calls your
+  `secretLinks[type]` at send time (`resolveSecretLink`). A token that exists only hashed in your
+  tables is passed as `notify({ secret })`, to exactly one recipient: encrypted onto the email's
+  send job with the Vault key, decrypted only when the runner claims it, cleared once the job
+  settles. Keys are matched as words, so `inviteToken` is refused as well as `invite_token`.
+- **Retries are byte-identical.** An email is rendered once, at its first claim, and stored with
+  its hash; every retry sends the stored copy with the same idempotency key. A secret link is
+  built afresh on each attempt, so **a `secretLinks` builder must be deterministic**: the same
+  link for the same notification every time. Resend's 409 `invalid_idempotent_request` (the key
+  with another body) fails the job loudly (`idempotency_body_changed`), never counting it as
+  sent; `concurrent_idempotent_requests` retries in 5 s. `resendProvider` paces its requests
+  (`perSecond`, default 5, under Resend's default 10 a second per team); two runners at once each
+  keep to their own pace.
+- **Links are the app's own.** A type's `render().url` must be a path (`/messages/42`): the push
+  carries it as is, the email resolves it against `appUrl`'s origin; anything else (another host,
+  `//host`, `javascript:`) is left out.
+- **Push stays within its lease.** Jobs are sent in Expo batches of 100 (a job's devices never
+  split), each batch's tickets recorded and its jobs settled on its own; no batch starts once the
+  lease is about to run out (those jobs come straight back). With `runBudgetMs` (your function's
+  wall-clock limit) a run claims again while claims come back full, and stops once the time left
+  is under the lease.
+- **One unreadable secret fails alone** (`secret_unreadable`); the rest of the claim goes out. No
+  Vault key at all raises, since that is the app's to fix.
+- **Transactional types** (`transactional: true`) have no unsubscribe link, and their email is
+  sent whatever the person chose for the category (an unsubscribe never stops a receipt or a
+  reset); they are never held by quiet hours or the email delay, and still reach someone who
+  complained (not someone who hard bounced). Rate caps stay in the domain. A critical type's
+  email has no unsubscribe link either (preferences can't turn it off).
+- **A job is never stuck.** One whose lease ran out `maxAttempts` times (the runner died with it
+  each time) fails as `lease_expired`.
+- **Erasure.** `genesis_notifications_erase(user, email, ref)` deletes a person's
+  notifications (with every send job, and for a login also those addressed to its email),
+  devices, receipts, preferences and device moves, logins or not. The suppression list keeps only a hash, so a bounced address stays suppressed.
+  `genesis_notifications_prune(keep, keep_rendered, keep_feed)` keeps the delivery log short
+  (30 days, rendered bodies a day, by default); notifications that were never in a feed
+  (email-only recipients) go with their send jobs.
+
+## Email
+
+One Resend key per app (`RESEND_API_KEY`). Each tenant has a sender identity in
+`notification_senders`: without its own domain, mail goes from the app's shared domain with the
+tenant's name as the from name and its reply-to; once its own domain is verified, from that
+domain. Verifying proves the domain is the tenant's: `genesis_notifications_set_sender` gives
+the sender a `domain_token`, the tenant adds the TXT record `senderOwnershipRecord(domain,
+token)` (`_genesis-notifications.<domain>` = `genesis-notifications-verify=<token>`) beside
+Resend's records, and `checkSenderDomain(domain, { token, reservedDomains })` reads it with SPF,
+DKIM and DMARC over DNS over HTTPS; `genesis_notifications_set_sender_dns(tenant, domain,
+token, status, dns)` records the result for the domain and token checked. A domain is verified for one tenant at
+most, and never the app's own shared domains or one under them (`reservedDomains`; the runner
+refuses one too). Transactional and other mail
+go from separate shared domains (`domains: { transactional, other }`), tagged `stream`.
+
+Everything that isn't transactional carries `List-Unsubscribe` and
+`List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) with a signed token; the endpoint
+never unsubscribes on a GET (link scanners follow links), only on the POST. The token never
+carries an address: someone with no login is named by its SHA-256 (`emailHash`). The unsubscribe
+is for the tenant the email came from: a person with a login has that tenant's email of the
+category turned off (a choice in Settings turns it back on everywhere); someone with none is
+suppressed for the category and tenant. Only a bounce Resend calls `Permanent` suppresses an
+address for good. The provider's id is kept the moment a send returns, so a webhook that comes
+before the job settles still finds it.
+
+The provider is chosen per job (`email.providerFor`), so a tenant-owned Resend key kept in
+Vault can be added later without changing the runner. It isn't built.
+
+## Push
+
+The device side stays in genesis-native's push block: registration, the permission, routing, the
+badge, and hiding a push for the screen already open (`useSuppressNotifications`, client-side).
+The runner sends every due job's devices in Expo batches of 100 with `threadId`, `categoryId`
+(the device category with Reply and Mark as read), `badge`, and a `collapseId` (the collapse key,
+else the notification id, so a resend after a timeout replaces rather than repeats). The payload's
+`data` is `{ url, notification_id, type, thread_key }`, never the notification's own `data`. A
+person who hides previews, or a type with `pushPrivacy: "generic"`, gets neutral text. Receipts
+are checked about every 15 minutes; `DeviceNotRegistered` forgets the device.
+
+Android shows a push only on a channel the app made: the runner sends the category id as
+`channelId`, so build the push block with `pushOptionsFrom(registry)` (one channel per
+category, `genesis` included when you spread `GENESIS_TEST_CATEGORY`).
+
+`notificationAction(response)` reads an action button: its id, the typed text, and the
+notification id, which an app uses as the reply's client id so a retried reply stays one reply.
+
+## Admins
+
+`DeliveryLog`, `SuppressionList` and `SendTestNotification` (web) read the log columns of
+`notification_deliveries` (status, attempts, an error code, a masked address; never content,
+the rendered email or a secret) and the suppression list, through
+`private.genesis_notifications_admin`.
+
+## Coming from genesis-supabase's push migration (0005)
+
+The migration adopts `push_devices`, `notification_preferences` and `push_receipts` as they are
+and only adds to them (`notification_preferences.channels`, `push_receipts.delivery_id`,
+`push_devices.installation_id`); no row changes. Then:
+
+- stop calling the `genesis-push-send` function and 0005's sender functions; the runner here
+  replaces them;
+- remove 0005's pgTAP test from `supabase/tests/database/`: this migration redefines
+  `genesis_push_register` so a token another login holds moves only with the same install id
+  (0005's test asserts the old move), and `genesis_push_forget` answers the same whether or not
+  there was a token (0005's test asserts `false` for an unknown one);
+- switch the push block to `notificationsPushBackend(supabase)`, so it registers with the install id.
+
+A category someone switched off under 0005 (`categories`) still turns its push and email off,
+and every screen here shows it so; the first time they change one of its channels, the old
+switch becomes explicit channel choices (`genesis_notifications_set_preference`).
+
+## Not in v1
+
+- **Digests** (next, v1.1).
+- SMS.
+- Web push.
+- The Notification Service Extension and Communication Notifications (rich pushes, sender avatars).
+- Live Activities.
+- Slack as a channel.
+- Routing auth emails (sign-in links, password resets) through Supabase's send-email hook.
+- Per-tenant Resend keys (the provider seam is there; reading a key from Vault isn't).
+
+Also not done yet: nothing has been sent through Expo or Resend with real credentials; the
+providers are tested against faked services.
+
+Part of the [Genesis framework](https://github.com/marktiderman/genesis).

package/dist/blocks.d.ts

@@ -0,0 +1,10 @@
+import * as _marktiderman_genesis_features_blocks from '@marktiderman/genesis-features/blocks';
+
+/**
+ * Notifications: the feed, push and email for every domain, on one notifier.
+ *
+ * @stability Beta
+ */
+declare const notificationsBlock: _marktiderman_genesis_features_blocks.BlockDef<"notifications", never>;
+
+export { notificationsBlock };

package/dist/blocks.js

@@ -0,0 +1,35 @@
+import { defineBlock } from '@marktiderman/genesis-features/blocks';
+
+// src/blocks.ts
+var PACKAGE = "@marktiderman/genesis-notifications";
+var notificationsBlock = defineBlock({
+  id: "notifications",
+  platforms: ["web", "native", "server"],
+  contributes: {
+    nav: [{ id: "notifications", label: "Notifications", path: "/notifications", icon: "bell", order: 50 }],
+    settings: [{ id: "notification-preferences", section: "notifications", title: "Notifications", href: "/settings/notifications", testID: "genesis-notifications-settings" }],
+    routes: [
+      { path: "/notifications", description: "The notification feed", signedIn: true },
+      { path: "/settings/notifications", description: "Notification preferences: categories by channel, quiet hours, previews", signedIn: true },
+      { path: "/admin/notifications", description: "Admin: the delivery log, suppressed addresses, send a test", signedIn: true }
+    ],
+    migrations: [{ package: PACKAGE, file: "migrations/0001_genesis_notifications.sql", test: "migrations/tests/0001_genesis_notifications.test.sql" }],
+    privacy: {
+      collects: [
+        { type: "device ID", purposes: ["app functionality"], linked: true, tracking: false },
+        { type: "email address", purposes: ["app functionality"], linked: true, tracking: false }
+      ],
+      notes: [
+        "Keeps each person's notifications (what the app told them), read and archived, until they are pruned or the person is erased.",
+        "Keeps this device's push token against the signed-in person; forgotten on sign-out and account deletion. A token moves to another login only on the same phone, and each move is recorded.",
+        "Keeps notification preferences per person: each category by channel, quiet hours with a time zone, and previews.",
+        "Keeps a short delivery log (status and an error code, no content) and, for addresses that bounced, complained or unsubscribed with no login, a hash of the address.",
+        "Erasing a person deletes their notifications, send jobs, devices and preferences, whether or not they have a login."
+      ]
+    }
+  }
+});
+
+export { notificationsBlock };
+//# sourceMappingURL=blocks.js.map
+//# sourceMappingURL=blocks.js.map

package/dist/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/blocks.ts"],"names":[],"mappings":";;;AAQA,IAAM,OAAA,GAAU,qCAAA;AAOT,IAAM,qBAAqB,WAAA,CAAY;AAAA,EAC5C,EAAA,EAAI,eAAA;AAAA,EACJ,SAAA,EAAW,CAAC,KAAA,EAAO,QAAA,EAAU,QAAQ,CAAA;AAAA,EACrC,WAAA,EAAa;AAAA,IACX,GAAA,EAAK,CAAC,EAAE,EAAA,EAAI,eAAA,EAAiB,KAAA,EAAO,eAAA,EAAiB,IAAA,EAAM,gBAAA,EAAkB,IAAA,EAAM,MAAA,EAAQ,KAAA,EAAO,IAAI,CAAA;AAAA,IACtG,QAAA,EAAU,CAAC,EAAE,EAAA,EAAI,0BAAA,EAA4B,OAAA,EAAS,eAAA,EAAiB,KAAA,EAAO,eAAA,EAAiB,IAAA,EAAM,yBAAA,EAA2B,MAAA,EAAQ,kCAAkC,CAAA;AAAA,IAC1K,MAAA,EAAQ;AAAA,MACN,EAAE,IAAA,EAAM,gBAAA,EAAkB,WAAA,EAAa,uBAAA,EAAyB,UAAU,IAAA,EAAK;AAAA,MAC/E,EAAE,IAAA,EAAM,yBAAA,EAA2B,WAAA,EAAa,wEAAA,EAA0E,UAAU,IAAA,EAAK;AAAA,MACzI,EAAE,IAAA,EAAM,sBAAA,EAAwB,WAAA,EAAa,4DAAA,EAA8D,UAAU,IAAA;AAAK,KAC5H;AAAA,IACA,UAAA,EAAY,CAAC,EAAE,OAAA,EAAS,SAAS,IAAA,EAAM,2CAAA,EAA6C,IAAA,EAAM,sDAAA,EAAwD,CAAA;AAAA,IAClJ,OAAA,EAAS;AAAA,MACP,QAAA,EAAU;AAAA,QACR,EAAE,IAAA,EAAM,WAAA,EAAa,QAAA,EAAU,CAAC,mBAAmB,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAM,QAAA,EAAU,KAAA,EAAM;AAAA,QACpF,EAAE,IAAA,EAAM,eAAA,EAAiB,QAAA,EAAU,CAAC,mBAAmB,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAM,QAAA,EAAU,KAAA;AAAM,OAC1F;AAAA,MACA,KAAA,EAAO;AAAA,QACL,+HAAA;AAAA,QACA,4LAAA;AAAA,QACA,kHAAA;AAAA,QACA,qKAAA;AAAA,QACA;AAAA;AACF;AACF;AAEJ,CAAC","file":"blocks.js","sourcesContent":["/**\n * The notifications block, as a `defineBlock` declaration: what `genesis add\n * notifications` installs (the migration and its pgTAP test), the screens it\n * needs routed, its nav and Settings rows, and what it means for the stores'\n * privacy forms. Node-safe: no React, no Supabase client.\n */\nimport { defineBlock } from \"@marktiderman/genesis-features/blocks\";\n\nconst PACKAGE = \"@marktiderman/genesis-notifications\";\n\n/**\n * Notifications: the feed, push and email for every domain, on one notifier.\n *\n * @stability Beta\n */\nexport const notificationsBlock = defineBlock({\n  id: \"notifications\",\n  platforms: [\"web\", \"native\", \"server\"],\n  contributes: {\n    nav: [{ id: \"notifications\", label: \"Notifications\", path: \"/notifications\", icon: \"bell\", order: 50 }],\n    settings: [{ id: \"notification-preferences\", section: \"notifications\", title: \"Notifications\", href: \"/settings/notifications\", testID: \"genesis-notifications-settings\" }],\n    routes: [\n      { path: \"/notifications\", description: \"The notification feed\", signedIn: true },\n      { path: \"/settings/notifications\", description: \"Notification preferences: categories by channel, quiet hours, previews\", signedIn: true },\n      { path: \"/admin/notifications\", description: \"Admin: the delivery log, suppressed addresses, send a test\", signedIn: true },\n    ],\n    migrations: [{ package: PACKAGE, file: \"migrations/0001_genesis_notifications.sql\", test: \"migrations/tests/0001_genesis_notifications.test.sql\" }],\n    privacy: {\n      collects: [\n        { type: \"device ID\", purposes: [\"app functionality\"], linked: true, tracking: false },\n        { type: \"email address\", purposes: [\"app functionality\"], linked: true, tracking: false },\n      ],\n      notes: [\n        \"Keeps each person's notifications (what the app told them), read and archived, until they are pruned or the person is erased.\",\n        \"Keeps this device's push token against the signed-in person; forgotten on sign-out and account deletion. A token moves to another login only on the same phone, and each move is recorded.\",\n        \"Keeps notification preferences per person: each category by channel, quiet hours with a time zone, and previews.\",\n        \"Keeps a short delivery log (status and an error code, no content) and, for addresses that bounced, complained or unsubscribed with no login, a hash of the address.\",\n        \"Erasing a person deletes their notifications, send jobs, devices and preferences, whether or not they have a login.\",\n      ],\n    },\n  },\n});\n"]}

package/dist/chunk-2BG336II.js

@@ -0,0 +1,124 @@
+import { notificationsClient } from './chunk-EWZB35V6.js';
+import { createContext, useMemo, useEffect, useContext } from 'react';
+import { useQueryClient, useQuery, useMutation } from '@tanstack/react-query';
+import { jsx } from 'react/jsx-runtime';
+
+var NotificationsContext = createContext(null);
+var isClient = (c) => typeof c.feed === "function";
+var notificationKeys = {
+  all: (userId) => ["genesis-notifications", userId],
+  feed: (userId, filter, limit) => ["genesis-notifications", userId, "feed", filter, limit],
+  unread: (userId) => ["genesis-notifications", userId, "unread"],
+  choices: (userId) => ["genesis-notifications", userId, "choices"]
+};
+function NotificationsProvider({ client, registry, userId, realtime = true, children }) {
+  const resolved = useMemo(() => isClient(client) ? client : notificationsClient(client), [client]);
+  const queryClient = useQueryClient();
+  useEffect(() => {
+    if (!realtime || !userId) return;
+    try {
+      return resolved.subscribe(userId, () => {
+        void queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });
+      });
+    } catch (error) {
+      console.warn(`[genesis-notifications] couldn't listen for feed changes: ${error instanceof Error ? error.message : "unknown error"}`);
+      return void 0;
+    }
+  }, [resolved, userId, realtime, queryClient]);
+  const value = useMemo(() => ({ client: resolved, registry, userId }), [resolved, registry, userId]);
+  return /* @__PURE__ */ jsx(NotificationsContext.Provider, { value, children });
+}
+function useNotificationsContext() {
+  const ctx = useContext(NotificationsContext);
+  if (!ctx) throw new Error("useNotifications: wrap the screen in <NotificationsProvider>.");
+  return ctx;
+}
+function useNotifications(options = {}) {
+  const { client, registry, userId } = useNotificationsContext();
+  const filter = options.filter ?? "all";
+  const limit = options.limit ?? 50;
+  const queryClient = useQueryClient();
+  const query = useQuery({
+    queryKey: notificationKeys.feed(userId, filter, limit),
+    queryFn: () => client.feed({ filter, limit }),
+    enabled: userId !== null
+  });
+  const items = useMemo(
+    () => (query.data ?? []).map((row) => {
+      const text = registry.render(row.type, row.data ?? {});
+      return { ...row, ...text, unread: row.read_at === null };
+    }),
+    [query.data, registry]
+  );
+  const changed = () => queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });
+  const mark = useMutation({
+    mutationFn: ({ ids, state }) => client.mark(ids, state),
+    onSettled: changed
+  });
+  const all = useMutation({ mutationFn: (state) => client.markAll(state), onSettled: changed });
+  const list = (ids) => typeof ids === "string" ? [ids] : ids;
+  return {
+    items,
+    isLoading: query.isLoading,
+    isRefetching: query.isRefetching,
+    error: query.error ?? null,
+    refetch: () => query.refetch(),
+    markRead: async (ids) => void await mark.mutateAsync({ ids: list(ids), state: "read" }),
+    markUnread: async (ids) => void await mark.mutateAsync({ ids: list(ids), state: "unread" }),
+    archive: async (ids) => void await mark.mutateAsync({ ids: list(ids), state: "archived" }),
+    markAllRead: async () => void await all.mutateAsync("read"),
+    markAllSeen: async () => void await all.mutateAsync("seen")
+  };
+}
+function useUnreadCount() {
+  const { client, userId } = useNotificationsContext();
+  const query = useQuery({ queryKey: notificationKeys.unread(userId), queryFn: () => client.unreadCount(), enabled: userId !== null });
+  return query.data ?? 0;
+}
+function preferenceRows(registry, choices) {
+  return registry.matrix().map((row) => {
+    const chosen = choices[row.id] ?? {};
+    const values = {};
+    for (const ch of row.channels) values[ch] = row.critical ? Boolean(row.defaults[ch]) : chosen[ch] ?? Boolean(row.defaults[ch]);
+    return { ...row, values, chosen: row.critical ? {} : chosen };
+  });
+}
+function usePreferences() {
+  const { client, registry, userId } = useNotificationsContext();
+  const queryClient = useQueryClient();
+  const key = notificationKeys.choices(userId);
+  const query = useQuery({ queryKey: key, queryFn: () => client.choices(userId), enabled: userId !== null });
+  const save = useMutation({
+    mutationFn: ({ category, channel, on }) => client.setChoice(category, channel, on),
+    onMutate: async ({ category, channel, on }) => {
+      await queryClient.cancelQueries({ queryKey: key });
+      const before = queryClient.getQueryData(key);
+      const next = { ...before ?? {} };
+      const row = { ...next[category] ?? {} };
+      if (on === null) delete row[channel];
+      else row[channel] = on;
+      next[category] = row;
+      queryClient.setQueryData(key, next);
+      return { before };
+    },
+    onError: (_e, _v, context) => queryClient.setQueryData(key, context?.before),
+    // Read back through `choices()` (which folds in 0005's category switches), never the raw row the save returns.
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key })
+  });
+  const rows = useMemo(() => preferenceRows(registry, query.data ?? {}), [registry, query.data]);
+  return {
+    rows,
+    status: query.isError ? "error" : query.isSuccess ? "ready" : "loading",
+    error: query.error ?? save.error ?? null,
+    saving: save.isPending,
+    set: async (category, channel, on) => {
+      const row = rows.find((r) => r.id === category);
+      if (!row || !row.channels.includes(channel) || row.critical && on === false) return;
+      await save.mutateAsync({ category, channel, on });
+    }
+  };
+}
+
+export { NotificationsProvider, notificationKeys, preferenceRows, useNotifications, useNotificationsContext, usePreferences, useUnreadCount };
+//# sourceMappingURL=chunk-2BG336II.js.map
+//# sourceMappingURL=chunk-2BG336II.js.map

package/dist/chunk-2BG336II.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/index.tsx"],"names":[],"mappings":"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","file":"chunk-2BG336II.js","sourcesContent":["/**\n * `@marktiderman/genesis-notifications/react`: the hooks every screen uses,\n * on web and native alike. `NotificationsProvider` holds the client, the\n * registry and the signed-in user, and listens on the person's private\n * realtime channel: any change refetches (the broadcast carries ids only).\n *\n *   useNotifications()   the feed, each row rendered by the registry, plus mark read / archive\n *   useUnreadCount()     the unread count, for a bell or a tab badge\n *   usePreferences()     the category × channel matrix and its switches\n *\n * Built on TanStack Query (a peer): the app's QueryClientProvider must be above.\n *\n * @packageDocumentation\n */\nimport { createContext, useContext, useEffect, useMemo, type ReactNode } from \"react\";\nimport { useMutation, useQuery, useQueryClient } from \"@tanstack/react-query\";\nimport type { Channel, ChannelChoices, MatrixRow, NotificationRegistry, NotificationRow } from \"../core/index\";\nimport { notificationsClient, type FeedFilter, type NotificationsClient, type NotificationsSupabaseLike } from \"../supabase/index\";\n\ninterface Context {\n  client: NotificationsClient;\n  registry: NotificationRegistry;\n  userId: string | null;\n}\n\nconst NotificationsContext = createContext<Context | null>(null);\n\nexport interface NotificationsProviderProps {\n  /** A Supabase client signed in as the person (or a `notificationsClient`). */\n  client: NotificationsSupabaseLike | NotificationsClient;\n  registry: NotificationRegistry;\n  /** The signed-in user; null while signed out (nothing is read). */\n  userId: string | null;\n  /** Listen on `user:<id>` and refetch on a change. Default true. */\n  realtime?: boolean;\n  children?: ReactNode;\n}\n\nconst isClient = (c: NotificationsSupabaseLike | NotificationsClient): c is NotificationsClient => typeof (c as NotificationsClient).feed === \"function\";\n\n/** The query keys, for an app that invalidates them itself. */\nexport const notificationKeys = {\n  all: (userId: string | null) => [\"genesis-notifications\", userId] as const,\n  feed: (userId: string | null, filter: FeedFilter, limit: number) => [\"genesis-notifications\", userId, \"feed\", filter, limit] as const,\n  unread: (userId: string | null) => [\"genesis-notifications\", userId, \"unread\"] as const,\n  choices: (userId: string | null) => [\"genesis-notifications\", userId, \"choices\"] as const,\n};\n\n/**\n * Provides the notifier to the hooks.\n *\n * @stability Beta\n */\nexport function NotificationsProvider({ client, registry, userId, realtime = true, children }: NotificationsProviderProps) {\n  const resolved = useMemo(() => (isClient(client) ? client : notificationsClient(client)), [client]);\n  const queryClient = useQueryClient();\n  useEffect(() => {\n    if (!realtime || !userId) return;\n    try {\n      return resolved.subscribe(userId, () => {\n        void queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });\n      });\n    } catch (error) {\n      console.warn(`[genesis-notifications] couldn't listen for feed changes: ${error instanceof Error ? error.message : \"unknown error\"}`);\n      return undefined;\n    }\n  }, [resolved, userId, realtime, queryClient]);\n  const value = useMemo(() => ({ client: resolved, registry, userId }), [resolved, registry, userId]);\n  return <NotificationsContext.Provider value={value}>{children}</NotificationsContext.Provider>;\n}\n\n/** The provider's client, registry and user. Throws outside one. */\nexport function useNotificationsContext(): Context {\n  const ctx = useContext(NotificationsContext);\n  if (!ctx) throw new Error(\"useNotifications: wrap the screen in <NotificationsProvider>.\");\n  return ctx;\n}\n\n/** A feed row with what the registry says about it. */\nexport interface FeedItem extends NotificationRow {\n  title: string;\n  body?: string;\n  url?: string;\n  unread: boolean;\n}\n\nexport interface UseNotificationsResult {\n  items: FeedItem[];\n  isLoading: boolean;\n  isRefetching: boolean;\n  error: Error | null;\n  refetch: () => Promise<unknown>;\n  markRead: (ids: string | readonly string[]) => Promise<void>;\n  markUnread: (ids: string | readonly string[]) => Promise<void>;\n  markAllRead: () => Promise<void>;\n  archive: (ids: string | readonly string[]) => Promise<void>;\n  /** Mark everything shown as seen (opening the feed); the unread count is about read, not seen. */\n  markAllSeen: () => Promise<void>;\n}\n\n/**\n * The person's feed.\n *\n * @stability Beta\n */\nexport function useNotifications(options: { filter?: FeedFilter; limit?: number } = {}): UseNotificationsResult {\n  const { client, registry, userId } = useNotificationsContext();\n  const filter = options.filter ?? \"all\";\n  const limit = options.limit ?? 50;\n  const queryClient = useQueryClient();\n  const query = useQuery({\n    queryKey: notificationKeys.feed(userId, filter, limit),\n    queryFn: () => client.feed({ filter, limit }),\n    enabled: userId !== null,\n  });\n  const items = useMemo<FeedItem[]>(\n    () =>\n      (query.data ?? []).map((row) => {\n        const text = registry.render(row.type, row.data ?? {});\n        return { ...row, ...text, unread: row.read_at === null };\n      }),\n    [query.data, registry],\n  );\n  const changed = () => queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });\n  const mark = useMutation({\n    mutationFn: ({ ids, state }: { ids: readonly string[]; state: \"seen\" | \"read\" | \"unread\" | \"archived\" }) => client.mark(ids, state),\n    onSettled: changed,\n  });\n  const all = useMutation({ mutationFn: (state: \"seen\" | \"read\") => client.markAll(state), onSettled: changed });\n  const list = (ids: string | readonly string[]) => (typeof ids === \"string\" ? [ids] : ids);\n  return {\n    items,\n    isLoading: query.isLoading,\n    isRefetching: query.isRefetching,\n    error: (query.error as Error | null) ?? null,\n    refetch: () => query.refetch(),\n    markRead: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: \"read\" })),\n    markUnread: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: \"unread\" })),\n    archive: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: \"archived\" })),\n    markAllRead: async () => void (await all.mutateAsync(\"read\")),\n    markAllSeen: async () => void (await all.mutateAsync(\"seen\")),\n  };\n}\n\n/**\n * The unread count (0 while signed out).\n *\n * @stability Beta\n */\nexport function useUnreadCount(): number {\n  const { client, userId } = useNotificationsContext();\n  const query = useQuery({ queryKey: notificationKeys.unread(userId), queryFn: () => client.unreadCount(), enabled: userId !== null });\n  return query.data ?? 0;\n}\n\n/** One category's row in the matrix. */\nexport interface PreferenceRow extends MatrixRow {\n  /** What each offered channel is now: the person's choice, else the default. */\n  values: Partial<Record<Channel, boolean>>;\n  /** Which values the person chose (the rest are defaults). */\n  chosen: Partial<Record<Channel, boolean>>;\n}\n\nexport interface UsePreferencesResult {\n  rows: PreferenceRow[];\n  status: \"loading\" | \"ready\" | \"error\";\n  error: Error | null;\n  saving: boolean;\n  /** Turn one category's channel on or off; `null` goes back to the default. Critical rows can't be turned off. */\n  set: (category: string, channel: Channel, on: boolean | null) => Promise<void>;\n}\n\n/** The matrix with the person's choices applied. Exported for tests and custom screens. */\nexport function preferenceRows(registry: NotificationRegistry, choices: ChannelChoices): PreferenceRow[] {\n  return registry.matrix().map((row) => {\n    const chosen = choices[row.id] ?? {};\n    const values: Partial<Record<Channel, boolean>> = {};\n    for (const ch of row.channels) values[ch] = row.critical ? Boolean(row.defaults[ch]) : (chosen[ch] ?? Boolean(row.defaults[ch]));\n    return { ...row, values, chosen: row.critical ? {} : chosen };\n  });\n}\n\n/**\n * The person's preferences by category and channel. A tenant's default\n * isn't shown here (the server applies it); what shows for a channel the\n * person never chose is the type's default.\n *\n * @stability Beta\n */\nexport function usePreferences(): UsePreferencesResult {\n  const { client, registry, userId } = useNotificationsContext();\n  const queryClient = useQueryClient();\n  const key = notificationKeys.choices(userId);\n  const query = useQuery({ queryKey: key, queryFn: () => client.choices(userId!), enabled: userId !== null });\n  const save = useMutation({\n    mutationFn: ({ category, channel, on }: { category: string; channel: Channel; on: boolean | null }) => client.setChoice(category, channel, on),\n    onMutate: async ({ category, channel, on }) => {\n      await queryClient.cancelQueries({ queryKey: key });\n      const before = queryClient.getQueryData<ChannelChoices>(key);\n      const next: ChannelChoices = { ...(before ?? {}) };\n      const row = { ...(next[category] ?? {}) };\n      if (on === null) delete row[channel];\n      else row[channel] = on;\n      next[category] = row;\n      queryClient.setQueryData(key, next);\n      return { before };\n    },\n    onError: (_e, _v, context) => queryClient.setQueryData(key, context?.before),\n    // Read back through `choices()` (which folds in 0005's category switches), never the raw row the save returns.\n    onSettled: () => queryClient.invalidateQueries({ queryKey: key }),\n  });\n  const rows = useMemo(() => preferenceRows(registry, query.data ?? {}), [registry, query.data]);\n  return {\n    rows,\n    status: query.isError ? \"error\" : query.isSuccess ? \"ready\" : \"loading\",\n    error: ((query.error ?? save.error) as Error | null) ?? null,\n    saving: save.isPending,\n    set: async (category, channel, on) => {\n      const row = rows.find((r) => r.id === category);\n      if (!row || !row.channels.includes(channel) || (row.critical && on === false)) return;\n      await save.mutateAsync({ category, channel, on });\n    },\n  };\n}\n\nexport { notificationsClient, type NotificationsClient } from \"../supabase/index\";\n"]}

package/dist/chunk-7PHA3WVG.js

@@ -0,0 +1,51 @@
+// src/core/validate.ts
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var EMAIL = /^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/;
+var SECRET_KEY = /((token|code|secret|key|otp|password)|(^|[._-])(signature|sig|magic_?link|invite_?link|reset_?link))$/;
+function keyWords(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+var SECRET_URL = /^([a-z][a-z0-9+.-]*:|\/|\.\.?\/|(?=[?#]))\S*[?&#;][^=&#;\s]*(token|code|secret|key|otp|password|signature|sig)=/i;
+var SecretInDataError = class extends Error {
+  constructor(path) {
+    super(`notify: data.${path} looks like a secret. Store a reference and build the link at send time with resolveSecretLink.`);
+    this.path = path;
+    this.name = "SecretInDataError";
+  }
+  path;
+};
+function assertNoSecrets(data, path = "") {
+  if (!data || typeof data !== "object") return;
+  for (const [key, value] of Object.entries(data)) {
+    const here = path ? `${path}.${key}` : key;
+    if (SECRET_KEY.test(keyWords(key))) throw new SecretInDataError(here);
+    if (typeof value === "string" && SECRET_URL.test(value)) throw new SecretInDataError(here);
+    if (value && typeof value === "object") assertNoSecrets(value, here);
+  }
+}
+function recipientsToJson(recipients) {
+  if (!Array.isArray(recipients) || recipients.length === 0) throw new Error("notify: no recipients");
+  if (recipients.length > 1e3) throw new Error("notify: at most 1000 recipients a call");
+  return recipients.map((r, i) => {
+    if (typeof r === "string") {
+      if (!UUID.test(r)) throw new Error(`notify: recipient ${i} is not a user id`);
+      return { user_id: r };
+    }
+    if ("userId" in r) {
+      if (!UUID.test(r.userId)) throw new Error(`notify: recipient ${i} is not a user id`);
+      if (r.badge === void 0) return { user_id: r.userId };
+      if (!Number.isInteger(r.badge) || r.badge < 0 || r.badge > 99999) throw new Error(`notify: recipient ${i}'s badge is a whole number from 0`);
+      return { user_id: r.userId, badge: r.badge };
+    }
+    if ("email" in r) {
+      const email = r.email.trim();
+      if (!EMAIL.test(email) || email.length > 254) throw new Error(`notify: recipient ${i} has no valid email address`);
+      return { email, ...r.name ? { name: r.name.slice(0, 200) } : {}, ...r.ref ? { ref: r.ref.slice(0, 200) } : {} };
+    }
+    throw new Error(`notify: recipient ${i} is neither a user id nor an email`);
+  });
+}
+
+export { SecretInDataError, assertNoSecrets, recipientsToJson };
+//# sourceMappingURL=chunk-7PHA3WVG.js.map
+//# sourceMappingURL=chunk-7PHA3WVG.js.map

package/dist/chunk-7PHA3WVG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/validate.ts"],"names":[],"mappings":";AAOA,IAAM,IAAA,GAAO,iEAAA;AACb,IAAM,KAAA,GAAQ,mEAAA;AASP,IAAM,UAAA,GAAa,uGAAA;AAGnB,SAAS,SAAS,GAAA,EAAqB;AAC5C,EAAA,OAAO,GAAA,CAAI,OAAA,CAAQ,oBAAA,EAAsB,OAAO,EAAE,WAAA,EAAY;AAChE;AAOO,IAAM,UAAA,GAAa,kHAAA;AAGnB,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EAC3C,YAAqB,IAAA,EAAc;AACjC,IAAA,KAAA,CAAM,CAAA,aAAA,EAAgB,IAAI,CAAA,+FAAA,CAAiG,CAAA;AADxG,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAEnB,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AAAA,EACd;AAAA,EAHqB,IAAA;AAIvB;AAGO,SAAS,eAAA,CAAgB,IAAA,EAAoC,IAAA,GAAO,EAAA,EAAU;AACnF,EAAA,IAAI,CAAC,IAAA,IAAQ,OAAO,IAAA,KAAS,QAAA,EAAU;AACvC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA,EAAG;AAC/C,IAAA,MAAM,OAAO,IAAA,GAAO,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,CAAA,CAAA,GAAK,GAAA;AACvC,IAAA,IAAI,UAAA,CAAW,KAAK,QAAA,CAAS,GAAG,CAAC,CAAA,EAAG,MAAM,IAAI,iBAAA,CAAkB,IAAI,CAAA;AACpE,IAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,UAAA,CAAW,IAAA,CAAK,KAAK,CAAA,EAAG,MAAM,IAAI,iBAAA,CAAkB,IAAI,CAAA;AACzF,IAAA,IAAI,SAAS,OAAO,KAAA,KAAU,QAAA,EAAU,eAAA,CAAgB,OAA2B,IAAI,CAAA;AAAA,EACzF;AACF;AAGO,SAAS,iBAAiB,UAAA,EAA4H;AAC3J,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,UAAU,CAAA,IAAK,UAAA,CAAW,MAAA,KAAW,CAAA,EAAG,MAAM,IAAI,KAAA,CAAM,uBAAuB,CAAA;AAClG,EAAA,IAAI,WAAW,MAAA,GAAS,GAAA,EAAM,MAAM,IAAI,MAAM,wCAAwC,CAAA;AACtF,EAAA,OAAO,UAAA,CAAW,GAAA,CAAI,CAAC,CAAA,EAAG,CAAA,KAAM;AAC9B,IAAA,IAAI,OAAO,MAAM,QAAA,EAAU;AACzB,MAAA,IAAI,CAAC,IAAA,CAAK,IAAA,CAAK,CAAC,CAAA,QAAS,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqB,CAAC,CAAA,iBAAA,CAAmB,CAAA;AAC5E,MAAA,OAAO,EAAE,SAAS,CAAA,EAAE;AAAA,IACtB;AACA,IAAA,IAAI,YAAY,CAAA,EAAG;AACjB,MAAA,IAAI,CAAC,IAAA,CAAK,IAAA,CAAK,CAAA,CAAE,MAAM,CAAA,EAAG,MAAM,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqB,CAAC,CAAA,iBAAA,CAAmB,CAAA;AACnF,MAAA,IAAI,EAAE,KAAA,KAAU,MAAA,SAAkB,EAAE,OAAA,EAAS,EAAE,MAAA,EAAO;AACtD,MAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,CAAA,CAAE,KAAK,KAAK,CAAA,CAAE,KAAA,GAAQ,CAAA,IAAK,CAAA,CAAE,QAAQ,KAAA,EAAO,MAAM,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqB,CAAC,CAAA,iCAAA,CAAmC,CAAA;AAC3I,MAAA,OAAO,EAAE,OAAA,EAAS,CAAA,CAAE,MAAA,EAAQ,KAAA,EAAO,EAAE,KAAA,EAAM;AAAA,IAC7C;AACA,IAAA,IAAI,WAAW,CAAA,EAAG;AAChB,MAAA,MAAM,KAAA,GAAQ,CAAA,CAAE,KAAA,CAAM,IAAA,EAAK;AAC3B,MAAA,IAAI,CAAC,KAAA,CAAM,IAAA,CAAK,KAAK,CAAA,IAAK,KAAA,CAAM,MAAA,GAAS,GAAA,EAAK,MAAM,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqB,CAAC,CAAA,2BAAA,CAA6B,CAAA;AACjH,MAAA,OAAO,EAAE,KAAA,EAAO,GAAI,CAAA,CAAE,IAAA,GAAO,EAAE,IAAA,EAAM,CAAA,CAAE,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA,EAAE,GAAI,EAAC,EAAI,GAAI,CAAA,CAAE,GAAA,GAAM,EAAE,GAAA,EAAK,CAAA,CAAE,GAAA,CAAI,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA,EAAE,GAAI,EAAC,EAAG;AAAA,IACpH;AACA,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqB,CAAC,CAAA,kCAAA,CAAoC,CAAA;AAAA,EAC5E,CAAC,CAAA;AACH","file":"chunk-7PHA3WVG.js","sourcesContent":["/**\n * Checks `notify()` runs before anything reaches the database (which checks\n * the same again): recipients are well formed, and `data` holds no secret.\n */\nimport type { NotificationData } from \"./registry\";\nimport type { Recipient } from \"./types\";\n\nconst UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nconst EMAIL = /^[^\\s@<>,;:\"()[\\]\\\\]+@[^\\s@<>,;:\"()[\\]\\\\]+\\.[^\\s@<>,;:\"()[\\]\\\\]+$/;\n\n/**\n * Keys that hold a secret by their name, matched on the key split into words\n * (`inviteToken` is `invite_token`): any key ending in token, code, secret,\n * key, otp or password, and a few more by word. The database refuses the same\n * list. A backstop, not a guarantee: it catches the usual names, so a display\n * value named that way (`country_code`) is refused too; name it otherwise.\n */\nexport const SECRET_KEY = /((token|code|secret|key|otp|password)|(^|[._-])(signature|sig|magic_?link|invite_?link|reset_?link))$/;\n\n/** A key as words, lower case: `inviteToken` → `invite_token`. */\nexport function keyWords(key: string): string {\n  return key.replace(/([a-z0-9])([A-Z])/g, \"$1_$2\").toLowerCase();\n}\n/**\n * A link, absolute (`https://…`, `mailto:…`) or relative (`/…`, `./…`, `?…`,\n * `#…`), with a query or fragment parameter whose name ends in token, code,\n * secret, key, otp, password, sig or signature (`?token=`, `#access_token=`,\n * `&inviteCode=`).\n */\nexport const SECRET_URL = /^([a-z][a-z0-9+.-]*:|\\/|\\.\\.?\\/|(?=[?#]))\\S*[?&#;][^=&#;\\s]*(token|code|secret|key|otp|password|signature|sig)=/i;\n\n/** `data` held something that looks like a secret: build such links at send time instead. */\nexport class SecretInDataError extends Error {\n  constructor(readonly path: string) {\n    super(`notify: data.${path} looks like a secret. Store a reference and build the link at send time with resolveSecretLink.`);\n    this.name = \"SecretInDataError\";\n  }\n}\n\n/** Throws a `SecretInDataError` naming the first key (or link) that looks like a secret. */\nexport function assertNoSecrets(data: NotificationData | undefined, path = \"\"): void {\n  if (!data || typeof data !== \"object\") return;\n  for (const [key, value] of Object.entries(data)) {\n    const here = path ? `${path}.${key}` : key;\n    if (SECRET_KEY.test(keyWords(key))) throw new SecretInDataError(here);\n    if (typeof value === \"string\" && SECRET_URL.test(value)) throw new SecretInDataError(here);\n    if (value && typeof value === \"object\") assertNoSecrets(value as NotificationData, here);\n  }\n}\n\n/** The recipients as `genesis_notify` takes them; throws on a malformed one. */\nexport function recipientsToJson(recipients: readonly Recipient[]): ({ user_id: string; badge?: number } | { email: string; name?: string; ref?: string })[] {\n  if (!Array.isArray(recipients) || recipients.length === 0) throw new Error(\"notify: no recipients\");\n  if (recipients.length > 1000) throw new Error(\"notify: at most 1000 recipients a call\");\n  return recipients.map((r, i) => {\n    if (typeof r === \"string\") {\n      if (!UUID.test(r)) throw new Error(`notify: recipient ${i} is not a user id`);\n      return { user_id: r };\n    }\n    if (\"userId\" in r) {\n      if (!UUID.test(r.userId)) throw new Error(`notify: recipient ${i} is not a user id`);\n      if (r.badge === undefined) return { user_id: r.userId };\n      if (!Number.isInteger(r.badge) || r.badge < 0 || r.badge > 99999) throw new Error(`notify: recipient ${i}'s badge is a whole number from 0`);\n      return { user_id: r.userId, badge: r.badge };\n    }\n    if (\"email\" in r) {\n      const email = r.email.trim();\n      if (!EMAIL.test(email) || email.length > 254) throw new Error(`notify: recipient ${i} has no valid email address`);\n      return { email, ...(r.name ? { name: r.name.slice(0, 200) } : {}), ...(r.ref ? { ref: r.ref.slice(0, 200) } : {}) };\n    }\n    throw new Error(`notify: recipient ${i} is neither a user id nor an email`);\n  });\n}\n"]}