@aglyn/aglyn 1.0.0-beta.195 → 1.0.0-beta.196

package/src/lib/app-utils/system-email-chrome.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @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.
+ */
+/**
+ * The header and footer a system email is drawn inside, for the brand it is
+ * sent under (AGL-3322).
+ *
+ * A system email's built-in copy is a few lines of text, and only a staff
+ * design can place the platform marketing site's email blocks. Without this,
+ * the mail the platform sends most — every password reset, invite and alert
+ * nobody has designed — would name its sender nowhere but the From line, and
+ * tell the reader neither why it came nor where to get help. The renderer
+ * draws whatever `EmailChrome` it is handed; this module decides what that
+ * is, which comes down to one question: whose mail is this?
+ *
+ * ## The platform's own
+ *
+ * Its logo linked to its home page, and a footer of the email's reason, the
+ * support link and a `© {year} {legal name} · {postal address}` line. Every
+ * value is read from `platform-brand.ts`, so a renamed or self-hosted
+ * deployment prints its own configuration: its logo or its name in bold, its
+ * home page or no link, its address or none — and never ours. The Aglyn
+ * defaults there apply only while the deployment is still called Aglyn.
+ *
+ * ## A white-label organization's
+ *
+ * Its own email logo, or its product name in bold; the reason, whose brand
+ * tokens are the agency's; and a support link only when the agency set one.
+ * No legal line: the only legal name and address this module knows are the
+ * platform's, and the recipient is the agency's customer, who must not learn
+ * the platform exists from the foot of an invite.
+ *
+ * Pure: no reads, no clock of its own that a test cannot replace.
+ */
+import type { EmailChrome } from '@aglyn/shared-util-email/email-render';
+import type { SystemEmailTemplateDefinition } from '@aglyn/shared-util-email/system-email-catalog';
+/**
+ * `brand.*` tokens every system email resolves, UNDER whatever the caller
+ * supplies (AGL-2139).
+ *
+ * The order is the whole safety property. A system email blanks any token
+ * the caller did not provide, so a designed template written against
+ * `{{brand.productName}}` would ship with a hole in the sentence at any send
+ * site that forgot to pass one. Defaulting to the platform profile means the
+ * worst case is the platform's own copy rather than a gap — and an
+ * org-context sender that spreads `brandMergeTokens(branding)` into its merge
+ * map wins, because a later key overwrites an earlier one.
+ *
+ * The platform-scoped senders — password reset, email verification, the
+ * security alerts, the staff erasure-hold alert — genuinely have no org (each
+ * says so at its own call site, and password reset deliberately refuses to
+ * look one up because that would be an enumeration oracle). The platform IS
+ * their brand, so these are the right answer for them.
+ */
+export declare const PLATFORM_BRAND_MERGE_TOKENS: Readonly<Record<string, string>>;
+/**
+ * Brand inputs that are NOT merge tokens (AGL-2139).
+ *
+ * `brand.productName` and friends ride the merge map because a designer types
+ * them into copy. The logo and the home page are structural — the header the
+ * renderer draws, or does not — so they are options rather than tokens a
+ * template could forget to place.
+ */
+export interface SystemEmailBrandOptions {
+    /** The org's resolved `emailLogoUrl`; absent or blank is no org logo. */
+    brandLogoUrl?: string | null;
+    /**
+     * The org's resolved `homeUrl`: where a white-label header links. Only an
+     * `http(s)` URL is linked; a `mailto:` home is no destination for a logo.
+     */
+    brandHomeUrl?: string | null;
+}
+/**
+ * Whether a send goes out under the PLATFORM's brand, which is the only kind
+ * that may carry the platform's header and footer — the marketing site's
+ * email blocks (AGL-3318), or the chrome {@link buildSystemEmailChrome} draws
+ * in their place (AGL-3322).
+ *
+ * Those are the platform's logo, its address, its line telling the reader why
+ * they get the mail. An agency on white-label sells its clients a product
+ * with no vendor in it, and an invite or a usage summary sent to one of their
+ * people reads as the agency's own mail. One platform footer in it names the
+ * vendor the whole tier is bought to hide.
+ *
+ * Read off what the send is actually branded as, rather than asked of the
+ * caller, so no sender can forget to say. An org-context sender spreads
+ * `brandMergeTokens(resolveBrandingProfile(org))` over the defaults and passes
+ * the profile's email logo. A white-label profile never inherits the
+ * platform's support URL (AGL-2428), so its tokens differ from
+ * {@link PLATFORM_BRAND_MERGE_TOKENS} on `brand.supportUrl` at least, and the
+ * platform profile has no email logo of its own, so any logo is an org's. The
+ * org-less senders, and every org without white-label, which resolves to the
+ * platform profile itself, match the defaults exactly: those sends are the
+ * platform's.
+ */
+export declare function isPlatformBrandedSend(merged: Readonly<Record<string, string>>, options?: SystemEmailBrandOptions): boolean;
+export interface SystemEmailChromeInput extends SystemEmailBrandOptions {
+    /** The email being sent; its `footerReason` is the footer's first line. */
+    definition: Pick<SystemEmailTemplateDefinition, 'footerReason'>;
+    /**
+     * The send's merge map, platform brand tokens under the caller's — the map
+     * the body renders with, which is what makes the reason's tokens resolve to
+     * the same names the body uses.
+     */
+    merged: Readonly<Record<string, string>>;
+    /** The clock the copyright year is read from. */
+    now?: () => Date;
+}
+/**
+ * The chrome one system email is drawn inside, for the brand it is sent
+ * under. See the module comment for the two shapes and why they differ.
+ *
+ * The reason and the other lines go out as templates: the renderer runs them
+ * through the same merge substitution as the body, so `{{org.name}}` and
+ * `{{brand.productName}}` read exactly as they do in the copy above them.
+ */
+export declare function buildSystemEmailChrome(input: SystemEmailChromeInput): EmailChrome;

package/src/lib/app-utils/system-email-chrome.js

@@ -0,0 +1,171 @@
+/**
+ * @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.
+ */ /**
+ * The header and footer a system email is drawn inside, for the brand it is
+ * sent under (AGL-3322).
+ *
+ * A system email's built-in copy is a few lines of text, and only a staff
+ * design can place the platform marketing site's email blocks. Without this,
+ * the mail the platform sends most — every password reset, invite and alert
+ * nobody has designed — would name its sender nowhere but the From line, and
+ * tell the reader neither why it came nor where to get help. The renderer
+ * draws whatever `EmailChrome` it is handed; this module decides what that
+ * is, which comes down to one question: whose mail is this?
+ *
+ * ## The platform's own
+ *
+ * Its logo linked to its home page, and a footer of the email's reason, the
+ * support link and a `© {year} {legal name} · {postal address}` line. Every
+ * value is read from `platform-brand.ts`, so a renamed or self-hosted
+ * deployment prints its own configuration: its logo or its name in bold, its
+ * home page or no link, its address or none — and never ours. The Aglyn
+ * defaults there apply only while the deployment is still called Aglyn.
+ *
+ * ## A white-label organization's
+ *
+ * Its own email logo, or its product name in bold; the reason, whose brand
+ * tokens are the agency's; and a support link only when the agency set one.
+ * No legal line: the only legal name and address this module knows are the
+ * platform's, and the recipient is the agency's customer, who must not learn
+ * the platform exists from the foot of an invite.
+ *
+ * Pure: no reads, no clock of its own that a test cannot replace.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { brandMergeTokens } from "./plan-entitlements.js";
+import { PLATFORM_BRANDING_PROFILE, PLATFORM_BRAND_LEGAL_NAME, PLATFORM_BRAND_NAME, PLATFORM_EMAIL_LOGO_URL, PLATFORM_HOME_URL, PLATFORM_POSTAL_ADDRESS } from "./platform-brand.js";
+/**
+ * `brand.*` tokens every system email resolves, UNDER whatever the caller
+ * supplies (AGL-2139).
+ *
+ * The order is the whole safety property. A system email blanks any token
+ * the caller did not provide, so a designed template written against
+ * `{{brand.productName}}` would ship with a hole in the sentence at any send
+ * site that forgot to pass one. Defaulting to the platform profile means the
+ * worst case is the platform's own copy rather than a gap — and an
+ * org-context sender that spreads `brandMergeTokens(branding)` into its merge
+ * map wins, because a later key overwrites an earlier one.
+ *
+ * The platform-scoped senders — password reset, email verification, the
+ * security alerts, the staff erasure-hold alert — genuinely have no org (each
+ * says so at its own call site, and password reset deliberately refuses to
+ * look one up because that would be an enumeration oracle). The platform IS
+ * their brand, so these are the right answer for them.
+ */ export const PLATFORM_BRAND_MERGE_TOKENS = brandMergeTokens(PLATFORM_BRANDING_PROFILE);
+/**
+ * Whether a send goes out under the PLATFORM's brand, which is the only kind
+ * that may carry the platform's header and footer — the marketing site's
+ * email blocks (AGL-3318), or the chrome {@link buildSystemEmailChrome} draws
+ * in their place (AGL-3322).
+ *
+ * Those are the platform's logo, its address, its line telling the reader why
+ * they get the mail. An agency on white-label sells its clients a product
+ * with no vendor in it, and an invite or a usage summary sent to one of their
+ * people reads as the agency's own mail. One platform footer in it names the
+ * vendor the whole tier is bought to hide.
+ *
+ * Read off what the send is actually branded as, rather than asked of the
+ * caller, so no sender can forget to say. An org-context sender spreads
+ * `brandMergeTokens(resolveBrandingProfile(org))` over the defaults and passes
+ * the profile's email logo. A white-label profile never inherits the
+ * platform's support URL (AGL-2428), so its tokens differ from
+ * {@link PLATFORM_BRAND_MERGE_TOKENS} on `brand.supportUrl` at least, and the
+ * platform profile has no email logo of its own, so any logo is an org's. The
+ * org-less senders, and every org without white-label, which resolves to the
+ * platform profile itself, match the defaults exactly: those sends are the
+ * platform's.
+ */ export function isPlatformBrandedSend(merged, options = {}) {
+    var _options_brandLogoUrl;
+    if (String((_options_brandLogoUrl = options.brandLogoUrl) != null ? _options_brandLogoUrl : '').trim()) return false;
+    return Object.entries(PLATFORM_BRAND_MERGE_TOKENS).every(([token, value])=>merged[token] === value);
+}
+/** A non-empty trimmed string, else undefined. */ const clean = (value)=>{
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text.length ? text : undefined;
+};
+/**
+ * The footer's support link, from the send's `brand.supportUrl`, or
+ * undefined when it has none.
+ *
+ * Empty is a decision, not a gap: a white-label org that set no support URL
+ * gets NO line rather than the platform's desk (AGL-2428), which cannot help
+ * its customers and would name the vendor to them. A `mailto:` reads as the
+ * mailbox, which is what the reader has to type into a client that does not
+ * follow the link; a web page reads as an instruction.
+ */ function supportLink(url) {
+    const href = clean(url);
+    if (!href) return undefined;
+    if (/^mailto:/i.test(href)) {
+        const address = clean(href.slice('mailto:'.length).split('?')[0]);
+        return address ? {
+            label: address,
+            href
+        } : undefined;
+    }
+    return {
+        label: 'Get help',
+        href
+    };
+}
+/**
+ * The chrome one system email is drawn inside, for the brand it is sent
+ * under. See the module comment for the two shapes and why they differ.
+ *
+ * The reason and the other lines go out as templates: the renderer runs them
+ * through the same merge substitution as the body, so `{{org.name}}` and
+ * `{{brand.productName}}` read exactly as they do in the copy above them.
+ */ export function buildSystemEmailChrome(input) {
+    var _input_now, _merged_brandproductName;
+    const { definition, merged, brandLogoUrl, brandHomeUrl } = input;
+    const now = (_input_now = input.now) != null ? _input_now : ()=>new Date();
+    const reason = clean(definition.footerReason);
+    const support = supportLink(merged['brand.supportUrl']);
+    const footer = _extends({}, reason ? {
+        reason
+    } : {}, support ? {
+        support
+    } : {});
+    if (isPlatformBrandedSend(merged, {
+        brandLogoUrl
+    })) {
+        const legal = `© ${now().getUTCFullYear()} ${PLATFORM_BRAND_LEGAL_NAME}` + (PLATFORM_POSTAL_ADDRESS ? ` · ${PLATFORM_POSTAL_ADDRESS}` : '');
+        return {
+            header: _extends({}, PLATFORM_EMAIL_LOGO_URL ? {
+                logoUrl: PLATFORM_EMAIL_LOGO_URL
+            } : {}, {
+                logoAlt: PLATFORM_BRAND_NAME
+            }, PLATFORM_HOME_URL ? {
+                href: PLATFORM_HOME_URL
+            } : {}),
+            footer: _extends({}, footer, {
+                legal
+            })
+        };
+    }
+    const logoUrl = clean(brandLogoUrl);
+    const home = clean(brandHomeUrl);
+    return {
+        header: _extends({}, logoUrl ? {
+            logoUrl
+        } : {}, {
+            logoAlt: (_merged_brandproductName = merged['brand.productName']) != null ? _merged_brandproductName : ''
+        }, home && /^https?:\/\//i.test(home) ? {
+            href: home
+        } : {}),
+        footer
+    };
+}
+
+//# sourceMappingURL=system-email-chrome.js.map

package/src/lib/app-utils/system-email-chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/system-email-chrome.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 * The header and footer a system email is drawn inside, for the brand it is\n * sent under (AGL-3322).\n *\n * A system email's built-in copy is a few lines of text, and only a staff\n * design can place the platform marketing site's email blocks. Without this,\n * the mail the platform sends most — every password reset, invite and alert\n * nobody has designed — would name its sender nowhere but the From line, and\n * tell the reader neither why it came nor where to get help. The renderer\n * draws whatever `EmailChrome` it is handed; this module decides what that\n * is, which comes down to one question: whose mail is this?\n *\n * ## The platform's own\n *\n * Its logo linked to its home page, and a footer of the email's reason, the\n * support link and a `© {year} {legal name} · {postal address}` line. Every\n * value is read from `platform-brand.ts`, so a renamed or self-hosted\n * deployment prints its own configuration: its logo or its name in bold, its\n * home page or no link, its address or none — and never ours. The Aglyn\n * defaults there apply only while the deployment is still called Aglyn.\n *\n * ## A white-label organization's\n *\n * Its own email logo, or its product name in bold; the reason, whose brand\n * tokens are the agency's; and a support link only when the agency set one.\n * No legal line: the only legal name and address this module knows are the\n * platform's, and the recipient is the agency's customer, who must not learn\n * the platform exists from the foot of an invite.\n *\n * Pure: no reads, no clock of its own that a test cannot replace.\n */\n\nimport type {\n  EmailChrome,\n  EmailChromeFooter,\n} from '@aglyn/shared-util-email/email-render'\nimport type { SystemEmailTemplateDefinition } from '@aglyn/shared-util-email/system-email-catalog'\n\nimport { brandMergeTokens } from './plan-entitlements'\nimport {\n  PLATFORM_BRANDING_PROFILE,\n  PLATFORM_BRAND_LEGAL_NAME,\n  PLATFORM_BRAND_NAME,\n  PLATFORM_EMAIL_LOGO_URL,\n  PLATFORM_HOME_URL,\n  PLATFORM_POSTAL_ADDRESS,\n} from './platform-brand'\n\n/**\n * `brand.*` tokens every system email resolves, UNDER whatever the caller\n * supplies (AGL-2139).\n *\n * The order is the whole safety property. A system email blanks any token\n * the caller did not provide, so a designed template written against\n * `{{brand.productName}}` would ship with a hole in the sentence at any send\n * site that forgot to pass one. Defaulting to the platform profile means the\n * worst case is the platform's own copy rather than a gap — and an\n * org-context sender that spreads `brandMergeTokens(branding)` into its merge\n * map wins, because a later key overwrites an earlier one.\n *\n * The platform-scoped senders — password reset, email verification, the\n * security alerts, the staff erasure-hold alert — genuinely have no org (each\n * says so at its own call site, and password reset deliberately refuses to\n * look one up because that would be an enumeration oracle). The platform IS\n * their brand, so these are the right answer for them.\n */\nexport const PLATFORM_BRAND_MERGE_TOKENS: Readonly<Record<string, string>> =\n  brandMergeTokens(PLATFORM_BRANDING_PROFILE)\n\n/**\n * Brand inputs that are NOT merge tokens (AGL-2139).\n *\n * `brand.productName` and friends ride the merge map because a designer types\n * them into copy. The logo and the home page are structural — the header the\n * renderer draws, or does not — so they are options rather than tokens a\n * template could forget to place.\n */\nexport interface SystemEmailBrandOptions {\n  /** The org's resolved `emailLogoUrl`; absent or blank is no org logo. */\n  brandLogoUrl?: string | null\n  /**\n   * The org's resolved `homeUrl`: where a white-label header links. Only an\n   * `http(s)` URL is linked; a `mailto:` home is no destination for a logo.\n   */\n  brandHomeUrl?: string | null\n}\n\n/**\n * Whether a send goes out under the PLATFORM's brand, which is the only kind\n * that may carry the platform's header and footer — the marketing site's\n * email blocks (AGL-3318), or the chrome {@link buildSystemEmailChrome} draws\n * in their place (AGL-3322).\n *\n * Those are the platform's logo, its address, its line telling the reader why\n * they get the mail. An agency on white-label sells its clients a product\n * with no vendor in it, and an invite or a usage summary sent to one of their\n * people reads as the agency's own mail. One platform footer in it names the\n * vendor the whole tier is bought to hide.\n *\n * Read off what the send is actually branded as, rather than asked of the\n * caller, so no sender can forget to say. An org-context sender spreads\n * `brandMergeTokens(resolveBrandingProfile(org))` over the defaults and passes\n * the profile's email logo. A white-label profile never inherits the\n * platform's support URL (AGL-2428), so its tokens differ from\n * {@link PLATFORM_BRAND_MERGE_TOKENS} on `brand.supportUrl` at least, and the\n * platform profile has no email logo of its own, so any logo is an org's. The\n * org-less senders, and every org without white-label, which resolves to the\n * platform profile itself, match the defaults exactly: those sends are the\n * platform's.\n */\nexport function isPlatformBrandedSend(\n  merged: Readonly<Record<string, string>>,\n  options: SystemEmailBrandOptions = {},\n): boolean {\n  if (String(options.brandLogoUrl ?? '').trim()) return false\n  return Object.entries(PLATFORM_BRAND_MERGE_TOKENS).every(\n    ([token, value]) => merged[token] === value,\n  )\n}\n\nexport interface SystemEmailChromeInput extends SystemEmailBrandOptions {\n  /** The email being sent; its `footerReason` is the footer's first line. */\n  definition: Pick<SystemEmailTemplateDefinition, 'footerReason'>\n  /**\n   * The send's merge map, platform brand tokens under the caller's — the map\n   * the body renders with, which is what makes the reason's tokens resolve to\n   * the same names the body uses.\n   */\n  merged: Readonly<Record<string, string>>\n  /** The clock the copyright year is read from. */\n  now?: () => Date\n}\n\n/** A non-empty trimmed string, else undefined. */\nconst clean = (value: string | null | undefined): string | undefined => {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return text.length ? text : undefined\n}\n\n/**\n * The footer's support link, from the send's `brand.supportUrl`, or\n * undefined when it has none.\n *\n * Empty is a decision, not a gap: a white-label org that set no support URL\n * gets NO line rather than the platform's desk (AGL-2428), which cannot help\n * its customers and would name the vendor to them. A `mailto:` reads as the\n * mailbox, which is what the reader has to type into a client that does not\n * follow the link; a web page reads as an instruction.\n */\nfunction supportLink(\n  url: string | undefined,\n): EmailChromeFooter['support'] | undefined {\n  const href = clean(url)\n  if (!href) return undefined\n  if (/^mailto:/i.test(href)) {\n    const address = clean(href.slice('mailto:'.length).split('?')[0])\n    return address ? { label: address, href } : undefined\n  }\n  return { label: 'Get help', href }\n}\n\n/**\n * The chrome one system email is drawn inside, for the brand it is sent\n * under. See the module comment for the two shapes and why they differ.\n *\n * The reason and the other lines go out as templates: the renderer runs them\n * through the same merge substitution as the body, so `{{org.name}}` and\n * `{{brand.productName}}` read exactly as they do in the copy above them.\n */\nexport function buildSystemEmailChrome(\n  input: SystemEmailChromeInput,\n): EmailChrome {\n  const { definition, merged, brandLogoUrl, brandHomeUrl } = input\n  const now = input.now ?? (() => new Date())\n  const reason = clean(definition.footerReason)\n  const support = supportLink(merged['brand.supportUrl'])\n  const footer: EmailChromeFooter = {\n    ...(reason ? { reason } : {}),\n    ...(support ? { support } : {}),\n  }\n\n  if (isPlatformBrandedSend(merged, { brandLogoUrl })) {\n    const legal =\n      `© ${now().getUTCFullYear()} ${PLATFORM_BRAND_LEGAL_NAME}` +\n      (PLATFORM_POSTAL_ADDRESS ? ` · ${PLATFORM_POSTAL_ADDRESS}` : '')\n    return {\n      header: {\n        ...(PLATFORM_EMAIL_LOGO_URL ? { logoUrl: PLATFORM_EMAIL_LOGO_URL } : {}),\n        logoAlt: PLATFORM_BRAND_NAME,\n        ...(PLATFORM_HOME_URL ? { href: PLATFORM_HOME_URL } : {}),\n      },\n      footer: { ...footer, legal },\n    }\n  }\n\n  const logoUrl = clean(brandLogoUrl)\n  const home = clean(brandHomeUrl)\n  return {\n    header: {\n      ...(logoUrl ? { logoUrl } : {}),\n      logoAlt: merged['brand.productName'] ?? '',\n      ...(home && /^https?:\\/\\//i.test(home) ? { href: home } : {}),\n    },\n    footer,\n  }\n}\n"],"names":["brandMergeTokens","PLATFORM_BRANDING_PROFILE","PLATFORM_BRAND_LEGAL_NAME","PLATFORM_BRAND_NAME","PLATFORM_EMAIL_LOGO_URL","PLATFORM_HOME_URL","PLATFORM_POSTAL_ADDRESS","PLATFORM_BRAND_MERGE_TOKENS","isPlatformBrandedSend","merged","options","String","brandLogoUrl","trim","Object","entries","every","token","value","clean","text","length","undefined","supportLink","url","href","test","address","slice","split","label","buildSystemEmailChrome","input","definition","brandHomeUrl","now","Date","reason","footerReason","support","footer","legal","getUTCFullYear","header","logoUrl","logoAlt","home"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC;AAQD,SAASA,gBAAgB,QAAQ,yBAAqB;AACtD,SACEC,yBAAyB,EACzBC,yBAAyB,EACzBC,mBAAmB,EACnBC,uBAAuB,EACvBC,iBAAiB,EACjBC,uBAAuB,QAClB,sBAAkB;AAEzB;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,MAAMC,8BACXP,iBAAiBC,2BAA0B;AAoB7C;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASO,sBACdC,MAAwC,EACxCC,UAAmC,CAAC,CAAC;QAE1BA;IAAX,IAAIC,QAAOD,wBAAAA,QAAQE,YAAY,YAApBF,wBAAwB,IAAIG,IAAI,IAAI,OAAO;IACtD,OAAOC,OAAOC,OAAO,CAACR,6BAA6BS,KAAK,CACtD,CAAC,CAACC,OAAOC,MAAM,GAAKT,MAAM,CAACQ,MAAM,KAAKC;AAE1C;AAeA,gDAAgD,GAChD,MAAMC,QAAQ,CAACD;IACb,MAAME,OAAO,OAAOF,UAAU,WAAWA,MAAML,IAAI,KAAK;IACxD,OAAOO,KAAKC,MAAM,GAAGD,OAAOE;AAC9B;AAEA;;;;;;;;;CASC,GACD,SAASC,YACPC,GAAuB;IAEvB,MAAMC,OAAON,MAAMK;IACnB,IAAI,CAACC,MAAM,OAAOH;IAClB,IAAI,YAAYI,IAAI,CAACD,OAAO;QAC1B,MAAME,UAAUR,MAAMM,KAAKG,KAAK,CAAC,UAAUP,MAAM,EAAEQ,KAAK,CAAC,IAAI,CAAC,EAAE;QAChE,OAAOF,UAAU;YAAEG,OAAOH;YAASF;QAAK,IAAIH;IAC9C;IACA,OAAO;QAAEQ,OAAO;QAAYL;IAAK;AACnC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASM,uBACdC,KAA6B;QAGjBA,YA2BCvB;IA5Bb,MAAM,EAAEwB,UAAU,EAAExB,MAAM,EAAEG,YAAY,EAAEsB,YAAY,EAAE,GAAGF;IAC3D,MAAMG,OAAMH,aAAAA,MAAMG,GAAG,YAATH,aAAc,IAAM,IAAII;IACpC,MAAMC,SAASlB,MAAMc,WAAWK,YAAY;IAC5C,MAAMC,UAAUhB,YAAYd,MAAM,CAAC,mBAAmB;IACtD,MAAM+B,SAA4B,aAC5BH,SAAS;QAAEA;IAAO,IAAI,CAAC,GACvBE,UAAU;QAAEA;IAAQ,IAAI,CAAC;IAG/B,IAAI/B,sBAAsBC,QAAQ;QAAEG;IAAa,IAAI;QACnD,MAAM6B,QACJ,CAAC,EAAE,EAAEN,MAAMO,cAAc,GAAG,CAAC,EAAExC,2BAA2B,GACzDI,CAAAA,0BAA0B,CAAC,GAAG,EAAEA,yBAAyB,GAAG,EAAC;QAChE,OAAO;YACLqC,QAAQ,aACFvC,0BAA0B;gBAAEwC,SAASxC;YAAwB,IAAI,CAAC;gBACtEyC,SAAS1C;eACLE,oBAAoB;gBAAEoB,MAAMpB;YAAkB,IAAI,CAAC;YAEzDmC,QAAQ,aAAKA;gBAAQC;;QACvB;IACF;IAEA,MAAMG,UAAUzB,MAAMP;IACtB,MAAMkC,OAAO3B,MAAMe;IACnB,OAAO;QACLS,QAAQ,aACFC,UAAU;YAAEA;QAAQ,IAAI,CAAC;YAC7BC,OAAO,GAAEpC,2BAAAA,MAAM,CAAC,oBAAoB,YAA3BA,2BAA+B;WACpCqC,QAAQ,gBAAgBpB,IAAI,CAACoB,QAAQ;YAAErB,MAAMqB;QAAK,IAAI,CAAC;QAE7DN;IACF;AACF"}

package/src/lib/plugin-manager/plugin-text-generation.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @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.
+ */
+/**
+ * Text one plugin has written for it by the workspace's generation service
+ * (AGL-3324).
+ *
+ * A plugin that wants a paragraph drafted — a sequence's email for one
+ * person, a summary, a subject line — must not reach a model itself: the
+ * provider, the model choice, the credits, the allotments and the usage
+ * ledger all belong to whichever plugin sells generation to the workspace,
+ * and the package map forbids importing it. So that plugin registers ONE
+ * generator here (a slot), and a caller asks for it by nothing more than
+ * "the generator": the request names the member the text is for and what
+ * the text is for, and the generator applies every rule it applies at its
+ * own doors — the permission, the entitlement, the switches, the meter —
+ * and answers the text, or why not, and never throws for a refusal.
+ *
+ * ## The registry carries no authorization of the CALLER
+ *
+ * A generator applies its rules to the member the request names, and knows
+ * nothing about whether the caller may act for that member. A caller
+ * establishes, in its own terms and before it asks: who is asking, and that
+ * the org is the one they are a member of.
+ *
+ * ## What a request may carry
+ *
+ * `system` is the caller's standing instructions, byte-identical from one
+ * call to the next so a provider that caches a prefix can; everything about
+ * the particular person or record rides in `prompt`. Nothing here is
+ * remembered by the generator beyond its usage ledger, which keeps the
+ * purpose and the tokens and never the words.
+ */
+export interface PluginTextGenerationRequest {
+    orgId: string;
+    /**
+     * The site the text is for, when it is for one: a collaborator's
+     * permission and a site's allotment are decided on it. `null` on an
+     * org-level surface.
+     */
+    hostId: string | null;
+    /** The member the text is for: their permission, their allotment, their usage. */
+    uid: string;
+    /** Whether the member's session carries a verified staff claim. */
+    staff: boolean;
+    /**
+     * The org document the caller already read, for the generator's
+     * entitlement and meter reads; `null` and the generator reads it.
+     */
+    org: Readonly<Record<string, unknown>> | null;
+    /**
+     * What the text is for, as the usage ledger buckets it: the plugin's id
+     * and a word, joined by a hyphen (`outreach-curate`). Letters, digits and
+     * hyphens only; a generator normalizes anything else.
+     */
+    purpose: string;
+    /** The caller's standing instructions — see the module note. */
+    system: string;
+    /** The one turn: the brief, the record's facts, the skeleton to rewrite. */
+    prompt: string;
+    /** The longest answer wanted, in tokens; the generator caps it at its own ceiling. */
+    maxTokens?: number;
+    now?: Date;
+    signal?: AbortSignal;
+}
+/** Why a generator did not answer with text. */
+export type PluginTextGenerationRefusalReason = 
+/** No plugin generates text for this workspace, or the door is not released to it. */
+'unavailable'
+/** The member's role lacks the generation permission. */
+ | 'permission'
+/** The workspace's plan does not include generation. */
+ | 'entitlement'
+/** Generation is switched off — for the platform, the workspace or the site. */
+ | 'off'
+/** A limit refused the request: credits, a budget, an allotment. */
+ | 'quota'
+/** The model declined to write it. */
+ | 'refused'
+/** The provider could not be reached or failed; nothing was spent. */
+ | 'failed';
+export interface PluginTextGenerationRefusal {
+    ok: false;
+    /** The HTTP status a door would answer with. */
+    status: number;
+    reason: PluginTextGenerationRefusalReason;
+    /** Customer-safe: a caller shows it as it stands. */
+    error: string;
+}
+export interface PluginTextGenerationAnswer {
+    ok: true;
+    text: string;
+    /** The model that wrote it, for the caller's own audit record. */
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export type PluginTextGenerationResult = PluginTextGenerationAnswer | PluginTextGenerationRefusal;
+export interface PluginTextGenerator {
+    /** The text, or why not. A refusal is returned, never thrown. */
+    generate(request: PluginTextGenerationRequest): Promise<PluginTextGenerationResult>;
+}
+export declare const PLUGIN_TEXT_GENERATION: import("./plugin-services").PluginServiceContract<PluginTextGenerator>;
+/**
+ * Registers the workspace's text generator. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A second plugin's generator throws naming both, and
+ * the incumbent keeps serving; the same plugin registering again replaces
+ * its own.
+ */
+export declare function registerPluginTextGenerator(generator: PluginTextGenerator, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginTextGenerator {
+    /** The plugin that generates. */
+    pluginId: string;
+    generator: PluginTextGenerator;
+}
+/** The generator with its owner, or `null` when no plugin generates text. */
+export declare function pluginTextGenerator(): ResolvedPluginTextGenerator | null;
+/** A purpose as the ledger keys it: lower-case letters, digits and hyphens. */
+export declare function normalizePluginTextGenerationPurpose(purpose: string): string;

package/src/lib/plugin-manager/plugin-text-generation.js

@@ -0,0 +1,43 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_TEXT_GENERATION = definePluginServiceContract('core.text-generation', {
+    multiple: false
+});
+/**
+ * Registers the workspace's text generator. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A second plugin's generator throws naming both, and
+ * the incumbent keeps serving; the same plugin registering again replaces
+ * its own.
+ */ export function registerPluginTextGenerator(generator, options) {
+    registerPluginService(PLUGIN_TEXT_GENERATION, generator, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The generator with its owner, or `null` when no plugin generates text. */ export function pluginTextGenerator() {
+    const entry = resolvePluginServices(PLUGIN_TEXT_GENERATION)[0];
+    return entry ? {
+        pluginId: entry.pluginId,
+        generator: entry.impl
+    } : null;
+}
+/** A purpose as the ledger keys it: lower-case letters, digits and hyphens. */ export function normalizePluginTextGenerationPurpose(purpose) {
+    return String(purpose != null ? purpose : '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'plugin';
+}
+
+//# sourceMappingURL=plugin-text-generation.js.map

package/src/lib/plugin-manager/plugin-text-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-text-generation.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 {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * Text one plugin has written for it by the workspace's generation service\n * (AGL-3324).\n *\n * A plugin that wants a paragraph drafted — a sequence's email for one\n * person, a summary, a subject line — must not reach a model itself: the\n * provider, the model choice, the credits, the allotments and the usage\n * ledger all belong to whichever plugin sells generation to the workspace,\n * and the package map forbids importing it. So that plugin registers ONE\n * generator here (a slot), and a caller asks for it by nothing more than\n * \"the generator\": the request names the member the text is for and what\n * the text is for, and the generator applies every rule it applies at its\n * own doors — the permission, the entitlement, the switches, the meter —\n * and answers the text, or why not, and never throws for a refusal.\n *\n * ## The registry carries no authorization of the CALLER\n *\n * A generator applies its rules to the member the request names, and knows\n * nothing about whether the caller may act for that member. A caller\n * establishes, in its own terms and before it asks: who is asking, and that\n * the org is the one they are a member of.\n *\n * ## What a request may carry\n *\n * `system` is the caller's standing instructions, byte-identical from one\n * call to the next so a provider that caches a prefix can; everything about\n * the particular person or record rides in `prompt`. Nothing here is\n * remembered by the generator beyond its usage ledger, which keeps the\n * purpose and the tokens and never the words.\n */\n\nexport interface PluginTextGenerationRequest {\n  orgId: string\n  /**\n   * The site the text is for, when it is for one: a collaborator's\n   * permission and a site's allotment are decided on it. `null` on an\n   * org-level surface.\n   */\n  hostId: string | null\n  /** The member the text is for: their permission, their allotment, their usage. */\n  uid: string\n  /** Whether the member's session carries a verified staff claim. */\n  staff: boolean\n  /**\n   * The org document the caller already read, for the generator's\n   * entitlement and meter reads; `null` and the generator reads it.\n   */\n  org: Readonly<Record<string, unknown>> | null\n  /**\n   * What the text is for, as the usage ledger buckets it: the plugin's id\n   * and a word, joined by a hyphen (`outreach-curate`). Letters, digits and\n   * hyphens only; a generator normalizes anything else.\n   */\n  purpose: string\n  /** The caller's standing instructions — see the module note. */\n  system: string\n  /** The one turn: the brief, the record's facts, the skeleton to rewrite. */\n  prompt: string\n  /** The longest answer wanted, in tokens; the generator caps it at its own ceiling. */\n  maxTokens?: number\n  now?: Date\n  signal?: AbortSignal\n}\n\n/** Why a generator did not answer with text. */\nexport type PluginTextGenerationRefusalReason =\n  /** No plugin generates text for this workspace, or the door is not released to it. */\n  | 'unavailable'\n  /** The member's role lacks the generation permission. */\n  | 'permission'\n  /** The workspace's plan does not include generation. */\n  | 'entitlement'\n  /** Generation is switched off — for the platform, the workspace or the site. */\n  | 'off'\n  /** A limit refused the request: credits, a budget, an allotment. */\n  | 'quota'\n  /** The model declined to write it. */\n  | 'refused'\n  /** The provider could not be reached or failed; nothing was spent. */\n  | 'failed'\n\nexport interface PluginTextGenerationRefusal {\n  ok: false\n  /** The HTTP status a door would answer with. */\n  status: number\n  reason: PluginTextGenerationRefusalReason\n  /** Customer-safe: a caller shows it as it stands. */\n  error: string\n}\n\nexport interface PluginTextGenerationAnswer {\n  ok: true\n  text: string\n  /** The model that wrote it, for the caller's own audit record. */\n  model: string\n  usage: { inputTokens: number; outputTokens: number }\n}\n\nexport type PluginTextGenerationResult = PluginTextGenerationAnswer | PluginTextGenerationRefusal\n\nexport interface PluginTextGenerator {\n  /** The text, or why not. A refusal is returned, never thrown. */\n  generate(request: PluginTextGenerationRequest): Promise<PluginTextGenerationResult>\n}\n\nexport const PLUGIN_TEXT_GENERATION = definePluginServiceContract<PluginTextGenerator>(\n  'core.text-generation',\n  { multiple: false },\n)\n\n/**\n * Registers the workspace's text generator. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A second plugin's generator throws naming both, and\n * the incumbent keeps serving; the same plugin registering again replaces\n * its own.\n */\nexport function registerPluginTextGenerator(\n  generator: PluginTextGenerator,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_TEXT_GENERATION, generator, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginTextGenerator {\n  /** The plugin that generates. */\n  pluginId: string\n  generator: PluginTextGenerator\n}\n\n/** The generator with its owner, or `null` when no plugin generates text. */\nexport function pluginTextGenerator(): ResolvedPluginTextGenerator | null {\n  const entry = resolvePluginServices(PLUGIN_TEXT_GENERATION)[0]\n  return entry ? { pluginId: entry.pluginId, generator: entry.impl } : null\n}\n\n/** A purpose as the ledger keys it: lower-case letters, digits and hyphens. */\nexport function normalizePluginTextGenerationPurpose(purpose: string): string {\n  return (\n    String(purpose ?? '')\n      .toLowerCase()\n      .replace(/[^a-z0-9-]+/g, '-')\n      .replace(/^-+|-+$/g, '') || 'plugin'\n  )\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_TEXT_GENERATION","multiple","registerPluginTextGenerator","generator","options","pluginId","pluginTextGenerator","entry","impl","normalizePluginTextGenerationPurpose","purpose","String","toLowerCase","replace"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2G1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;;CAMC,GACD,OAAO,SAASC,4BACdC,SAA8B,EAC9BC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,WAAW,aACnDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,2EAA2E,GAC3E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,uBAAuB,CAAC,EAAE;IAC9D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,WAAWI,MAAMC,IAAI;IAAC,IAAI;AACvE;AAEA,6EAA6E,GAC7E,OAAO,SAASC,qCAAqCC,OAAe;IAClE,OACEC,OAAOD,kBAAAA,UAAW,IACfE,WAAW,GACXC,OAAO,CAAC,gBAAgB,KACxBA,OAAO,CAAC,YAAY,OAAO;AAElC"}