@aglyn/aglyn 1.0.0-beta.147 → 1.0.0-beta.150

package/src/lib/app-utils/media-src.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A usable `src` for a picked media asset.
+ *
+ * Lifted out of the listing detail editor when the publish form gained a
+ * media picker of its own (AGL-1080).
+ *
+ * NO LONGER THE WRITER FOR MARKDOWN BODIES (AGL-1705). This helper used to
+ * justify prefixing the origin by saying the markdown "renders elsewhere".
+ * That claim was checked and is false: the marketplace README's only renderer
+ * is the console's own `marketplaceListing` slot, and `apps/tenant` does not
+ * import the marketplace plugin. The two README writers and the blog body now
+ * store `mediaNodeSrc`'s `media:` reference, which `resolveMediaSrc` turns
+ * back into this same `/api/media/cdn/…` path at render — without freezing
+ * either the origin or the route shape into the document.
+ *
+ * What is left for this helper is the listing's image FIELDS —
+ * `previewImageUrl`, `logoUrl`, `screenshots` — read out of band by
+ * `og:image` and by `resolveSocialImage`, where an absolute URL is the point
+ * (AGL-1701). The origin prefix stays for them.
+ */
+export declare function mediaSrc(media: {
+    url?: string;
+    cdnPath?: string;
+}): string;
+/**
+ * A `src` for a THUMBNAIL — a grid tile, a picker cell, a preview strip.
+ *
+ * Separate from {@link mediaSrc} because the two answer different questions.
+ * `mediaSrc` produces a URL that gets *persisted* (markdown bodies, listing
+ * images), so it must stay width-free. This one produces a URL that is only
+ * ever rendered, so it can ask for the smallest generated WebP variant.
+ *
+ * The DAM grid read `media.url` directly, which is the raw
+ * `firebasestorage.googleapis.com` download URL: every tile fetched the
+ * FULL-SIZE original straight from Cloud Storage, bypassing both the WebP
+ * variants (AGL-175) and the Vercel edge cache. A library page of 24 assets
+ * at ~200 KB each is ~4.8 MB of Storage egress per view, re-fetched by every
+ * viewer, where the 320px variants are ~15 KB each.
+ *
+ * `?w=` degrades safely: `serveMediaCdn` only serves a variant when the
+ * asset's `variants` array actually contains that width, and otherwise
+ * serves the original — so an SVG, a small logo, or an asset uploaded before
+ * variants existed still renders, just without the saving.
+ */
+export declare function mediaThumbnailSrc(media: {
+    url?: string;
+    cdnPath?: string;
+}, width: number): string;
+/**
+ * A `src` for a VIDEO's poster still, or `undefined` when it has none
+ * (AGL-2742).
+ *
+ * The DAM grid drew a video tile as a `<video src>` pointing at the master.
+ * A browser paints a first frame by fetching enough of the file to decode
+ * one, so a folder of eight clips was tens of megabytes of Storage egress
+ * per view — the same defect {@link mediaThumbnailSrc} was written to fix for
+ * images, on the type where each tile costs a hundred times more. And unlike
+ * an image tile it could not be helped by a variant, because until now a
+ * video had nothing smaller to serve.
+ *
+ * Returns `undefined` rather than a fallback URL on purpose: the caller has
+ * to branch anyway (a `<video>` with no poster still needs `preload="none"`
+ * so it stops fetching), and an "always answers" helper would hand back a URL
+ * that 404s for every video uploaded before this shipped.
+ *
+ * Mirrors `Aglyn.mediaPosterSrc` for a media DOCUMENT rather than a stored
+ * `media:` reference — the console holds documents, the renderer holds
+ * references, and neither can use the other's input.
+ */
+export declare function mediaPosterThumbnailSrc(media: {
+    url?: string;
+    cdnPath?: string;
+    poster?: {
+        variants?: number[];
+    } | null;
+}, width?: number): string | undefined;
+export default mediaSrc;

package/src/lib/app-utils/media-src.js

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A usable `src` for a picked media asset.
+ *
+ * Lifted out of the listing detail editor when the publish form gained a
+ * media picker of its own (AGL-1080).
+ *
+ * NO LONGER THE WRITER FOR MARKDOWN BODIES (AGL-1705). This helper used to
+ * justify prefixing the origin by saying the markdown "renders elsewhere".
+ * That claim was checked and is false: the marketplace README's only renderer
+ * is the console's own `marketplaceListing` slot, and `apps/tenant` does not
+ * import the marketplace plugin. The two README writers and the blog body now
+ * store `mediaNodeSrc`'s `media:` reference, which `resolveMediaSrc` turns
+ * back into this same `/api/media/cdn/…` path at render — without freezing
+ * either the origin or the route shape into the document.
+ *
+ * What is left for this helper is the listing's image FIELDS —
+ * `previewImageUrl`, `logoUrl`, `screenshots` — read out of band by
+ * `og:image` and by `resolveSocialImage`, where an absolute URL is the point
+ * (AGL-1701). The origin prefix stays for them.
+ */ export function mediaSrc(media) {
+    // `cdnPath` FIRST (AGL-1215). It is keyed by media id, so it survives a
+    // folder move — which physically copies the object, rewrites `url` and
+    // deletes the original, permanently breaking anything holding the old
+    // raw URL. Preferring `url` meant this helper emitted the fragile form
+    // for every paid org, where both fields are always populated. `url`
+    // stays the fallback for free-tier orgs (`cdnPath` is a paid `mediaCdn`
+    // entitlement) and legacy uploads that predate it.
+    if (media.cdnPath) return typeof window === 'undefined' ? media.cdnPath : `${window.location.origin}${media.cdnPath}`;
+    if (media.url) return media.url;
+    return '';
+}
+/**
+ * A `src` for a THUMBNAIL — a grid tile, a picker cell, a preview strip.
+ *
+ * Separate from {@link mediaSrc} because the two answer different questions.
+ * `mediaSrc` produces a URL that gets *persisted* (markdown bodies, listing
+ * images), so it must stay width-free. This one produces a URL that is only
+ * ever rendered, so it can ask for the smallest generated WebP variant.
+ *
+ * The DAM grid read `media.url` directly, which is the raw
+ * `firebasestorage.googleapis.com` download URL: every tile fetched the
+ * FULL-SIZE original straight from Cloud Storage, bypassing both the WebP
+ * variants (AGL-175) and the Vercel edge cache. A library page of 24 assets
+ * at ~200 KB each is ~4.8 MB of Storage egress per view, re-fetched by every
+ * viewer, where the 320px variants are ~15 KB each.
+ *
+ * `?w=` degrades safely: `serveMediaCdn` only serves a variant when the
+ * asset's `variants` array actually contains that width, and otherwise
+ * serves the original — so an SVG, a small logo, or an asset uploaded before
+ * variants existed still renders, just without the saving.
+ */ export function mediaThumbnailSrc(media, width) {
+    const cdnPath = media.cdnPath;
+    // No `cdnPath` means a free-tier or private asset, and a width parameter
+    // on a raw storage URL means nothing — appending one would only fork the
+    // browser cache for identical bytes.
+    if (!cdnPath) return mediaSrc(media);
+    // A signed private URL already carries `?exp=&sig=`; a second `?` makes a
+    // path the route rejects outright.
+    if (cdnPath.includes('?')) return mediaSrc(media);
+    return `${mediaSrc(media)}?w=${width}`;
+}
+/**
+ * A `src` for a VIDEO's poster still, or `undefined` when it has none
+ * (AGL-2742).
+ *
+ * The DAM grid drew a video tile as a `<video src>` pointing at the master.
+ * A browser paints a first frame by fetching enough of the file to decode
+ * one, so a folder of eight clips was tens of megabytes of Storage egress
+ * per view — the same defect {@link mediaThumbnailSrc} was written to fix for
+ * images, on the type where each tile costs a hundred times more. And unlike
+ * an image tile it could not be helped by a variant, because until now a
+ * video had nothing smaller to serve.
+ *
+ * Returns `undefined` rather than a fallback URL on purpose: the caller has
+ * to branch anyway (a `<video>` with no poster still needs `preload="none"`
+ * so it stops fetching), and an "always answers" helper would hand back a URL
+ * that 404s for every video uploaded before this shipped.
+ *
+ * Mirrors `Aglyn.mediaPosterSrc` for a media DOCUMENT rather than a stored
+ * `media:` reference — the console holds documents, the renderer holds
+ * references, and neither can use the other's input.
+ */ export function mediaPosterThumbnailSrc(media, width) {
+    var _media_poster_variants;
+    // A poster is only reachable through the CDN route, so a free-tier or
+    // private asset has no URL that could serve one — the same reason
+    // `mediaThumbnailSrc` gives up on `?w=` there.
+    if (!media.poster || !media.cdnPath || media.cdnPath.includes('?')) {
+        return undefined;
+    }
+    const variants = (_media_poster_variants = media.poster.variants) != null ? _media_poster_variants : [];
+    // Only a width that was actually generated. `serveMediaCdn` would fall
+    // back to the full poster for any other, which works and defeats the point
+    // — a 1920px still in a 116px tile.
+    const narrowed = width && variants.includes(width) ? `&w=${width}` : '';
+    return `${mediaSrc(media)}?poster=1${narrowed}`;
+}
+export default mediaSrc;
+
+//# sourceMappingURL=media-src.js.map

package/src/lib/app-utils/media-src.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/media-src.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A usable `src` for a picked media asset.\n *\n * Lifted out of the listing detail editor when the publish form gained a\n * media picker of its own (AGL-1080).\n *\n * NO LONGER THE WRITER FOR MARKDOWN BODIES (AGL-1705). This helper used to\n * justify prefixing the origin by saying the markdown \"renders elsewhere\".\n * That claim was checked and is false: the marketplace README's only renderer\n * is the console's own `marketplaceListing` slot, and `apps/tenant` does not\n * import the marketplace plugin. The two README writers and the blog body now\n * store `mediaNodeSrc`'s `media:` reference, which `resolveMediaSrc` turns\n * back into this same `/api/media/cdn/…` path at render — without freezing\n * either the origin or the route shape into the document.\n *\n * What is left for this helper is the listing's image FIELDS —\n * `previewImageUrl`, `logoUrl`, `screenshots` — read out of band by\n * `og:image` and by `resolveSocialImage`, where an absolute URL is the point\n * (AGL-1701). The origin prefix stays for them.\n */\nexport function mediaSrc(media: {\n  url?: string\n  cdnPath?: string\n}): string {\n  // `cdnPath` FIRST (AGL-1215). It is keyed by media id, so it survives a\n  // folder move — which physically copies the object, rewrites `url` and\n  // deletes the original, permanently breaking anything holding the old\n  // raw URL. Preferring `url` meant this helper emitted the fragile form\n  // for every paid org, where both fields are always populated. `url`\n  // stays the fallback for free-tier orgs (`cdnPath` is a paid `mediaCdn`\n  // entitlement) and legacy uploads that predate it.\n  if (media.cdnPath)\n    return typeof window === 'undefined'\n      ? media.cdnPath\n      : `${window.location.origin}${media.cdnPath}`\n  if (media.url) return media.url\n  return ''\n}\n\n/**\n * A `src` for a THUMBNAIL — a grid tile, a picker cell, a preview strip.\n *\n * Separate from {@link mediaSrc} because the two answer different questions.\n * `mediaSrc` produces a URL that gets *persisted* (markdown bodies, listing\n * images), so it must stay width-free. This one produces a URL that is only\n * ever rendered, so it can ask for the smallest generated WebP variant.\n *\n * The DAM grid read `media.url` directly, which is the raw\n * `firebasestorage.googleapis.com` download URL: every tile fetched the\n * FULL-SIZE original straight from Cloud Storage, bypassing both the WebP\n * variants (AGL-175) and the Vercel edge cache. A library page of 24 assets\n * at ~200 KB each is ~4.8 MB of Storage egress per view, re-fetched by every\n * viewer, where the 320px variants are ~15 KB each.\n *\n * `?w=` degrades safely: `serveMediaCdn` only serves a variant when the\n * asset's `variants` array actually contains that width, and otherwise\n * serves the original — so an SVG, a small logo, or an asset uploaded before\n * variants existed still renders, just without the saving.\n */\nexport function mediaThumbnailSrc(\n  media: { url?: string; cdnPath?: string },\n  width: number,\n): string {\n  const cdnPath = media.cdnPath\n  // No `cdnPath` means a free-tier or private asset, and a width parameter\n  // on a raw storage URL means nothing — appending one would only fork the\n  // browser cache for identical bytes.\n  if (!cdnPath) return mediaSrc(media)\n  // A signed private URL already carries `?exp=&sig=`; a second `?` makes a\n  // path the route rejects outright.\n  if (cdnPath.includes('?')) return mediaSrc(media)\n  return `${mediaSrc(media)}?w=${width}`\n}\n\n/**\n * A `src` for a VIDEO's poster still, or `undefined` when it has none\n * (AGL-2742).\n *\n * The DAM grid drew a video tile as a `<video src>` pointing at the master.\n * A browser paints a first frame by fetching enough of the file to decode\n * one, so a folder of eight clips was tens of megabytes of Storage egress\n * per view — the same defect {@link mediaThumbnailSrc} was written to fix for\n * images, on the type where each tile costs a hundred times more. And unlike\n * an image tile it could not be helped by a variant, because until now a\n * video had nothing smaller to serve.\n *\n * Returns `undefined` rather than a fallback URL on purpose: the caller has\n * to branch anyway (a `<video>` with no poster still needs `preload=\"none\"`\n * so it stops fetching), and an \"always answers\" helper would hand back a URL\n * that 404s for every video uploaded before this shipped.\n *\n * Mirrors `Aglyn.mediaPosterSrc` for a media DOCUMENT rather than a stored\n * `media:` reference — the console holds documents, the renderer holds\n * references, and neither can use the other's input.\n */\nexport function mediaPosterThumbnailSrc(\n  media: {\n    url?: string\n    cdnPath?: string\n    poster?: { variants?: number[] } | null\n  },\n  width?: number,\n): string | undefined {\n  // A poster is only reachable through the CDN route, so a free-tier or\n  // private asset has no URL that could serve one — the same reason\n  // `mediaThumbnailSrc` gives up on `?w=` there.\n  if (!media.poster || !media.cdnPath || media.cdnPath.includes('?')) {\n    return undefined\n  }\n  const variants = media.poster.variants ?? []\n  // Only a width that was actually generated. `serveMediaCdn` would fall\n  // back to the full poster for any other, which works and defeats the point\n  // — a 1920px still in a 116px tile.\n  const narrowed = width && variants.includes(width) ? `&w=${width}` : ''\n  return `${mediaSrc(media)}?poster=1${narrowed}`\n}\n\nexport default mediaSrc\n"],"names":["mediaSrc","media","cdnPath","window","location","origin","url","mediaThumbnailSrc","width","includes","mediaPosterThumbnailSrc","poster","undefined","variants","narrowed"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASA,SAASC,KAGxB;IACC,wEAAwE;IACxE,uEAAuE;IACvE,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,wEAAwE;IACxE,mDAAmD;IACnD,IAAIA,MAAMC,OAAO,EACf,OAAO,OAAOC,WAAW,cACrBF,MAAMC,OAAO,GACb,GAAGC,OAAOC,QAAQ,CAACC,MAAM,GAAGJ,MAAMC,OAAO,EAAE;IACjD,IAAID,MAAMK,GAAG,EAAE,OAAOL,MAAMK,GAAG;IAC/B,OAAO;AACT;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,kBACdN,KAAyC,EACzCO,KAAa;IAEb,MAAMN,UAAUD,MAAMC,OAAO;IAC7B,yEAAyE;IACzE,yEAAyE;IACzE,qCAAqC;IACrC,IAAI,CAACA,SAAS,OAAOF,SAASC;IAC9B,0EAA0E;IAC1E,mCAAmC;IACnC,IAAIC,QAAQO,QAAQ,CAAC,MAAM,OAAOT,SAASC;IAC3C,OAAO,GAAGD,SAASC,OAAO,GAAG,EAAEO,OAAO;AACxC;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASE,wBACdT,KAIC,EACDO,KAAc;QAQGP;IANjB,sEAAsE;IACtE,kEAAkE;IAClE,+CAA+C;IAC/C,IAAI,CAACA,MAAMU,MAAM,IAAI,CAACV,MAAMC,OAAO,IAAID,MAAMC,OAAO,CAACO,QAAQ,CAAC,MAAM;QAClE,OAAOG;IACT;IACA,MAAMC,YAAWZ,yBAAAA,MAAMU,MAAM,CAACE,QAAQ,YAArBZ,yBAAyB,EAAE;IAC5C,uEAAuE;IACvE,2EAA2E;IAC3E,oCAAoC;IACpC,MAAMa,WAAWN,SAASK,SAASJ,QAAQ,CAACD,SAAS,CAAC,GAAG,EAAEA,OAAO,GAAG;IACrE,OAAO,GAAGR,SAASC,OAAO,SAAS,EAAEa,UAAU;AACjD;AAEA,eAAed,SAAQ"}

package/src/lib/app-utils/notifications.d.ts

@@ -22,7 +22,7 @@ import type { ITimestamp } from '@aglyn/shared-util-timestamp';
  * their owner. Types follow the common SaaS taxonomy so the console can
  * icon/group them without a registry.
  */
-export type AglynNotificationType = 'billing.invoice' | 'billing.paymentFailed' | 'billing.subscriptionCanceled' | 'billing.usage' | 'team.invite' | 'team.roleChanged' | 'team.hostAccessGranted' | 'content.formSubmission' | 'content.booking' | 'content.order' | 'content.lowStock' | 'content.taskAssigned' | 'content.taskReminder' | 'content.contactAssigned' | 'content.leadAssigned' | 'content.crmDailyDigest' | 'content.insightsDigest' | 'marketplace.review' | 'support.ticketOpened' | 'support.ticketReply' | 'system.announcement' | 'system.pluginVerifierRegression' | 'system.signInMethodRemoved' | 'system.scopeDrift' | 'system.ssoDomainUnverified' | 'system.formSubmissionsPaused' | 'system.visitorRecordsPaused' | 'system.abuseReportUrgent' | 'system.dmcaCounterNotice' | 'system.bandwidthCeilingTripped' | 'system.bandwidthCapEngaged' | 'system.billingWebhookHalfApplied' | 'system.disputeUnattributed';
+export type AglynNotificationType = 'billing.invoice' | 'billing.paymentFailed' | 'billing.subscriptionCanceled' | 'billing.usage' | 'team.invite' | 'team.roleChanged' | 'team.hostAccessGranted' | 'content.formSubmission' | 'content.booking' | 'content.order' | 'content.lowStock' | 'content.taskAssigned' | 'content.taskReminder' | 'content.contactAssigned' | 'content.leadAssigned' | 'content.crmDailyDigest' | 'content.insightsDigest' | 'marketplace.review' | 'support.ticketOpened' | 'support.ticketReply' | 'system.announcement' | 'system.pluginVerifierRegression' | 'system.signInMethodRemoved' | 'system.scopeDrift' | 'system.ssoDomainUnverified' | 'system.formSubmissionsPaused' | 'system.visitorRecordsPaused' | 'system.abuseReportUrgent' | 'system.dmcaCounterNotice' | 'system.bandwidthCeilingTripped' | 'system.bandwidthCapEngaged' | 'system.billingWebhookHalfApplied' | 'system.disputeUnattributed' | 'staff.userSignedUp' | 'staff.orgCreated';
 export interface AglynNotification {
     $id?: string;
     type: AglynNotificationType;
@@ -38,8 +38,17 @@ export interface AglynNotification {
 }
 export declare const NOTIFICATION_TYPE_LABELS: Record<AglynNotificationType, string>;
 /** Preference buckets (AGL-267): the prefix before the dot. */
-export type NotificationCategory = 'billing' | 'team' | 'content' | 'marketplace' | 'support' | 'system';
+export type NotificationCategory = 'billing' | 'team' | 'content' | 'marketplace' | 'support' | 'system' | 'staff';
 export declare const NOTIFICATION_CATEGORY_LABELS: Record<NotificationCategory, string>;
+/**
+ * The categories only staff can receive (AGL-3225).
+ *
+ * The settings page hides these rows from everybody else, because a switch
+ * for mail that can never arrive is a promise the product does not keep. It
+ * is presentation only: `notifyStaff` is what decides the audience, and it
+ * enumerates the `staff` claim rather than reading this.
+ */
+export declare const STAFF_NOTIFICATION_CATEGORIES: ReadonlySet<NotificationCategory>;
 export declare function notificationCategory(type: AglynNotificationType | string): NotificationCategory;
 /**
  * Per-user mute map stored at `users/{uid}.notificationPrefs`
@@ -69,3 +78,128 @@ export declare function crmDailyDigestEnabled(prefs: Record<string, boolean> | n
 export declare const INSIGHT_DIGESTS_FIELD = "insightDigests";
 /** Whether a person asked for a workspace's weekly insights. */
 export declare function insightDigestSubscribed(value: Record<string, boolean> | null | undefined, orgId: string): boolean;
+/**
+ * The channels a notification can travel on (AGL-3223).
+ *
+ * `console` is the feed at `/manage/notifications` and the app-bar dropdown
+ * that reads it — the only channel that existed. `email` is the message the
+ * fan-out sends beside that doc when the recipient asked for one.
+ */
+export type NotificationChannel = 'console' | 'email';
+/**
+ * One scope's answer for one category. **Tri-state on purpose**: `true` and
+ * `false` decide, and an ABSENT key inherits from the scope above.
+ *
+ * Inheritance is the whole reason this is a partial rather than a pair of
+ * booleans. A person who wants form submissions from one busy site and not
+ * from the other five has to be able to say that about the one site without
+ * restating their answer for every other category at every other scope — and
+ * a two-valued leaf cannot express "I have not said", so every override would
+ * have to be written out in full and would then stop tracking the account
+ * default it was never meant to detach from.
+ */
+export interface NotificationChannelPrefs {
+    console?: boolean;
+    email?: boolean;
+}
+export type NotificationCategoryPrefs = Partial<Record<NotificationCategory, NotificationChannelPrefs>>;
+/**
+ * Per-scope, per-channel notification preferences (AGL-3223), stored at
+ * `users/{uid}.notificationSettings`.
+ *
+ * Three layers, narrowest first when resolving: the SITE a notification
+ * concerns, then the WORKSPACE, then the account. Anything none of them
+ * answers falls to {@link NOTIFICATION_CHANNEL_DEFAULTS}.
+ *
+ * ON THE USER DOCUMENT, not on `orgs/{orgId}/members/{uid}`, and that is a
+ * cost decision rather than a modelling preference. `notifyUsers` already
+ * does exactly one `getAll` over the recipients' user docs to read their
+ * category mutes, so every layer living here means per-site preferences are
+ * read for free on the fan-out's hot path. The member row would add a read
+ * per recipient per notification to answer a question the document already in
+ * hand could have answered.
+ */
+export interface NotificationSettings {
+    account?: NotificationCategoryPrefs;
+    /** Keyed by org id. */
+    orgs?: Record<string, NotificationCategoryPrefs>;
+    /** Keyed by host id — a site's own answer, narrower than its workspace's. */
+    hosts?: Record<string, NotificationCategoryPrefs>;
+}
+export declare const NOTIFICATION_SETTINGS_FIELD = "notificationSettings";
+/**
+ * What a category does when nobody has said otherwise.
+ *
+ * Console on, email OFF, everywhere. Email defaults off because the inbox is
+ * not ours to fill: the product already sends transactional mail nobody opted
+ * into — welcome, verification, invites, dunning, usage alerts — and every one
+ * of those leaves on the same domain a customer's password reset depends on.
+ * Turning a busy site's form submissions into mail by default would put that
+ * domain's reputation behind traffic the recipient never asked for.
+ *
+ * Exhaustive `Record` deliberately: a new {@link NotificationCategory} is a
+ * compile error here until somebody decides what it does by default, which is
+ * the one question a new category must not be able to ship without answering.
+ */
+export declare const NOTIFICATION_CHANNEL_DEFAULTS: Record<NotificationCategory, Record<NotificationChannel, boolean>>;
+/**
+ * The types that send their OWN email and must never be mailed again by the
+ * generic channel (AGL-3224).
+ *
+ * Both digests compose a message the fan-out could not reproduce — a day's
+ * owed tasks, a week's figures — and send it from their own route under their
+ * own switch (`digestPrefs.crmDaily`, `insightDigests.{orgId}`). A recipient
+ * who switches the `content` email channel on would otherwise receive the
+ * digest twice: once as the digest, once as a one-line "Daily CRM digest"
+ * notification saying that the digest happened.
+ */
+export declare const NOTIFICATION_SELF_SENT_EMAIL_TYPES: ReadonlySet<string>;
+/**
+ * Whether a channel is on for one notification, at its own scope.
+ *
+ * Resolution order, first answer wins: the notification's SITE, its
+ * WORKSPACE, the account, then {@link NOTIFICATION_CHANNEL_DEFAULTS}. A scope
+ * that holds no entry for the category, or an entry with the channel key
+ * absent, does not answer — see {@link NotificationChannelPrefs}.
+ *
+ * `legacyPrefs` is the flat `notificationPrefs` mute map this replaces
+ * (AGL-267), and it sits BELOW the account layer rather than beside it.
+ * Nothing migrates it: a person who never opens the new settings page keeps
+ * being governed by the mutes they set years ago, and the first thing they do
+ * set on the account layer overrides the old map for that category without
+ * disturbing the rest of it. It answers for `console` only, because the map
+ * predates there being a second channel and reading a console mute as an
+ * email preference would be inventing an answer its author never gave.
+ */
+export declare function notificationChannelEnabled(settings: NotificationSettings | null | undefined, channel: NotificationChannel, type: AglynNotificationType | string, scope?: {
+    orgId?: string | null;
+    hostId?: string | null;
+}, legacyPrefs?: Record<string, boolean> | null): boolean;
+/**
+ * What one scope says, with no inheritance applied — what the settings page
+ * renders as Inherit / On / Off, and `undefined` is Inherit.
+ *
+ * `scope` names the layer directly rather than being derived from a
+ * notification, because the page edits a layer whether or not anything has
+ * ever arrived from it.
+ */
+export declare function notificationScopePref(settings: NotificationSettings | null | undefined, scope: {
+    kind: 'account';
+} | {
+    kind: 'org' | 'host';
+    id: string;
+}, category: NotificationCategory, channel: NotificationChannel): boolean | undefined;
+/**
+ * The scopes this person has said something different about — what the
+ * settings page lists so an override is never somewhere you have to go
+ * looking for.
+ *
+ * Returns ids, not names: the page holds the org and host rosters and this
+ * module holds no lookups. An id with no name is still worth listing, because
+ * a preference about a workspace somebody left is exactly the kind of
+ * leftover that is invisible until it is listed.
+ */
+export declare function notificationOverriddenScopes(settings: NotificationSettings | null | undefined): {
+    orgIds: string[];
+    hostIds: string[];
+};

package/src/lib/app-utils/notifications.js

@@ -46,7 +46,9 @@
     'system.bandwidthCeilingTripped': 'Bandwidth ceiling reached',
     'system.bandwidthCapEngaged': 'Monthly traffic limit reached',
     'system.billingWebhookHalfApplied': 'Billing webhook half applied',
-    'system.disputeUnattributed': 'Card dispute with no owner'
+    'system.disputeUnattributed': 'Card dispute with no owner',
+    'staff.userSignedUp': 'New account',
+    'staff.orgCreated': 'New workspace'
 };
 export const NOTIFICATION_CATEGORY_LABELS = {
     billing: 'Billing',
@@ -54,8 +56,19 @@ export const NOTIFICATION_CATEGORY_LABELS = {
     content: 'Forms & bookings',
     marketplace: 'Marketplace',
     support: 'Support',
-    system: 'Product & system'
+    system: 'Product & system',
+    staff: 'Platform growth'
 };
+/**
+ * The categories only staff can receive (AGL-3225).
+ *
+ * The settings page hides these rows from everybody else, because a switch
+ * for mail that can never arrive is a promise the product does not keep. It
+ * is presentation only: `notifyStaff` is what decides the audience, and it
+ * enumerates the `staff` claim rather than reading this.
+ */ export const STAFF_NOTIFICATION_CATEGORIES = new Set([
+    'staff'
+]);
 export function notificationCategory(type) {
     const prefix = String(type).split('.')[0];
     return [
@@ -64,7 +77,8 @@ export function notificationCategory(type) {
         'content',
         'marketplace',
         'support',
-        'system'
+        'system',
+        'staff'
     ].includes(prefix) ? prefix : 'system';
 }
 /**
@@ -97,5 +111,127 @@ export function crmDailyDigestEnabled(prefs) {
 /** Whether a person asked for a workspace's weekly insights. */ export function insightDigestSubscribed(value, orgId) {
     return Boolean(orgId) && (value == null ? void 0 : value[orgId]) === true;
 }
+export const NOTIFICATION_SETTINGS_FIELD = 'notificationSettings';
+/**
+ * What a category does when nobody has said otherwise.
+ *
+ * Console on, email OFF, everywhere. Email defaults off because the inbox is
+ * not ours to fill: the product already sends transactional mail nobody opted
+ * into — welcome, verification, invites, dunning, usage alerts — and every one
+ * of those leaves on the same domain a customer's password reset depends on.
+ * Turning a busy site's form submissions into mail by default would put that
+ * domain's reputation behind traffic the recipient never asked for.
+ *
+ * Exhaustive `Record` deliberately: a new {@link NotificationCategory} is a
+ * compile error here until somebody decides what it does by default, which is
+ * the one question a new category must not be able to ship without answering.
+ */ export const NOTIFICATION_CHANNEL_DEFAULTS = {
+    billing: {
+        console: true,
+        email: false
+    },
+    team: {
+        console: true,
+        email: false
+    },
+    content: {
+        console: true,
+        email: false
+    },
+    marketplace: {
+        console: true,
+        email: false
+    },
+    support: {
+        console: true,
+        email: false
+    },
+    system: {
+        console: true,
+        email: false
+    },
+    // Console ON, because the complaint this answers is that staff never heard
+    // about a sign-up at all; email off, like everything else, because that is
+    // what the channel defaults to and a sign-up is not urgent enough to be the
+    // exception that starts filling inboxes by default.
+    staff: {
+        console: true,
+        email: false
+    }
+};
+/**
+ * The types that send their OWN email and must never be mailed again by the
+ * generic channel (AGL-3224).
+ *
+ * Both digests compose a message the fan-out could not reproduce — a day's
+ * owed tasks, a week's figures — and send it from their own route under their
+ * own switch (`digestPrefs.crmDaily`, `insightDigests.{orgId}`). A recipient
+ * who switches the `content` email channel on would otherwise receive the
+ * digest twice: once as the digest, once as a one-line "Daily CRM digest"
+ * notification saying that the digest happened.
+ */ export const NOTIFICATION_SELF_SENT_EMAIL_TYPES = new Set([
+    'content.crmDailyDigest',
+    'content.insightsDigest'
+]);
+/**
+ * Whether a channel is on for one notification, at its own scope.
+ *
+ * Resolution order, first answer wins: the notification's SITE, its
+ * WORKSPACE, the account, then {@link NOTIFICATION_CHANNEL_DEFAULTS}. A scope
+ * that holds no entry for the category, or an entry with the channel key
+ * absent, does not answer — see {@link NotificationChannelPrefs}.
+ *
+ * `legacyPrefs` is the flat `notificationPrefs` mute map this replaces
+ * (AGL-267), and it sits BELOW the account layer rather than beside it.
+ * Nothing migrates it: a person who never opens the new settings page keeps
+ * being governed by the mutes they set years ago, and the first thing they do
+ * set on the account layer overrides the old map for that category without
+ * disturbing the rest of it. It answers for `console` only, because the map
+ * predates there being a second channel and reading a console mute as an
+ * email preference would be inventing an answer its author never gave.
+ */ export function notificationChannelEnabled(settings, channel, type, scope, legacyPrefs) {
+    var _settings_hosts, _settings_orgs;
+    const category = notificationCategory(type);
+    const layers = [
+        (scope == null ? void 0 : scope.hostId) ? settings == null ? void 0 : (_settings_hosts = settings.hosts) == null ? void 0 : _settings_hosts[scope.hostId] : undefined,
+        (scope == null ? void 0 : scope.orgId) ? settings == null ? void 0 : (_settings_orgs = settings.orgs) == null ? void 0 : _settings_orgs[scope.orgId] : undefined,
+        settings == null ? void 0 : settings.account
+    ];
+    for (const layer of layers){
+        var _layer_category;
+        const answer = layer == null ? void 0 : (_layer_category = layer[category]) == null ? void 0 : _layer_category[channel];
+        if (typeof answer === 'boolean') return answer;
+    }
+    if (channel === 'console' && notificationMuted(legacyPrefs, type)) return false;
+    return NOTIFICATION_CHANNEL_DEFAULTS[category][channel];
+}
+/**
+ * What one scope says, with no inheritance applied — what the settings page
+ * renders as Inherit / On / Off, and `undefined` is Inherit.
+ *
+ * `scope` names the layer directly rather than being derived from a
+ * notification, because the page edits a layer whether or not anything has
+ * ever arrived from it.
+ */ export function notificationScopePref(settings, scope, category, channel) {
+    var _settings_orgs, _settings_hosts, _layer_category;
+    const layer = scope.kind === 'account' ? settings == null ? void 0 : settings.account : scope.kind === 'org' ? settings == null ? void 0 : (_settings_orgs = settings.orgs) == null ? void 0 : _settings_orgs[scope.id] : settings == null ? void 0 : (_settings_hosts = settings.hosts) == null ? void 0 : _settings_hosts[scope.id];
+    return layer == null ? void 0 : (_layer_category = layer[category]) == null ? void 0 : _layer_category[channel];
+}
+/**
+ * The scopes this person has said something different about — what the
+ * settings page lists so an override is never somewhere you have to go
+ * looking for.
+ *
+ * Returns ids, not names: the page holds the org and host rosters and this
+ * module holds no lookups. An id with no name is still worth listing, because
+ * a preference about a workspace somebody left is exactly the kind of
+ * leftover that is invisible until it is listed.
+ */ export function notificationOverriddenScopes(settings) {
+    const named = (layers)=>Object.entries(layers != null ? layers : {}).filter(([, prefs])=>Object.values(prefs != null ? prefs : {}).some((channels)=>Object.values(channels != null ? channels : {}).some((value)=>typeof value === 'boolean'))).map(([id])=>id).sort();
+    return {
+        orgIds: named(settings == null ? void 0 : settings.orgs),
+        hostIds: named(settings == null ? void 0 : settings.hosts)
+    };
+}
 
 //# sourceMappingURL=notifications.js.map