@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/host-tokens.js

@@ -0,0 +1,304 @@
+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 { hostPublicOrigin } from "./host-naming.js";
+const trimmed = (value)=>{
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text || undefined;
+};
+/**
+ * The site's public URL.
+ *
+ * A custom domain wins when connected, because that is the address the site is
+ * actually known by — a template linking to the aglyn.app subdomain of a site
+ * with its own domain is technically correct and reads as a mistake.
+ */ function siteUrl(host) {
+    const custom = trimmed(host.cname);
+    if (custom) return `https://${custom.replace(/^https?:\/\//, '')}`;
+    // `hostPublicOrigin`, not a fourth hand-rolled apex (AGL-2195). The cname
+    // branch stays here because this one strips a scheme the token source may
+    // carry; the subdomain branch has no such difference and had none — it was
+    // the same two lines with `aglyn.app` written in, so an operator's own apex
+    // was honoured everywhere except in the tokens a template renders.
+    return hostPublicOrigin({
+        subdomain: trimmed(host.subdomain)
+    });
+}
+function businessName(host) {
+    var _trimmed;
+    var _host_seo_entity, _host_seo;
+    return (_trimmed = trimmed((_host_seo = host.seo) == null ? void 0 : (_host_seo_entity = _host_seo.entity) == null ? void 0 : _host_seo_entity.name)) != null ? _trimmed : trimmed(host.displayName);
+}
+/**
+ * The closed registry.
+ *
+ * Ordered as an author would look for them. Every entry is reachable from a
+ * field a site can actually set — a token that can never resolve is worse than
+ * an absent one, because it teaches people the feature does not work.
+ */ export const HOST_TOKENS = {
+    businessName: {
+        key: 'businessName',
+        type: 'text',
+        label: 'Business name',
+        description: 'The site’s business or brand name.',
+        resolve: businessName,
+        whenEmpty: 'blank'
+    },
+    logo: {
+        key: 'logo',
+        type: 'image',
+        label: 'Logo',
+        description: 'The site’s logo image.',
+        resolve: (host)=>{
+            var _trimmed;
+            var _host_seo_entity, _host_seo;
+            return (_trimmed = trimmed(host.logoUrl)) != null ? _trimmed : trimmed((_host_seo = host.seo) == null ? void 0 : (_host_seo_entity = _host_seo.entity) == null ? void 0 : _host_seo_entity.logo);
+        },
+        // No image: the block is dropped and the business name carries the brand
+        // instead, which is what the block was for.
+        whenEmpty: 'omit-block'
+    },
+    url: {
+        key: 'url',
+        type: 'url',
+        label: 'Site address',
+        description: 'The site’s public URL — its custom domain when connected.',
+        resolve: siteUrl,
+        whenEmpty: 'blank'
+    },
+    supportEmail: {
+        key: 'supportEmail',
+        type: 'email',
+        label: 'Support email',
+        description: 'Where visitors should write for help.',
+        resolve: (host)=>{
+            var _host_business;
+            return trimmed((_host_business = host.business) == null ? void 0 : _host_business.supportEmail);
+        },
+        whenEmpty: 'omit-block'
+    },
+    address: {
+        key: 'address',
+        type: 'address',
+        label: 'Postal address',
+        description: 'The business’s postal address, as one block of text.',
+        resolve: (host)=>{
+            var _host_business;
+            return trimmed((_host_business = host.business) == null ? void 0 : _host_business.address);
+        },
+        whenEmpty: 'omit-block'
+    },
+    socialLinks: {
+        key: 'socialLinks',
+        type: 'text',
+        label: 'Social links',
+        description: 'The site’s social profiles, as a list of labeled links.',
+        // Rendered as text here so a token in copy degrades to something readable;
+        // a renderer wanting real links reads `host.business.socialLinks` itself.
+        resolve: (host)=>{
+            var _ref;
+            var _host_business;
+            const links = (_ref = (_host_business = host.business) == null ? void 0 : _host_business.socialLinks) != null ? _ref : [];
+            const labels = links.map((link)=>{
+                var _trimmed;
+                return (_trimmed = trimmed(link == null ? void 0 : link.label)) != null ? _trimmed : trimmed(link == null ? void 0 : link.url);
+            }).filter((label)=>Boolean(label));
+            return labels.length ? labels.join(' · ') : undefined;
+        },
+        whenEmpty: 'omit-block'
+    }
+};
+/**
+ * The registry's entry for `key`, or undefined when it declares none.
+ *
+ * An OWN entry only. `HOST_TOKENS` is an object literal, so a bare index also
+ * finds the `Object.prototype` members — `constructor`, `toString`, `valueOf` —
+ * and every one of those names matches {@link HOST_TOKEN_PATTERN}. Read that
+ * way, `{{host.constructor}}` answers the `Object` function where a definition
+ * belongs, and calling its `resolve` throws in the middle of a render. A name
+ * the registry does not declare resolves to nothing, whatever the name is.
+ */ export function hostTokenDefinition(key) {
+    return Object.prototype.hasOwnProperty.call(HOST_TOKENS, key) ? HOST_TOKENS[key] : undefined;
+}
+/**
+ * `{{host.key}}` — whitespace-tolerant, and deliberately NOT dotted beyond one
+ * segment. `host.a.b` does not match, so there is no path syntax to abuse.
+ */ export const HOST_TOKEN_PATTERN = /\{\{\s*host\.([a-zA-Z][a-zA-Z0-9_]*)\s*\}\}/g;
+/** Every `host.*` token in a string, in order, including unknown ones. */ export function hostTokensIn(text) {
+    if (typeof text !== 'string' || !text.includes('{{')) return [];
+    const keys = [];
+    for (const match of text.matchAll(HOST_TOKEN_PATTERN))keys.push(match[1]);
+    return keys;
+}
+/** The resolved value of one token, or undefined when the site has none. */ export function resolveHostToken(key, host) {
+    var _definition_resolve;
+    const definition = hostTokenDefinition(key);
+    if (!definition || !host) return undefined;
+    return (_definition_resolve = definition.resolve(host)) != null ? _definition_resolve : definition.fallback == null ? void 0 : definition.fallback.call(definition, host);
+}
+/**
+ * Replaces every `host.*` token with the installing site's value.
+ *
+ * An unresolved token — unknown key, or a site that has not set the field —
+ * renders EMPTY, never the literal. Leaking `{{host.logo}}` into a sent email
+ * is the failure this feature exists to prevent, so it cannot be the fallback
+ * for the feature's own gaps. The authoring-time check
+ * ({@link validateHostTokens}) is where a typo is meant to be caught, while the
+ * writer can still fix it.
+ */ export function resolveHostTokens(text, host) {
+    if (typeof text !== 'string' || !text.includes('{{')) return text;
+    return text.replace(HOST_TOKEN_PATTERN, (_token, key)=>{
+        var _resolveHostToken;
+        return (_resolveHostToken = resolveHostToken(String(key), host)) != null ? _resolveHostToken : '';
+    });
+}
+/**
+ * Authoring-time check: catch a token before it reaches a visitor.
+ *
+ * The two things worth failing on are a typo (which would silently render
+ * nothing) and a type mismatch (an image URL dropped into a sentence). Both are
+ * invisible at authoring time without this and obvious afterwards, which is the
+ * wrong way round for something that ends up in a sent email.
+ *
+ * `allow` names the types this slot can take. Omit it for free text, where only
+ * `text` and the string-ish types make sense.
+ */ export function validateHostTokens(text, options) {
+    var _ref;
+    const allow = (_ref = options == null ? void 0 : options.allow) != null ? _ref : [
+        'text',
+        'url',
+        'email',
+        'address'
+    ];
+    const issues = [];
+    const seen = new Set();
+    for (const key of hostTokensIn(text)){
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const definition = hostTokenDefinition(key);
+        if (!definition) {
+            issues.push({
+                key,
+                kind: 'unknown',
+                message: `There is no host variable called "${key}". It will render as ` + 'nothing. Available: ' + Object.keys(HOST_TOKENS).join(', ') + '.'
+            });
+            continue;
+        }
+        if (!allow.includes(definition.type)) {
+            issues.push({
+                key,
+                kind: 'wrong-slot',
+                message: `"${definition.label}" is ${definition.type === 'image' ? 'an image' : `a ${definition.type}`}, so it cannot go here. Put it in a slot that takes ` + `${definition.type === 'image' ? 'an image' : `a ${definition.type}`}.`
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Whether a block containing these tokens should be dropped for this site.
+ *
+ * The other half of "every token needs a defined empty behaviour": a logo block
+ * on a site with no logo should not render an empty image, and the renderer
+ * cannot know that from the resolved string alone — `''` is both "no value" and
+ * "a value that happens to be empty". Asking here keeps the rule with the
+ * token definition rather than spread across the surfaces that render it.
+ */ export function shouldOmitBlock(text, host) {
+    for (const key of hostTokensIn(text)){
+        const definition = hostTokenDefinition(key);
+        if (!definition || definition.whenEmpty !== 'omit-block') continue;
+        if (!resolveHostToken(key, host)) return true;
+    }
+    return false;
+}
+/**
+ * Every token with its resolved value for one site, for an authoring picker
+ * that shows what each will actually produce here.
+ *
+ * A picker listing token names alone makes the author guess; showing the value
+ * this site would render is what turns "is it businessName or business_name"
+ * into a question nobody has to ask.
+ */ export function describeHostTokens(host) {
+    return Object.values(HOST_TOKENS).map((definition)=>{
+        const value = resolveHostToken(definition.key, host);
+        return _extends({}, definition, {
+            token: `{{host.${definition.key}}}`,
+            value,
+            set: Boolean(value)
+        });
+    });
+}
+/**
+ * The `host.*` values as a merge-token map, for surfaces that already have a
+ * token substituter of their own.
+ *
+ * This is how EMAIL gets host variables without the email library depending on
+ * this one: `substituteMergeTokens` already matches `{{a.b}}`, so a caller
+ * spreads this into the merge map it was passing anyway. One registry, two
+ * surfaces, no second substitution engine to drift.
+ *
+ * Every registered token appears, INCLUDING the ones this site has not set —
+ * as `''`. Omitting them would leave `{{host.supportEmail}}` for the generic
+ * catch-all to blank, which works today and works by accident: the moment a
+ * surface without that catch-all uses this map, the literal token ships.
+ */ export function hostTokenMerge(host) {
+    const merge = {};
+    for (const key of Object.keys(HOST_TOKENS)){
+        var _resolveHostToken;
+        merge[`host.${key}`] = (_resolveHostToken = resolveHostToken(key, host)) != null ? _resolveHostToken : '';
+    }
+    return merge;
+}
+/**
+ * Resolves `host.*` tokens across every string prop of a normalized node map.
+ *
+ * Mirrors `resolveNodesBindings` deliberately — same shallow-copy discipline,
+ * same string-props-only rule — so a screen and an email resolve the same token
+ * to the same value. The issue's warning is the reason: two resolvers drift,
+ * and then the same token means different things depending on where an author
+ * typed it.
+ *
+ * Returns the input untouched when the site has nothing to substitute, so a
+ * binding-free tree costs one `Object.entries`.
+ */ export function resolveNodesHostTokens(nodes, host) {
+    if (!nodes) return nodes;
+    let changed = false;
+    const next = {};
+    for (const [id, node] of Object.entries(nodes)){
+        const props = node == null ? void 0 : node.props;
+        if (!props) {
+            next[id] = node;
+            continue;
+        }
+        let nodeChanged = false;
+        const nextProps = {};
+        for (const [key, value] of Object.entries(props)){
+            if (typeof value === 'string' && value.includes('{{')) {
+                const resolved = resolveHostTokens(value, host);
+                nextProps[key] = resolved;
+                if (resolved !== value) nodeChanged = true;
+            } else {
+                nextProps[key] = value;
+            }
+        }
+        next[id] = nodeChanged ? _extends({}, node, {
+            props: nextProps
+        }) : node;
+        changed = changed || nodeChanged;
+    }
+    return changed ? next : nodes;
+}
+
+//# sourceMappingURL=host-tokens.js.map

package/src/lib/app-utils/host-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/host-tokens.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 { hostPublicOrigin } from './host-naming'\n\n/**\n * Host variables — publisher templates that fill themselves in (AGL-1022).\n *\n * A publisher writing an email template cannot reference the installing site,\n * so every install begins with the same chore: swap the placeholder logo, fix\n * the business name, correct the links. Miss one and the site sends an email\n * carrying someone else's branding.\n *\n * `host.*` gives artifacts a way to NAME the host instead of hard-coding it.\n * The author writes `{{host.businessName}}`; the installing site fills it in,\n * and it stays filled in when that site rebrands.\n *\n * ## The namespace IS the security boundary\n *\n * This is publisher-authored content resolving against tenant data, so the\n * registry is CLOSED and each token reads through a hand-written function\n * rather than a path into the document. That is the whole design: a token\n * cannot address `stripeAccountId`, or `memberRoles`, or anything else, because\n * there is no path syntax to express it — `host.` is followed by a key that\n * either appears in {@link HOST_TOKENS} or resolves to nothing at all. Adding a\n * token is a deliberate edit here, reviewable as a diff.\n *\n * A path-based registry (\"allow `host.seo.title`\") would have been shorter and\n * is the version to refuse: allowlisting prefixes is how a namespace grows a\n * hole, and the first `host.orgId` would be a data leak with a plausible commit\n * message.\n *\n * ## Resolve LATE\n *\n * At render and at send, never at install. Freezing values into the artifact\n * would make a rebrand stop propagating silently — the site would keep sending\n * last year's business name from a template nobody remembers is a template.\n *\n * ## Every token defines what \"empty\" does\n *\n * A site with no logo must produce something deliberate. Never an empty image,\n * and never the literal `{{host.logo}}` reaching a visitor — a leaked token is\n * the most embarrassing possible failure for a feature whose entire purpose is\n * to stop templates looking unfinished.\n */\n\n/**\n * What a token yields, so a renderer knows how to place it and the authoring\n * surface can refuse it in the wrong slot.\n *\n * `text` is the only type safe to drop into arbitrary copy. The others carry a\n * shape a slot has to understand — an `image` in a paragraph is a URL sitting\n * in the middle of a sentence, which is exactly the \"fails in a sent email\"\n * outcome this typing exists to move to authoring time.\n */\nexport type HostTokenType = 'text' | 'url' | 'email' | 'image' | 'address'\n\n/** What a renderer should do when a token resolves to nothing. */\nexport type HostTokenEmptyBehaviour =\n  /** Render nothing in its place; the surrounding copy still makes sense. */\n  | 'blank'\n  /**\n   * The block holding it should be dropped entirely. An `<img src=\"\">` is a\n   * broken-image icon in every mail client, which is worse than no logo.\n   */\n  | 'omit-block'\n\n/** The site fields a token may read. A closed, explicit surface. */\nexport interface HostTokenSource {\n  displayName?: string\n  logoUrl?: string\n  subdomain?: string\n  cname?: string\n  /** Contact details a publisher template can reference (AGL-1022). */\n  business?: {\n    supportEmail?: string\n    address?: string\n    socialLinks?: Array<{ label?: string; url?: string }>\n  }\n  seo?: { entity?: { name?: string; logo?: string } }\n}\n\nexport interface HostTokenDefinition {\n  /** The key after `host.` */\n  key: string\n  type: HostTokenType\n  label: string\n  description: string\n  /** Reads the value. Hand-written per token — never a path into the document. */\n  resolve: (host: HostTokenSource) => string | undefined\n  /**\n   * A deliberate second choice when `resolve` finds nothing.\n   *\n   * Not a nicety: \"fall back to the business name\" is what turns a missing logo\n   * from a hole in the page into a wordmark, which is what a careful designer\n   * would have done by hand.\n   */\n  fallback?: (host: HostTokenSource) => string | undefined\n  whenEmpty: HostTokenEmptyBehaviour\n}\n\nconst trimmed = (value: unknown): string | undefined => {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return text || undefined\n}\n\n/**\n * The site's public URL.\n *\n * A custom domain wins when connected, because that is the address the site is\n * actually known by — a template linking to the aglyn.app subdomain of a site\n * with its own domain is technically correct and reads as a mistake.\n */\nfunction siteUrl(host: HostTokenSource): string | undefined {\n  const custom = trimmed(host.cname)\n  if (custom) return `https://${custom.replace(/^https?:\\/\\//, '')}`\n  // `hostPublicOrigin`, not a fourth hand-rolled apex (AGL-2195). The cname\n  // branch stays here because this one strips a scheme the token source may\n  // carry; the subdomain branch has no such difference and had none — it was\n  // the same two lines with `aglyn.app` written in, so an operator's own apex\n  // was honoured everywhere except in the tokens a template renders.\n  return hostPublicOrigin({ subdomain: trimmed(host.subdomain) })\n}\n\nfunction businessName(host: HostTokenSource): string | undefined {\n  return trimmed(host.seo?.entity?.name) ?? trimmed(host.displayName)\n}\n\n/**\n * The closed registry.\n *\n * Ordered as an author would look for them. Every entry is reachable from a\n * field a site can actually set — a token that can never resolve is worse than\n * an absent one, because it teaches people the feature does not work.\n */\nexport const HOST_TOKENS: Record<string, HostTokenDefinition> = {\n  businessName: {\n    key: 'businessName',\n    type: 'text',\n    label: 'Business name',\n    description: 'The site’s business or brand name.',\n    resolve: businessName,\n    whenEmpty: 'blank',\n  },\n  logo: {\n    key: 'logo',\n    type: 'image',\n    label: 'Logo',\n    description: 'The site’s logo image.',\n    resolve: (host) =>\n      trimmed(host.logoUrl) ?? trimmed(host.seo?.entity?.logo),\n    // No image: the block is dropped and the business name carries the brand\n    // instead, which is what the block was for.\n    whenEmpty: 'omit-block',\n  },\n  url: {\n    key: 'url',\n    type: 'url',\n    label: 'Site address',\n    description: 'The site’s public URL — its custom domain when connected.',\n    resolve: siteUrl,\n    whenEmpty: 'blank',\n  },\n  supportEmail: {\n    key: 'supportEmail',\n    type: 'email',\n    label: 'Support email',\n    description: 'Where visitors should write for help.',\n    resolve: (host) => trimmed(host.business?.supportEmail),\n    whenEmpty: 'omit-block',\n  },\n  address: {\n    key: 'address',\n    type: 'address',\n    label: 'Postal address',\n    description: 'The business’s postal address, as one block of text.',\n    resolve: (host) => trimmed(host.business?.address),\n    whenEmpty: 'omit-block',\n  },\n  socialLinks: {\n    key: 'socialLinks',\n    type: 'text',\n    label: 'Social links',\n    description: 'The site’s social profiles, as a list of labeled links.',\n    // Rendered as text here so a token in copy degrades to something readable;\n    // a renderer wanting real links reads `host.business.socialLinks` itself.\n    resolve: (host) => {\n      const links = host.business?.socialLinks ?? []\n      const labels = links\n        .map((link) => trimmed(link?.label) ?? trimmed(link?.url))\n        .filter((label): label is string => Boolean(label))\n      return labels.length ? labels.join(' · ') : undefined\n    },\n    whenEmpty: 'omit-block',\n  },\n}\n\n/**\n * The registry's entry for `key`, or undefined when it declares none.\n *\n * An OWN entry only. `HOST_TOKENS` is an object literal, so a bare index also\n * finds the `Object.prototype` members — `constructor`, `toString`, `valueOf` —\n * and every one of those names matches {@link HOST_TOKEN_PATTERN}. Read that\n * way, `{{host.constructor}}` answers the `Object` function where a definition\n * belongs, and calling its `resolve` throws in the middle of a render. A name\n * the registry does not declare resolves to nothing, whatever the name is.\n */\nexport function hostTokenDefinition(\n  key: string,\n): HostTokenDefinition | undefined {\n  return Object.prototype.hasOwnProperty.call(HOST_TOKENS, key)\n    ? HOST_TOKENS[key]\n    : undefined\n}\n\n/**\n * `{{host.key}}` — whitespace-tolerant, and deliberately NOT dotted beyond one\n * segment. `host.a.b` does not match, so there is no path syntax to abuse.\n */\nexport const HOST_TOKEN_PATTERN = /\\{\\{\\s*host\\.([a-zA-Z][a-zA-Z0-9_]*)\\s*\\}\\}/g\n\n/** Every `host.*` token in a string, in order, including unknown ones. */\nexport function hostTokensIn(text: string): string[] {\n  if (typeof text !== 'string' || !text.includes('{{')) return []\n  const keys: string[] = []\n  for (const match of text.matchAll(HOST_TOKEN_PATTERN)) keys.push(match[1])\n  return keys\n}\n\n/** The resolved value of one token, or undefined when the site has none. */\nexport function resolveHostToken(\n  key: string,\n  host: HostTokenSource | null | undefined,\n): string | undefined {\n  const definition = hostTokenDefinition(key)\n  if (!definition || !host) return undefined\n  return definition.resolve(host) ?? definition.fallback?.(host)\n}\n\n/**\n * Replaces every `host.*` token with the installing site's value.\n *\n * An unresolved token — unknown key, or a site that has not set the field —\n * renders EMPTY, never the literal. Leaking `{{host.logo}}` into a sent email\n * is the failure this feature exists to prevent, so it cannot be the fallback\n * for the feature's own gaps. The authoring-time check\n * ({@link validateHostTokens}) is where a typo is meant to be caught, while the\n * writer can still fix it.\n */\nexport function resolveHostTokens(\n  text: string,\n  host: HostTokenSource | null | undefined,\n): string {\n  if (typeof text !== 'string' || !text.includes('{{')) return text\n  return text.replace(HOST_TOKEN_PATTERN, (_token, key) =>\n    resolveHostToken(String(key), host) ?? '',\n  )\n}\n\nexport interface HostTokenIssue {\n  key: string\n  /**\n   * `unknown` — no such token; it will render empty.\n   * `wrong-slot` — the token's type cannot be placed here.\n   */\n  kind: 'unknown' | 'wrong-slot'\n  message: string\n}\n\n/**\n * Authoring-time check: catch a token before it reaches a visitor.\n *\n * The two things worth failing on are a typo (which would silently render\n * nothing) and a type mismatch (an image URL dropped into a sentence). Both are\n * invisible at authoring time without this and obvious afterwards, which is the\n * wrong way round for something that ends up in a sent email.\n *\n * `allow` names the types this slot can take. Omit it for free text, where only\n * `text` and the string-ish types make sense.\n */\nexport function validateHostTokens(\n  text: string,\n  options?: { allow?: readonly HostTokenType[] },\n): HostTokenIssue[] {\n  const allow = options?.allow ?? ['text', 'url', 'email', 'address']\n  const issues: HostTokenIssue[] = []\n  const seen = new Set<string>()\n  for (const key of hostTokensIn(text)) {\n    if (seen.has(key)) continue\n    seen.add(key)\n    const definition = hostTokenDefinition(key)\n    if (!definition) {\n      issues.push({\n        key,\n        kind: 'unknown',\n        message:\n          `There is no host variable called \"${key}\". It will render as ` +\n          'nothing. Available: ' +\n          Object.keys(HOST_TOKENS).join(', ') +\n          '.',\n      })\n      continue\n    }\n    if (!allow.includes(definition.type)) {\n      issues.push({\n        key,\n        kind: 'wrong-slot',\n        message:\n          `\"${definition.label}\" is ${\n            definition.type === 'image' ? 'an image' : `a ${definition.type}`\n          }, so it cannot go here. Put it in a slot that takes ` +\n          `${definition.type === 'image' ? 'an image' : `a ${definition.type}`}.`,\n      })\n    }\n  }\n  return issues\n}\n\n/**\n * Whether a block containing these tokens should be dropped for this site.\n *\n * The other half of \"every token needs a defined empty behaviour\": a logo block\n * on a site with no logo should not render an empty image, and the renderer\n * cannot know that from the resolved string alone — `''` is both \"no value\" and\n * \"a value that happens to be empty\". Asking here keeps the rule with the\n * token definition rather than spread across the surfaces that render it.\n */\nexport function shouldOmitBlock(\n  text: string,\n  host: HostTokenSource | null | undefined,\n): boolean {\n  for (const key of hostTokensIn(text)) {\n    const definition = hostTokenDefinition(key)\n    if (!definition || definition.whenEmpty !== 'omit-block') continue\n    if (!resolveHostToken(key, host)) return true\n  }\n  return false\n}\n\n/**\n * Every token with its resolved value for one site, for an authoring picker\n * that shows what each will actually produce here.\n *\n * A picker listing token names alone makes the author guess; showing the value\n * this site would render is what turns \"is it businessName or business_name\"\n * into a question nobody has to ask.\n */\nexport function describeHostTokens(\n  host: HostTokenSource | null | undefined,\n): Array<HostTokenDefinition & { token: string; value?: string; set: boolean }> {\n  return Object.values(HOST_TOKENS).map((definition) => {\n    const value = resolveHostToken(definition.key, host)\n    return {\n      ...definition,\n      token: `{{host.${definition.key}}}`,\n      value,\n      set: Boolean(value),\n    }\n  })\n}\n\n/**\n * The `host.*` values as a merge-token map, for surfaces that already have a\n * token substituter of their own.\n *\n * This is how EMAIL gets host variables without the email library depending on\n * this one: `substituteMergeTokens` already matches `{{a.b}}`, so a caller\n * spreads this into the merge map it was passing anyway. One registry, two\n * surfaces, no second substitution engine to drift.\n *\n * Every registered token appears, INCLUDING the ones this site has not set —\n * as `''`. Omitting them would leave `{{host.supportEmail}}` for the generic\n * catch-all to blank, which works today and works by accident: the moment a\n * surface without that catch-all uses this map, the literal token ships.\n */\nexport function hostTokenMerge(\n  host: HostTokenSource | null | undefined,\n): Record<string, string> {\n  const merge: Record<string, string> = {}\n  for (const key of Object.keys(HOST_TOKENS)) {\n    merge[`host.${key}`] = resolveHostToken(key, host) ?? ''\n  }\n  return merge\n}\n\n/**\n * Resolves `host.*` tokens across every string prop of a normalized node map.\n *\n * Mirrors `resolveNodesBindings` deliberately — same shallow-copy discipline,\n * same string-props-only rule — so a screen and an email resolve the same token\n * to the same value. The issue's warning is the reason: two resolvers drift,\n * and then the same token means different things depending on where an author\n * typed it.\n *\n * Returns the input untouched when the site has nothing to substitute, so a\n * binding-free tree costs one `Object.entries`.\n */\nexport function resolveNodesHostTokens<T extends Record<string, any>>(\n  nodes: T,\n  host: HostTokenSource | null | undefined,\n): T {\n  if (!nodes) return nodes\n  let changed = false\n  const next: Record<string, any> = {}\n  for (const [id, node] of Object.entries(nodes)) {\n    const props = node?.props\n    if (!props) {\n      next[id] = node\n      continue\n    }\n    let nodeChanged = false\n    const nextProps: Record<string, unknown> = {}\n    for (const [key, value] of Object.entries(props)) {\n      if (typeof value === 'string' && value.includes('{{')) {\n        const resolved = resolveHostTokens(value, host)\n        nextProps[key] = resolved\n        if (resolved !== value) nodeChanged = true\n      } else {\n        nextProps[key] = value\n      }\n    }\n    next[id] = nodeChanged ? { ...node, props: nextProps } : node\n    changed = changed || nodeChanged\n  }\n  return (changed ? next : nodes) as T\n}\n"],"names":["hostPublicOrigin","trimmed","value","text","trim","undefined","siteUrl","host","custom","cname","replace","subdomain","businessName","seo","entity","name","displayName","HOST_TOKENS","key","type","label","description","resolve","whenEmpty","logo","logoUrl","url","supportEmail","business","address","socialLinks","links","labels","map","link","filter","Boolean","length","join","hostTokenDefinition","Object","prototype","hasOwnProperty","call","HOST_TOKEN_PATTERN","hostTokensIn","includes","keys","match","matchAll","push","resolveHostToken","definition","fallback","resolveHostTokens","_token","String","validateHostTokens","options","allow","issues","seen","Set","has","add","kind","message","shouldOmitBlock","describeHostTokens","values","token","set","hostTokenMerge","merge","resolveNodesHostTokens","nodes","changed","next","id","node","entries","props","nodeChanged","nextProps","resolved"],"mappings":"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"}

package/src/lib/app-utils/idp-profile.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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.
+ */
+export interface IdpNameClaims {
+    name?: unknown;
+    firebase?: {
+        sign_in_attributes?: Record<string, unknown>;
+    } | unknown;
+    [claim: string]: unknown;
+}
+/**
+ * Resolve a display name from a decoded ID token, or `''` when the provider
+ * genuinely sent nothing.
+ *
+ * Empty rather than a placeholder: callers seed only ABSENT fields, and a
+ * fabricated name would be indistinguishable from one the user chose and
+ * would never be corrected.
+ */
+export declare function resolveIdpDisplayName(decoded: IdpNameClaims | null | undefined): string;
+/**
+ * Resolve an avatar URL from a decoded ID token, or `''`.
+ *
+ * Only `https:` survives. The value is written to the roster and rendered as
+ * an `<img src>` for every member of the org, so an assertion carrying a
+ * `javascript:` or `data:` URL would turn a mapped IdP attribute into stored
+ * script that we hand to teammates. The IdP is trusted to say who someone is,
+ * which is not the same as being trusted to supply markup.
+ */
+export declare function resolveIdpPhotoUrl(decoded: IdpNameClaims | null | undefined): string;
+/**
+ * Resolve a phone number from a decoded ID token, or `''`.
+ *
+ * Returned verbatim rather than normalised to E.164: this is the number the
+ * directory holds, and guessing a country code for a national-format string
+ * invents digits. `normalizePhone` is applied where a user confirms it, not
+ * here.
+ */
+export declare function resolveIdpPhone(decoded: IdpNameClaims | null | undefined): string;
+/**
+ * The postal address an identity provider sent, as loose parts (AGL-1963).
+ *
+ * Deliberately NOT an `AglynPostalAddress`, and this module deliberately does
+ * not import one. `normalizeAddress` is what decides whether these parts add
+ * up to an address at all — it drops blanks, rejects a country that is not
+ * ISO-3166 alpha-2, and returns `null` when nothing survives. Returning a
+ * half-populated object from here would hand the caller something that reads
+ * as truthy to every `if (address)` while holding a city and no street, which
+ * is exactly the shape AGL-1963 says must not exist.
+ */
+export interface IdpAddressParts {
+    line1: string;
+    line2: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+}
+/**
+ * Resolve a postal address from a decoded ID token.
+ *
+ * Every field independently optional: a directory that holds a city and no
+ * street is a normal directory, and demanding a complete address would
+ * discard the parts it does have. `normalizeAddress` downstream is what turns
+ * "some parts" into either a stored address or `null`.
+ *
+ * `state`, never `region`, in the RESULT — that is the canonical spelling in
+ * `AglynPostalAddress`, matching Stripe's customer address. `region` appears
+ * only as an INPUT key, because that is what Google Workspace calls it.
+ */
+export declare function resolveIdpAddress(decoded: IdpNameClaims | null | undefined): IdpAddressParts;