@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/notifications.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\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\n\n/**\n * In-app notifications (AGL-259): per-user docs at\n * `users/{uid}/notifications/{id}`, written by the Admin SDK (emitters in\n * the API routes + the `notifyAdmins` automation step) and read/marked by\n * their owner. Types follow the common SaaS taxonomy so the console can\n * icon/group them without a registry.\n */\nexport type AglynNotificationType =\n  | 'billing.invoice'\n  | 'billing.paymentFailed'\n  // Stripe gave up on a failed renewal and CANCELLED the subscription\n  // (AGL-1877). Distinct from `paymentFailed`, which announces one failed\n  // attempt inside a retry window the customer can still recover from; this\n  // one is the window having closed. Measured on the test account with a\n  // test clock: five attempts over 21.08 days, then\n  // `cancellation_details.reason: 'payment_failed'` — and until this existed\n  // the org went silently to Free at that moment, with the `past_due` banner\n  // disappearing at exactly the instant the consequence arrived.\n  | 'billing.subscriptionCanceled'\n  | 'billing.usage'\n  | 'team.invite'\n  | 'team.roleChanged'\n  | 'team.hostAccessGranted'\n  | 'content.formSubmission'\n  | 'content.booking'\n  | 'content.order'\n  | 'content.lowStock'\n  // A CRM task was assigned to the recipient by somebody else (AGL-2599).\n  // `content.` because it is the same kind of message as a form submission\n  // or a booking: a thing on the site that now needs this person's hands,\n  // not a change to their standing (`team.`) and not a platform notice\n  // (`system.`). Someone who has muted the operational stream has said they\n  // do not want to be told about work as it arrives, and a task is work.\n  | 'content.taskAssigned'\n  // A CRM task's reminder came due (AGL-2659): the hourly runner telling\n  // the assignee, at the task's own time, that the task is due. `content.`\n  // beside `taskAssigned` for the same reason it gives — work on the site,\n  // not standing — and so the one mute that stops \"work arriving\" stops\n  // \"work falling due\" with it. The mute governs the whole reminder, mail\n  // included, unlike the digest's: a reminder is one message about one\n  // task, and there is no schedule to keep separately from it.\n  | 'content.taskReminder'\n  // A contact, or a lead, became the recipient's to work (AGL-2618): a\n  // capture the assignment rules or the site's default owner routed to\n  // them, a lead somebody converted and handed to them, or an automation's\n  // \"assign an owner\" step — every server path that writes `ownerUid`\n  // except the recipient assigning themselves. Two types rather than one\n  // because the record the person opens differs: a lead is the site's own\n  // working record and a contact is the org's, and the link goes to the\n  // one they will actually work. `content.`, beside `taskAssigned`, for the\n  // same reason: work arriving, not standing changing.\n  | 'content.contactAssigned'\n  | 'content.leadAssigned'\n  // The morning's CRM digest (AGL-2619): what the recipient owes today —\n  // overdue and due-today tasks, and the leads nobody has worked. `content.`\n  // for the reason `taskAssigned` is: it is about work on the site, and the\n  // person who muted the operational stream has asked not to be told about\n  // work. The digest EMAIL is governed separately, by\n  // `crmDailyDigestEnabled`: the mute is a fact about the console feed and\n  // the digest switch is a fact about the digest.\n  | 'content.crmDailyDigest'\n  // The weekly insights (AGL-2915): what a site's figures showed that week,\n  // for a person who asked for them. `content.` beside the CRM digest, for the\n  // reason that one gives: it is about the site's work, and the operational\n  // mute governs the console notification while the person's own switch for\n  // the digest governs the digest.\n  | 'content.insightsDigest'\n  // Marketplace review verdicts (AGL-432/653).\n  | 'marketplace.review'\n  // Support desk, staff audience (AGL-850): a subscriber opened or replied to\n  // a ticket. Fanned out to staff-claim holders, not org members.\n  | 'support.ticketOpened'\n  | 'support.ticketReply'\n  | 'system.announcement'\n  // A live plugin version stopped passing the static verifier (AGL-1086).\n  // Staff audience: bytes we told workspaces were checked now fail checks\n  // that did not exist when they were approved.\n  //\n  // Deliberately NOT under `marketplace.` (AGL-1088). Category is the prefix,\n  // categories are mutable per user, and Marketplace is the category a staff\n  // member mutes to stop routine listing-review chatter — which would drop\n  // this alert as collateral. `system` is the bucket nobody mutes to reduce\n  // noise. The adminAudit record survives a mute either way; the timeliness\n  // does not, and timeliness is the whole point of the alert.\n  | 'system.pluginVerifierRegression'\n  // A sign-in method was removed from the user's own account because their\n  // organization turned on SSO enforcement (AGL-1129). `system.`, not\n  // `team.`, for the AGL-1088 reason above: `team` is the category someone\n  // mutes to stop routine roster chatter, and \"the way you sign in just\n  // changed\" is not chatter — the next sign-in fails without it.\n  | 'system.signInMethodRemoved'\n  // Documents in a scoped collection carrying no `visibleTo` (AGL-1478).\n  // Staff audience: the weekly dry run found resources that are invisible\n  // to every site-scoped read, which always means a creation path forgot\n  // the field. `system.` for the AGL-1088 reason above, and because the\n  // collection it names may be `marketplace`-adjacent or not.\n  | 'system.scopeDrift'\n  // An SSO domain that WAS DNS-proven has stopped answering with our\n  // challenge record, for three consecutive weekly sweeps (AGL-1210).\n  // Nothing has been turned off — sign-in for that domain still routes\n  // exactly as it did — and that is precisely why this has to be said out\n  // loud rather than left in a log.\n  //\n  // `system.`, not `team.`, for the AGL-1088 reason above and one of its\n  // own: the audience is the org's own admins, the subject is whether their\n  // people can still sign in, and it must reach them BEFORE anybody decides\n  // to revoke the routing. A category somebody mutes to quieten roster\n  // chatter is the wrong place for the one warning that precedes a lockout.\n  | 'system.ssoDomainUnverified'\n  // A site hit the per-month form-submission abuse ceiling and further\n  // submissions are being refused (AGL-1655). `system.`, not `content.`, for\n  // the AGL-1088 reason above and more sharply than any of them: `content` is\n  // literally the category a site owner mutes to stop routine form-submission\n  // chatter, and this is the one form notification that says the form has\n  // STOPPED accepting. Filing it under the muted bucket would guarantee it\n  // reaches nobody on exactly the sites busy enough to trip it.\n  | 'system.formSubmissionsPaused'\n  // A site reached the flat platform ceiling on member accounts or on lead\n  // records, so further ones are being refused (AGL-1529). `system.` for the\n  // same reason as `formSubmissionsPaused` directly above, and with the same\n  // sharpness: `content.` is the bucket an owner mutes to stop routine\n  // sign-up and lead chatter, and this is the one notification saying the\n  // sign-ups have STOPPED — muted exactly on the sites busy enough to trip it.\n  | 'system.visitorRecordsPaused'\n  // An outsider reported one of our sites for phishing, malware or CSAM\n  // (AGL-1964). `system` for the AGL-1088 reason and, again, more sharply\n  // than most: this notification goes to STAFF, not to a customer, and its\n  // subject is somebody else's site. There is no bucket a recipient could\n  // mute it into that would be honest — nobody has opted into being told a\n  // stranger is being phished through our platform, and nobody should be able\n  // to opt out of it either.\n  //\n  // Only the urgent categories raise one, and only on a first report. See the\n  // fan-out in apps/tenant/app/api/report-abuse/route.ts for why: a flood of\n  // alerts IS the flood, and the alert it would cost us is the phishing one.\n  | 'system.abuseReportUrgent'\n  // The §512(g) counter-notice (AGL-1983), and the one place the \"only urgent\n  // categories raise a notification\" restraint above is deliberately not\n  // applied. Every counter-notice carries a statutory deadline that is\n  // ALREADY RUNNING when it arrives — the clock counts from the subscriber's\n  // submission, not from our attention — so there is no low-value tail of\n  // these to drown out the important ones, and the one that goes unread is a\n  // customer locked out of their own work plus an unmet obligation under\n  // §512(g)(2)(A). Raised on first submission only, like the one above, so a\n  // resubmitting customer cannot re-alert.\n  | 'system.dmcaCounterNotice'\n  // A site crossed the per-month bandwidth abuse ceiling (AGL-2155). Two\n  // audiences share one type: staff, because an uncompensated free site\n  // serving six figures of page views is an incident; and the site's own\n  // managers, because on free the site is now serving a capped notice and\n  // nobody should learn that from a visitor.\n  //\n  // `system.`, not `billing.`, for the AGL-1088 reason and one specific to\n  // this meter: on the free plan there is no bill, so `billing` would be the\n  // one category where the message is literally never about money — and it is\n  // exactly the free-tier trip that changes what visitors see.\n  | 'system.bandwidthCeilingTripped'\n  // A free site crossed its PLAN's included bandwidth and is now serving the\n  // capped notice (AGL-2413). Distinct from the ceiling above on purpose: that\n  // one is an incident at 10x the band and goes to staff first; this one is an\n  // ordinary quota at 1x, concerns only the site's own managers, and its\n  // remedy is an upgrade rather than an investigation. Sending both under one\n  // type would tell an owner their traffic was being treated as suspected\n  // abuse when it is simply a successful free site.\n  | 'system.bandwidthCapEngaged'\n  // A Stripe billing webhook threw AFTER its handlers had begun (AGL-2157),\n  // so its side effects may be half applied and its idempotency claim is\n  // being HELD — Stripe will not retry it. Staff audience: this is the one\n  // failure on that route no automatic retry can make safe, because the\n  // handlers behind it are not all idempotent, and a human has to reconcile.\n  | 'system.billingWebhookHalfApplied'\n  // A card dispute arrived that NOTHING in the platform claimed (AGL-2429):\n  // no `platformRevenue` row, no storefront order, no marketplace purchase.\n  // Staff audience, and the reason it needs a type of its own is that its\n  // absence was the bug — the routine case (a storefront or marketplace\n  // chargeback, which the plugins own) and the fault case were the same\n  // silence from the route's side, so a dispute nobody handled looked\n  // exactly like one somebody did.\n  //\n  // `system.`, not `billing.`, for the AGL-1088 reason and one specific to\n  // this alert: `billing` is the category a recipient is most likely to have\n  // muted as routine invoice traffic, and this is the one message on that\n  // route where muting it means money moves with nobody looking.\n  | 'system.disputeUnattributed'\n\nexport interface AglynNotification {\n  $id?: string\n  type: AglynNotificationType\n  title: string\n  body?: string\n  /** Console path the notification opens (e.g. a host inbox). */\n  link?: string\n  orgId?: string\n  hostId?: string\n  createdAt?: ITimestamp\n  /** Set by the owner when read; unread while absent. */\n  readAt?: ITimestamp | null\n}\n\nexport const NOTIFICATION_TYPE_LABELS: Record<AglynNotificationType, string> =\n  {\n    'billing.invoice': 'Invoice available',\n    'billing.paymentFailed': 'Payment failed',\n    'billing.subscriptionCanceled': 'Subscription canceled',\n    'billing.usage': 'Usage threshold',\n    'team.invite': 'Team invite',\n    'team.roleChanged': 'Role changed',\n    'team.hostAccessGranted': 'Site access granted',\n    'content.formSubmission': 'Form submission',\n    'content.booking': 'New booking',\n    'content.order': 'New order',\n    'content.lowStock': 'Low stock',\n    'content.taskAssigned': 'Task assigned to you',\n    'content.taskReminder': 'Task reminder',\n    'content.contactAssigned': 'Contact assigned to you',\n    'content.leadAssigned': 'Lead assigned to you',\n    'content.crmDailyDigest': 'Daily CRM digest',\n    'content.insightsDigest': 'Weekly insights',\n    'marketplace.review': 'Listing review',\n\n    'support.ticketOpened': 'New support ticket',\n    'support.ticketReply': 'Support ticket reply',\n    'system.announcement': 'Announcement',\n    'system.pluginVerifierRegression': 'Plugin verifier regression',\n    'system.signInMethodRemoved': 'Sign-in method removed',\n    'system.scopeDrift': 'Resources missing a sharing scope',\n    'system.ssoDomainUnverified': 'SSO domain no longer proves ownership',\n    'system.formSubmissionsPaused': 'Form submissions paused',\n    'system.visitorRecordsPaused': 'Sign-ups or leads paused',\n    'system.abuseReportUrgent': 'Urgent abuse report',\n    'system.dmcaCounterNotice': 'DMCA counter-notice',\n    'system.bandwidthCeilingTripped': 'Bandwidth ceiling reached',\n    'system.bandwidthCapEngaged': 'Monthly traffic limit reached',\n    'system.billingWebhookHalfApplied': 'Billing webhook half applied',\n    'system.disputeUnattributed': 'Card dispute with no owner',\n  }\n\n/** Preference buckets (AGL-267): the prefix before the dot. */\nexport type NotificationCategory =\n  | 'billing'\n  | 'team'\n  | 'content'\n  | 'marketplace'\n  | 'support'\n  | 'system'\n\nexport const NOTIFICATION_CATEGORY_LABELS: Record<\n  NotificationCategory,\n  string\n> = {\n  billing: 'Billing',\n  team: 'Team & access',\n  content: 'Forms & bookings',\n  marketplace: 'Marketplace',\n  support: 'Support',\n  system: 'Product & system',\n}\n\nexport function notificationCategory(\n  type: AglynNotificationType | string,\n): NotificationCategory {\n  const prefix = String(type).split('.')[0]\n  return (\n    ['billing', 'team', 'content', 'marketplace', 'support', 'system'].includes(\n      prefix,\n    )\n      ? prefix\n      : 'system'\n  ) as NotificationCategory\n}\n\n/**\n * Per-user mute map stored at `users/{uid}.notificationPrefs`\n * (`{ [category]: false }` mutes); absent categories stay on.\n */\nexport function notificationMuted(\n  prefs: Record<string, boolean> | null | undefined,\n  type: AglynNotificationType | string,\n): boolean {\n  return prefs?.[notificationCategory(type)] === false\n}\n\n/**\n * The field on `users/{uid}` that holds a person's digest switches\n * (AGL-2619): `{ crmDaily: false }` turns the daily CRM digest off, and an\n * absent key leaves it on. Its own map rather than a key in\n * `notificationPrefs`, because that map is keyed by CATEGORY and read by\n * {@link notificationMuted} — a digest is a schedule a person keeps or\n * drops, not a bucket of types, and one switch governs both the console\n * notification and the email it travels with.\n */\nexport const DIGEST_PREFS_FIELD = 'digestPrefs'\n\nexport function crmDailyDigestEnabled(\n  prefs: Record<string, boolean> | null | undefined,\n): boolean {\n  return prefs?.['crmDaily'] !== false\n}\n\n/**\n * The field on `users/{uid}` naming the workspaces whose weekly insights a\n * person asked for (AGL-2915): `{ [orgId]: true }`. OPT-IN, unlike the CRM\n * digest — an absent key is off — because a weekly insight is generated, and a\n * generation spends the workspace's credits. The person turns it on beside the\n * answers themselves, where the plan, the release and their permission have\n * already been checked, and off again there or in Notifications; the weekly\n * sweep checks all three again before it spends anything.\n */\nexport const INSIGHT_DIGESTS_FIELD = 'insightDigests'\n\n/** Whether a person asked for a workspace's weekly insights. */\nexport function insightDigestSubscribed(\n  value: Record<string, boolean> | null | undefined,\n  orgId: string,\n): boolean {\n  return Boolean(orgId) && value?.[orgId] === true\n}\n"],"names":["NOTIFICATION_TYPE_LABELS","NOTIFICATION_CATEGORY_LABELS","billing","team","content","marketplace","support","system","notificationCategory","type","prefix","String","split","includes","notificationMuted","prefs","DIGEST_PREFS_FIELD","crmDailyDigestEnabled","INSIGHT_DIGESTS_FIELD","insightDigestSubscribed","value","orgId","Boolean"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA2MD,OAAO,MAAMA,2BACX;IACE,mBAAmB;IACnB,yBAAyB;IACzB,gCAAgC;IAChC,iBAAiB;IACjB,eAAe;IACf,oBAAoB;IACpB,0BAA0B;IAC1B,0BAA0B;IAC1B,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;IACpB,wBAAwB;IACxB,wBAAwB;IACxB,2BAA2B;IAC3B,wBAAwB;IACxB,0BAA0B;IAC1B,0BAA0B;IAC1B,sBAAsB;IAEtB,wBAAwB;IACxB,uBAAuB;IACvB,uBAAuB;IACvB,mCAAmC;IACnC,8BAA8B;IAC9B,qBAAqB;IACrB,8BAA8B;IAC9B,gCAAgC;IAChC,+BAA+B;IAC/B,4BAA4B;IAC5B,4BAA4B;IAC5B,kCAAkC;IAClC,8BAA8B;IAC9B,oCAAoC;IACpC,8BAA8B;AAChC,EAAC;AAWH,OAAO,MAAMC,+BAGT;IACFC,SAAS;IACTC,MAAM;IACNC,SAAS;IACTC,aAAa;IACbC,SAAS;IACTC,QAAQ;AACV,EAAC;AAED,OAAO,SAASC,qBACdC,IAAoC;IAEpC,MAAMC,SAASC,OAAOF,MAAMG,KAAK,CAAC,IAAI,CAAC,EAAE;IACzC,OACE;QAAC;QAAW;QAAQ;QAAW;QAAe;QAAW;KAAS,CAACC,QAAQ,CACzEH,UAEEA,SACA;AAER;AAEA;;;CAGC,GACD,OAAO,SAASI,kBACdC,KAAiD,EACjDN,IAAoC;IAEpC,OAAOM,CAAAA,yBAAAA,KAAO,CAACP,qBAAqBC,MAAM,MAAK;AACjD;AAEA;;;;;;;;CAQC,GACD,OAAO,MAAMO,qBAAqB,cAAa;AAE/C,OAAO,SAASC,sBACdF,KAAiD;IAEjD,OAAOA,CAAAA,yBAAAA,KAAO,CAAC,WAAW,MAAK;AACjC;AAEA;;;;;;;;CAQC,GACD,OAAO,MAAMG,wBAAwB,iBAAgB;AAErD,8DAA8D,GAC9D,OAAO,SAASC,wBACdC,KAAiD,EACjDC,KAAa;IAEb,OAAOC,QAAQD,UAAUD,CAAAA,yBAAAA,KAAO,CAACC,MAAM,MAAK;AAC9C"}

package/src/lib/app-utils/onboarding-deep-link.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @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.
+ */
+import type { OrgPlan } from '../foundation/definitions/org-billing.types';
+/**
+ * The marketing → console onboarding deep link (AGL-1117).
+ *
+ * `app.aglyn.com/signup?plan=pro&interval=year`, optionally `&ai=1` for the
+ * Aglyn AI add-on (AGL-2897).
+ *
+ * This is a CONTRACT with a site we do not control and cannot deploy in
+ * lockstep with. So it is parsed defensively and in one place: the pricing
+ * page will eventually be edited by someone who has never read this file, and
+ * a typo in a CTA must degrade to ordinary signup rather than break it or —
+ * far worse — silently start someone on the wrong plan.
+ */
+export type OnboardingInterval = 'month' | 'year';
+export interface OnboardingPlanIntent {
+    plan: OrgPlan;
+    interval: OnboardingInterval;
+    /**
+     * Whether the link ACTUALLY said an interval, as opposed to `interval`
+     * being the safe default below (AGL-1535).
+     *
+     * Some CTAs carry a plan and deliberately no interval — the /pricing scale
+     * strip quotes monthly and annual side by side and commits to neither. The
+     * billing page honours that (it only lets a *stated* interval move the
+     * toggle, so an annual org is not silently flipped to monthly on arrival),
+     * but every hop between the CTA and that page used to re-serialize the
+     * intent with `&interval=month` appended — which made the omission
+     * unrecoverable one redirect after it was made. Carrying the distinction is
+     * what keeps "no interval stated" a thing the last reader can still see.
+     */
+    intervalStated: boolean;
+    /**
+     * Enterprise is quoted, not bought. The CTA still carries `plan=enterprise`
+     * because that is what the visitor clicked, and the console has to route
+     * them to contact-sales rather than to a checkout that cannot price it
+     * (AGL-1110).
+     */
+    contactSales: boolean;
+    /**
+     * The Aglyn AI add-on, asked for alongside the plan (AGL-2897):
+     * `?plan=pro&interval=month&ai=1`.
+     *
+     * Present only when the link said so, and only ever `true` — the add-on
+     * rides the plan checkout as a second subscription item, so a flag that
+     * was never stated must not be told apart from one that was set to false
+     * by every hop that re-serializes the intent. Enterprise never carries it:
+     * the add-on is quoted with the deal, not bought through a checkout.
+     */
+    ai?: true;
+}
+/**
+ * Read a plan intent off the URL, or null when there isn't a usable one.
+ *
+ * Null for `free` on purpose: it is a real plan but not a purchase, so there
+ * is nothing to carry into checkout and a new org already starts there.
+ * Returning an intent for it would send someone to a billing page to buy
+ * what they already have.
+ */
+export declare function parseOnboardingPlanIntent(params: URLSearchParams | Record<string, string | string[] | undefined> | null | undefined): OnboardingPlanIntent | null;
+/**
+ * The intent as query params — the one place the wire form is written
+ * (AGL-1535).
+ *
+ * Every hop that re-serializes an intent (the signup landing, the auth-bounce
+ * `continue`, the home jump) used to build this string by hand and append
+ * `&interval=` unconditionally, which turned the parser's monthly DEFAULT into
+ * a statement the next reader could not tell from the real thing.
+ */
+export declare function onboardingPlanQuery(intent: OnboardingPlanIntent): string;
+/**
+ * The signup URL a marketing CTA should carry — the WRITER half of the
+ * contract above (AGL-1989).
+ *
+ * The contract had a parser and a re-serializer but nothing that produced a
+ * link in the first place, so every published CTA was hand-typed. That is how
+ * `/pricing` came to have six CTAs carrying `interval=` and three carrying
+ * none: the "Need more scale?" strip quotes Scale, Advanced and Agency at both
+ * cadences and its CHOOSE links say only `?plan=scale`, so a visitor who had
+ * just picked Annual arrived pre-selected for a MONTHLY plan and silently lost
+ * the annual discount they were shown. Nothing could have caught it, because
+ * the string that should have been published existed nowhere a check could
+ * read it.
+ *
+ * `interval: null` is a real and different thing from `'month'`: it means the
+ * CTA does not commit to a cadence, which the billing page honours by leaving
+ * an annual org on annual (`intervalStated`). Callers with a cadence to state
+ * must state it.
+ *
+ * The marketing site is authored content, not code, so this does not publish
+ * anything — it is what the authoring input quotes, so the person clicking the
+ * link into the besigner pastes a string this contract's own parser agrees
+ * with rather than one they typed.
+ */
+export declare function onboardingSignupHref(signupUrl: string, plan: OrgPlan, interval: OnboardingInterval | null, options?: {
+    ai?: boolean;
+}): string;
+/**
+ * Where a freshly provisioned workspace should land, given the plan the
+ * visitor picked on the marketing site.
+ *
+ * Deliberately returns a path rather than pushing: signup owns the
+ * navigation, and a pure function is the half worth testing.
+ */
+export declare function onboardingDestination(orgSlug: string, intent: OnboardingPlanIntent | null): string;

package/src/lib/app-utils/onboarding-deep-link.js

@@ -0,0 +1,142 @@
+/**
+ * @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.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { isCustomPricedPlan } from "./plan-entitlements.js";
+const SELF_SERVE_PLANS = [
+    'starter',
+    'pro',
+    'business',
+    'scale',
+    'advanced',
+    'agency'
+];
+/**
+ * Read a plan intent off the URL, or null when there isn't a usable one.
+ *
+ * Null for `free` on purpose: it is a real plan but not a purchase, so there
+ * is nothing to carry into checkout and a new org already starts there.
+ * Returning an intent for it would send someone to a billing page to buy
+ * what they already have.
+ */ export function parseOnboardingPlanIntent(params) {
+    if (!params) return null;
+    const read = (key)=>{
+        var _ref;
+        const raw = params instanceof URLSearchParams ? params.get(key) : params[key];
+        // Next gives `string[]` for a repeated param. Take the first rather than
+        // joining, so `?plan=pro&plan=free` cannot become the string "pro,free"
+        // and fall through to null — the first is what the CTA meant.
+        return String((_ref = Array.isArray(raw) ? raw[0] : raw) != null ? _ref : '').trim().toLowerCase();
+    };
+    const plan = read('plan');
+    if (!plan) return null;
+    if (isCustomPricedPlan(plan)) {
+        return {
+            plan: plan,
+            interval: 'month',
+            intervalStated: false,
+            contactSales: true
+        };
+    }
+    if (!SELF_SERVE_PLANS.includes(plan)) return null;
+    const interval = read('interval');
+    const known = interval === 'year' || interval === 'annual' || interval === 'month';
+    // The add-on is opt-in by an explicit affirmative. Anything else — absent,
+    // empty, `0`, `false`, a typo — is "not asked for": a checkout that adds a
+    // paid item off a malformed link is the expensive direction to be wrong in.
+    const ai = read('ai');
+    const aiStated = ai === '1' || ai === 'true' || ai === 'yes';
+    return _extends({
+        plan: plan,
+        // Anything unrecognized falls to monthly, never to yearly: guessing the
+        // longer commitment from a malformed link is the expensive direction to
+        // be wrong in.
+        interval: interval === 'year' || interval === 'annual' ? 'year' : 'month',
+        // A junk interval is not a stated one: `?interval=decade` means the link
+        // is broken, and the reader should fall back to what it knows about the
+        // org rather than be told "monthly" with a straight face.
+        intervalStated: known,
+        contactSales: false
+    }, aiStated ? {
+        ai: true
+    } : {});
+}
+/**
+ * The intent as query params — the one place the wire form is written
+ * (AGL-1535).
+ *
+ * Every hop that re-serializes an intent (the signup landing, the auth-bounce
+ * `continue`, the home jump) used to build this string by hand and append
+ * `&interval=` unconditionally, which turned the parser's monthly DEFAULT into
+ * a statement the next reader could not tell from the real thing.
+ */ export function onboardingPlanQuery(intent) {
+    return `plan=${encodeURIComponent(intent.plan)}` + (intent.intervalStated ? `&interval=${intent.interval}` : '') + (intent.ai ? '&ai=1' : '');
+}
+/**
+ * The signup URL a marketing CTA should carry — the WRITER half of the
+ * contract above (AGL-1989).
+ *
+ * The contract had a parser and a re-serializer but nothing that produced a
+ * link in the first place, so every published CTA was hand-typed. That is how
+ * `/pricing` came to have six CTAs carrying `interval=` and three carrying
+ * none: the "Need more scale?" strip quotes Scale, Advanced and Agency at both
+ * cadences and its CHOOSE links say only `?plan=scale`, so a visitor who had
+ * just picked Annual arrived pre-selected for a MONTHLY plan and silently lost
+ * the annual discount they were shown. Nothing could have caught it, because
+ * the string that should have been published existed nowhere a check could
+ * read it.
+ *
+ * `interval: null` is a real and different thing from `'month'`: it means the
+ * CTA does not commit to a cadence, which the billing page honours by leaving
+ * an annual org on annual (`intervalStated`). Callers with a cadence to state
+ * must state it.
+ *
+ * The marketing site is authored content, not code, so this does not publish
+ * anything — it is what the authoring input quotes, so the person clicking the
+ * link into the besigner pastes a string this contract's own parser agrees
+ * with rather than one they typed.
+ */ export function onboardingSignupHref(signupUrl, plan, interval, options = {}) {
+    const contactSales = isCustomPricedPlan(plan);
+    // A custom-priced plan is quoted, not bought, so `parseOnboardingPlanIntent`
+    // reports `intervalStated: false` for it HOWEVER the link is written. Writing
+    // `?plan=enterprise&interval=year` anyway puts a claim on the wire that no
+    // reader honours — and before AGL-1864 fixed the reader, that exact link
+    // flipped an annual org to monthly on arrival. Drop it at the source, which
+    // is the last place it can be dropped before it is published.
+    const stated = interval != null && contactSales === false;
+    return `${signupUrl}?${onboardingPlanQuery(_extends({
+        plan,
+        interval: stated ? interval : 'month',
+        intervalStated: stated,
+        contactSales
+    }, options.ai && !contactSales ? {
+        ai: true
+    } : {}))}`;
+}
+/**
+ * Where a freshly provisioned workspace should land, given the plan the
+ * visitor picked on the marketing site.
+ *
+ * Deliberately returns a path rather than pushing: signup owns the
+ * navigation, and a pure function is the half worth testing.
+ */ export function onboardingDestination(orgSlug, intent) {
+    if (!orgSlug) return '/';
+    if (!intent) return `/${orgSlug}`;
+    // Enterprise is a conversation, not a checkout (AGL-1110).
+    if (intent.contactSales) return `/${orgSlug}/support?topic=enterprise`;
+    return `/${orgSlug}/billing?${onboardingPlanQuery(intent)}`;
+}
+
+//# sourceMappingURL=onboarding-deep-link.js.map

package/src/lib/app-utils/onboarding-deep-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/onboarding-deep-link.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\nimport type { OrgPlan } from '../foundation/definitions/org-billing.types'\nimport { isCustomPricedPlan } from './plan-entitlements'\n\n/**\n * The marketing → console onboarding deep link (AGL-1117).\n *\n * `app.aglyn.com/signup?plan=pro&interval=year`, optionally `&ai=1` for the\n * Aglyn AI add-on (AGL-2897).\n *\n * This is a CONTRACT with a site we do not control and cannot deploy in\n * lockstep with. So it is parsed defensively and in one place: the pricing\n * page will eventually be edited by someone who has never read this file, and\n * a typo in a CTA must degrade to ordinary signup rather than break it or —\n * far worse — silently start someone on the wrong plan.\n */\nexport type OnboardingInterval = 'month' | 'year'\n\nexport interface OnboardingPlanIntent {\n  plan: OrgPlan\n  interval: OnboardingInterval\n  /**\n   * Whether the link ACTUALLY said an interval, as opposed to `interval`\n   * being the safe default below (AGL-1535).\n   *\n   * Some CTAs carry a plan and deliberately no interval — the /pricing scale\n   * strip quotes monthly and annual side by side and commits to neither. The\n   * billing page honours that (it only lets a *stated* interval move the\n   * toggle, so an annual org is not silently flipped to monthly on arrival),\n   * but every hop between the CTA and that page used to re-serialize the\n   * intent with `&interval=month` appended — which made the omission\n   * unrecoverable one redirect after it was made. Carrying the distinction is\n   * what keeps \"no interval stated\" a thing the last reader can still see.\n   */\n  intervalStated: boolean\n  /**\n   * Enterprise is quoted, not bought. The CTA still carries `plan=enterprise`\n   * because that is what the visitor clicked, and the console has to route\n   * them to contact-sales rather than to a checkout that cannot price it\n   * (AGL-1110).\n   */\n  contactSales: boolean\n  /**\n   * The Aglyn AI add-on, asked for alongside the plan (AGL-2897):\n   * `?plan=pro&interval=month&ai=1`.\n   *\n   * Present only when the link said so, and only ever `true` — the add-on\n   * rides the plan checkout as a second subscription item, so a flag that\n   * was never stated must not be told apart from one that was set to false\n   * by every hop that re-serializes the intent. Enterprise never carries it:\n   * the add-on is quoted with the deal, not bought through a checkout.\n   */\n  ai?: true\n}\n\nconst SELF_SERVE_PLANS: readonly OrgPlan[] = [\n  'starter',\n  'pro',\n  'business',\n  'scale',\n  'advanced',\n  'agency',\n]\n\n/**\n * Read a plan intent off the URL, or null when there isn't a usable one.\n *\n * Null for `free` on purpose: it is a real plan but not a purchase, so there\n * is nothing to carry into checkout and a new org already starts there.\n * Returning an intent for it would send someone to a billing page to buy\n * what they already have.\n */\nexport function parseOnboardingPlanIntent(\n  params:\n    | URLSearchParams\n    | Record<string, string | string[] | undefined>\n    | null\n    | undefined,\n): OnboardingPlanIntent | null {\n  if (!params) return null\n  const read = (key: string): string => {\n    const raw =\n      params instanceof URLSearchParams ? params.get(key) : params[key]\n    // Next gives `string[]` for a repeated param. Take the first rather than\n    // joining, so `?plan=pro&plan=free` cannot become the string \"pro,free\"\n    // and fall through to null — the first is what the CTA meant.\n    return String((Array.isArray(raw) ? raw[0] : raw) ?? '')\n      .trim()\n      .toLowerCase()\n  }\n  const plan = read('plan')\n  if (!plan) return null\n  if (isCustomPricedPlan(plan as OrgPlan)) {\n    return {\n      plan: plan as OrgPlan,\n      interval: 'month',\n      intervalStated: false,\n      contactSales: true,\n    }\n  }\n  if (!SELF_SERVE_PLANS.includes(plan as OrgPlan)) return null\n  const interval = read('interval')\n  const known = interval === 'year' || interval === 'annual' || interval === 'month'\n  // The add-on is opt-in by an explicit affirmative. Anything else — absent,\n  // empty, `0`, `false`, a typo — is \"not asked for\": a checkout that adds a\n  // paid item off a malformed link is the expensive direction to be wrong in.\n  const ai = read('ai')\n  const aiStated = ai === '1' || ai === 'true' || ai === 'yes'\n  return {\n    plan: plan as OrgPlan,\n    // Anything unrecognized falls to monthly, never to yearly: guessing the\n    // longer commitment from a malformed link is the expensive direction to\n    // be wrong in.\n    interval: interval === 'year' || interval === 'annual' ? 'year' : 'month',\n    // A junk interval is not a stated one: `?interval=decade` means the link\n    // is broken, and the reader should fall back to what it knows about the\n    // org rather than be told \"monthly\" with a straight face.\n    intervalStated: known,\n    contactSales: false,\n    ...(aiStated ? { ai: true } : {}),\n  }\n}\n\n/**\n * The intent as query params — the one place the wire form is written\n * (AGL-1535).\n *\n * Every hop that re-serializes an intent (the signup landing, the auth-bounce\n * `continue`, the home jump) used to build this string by hand and append\n * `&interval=` unconditionally, which turned the parser's monthly DEFAULT into\n * a statement the next reader could not tell from the real thing.\n */\nexport function onboardingPlanQuery(intent: OnboardingPlanIntent): string {\n  return (\n    `plan=${encodeURIComponent(intent.plan)}` +\n    (intent.intervalStated ? `&interval=${intent.interval}` : '') +\n    (intent.ai ? '&ai=1' : '')\n  )\n}\n\n/**\n * The signup URL a marketing CTA should carry — the WRITER half of the\n * contract above (AGL-1989).\n *\n * The contract had a parser and a re-serializer but nothing that produced a\n * link in the first place, so every published CTA was hand-typed. That is how\n * `/pricing` came to have six CTAs carrying `interval=` and three carrying\n * none: the \"Need more scale?\" strip quotes Scale, Advanced and Agency at both\n * cadences and its CHOOSE links say only `?plan=scale`, so a visitor who had\n * just picked Annual arrived pre-selected for a MONTHLY plan and silently lost\n * the annual discount they were shown. Nothing could have caught it, because\n * the string that should have been published existed nowhere a check could\n * read it.\n *\n * `interval: null` is a real and different thing from `'month'`: it means the\n * CTA does not commit to a cadence, which the billing page honours by leaving\n * an annual org on annual (`intervalStated`). Callers with a cadence to state\n * must state it.\n *\n * The marketing site is authored content, not code, so this does not publish\n * anything — it is what the authoring input quotes, so the person clicking the\n * link into the besigner pastes a string this contract's own parser agrees\n * with rather than one they typed.\n */\nexport function onboardingSignupHref(\n  signupUrl: string,\n  plan: OrgPlan,\n  interval: OnboardingInterval | null,\n  options: { ai?: boolean } = {},\n): string {\n  const contactSales = isCustomPricedPlan(plan)\n  // A custom-priced plan is quoted, not bought, so `parseOnboardingPlanIntent`\n  // reports `intervalStated: false` for it HOWEVER the link is written. Writing\n  // `?plan=enterprise&interval=year` anyway puts a claim on the wire that no\n  // reader honours — and before AGL-1864 fixed the reader, that exact link\n  // flipped an annual org to monthly on arrival. Drop it at the source, which\n  // is the last place it can be dropped before it is published.\n  const stated = interval != null && contactSales === false\n  return `${signupUrl}?${onboardingPlanQuery({\n    plan,\n    interval: stated ? interval : 'month',\n    intervalStated: stated,\n    contactSales,\n    // The add-on CTA (AGL-2897). Dropped for a custom-priced plan for the\n    // same reason the interval is: the parser refuses it there, so writing\n    // it would publish a claim no reader honors.\n    ...(options.ai && !contactSales ? { ai: true } : {}),\n  })}`\n}\n\n/**\n * Where a freshly provisioned workspace should land, given the plan the\n * visitor picked on the marketing site.\n *\n * Deliberately returns a path rather than pushing: signup owns the\n * navigation, and a pure function is the half worth testing.\n */\nexport function onboardingDestination(\n  orgSlug: string,\n  intent: OnboardingPlanIntent | null,\n): string {\n  if (!orgSlug) return '/'\n  if (!intent) return `/${orgSlug}`\n  // Enterprise is a conversation, not a checkout (AGL-1110).\n  if (intent.contactSales) return `/${orgSlug}/support?topic=enterprise`\n  return `/${orgSlug}/billing?${onboardingPlanQuery(intent)}`\n}\n"],"names":["isCustomPricedPlan","SELF_SERVE_PLANS","parseOnboardingPlanIntent","params","read","key","Array","raw","URLSearchParams","get","String","isArray","trim","toLowerCase","plan","interval","intervalStated","contactSales","includes","known","ai","aiStated","onboardingPlanQuery","intent","encodeURIComponent","onboardingSignupHref","signupUrl","options","stated","onboardingDestination","orgSlug"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,kBAAkB,QAAQ,yBAAqB;AAqDxD,MAAMC,mBAAuC;IAC3C;IACA;IACA;IACA;IACA;IACA;CACD;AAED;;;;;;;CAOC,GACD,OAAO,SAASC,0BACdC,MAIa;IAEb,IAAI,CAACA,QAAQ,OAAO;IACpB,MAAMC,OAAO,CAACC;YAMGC;QALf,MAAMC,MACJJ,kBAAkBK,kBAAkBL,OAAOM,GAAG,CAACJ,OAAOF,MAAM,CAACE,IAAI;QACnE,yEAAyE;QACzE,wEAAwE;QACxE,8DAA8D;QAC9D,OAAOK,QAAQJ,OAAAA,MAAMK,OAAO,CAACJ,OAAOA,GAAG,CAAC,EAAE,GAAGA,eAA9BD,OAAsC,IAClDM,IAAI,GACJC,WAAW;IAChB;IACA,MAAMC,OAAOV,KAAK;IAClB,IAAI,CAACU,MAAM,OAAO;IAClB,IAAId,mBAAmBc,OAAkB;QACvC,OAAO;YACLA,MAAMA;YACNC,UAAU;YACVC,gBAAgB;YAChBC,cAAc;QAChB;IACF;IACA,IAAI,CAAChB,iBAAiBiB,QAAQ,CAACJ,OAAkB,OAAO;IACxD,MAAMC,WAAWX,KAAK;IACtB,MAAMe,QAAQJ,aAAa,UAAUA,aAAa,YAAYA,aAAa;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAMK,KAAKhB,KAAK;IAChB,MAAMiB,WAAWD,OAAO,OAAOA,OAAO,UAAUA,OAAO;IACvD,OAAO;QACLN,MAAMA;QACN,wEAAwE;QACxE,wEAAwE;QACxE,eAAe;QACfC,UAAUA,aAAa,UAAUA,aAAa,WAAW,SAAS;QAClE,yEAAyE;QACzE,wEAAwE;QACxE,0DAA0D;QAC1DC,gBAAgBG;QAChBF,cAAc;OACVI,WAAW;QAAED,IAAI;IAAK,IAAI,CAAC;AAEnC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASE,oBAAoBC,MAA4B;IAC9D,OACE,CAAC,KAAK,EAAEC,mBAAmBD,OAAOT,IAAI,GAAG,GACxCS,CAAAA,OAAOP,cAAc,GAAG,CAAC,UAAU,EAAEO,OAAOR,QAAQ,EAAE,GAAG,EAAC,IAC1DQ,CAAAA,OAAOH,EAAE,GAAG,UAAU,EAAC;AAE5B;AAEA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASK,qBACdC,SAAiB,EACjBZ,IAAa,EACbC,QAAmC,EACnCY,UAA4B,CAAC,CAAC;IAE9B,MAAMV,eAAejB,mBAAmBc;IACxC,6EAA6E;IAC7E,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,4EAA4E;IAC5E,8DAA8D;IAC9D,MAAMc,SAASb,YAAY,QAAQE,iBAAiB;IACpD,OAAO,GAAGS,UAAU,CAAC,EAAEJ,oBAAoB;QACzCR;QACAC,UAAUa,SAASb,WAAW;QAC9BC,gBAAgBY;QAChBX;OAIIU,QAAQP,EAAE,IAAI,CAACH,eAAe;QAAEG,IAAI;IAAK,IAAI,CAAC,KAChD;AACN;AAEA;;;;;;CAMC,GACD,OAAO,SAASS,sBACdC,OAAe,EACfP,MAAmC;IAEnC,IAAI,CAACO,SAAS,OAAO;IACrB,IAAI,CAACP,QAAQ,OAAO,CAAC,CAAC,EAAEO,SAAS;IACjC,2DAA2D;IAC3D,IAAIP,OAAON,YAAY,EAAE,OAAO,CAAC,CAAC,EAAEa,QAAQ,yBAAyB,CAAC;IACtE,OAAO,CAAC,CAAC,EAAEA,QAAQ,SAAS,EAAER,oBAAoBC,SAAS;AAC7D"}

package/src/lib/app-utils/operator-identity.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @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.
+ */
+/**
+ * Who runs *this* deployment, and where its notices go (AGL-2016).
+ *
+ * the rule for the self-host path: *"the self hosted owner should probably
+ * not have to edit the source to update aglyn branded items urls or personal
+ * identification items, should probably move these to env vars"*. This module
+ * is that, for the one class of value where getting it wrong is not cosmetic —
+ * the identity a legal notice is addressed to.
+ *
+ * ## The defect this exists to close
+ *
+ * `ABUSE_REPORT_CONTACT_EMAIL` was `'support@aglyn.com'`, a bare literal, and
+ * it rendered on the **public, unauthenticated** abuse-report form that every
+ * deployment ships. So a self-hoster running their own Firebase published a
+ * DMCA/abuse intake instructing third-party reporters to send statutory
+ * notices to **Aglyn** — about content Aglyn does not host, cannot see and
+ * cannot remove.
+ *
+ * That is wrong in both directions at once. The reporter's notice goes to a
+ * desk with no ability to act on it while their clock runs, and Aglyn is made
+ * to look like it holds a takedown duty for a site it does not operate.
+ * §512's obligations attach to the entity that actually hosts and controls the
+ * material, which on a self-host install is the operator and nobody else.
+ *
+ * ## Why the default is EMPTY, and not our address
+ *
+ * AGL-2016 originally proposed our address as the default "so Aglyn's own
+ * deployment is unchanged". That is the wrong default *for this value*, and
+ * the distinction is worth stating because the sibling fixes went the other
+ * way and were right to.
+ *
+ * `TENANT_PRODUCTION_ROOT` (AGL-2022) defaults to `aglyn.app`, and an operator
+ * who does not set it gets links that are merely *wrong* — visibly, on the
+ * first click, in their own console. A contact address that defaults to ours
+ * fails **silently and off-site**: nothing in the operator's product looks
+ * broken, and the only party who learns is a copyright holder whose notice
+ * landed with a stranger. A wrong default that is invisible to the person who
+ * could fix it is not a default, it is a trap.
+ *
+ * So: absent is a first-class state, exactly as AGL-2021 established for the
+ * Texas registration identifiers, and for the same reason — an explicit
+ * "not configured" beats a blank that reads as an address, and beats a
+ * plausible-looking value that reads as fact. The cost is that Aglyn's own
+ * deployment must now configure these like any other operator. That is the
+ * point: it is what makes this configuration rather than a rename.
+ *
+ * ## Why `NEXT_PUBLIC_`, and why dot notation is load-bearing
+ *
+ * Every value here is printed to the public — that is what it is *for* — so
+ * `NEXT_PUBLIC_` carries no disclosure risk, unlike AGL-2021's staff-gated
+ * identifiers, which are deliberately server-only.
+ *
+ * Next inlines `NEXT_PUBLIC_*` into the browser bundle by textually
+ * substituting `process.env.NAME`. The **bracket** form is never substituted
+ * and reads `undefined` in the browser. AGL-2037 is that bug live in
+ * `tenant-dns.ts`; AGL-2022's `tenant-links.ts` is the corrected reference.
+ * Every read below is dot notation on purpose — do not "tidy" it to brackets,
+ * and do not introduce a parallel server-only `OPERATOR_*` name: AGL-733 is
+ * the record of what happens when one value acquires two env names.
+ *
+ * Note the build-time consequence for self-hosters: `NEXT_PUBLIC_*` is baked
+ * in when the image is built, so these must be set *before* `docker compose
+ * build`, not merely before `up`. `docs/SELF_HOSTING.md` says so.
+ *
+ * ## Empty vs whitespace
+ *
+ * `'   '` is the shape a half-finished `.env` actually takes and it satisfies
+ * a truthiness check. Every read is trimmed and treated as absent, so a
+ * half-finished file cannot produce a mailto with nothing behind it.
+ */
+/** The entity operating this deployment, as far as configuration knows. */
+export interface OperatorIdentity {
+    /** Legal/display name of the operator, e.g. `Aglyn LLC`. */
+    name: string | null;
+    /** Where support and abuse correspondence goes. */
+    supportEmail: string | null;
+    /**
+     * Where legal notices go. Falls back to {@link OperatorIdentity.supportEmail}
+     * when unset, because an operator with one mailbox is the common case and a
+     * missing legal address must not silently become *no* address.
+     */
+    legalEmail: string | null;
+    /** Origin serving the operator's published legal pages, no trailing slash. */
+    legalOrigin: string | null;
+    /**
+     * True when this deployment has published enough to be addressed at all —
+     * a name AND a way to reach it. Anything less renders the honest
+     * unconfigured state rather than a half-identity.
+     */
+    configured: boolean;
+}
+/**
+ * The operator's §512 designated agent, when — and only when — the operator
+ * has actually designated one.
+ *
+ * Separate from {@link OperatorIdentity} on purpose. Having a support address
+ * is not having a designated agent: the designation is a filing with the U.S.
+ * Copyright Office, it costs money, it must be renewed every three years, and
+ * it is what a service provider's safe harbour under 17 U.S.C. §512(c) hangs
+ * on. Aglyn has made that filing. A self-hoster who has merely set a support
+ * address has not, and is not covered by ours.
+ *
+ * So the designation is never inferred from the presence of an address. It
+ * renders only from its own configuration, and the *claim of registration* —
+ * the sentence that is legally load-bearing and legally false if borrowed —
+ * requires a further explicit opt-in. See {@link operatorDmcaAgent}.
+ */
+export interface OperatorDmcaAgent {
+    /** Name of the designated agent (a person or a department). */
+    name: string;
+    /** Physical address, as filed. Newlines permitted. */
+    address: string;
+    /** Address notices are accepted at. */
+    email: string | null;
+    /** Phone, as filed. */
+    phone: string | null;
+    /**
+     * Whether the operator asserts the designation is **registered with the
+     * U.S. Copyright Office**. Only this makes the product state it.
+     */
+    registered: boolean;
+}
+/**
+ * What a surface prints where an operator address would go when the
+ * deployment has not configured one.
+ *
+ * NOT an empty string, and NOT a plausible placeholder. A blank in a contact
+ * slot reads as "nobody filled it in yet" — harmless on a settings screen,
+ * actively misleading on a page whose entire job is to tell a copyright
+ * holder where to send a statutory notice. Same argument, same shape, as
+ * AGL-2021's `TX_REGISTRATION_UNSET`: say what is true and name the fix.
+ */
+export declare const OPERATOR_CONTACT_UNSET = "not configured \u2014 this deployment has published no contact address";
+/**
+ * The lede an unconfigured intake shows instead of naming an operator.
+ *
+ * Deliberately tells the reporter to stop and go elsewhere. A form that
+ * silently routes a legal notice to the wrong entity is worse than a form
+ * that admits it is unconfigured, because the first one consumes the
+ * reporter's time and their statutory clock before failing.
+ */
+export declare const OPERATOR_UNCONFIGURED_NOTICE: string;
+/**
+ * Resolve the operator from configuration.
+ *
+ * A function rather than module-scope constants, deliberately. Module-scope
+ * capture is what forced AGL-2022's spec into `jest.resetModules()` gymnastics
+ * to prove it read configuration at all — and a guard that cannot cheaply
+ * re-read config tends to end up only testing the default, which is exactly
+ * the failure this issue is about. Reading per call also means a test that
+ * sets the env and one that does not can sit next to each other in one file
+ * and prove the asymmetry.
+ *
+ * Next's build-time substitution is unaffected: `process.env.NEXT_PUBLIC_*` is
+ * replaced textually wherever it appears, function bodies included.
+ */
+export declare function operatorIdentity(): OperatorIdentity;
+/**
+ * The operator's designated agent, or `null` when they have not designated
+ * one — which is the correct answer for every deployment except one that has
+ * actually filed.
+ *
+ * `name` and `address` are both required because a designation without a
+ * physical address is not a designation; the Copyright Office directory
+ * record carries both, and a notice sender is entitled to either.
+ *
+ * `registered` is separately gated on an explicit `true`. An operator who
+ * fills in an agent block so their form has a name on it has *not* thereby
+ * claimed a Copyright Office registration, and the product must not upgrade
+ * their configuration into a legal assertion on their behalf.
+ */
+export declare function operatorDmcaAgent(): OperatorDmcaAgent | null;
+/**
+ * The address a contact line should print, or {@link OPERATOR_CONTACT_UNSET}.
+ *
+ * `kind: 'legal'` prefers the legal mailbox; everything else takes support.
+ * Returns the marker rather than `null` so a caller cannot accidentally
+ * interpolate `null` into copy — `String(null)` is `'null'`, which reads as a
+ * value.
+ */
+export declare function operatorContactLine(kind?: 'support' | 'legal'): {
+    address: string | null;
+    text: string;
+};
+/**
+ * How the intake should name whoever runs this deployment, in running prose.
+ *
+ * `'the operator of this site'` when unconfigured — true on every deployment,
+ * including ours, and it never names the wrong company.
+ */
+export declare function operatorDisplayName(): string;