@aglyn/aglyn 1.0.0-beta.263 → 1.0.0-beta.266

package/src/lib/app-utils/live-document-count.client.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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 Query } from 'firebase/firestore';
+/**
+ * The web SDK's half of the live-count rule (AGL-3918): how many of
+ * [documents] are not deleted, as `/api/hosts/resources` counts them for a
+ * plan allowance. Every document less the tombstones (`deletedAt != null`);
+ * an archived document is live and counted. See `live-document-count.ts` for
+ * why it is two aggregates.
+ *
+ * Rejects when either aggregate is refused, so a caller keeps whatever
+ * fallback it already has rather than reading a confident 0.
+ */
+export declare function getLiveCountFromServer(documents: Query): Promise<number>;

package/src/lib/app-utils/live-document-count.client.js

@@ -0,0 +1,35 @@
+/**
+ * @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 { getCountFromServer, query, where } from "firebase/firestore";
+import { liveDocumentCount, TOMBSTONE_FIELD } from "./live-document-count.js";
+/**
+ * The web SDK's half of the live-count rule (AGL-3918): how many of
+ * [documents] are not deleted, as `/api/hosts/resources` counts them for a
+ * plan allowance. Every document less the tombstones (`deletedAt != null`);
+ * an archived document is live and counted. See `live-document-count.ts` for
+ * why it is two aggregates.
+ *
+ * Rejects when either aggregate is refused, so a caller keeps whatever
+ * fallback it already has rather than reading a confident 0.
+ */ export async function getLiveCountFromServer(documents) {
+    const [total, tombstones] = await Promise.all([
+        getCountFromServer(documents),
+        getCountFromServer(query(documents, where(TOMBSTONE_FIELD, '!=', null)))
+    ]);
+    return liveDocumentCount(total.data().count, tombstones.data().count);
+}
+
+//# sourceMappingURL=live-document-count.client.js.map

package/src/lib/app-utils/live-document-count.client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/live-document-count.client.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 { getCountFromServer, query, where, type Query } from 'firebase/firestore'\nimport { liveDocumentCount, TOMBSTONE_FIELD } from './live-document-count'\n\n/**\n * The web SDK's half of the live-count rule (AGL-3918): how many of\n * [documents] are not deleted, as `/api/hosts/resources` counts them for a\n * plan allowance. Every document less the tombstones (`deletedAt != null`);\n * an archived document is live and counted. See `live-document-count.ts` for\n * why it is two aggregates.\n *\n * Rejects when either aggregate is refused, so a caller keeps whatever\n * fallback it already has rather than reading a confident 0.\n */\nexport async function getLiveCountFromServer(documents: Query): Promise<number> {\n  const [total, tombstones] = await Promise.all([\n    getCountFromServer(documents),\n    getCountFromServer(query(documents, where(TOMBSTONE_FIELD, '!=', null))),\n  ])\n  return liveDocumentCount(total.data().count, tombstones.data().count)\n}\n"],"names":["getCountFromServer","query","where","liveDocumentCount","TOMBSTONE_FIELD","getLiveCountFromServer","documents","total","tombstones","Promise","all","data","count"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,kBAAkB,EAAEC,KAAK,EAAEC,KAAK,QAAoB,qBAAoB;AACjF,SAASC,iBAAiB,EAAEC,eAAe,QAAQ,2BAAuB;AAE1E;;;;;;;;;CASC,GACD,OAAO,eAAeC,uBAAuBC,SAAgB;IAC3D,MAAM,CAACC,OAAOC,WAAW,GAAG,MAAMC,QAAQC,GAAG,CAAC;QAC5CV,mBAAmBM;QACnBN,mBAAmBC,MAAMK,WAAWJ,MAAME,iBAAiB,MAAM;KAClE;IACD,OAAOD,kBAAkBI,MAAMI,IAAI,GAAGC,KAAK,EAAEJ,WAAWG,IAAI,GAAGC,KAAK;AACtE"}

package/src/lib/app-utils/live-document-count.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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.
+ */
+/**
+ * How a plan allowance counts a collection whose delete is a SOFT delete
+ * (AGL-3918).
+ *
+ * The rule: a deleted document frees its slot, an archived one keeps it.
+ * Deleting stamps `deletedAt` and leaves the document in place (a tenant page
+ * keeps grafting until its next revalidate, a past order still names the
+ * product), so a plain `count()` charged a site for everything it had ever
+ * deleted: a product deleted on Starter never gave its slot back, and the
+ * Automation card read "4/25 workflows" beside a list of three. Archiving is a
+ * status the owner can reverse in place, so an archived product or a disabled
+ * workflow is still counted.
+ *
+ * ## Why total minus tombstones
+ *
+ * A live document has no `deletedAt` at all (created through
+ * `/api/hosts/resources`) or an explicit `deletedAt: null` (every product
+ * writer, a marketplace install). Firestore cannot match an absent field, so
+ * `where('deletedAt', '==', null)` counts the second shape alone. The
+ * TOMBSTONES are one shape — a value that is not `null` — and
+ * `where('deletedAt', '!=', null)` matches exactly them, so the total less
+ * that count is exactly the documents the server calls live. Two aggregates,
+ * one billed read each at these sizes, on the automatic single-field index
+ * `deletedAt` already has; no composite index.
+ *
+ * This module is SDK-agnostic: it names the Admin SDK's query shape
+ * structurally so a plugin, core and the console reach it without a second
+ * copy of the rule. The web SDK's counterpart is
+ * `live-document-count.client.ts`.
+ */
+/** The field every soft-deleting collection stamps on delete. */
+export declare const TOMBSTONE_FIELD = "deletedAt";
+/** The live count from the two aggregates, never below zero: they are separate reads, and a delete landing between them can make the second the larger. */
+export declare function liveDocumentCount(total: number, tombstones: number): number;
+/** Whether a stored document is live: no `deletedAt`, or `deletedAt: null`. */
+export declare function isLiveDocument(deletedAt: unknown): boolean;
+/** An aggregate query's snapshot, as the Admin SDK's `AggregateQuerySnapshot` answers it. */
+export interface LiveCountSnapshot {
+    data(): {
+        count: number;
+    };
+}
+/** An aggregate query the Admin SDK can execute directly. */
+export interface LiveCountAggregate {
+    get(): Promise<LiveCountSnapshot>;
+}
+/** A collection or query the Admin SDK can count and filter. */
+export interface LiveCountQuery<A extends LiveCountAggregate> {
+    count(): A;
+    where(field: string, op: '!=', value: null): {
+        count(): A;
+    };
+}
+/**
+ * The live documents [documents] matches: every one less the tombstones.
+ *
+ * `read` executes each aggregate, and defaults to executing it directly. A
+ * create that counts and writes in one transaction passes
+ * `(aggregate) => tx.get(aggregate)`, so both counts are the TRANSACTION's
+ * reads and the lock they take serializes a concurrent create (AGL-2231).
+ */
+export declare function countLiveDocuments<A extends LiveCountAggregate>(documents: LiveCountQuery<A>, read?: (aggregate: A) => Promise<LiveCountSnapshot>): Promise<number>;
+/** The `source.type` a platform-seeded starter template carries (AGL-687). */
+export declare const STARTER_TEMPLATE_SOURCE = "starter";
+/**
+ * Of a site's deleted templates, how many `templatesPerHost`'s first count
+ * included: `where('source.type', '!=', 'starter')` matches a template that
+ * carries a `source.type` other than a starter's, and skips one without the
+ * field. Subtracting these from that count leaves the live templates the
+ * allowance counts, without the composite index a second inequality on
+ * `deletedAt` beside it would need.
+ */
+export declare function deletedTemplatesCounted(tombstones: ReadonlyArray<{
+    get(field: string): unknown;
+}>): number;

package/src/lib/app-utils/live-document-count.js

@@ -0,0 +1,81 @@
+/**
+ * @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.
+ */ /**
+ * How a plan allowance counts a collection whose delete is a SOFT delete
+ * (AGL-3918).
+ *
+ * The rule: a deleted document frees its slot, an archived one keeps it.
+ * Deleting stamps `deletedAt` and leaves the document in place (a tenant page
+ * keeps grafting until its next revalidate, a past order still names the
+ * product), so a plain `count()` charged a site for everything it had ever
+ * deleted: a product deleted on Starter never gave its slot back, and the
+ * Automation card read "4/25 workflows" beside a list of three. Archiving is a
+ * status the owner can reverse in place, so an archived product or a disabled
+ * workflow is still counted.
+ *
+ * ## Why total minus tombstones
+ *
+ * A live document has no `deletedAt` at all (created through
+ * `/api/hosts/resources`) or an explicit `deletedAt: null` (every product
+ * writer, a marketplace install). Firestore cannot match an absent field, so
+ * `where('deletedAt', '==', null)` counts the second shape alone. The
+ * TOMBSTONES are one shape — a value that is not `null` — and
+ * `where('deletedAt', '!=', null)` matches exactly them, so the total less
+ * that count is exactly the documents the server calls live. Two aggregates,
+ * one billed read each at these sizes, on the automatic single-field index
+ * `deletedAt` already has; no composite index.
+ *
+ * This module is SDK-agnostic: it names the Admin SDK's query shape
+ * structurally so a plugin, core and the console reach it without a second
+ * copy of the rule. The web SDK's counterpart is
+ * `live-document-count.client.ts`.
+ */ /** The field every soft-deleting collection stamps on delete. */ export const TOMBSTONE_FIELD = 'deletedAt';
+/** The live count from the two aggregates, never below zero: they are separate reads, and a delete landing between them can make the second the larger. */ export function liveDocumentCount(total, tombstones) {
+    return Math.max(0, (Number(total) || 0) - (Number(tombstones) || 0));
+}
+/** Whether a stored document is live: no `deletedAt`, or `deletedAt: null`. */ export function isLiveDocument(deletedAt) {
+    return deletedAt == null;
+}
+/**
+ * The live documents [documents] matches: every one less the tombstones.
+ *
+ * `read` executes each aggregate, and defaults to executing it directly. A
+ * create that counts and writes in one transaction passes
+ * `(aggregate) => tx.get(aggregate)`, so both counts are the TRANSACTION's
+ * reads and the lock they take serializes a concurrent create (AGL-2231).
+ */ export async function countLiveDocuments(documents, read = (aggregate)=>aggregate.get()) {
+    const [total, tombstones] = await Promise.all([
+        read(documents.count()),
+        read(documents.where(TOMBSTONE_FIELD, '!=', null).count())
+    ]);
+    return liveDocumentCount(total.data().count, tombstones.data().count);
+}
+/** The `source.type` a platform-seeded starter template carries (AGL-687). */ export const STARTER_TEMPLATE_SOURCE = 'starter';
+/**
+ * Of a site's deleted templates, how many `templatesPerHost`'s first count
+ * included: `where('source.type', '!=', 'starter')` matches a template that
+ * carries a `source.type` other than a starter's, and skips one without the
+ * field. Subtracting these from that count leaves the live templates the
+ * allowance counts, without the composite index a second inequality on
+ * `deletedAt` beside it would need.
+ */ export function deletedTemplatesCounted(tombstones) {
+    return tombstones.filter((entry)=>{
+        const type = entry.get('source.type');
+        return type != null && type !== STARTER_TEMPLATE_SOURCE;
+    }).length;
+}
+
+//# sourceMappingURL=live-document-count.js.map

package/src/lib/app-utils/live-document-count.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/live-document-count.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 * How a plan allowance counts a collection whose delete is a SOFT delete\n * (AGL-3918).\n *\n * The rule: a deleted document frees its slot, an archived one keeps it.\n * Deleting stamps `deletedAt` and leaves the document in place (a tenant page\n * keeps grafting until its next revalidate, a past order still names the\n * product), so a plain `count()` charged a site for everything it had ever\n * deleted: a product deleted on Starter never gave its slot back, and the\n * Automation card read \"4/25 workflows\" beside a list of three. Archiving is a\n * status the owner can reverse in place, so an archived product or a disabled\n * workflow is still counted.\n *\n * ## Why total minus tombstones\n *\n * A live document has no `deletedAt` at all (created through\n * `/api/hosts/resources`) or an explicit `deletedAt: null` (every product\n * writer, a marketplace install). Firestore cannot match an absent field, so\n * `where('deletedAt', '==', null)` counts the second shape alone. The\n * TOMBSTONES are one shape — a value that is not `null` — and\n * `where('deletedAt', '!=', null)` matches exactly them, so the total less\n * that count is exactly the documents the server calls live. Two aggregates,\n * one billed read each at these sizes, on the automatic single-field index\n * `deletedAt` already has; no composite index.\n *\n * This module is SDK-agnostic: it names the Admin SDK's query shape\n * structurally so a plugin, core and the console reach it without a second\n * copy of the rule. The web SDK's counterpart is\n * `live-document-count.client.ts`.\n */\n\n/** The field every soft-deleting collection stamps on delete. */\nexport const TOMBSTONE_FIELD = 'deletedAt'\n\n/** The live count from the two aggregates, never below zero: they are separate reads, and a delete landing between them can make the second the larger. */\nexport function liveDocumentCount(total: number, tombstones: number): number {\n  return Math.max(0, (Number(total) || 0) - (Number(tombstones) || 0))\n}\n\n/** Whether a stored document is live: no `deletedAt`, or `deletedAt: null`. */\nexport function isLiveDocument(deletedAt: unknown): boolean {\n  return deletedAt == null\n}\n\n/** An aggregate query's snapshot, as the Admin SDK's `AggregateQuerySnapshot` answers it. */\nexport interface LiveCountSnapshot {\n  data(): { count: number }\n}\n\n/** An aggregate query the Admin SDK can execute directly. */\nexport interface LiveCountAggregate {\n  get(): Promise<LiveCountSnapshot>\n}\n\n/** A collection or query the Admin SDK can count and filter. */\nexport interface LiveCountQuery<A extends LiveCountAggregate> {\n  count(): A\n  where(field: string, op: '!=', value: null): { count(): A }\n}\n\n/**\n * The live documents [documents] matches: every one less the tombstones.\n *\n * `read` executes each aggregate, and defaults to executing it directly. A\n * create that counts and writes in one transaction passes\n * `(aggregate) => tx.get(aggregate)`, so both counts are the TRANSACTION's\n * reads and the lock they take serializes a concurrent create (AGL-2231).\n */\nexport async function countLiveDocuments<A extends LiveCountAggregate>(\n  documents: LiveCountQuery<A>,\n  read: (aggregate: A) => Promise<LiveCountSnapshot> = (aggregate) => aggregate.get(),\n): Promise<number> {\n  const [total, tombstones] = await Promise.all([\n    read(documents.count()),\n    read(documents.where(TOMBSTONE_FIELD, '!=', null).count()),\n  ])\n  return liveDocumentCount(total.data().count, tombstones.data().count)\n}\n\n/** The `source.type` a platform-seeded starter template carries (AGL-687). */\nexport const STARTER_TEMPLATE_SOURCE = 'starter'\n\n/**\n * Of a site's deleted templates, how many `templatesPerHost`'s first count\n * included: `where('source.type', '!=', 'starter')` matches a template that\n * carries a `source.type` other than a starter's, and skips one without the\n * field. Subtracting these from that count leaves the live templates the\n * allowance counts, without the composite index a second inequality on\n * `deletedAt` beside it would need.\n */\nexport function deletedTemplatesCounted(\n  tombstones: ReadonlyArray<{ get(field: string): unknown }>,\n): number {\n  return tombstones.filter((entry) => {\n    const type = entry.get('source.type')\n    return type != null && type !== STARTER_TEMPLATE_SOURCE\n  }).length\n}\n"],"names":["TOMBSTONE_FIELD","liveDocumentCount","total","tombstones","Math","max","Number","isLiveDocument","deletedAt","countLiveDocuments","documents","read","aggregate","get","Promise","all","count","where","data","STARTER_TEMPLATE_SOURCE","deletedTemplatesCounted","filter","entry","type","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GAED,+DAA+D,GAC/D,OAAO,MAAMA,kBAAkB,YAAW;AAE1C,yJAAyJ,GACzJ,OAAO,SAASC,kBAAkBC,KAAa,EAAEC,UAAkB;IACjE,OAAOC,KAAKC,GAAG,CAAC,GAAG,AAACC,CAAAA,OAAOJ,UAAU,CAAA,IAAMI,CAAAA,OAAOH,eAAe,CAAA;AACnE;AAEA,6EAA6E,GAC7E,OAAO,SAASI,eAAeC,SAAkB;IAC/C,OAAOA,aAAa;AACtB;AAkBA;;;;;;;CAOC,GACD,OAAO,eAAeC,mBACpBC,SAA4B,EAC5BC,OAAqD,CAACC,YAAcA,UAAUC,GAAG,EAAE;IAEnF,MAAM,CAACX,OAAOC,WAAW,GAAG,MAAMW,QAAQC,GAAG,CAAC;QAC5CJ,KAAKD,UAAUM,KAAK;QACpBL,KAAKD,UAAUO,KAAK,CAACjB,iBAAiB,MAAM,MAAMgB,KAAK;KACxD;IACD,OAAOf,kBAAkBC,MAAMgB,IAAI,GAAGF,KAAK,EAAEb,WAAWe,IAAI,GAAGF,KAAK;AACtE;AAEA,4EAA4E,GAC5E,OAAO,MAAMG,0BAA0B,UAAS;AAEhD;;;;;;;CAOC,GACD,OAAO,SAASC,wBACdjB,UAA0D;IAE1D,OAAOA,WAAWkB,MAAM,CAAC,CAACC;QACxB,MAAMC,OAAOD,MAAMT,GAAG,CAAC;QACvB,OAAOU,QAAQ,QAAQA,SAASJ;IAClC,GAAGK,MAAM;AACX"}

package/src/lib/app-utils/native-app-web-view.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+/**
+ * Whether a page is running inside the native apps' web view (AGL-3894).
+ *
+ * The Aglyn apps (iPhone, iPad, Mac, Android, Windows) open the Besigner in
+ * an in-app web view. Inside it the app owns what a browser tab would offer:
+ * its own push notifications, its own Done button, its own window title. The
+ * page uses this to leave those web-only extras out.
+ *
+ * Two signals, either one enough:
+ *
+ * - **The user-agent marker.** Every app's web view appends
+ *   `AglynApp/<version> (<platform>)` to its user agent (WKWebView's
+ *   `applicationNameForUserAgent`, Android's `userAgentString`, WebView2's
+ *   `UserAgent`). It is there from the first request, whichever page the
+ *   view opens first, so it holds even for a build that predates the entry
+ *   page below.
+ * - **The entry page's session mark.** `/auth/besigner` marks the tab when
+ *   the app opens the Besigner through it (AGL-3850). Session storage lives
+ *   exactly as long as the web view and never reaches a browser tab.
+ *
+ * PRESENTATION ONLY. A user agent is whatever the client says it is, so this
+ * decides what the page shows (a prompt, a back arrow, a title) and never
+ * what anyone may do: no auth, entitlement or security decision reads it.
+ */
+/** The product token every app's web view adds to its user agent. */
+export declare const NATIVE_APP_USER_AGENT_PRODUCT = "AglynApp";
+/**
+ * The marker the apps append, for the native code's specs and for anyone
+ * reading this file to know the exact shape: `AglynApp/1.4.0 (ios)`.
+ */
+export declare function nativeAppUserAgentMarker(version: string, platform: string): string;
+/** Whether a user-agent string carries the apps' marker. */
+export declare function userAgentNamesNativeApp(userAgent: string | null | undefined): boolean;
+/**
+ * Remember, for this tab, that it is the native apps' web view. Called by the
+ * Besigner entry page the apps open first.
+ */
+export declare function markNativeAppWebView(): void;
+/** Whether this page is inside the native apps' web view. */
+export declare function isNativeAppWebView(): boolean;
+/**
+ * `isNativeAppWebView()` for a render. The server cannot tell, so it renders
+ * the browser's page and hydration agrees with it; the client then renders
+ * again with the answer. Neither signal changes while a page is open, so
+ * there is nothing to subscribe to.
+ */
+export declare function useIsNativeAppWebView(): boolean;

package/src/lib/app-utils/native-app-web-view.js

@@ -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.
+ */ import { useSyncExternalStore } from "react";
+/**
+ * Whether a page is running inside the native apps' web view (AGL-3894).
+ *
+ * The Aglyn apps (iPhone, iPad, Mac, Android, Windows) open the Besigner in
+ * an in-app web view. Inside it the app owns what a browser tab would offer:
+ * its own push notifications, its own Done button, its own window title. The
+ * page uses this to leave those web-only extras out.
+ *
+ * Two signals, either one enough:
+ *
+ * - **The user-agent marker.** Every app's web view appends
+ *   `AglynApp/<version> (<platform>)` to its user agent (WKWebView's
+ *   `applicationNameForUserAgent`, Android's `userAgentString`, WebView2's
+ *   `UserAgent`). It is there from the first request, whichever page the
+ *   view opens first, so it holds even for a build that predates the entry
+ *   page below.
+ * - **The entry page's session mark.** `/auth/besigner` marks the tab when
+ *   the app opens the Besigner through it (AGL-3850). Session storage lives
+ *   exactly as long as the web view and never reaches a browser tab.
+ *
+ * PRESENTATION ONLY. A user agent is whatever the client says it is, so this
+ * decides what the page shows (a prompt, a back arrow, a title) and never
+ * what anyone may do: no auth, entitlement or security decision reads it.
+ */ /** The product token every app's web view adds to its user agent. */ export const NATIVE_APP_USER_AGENT_PRODUCT = 'AglynApp';
+/** Set by the Besigner entry page for the life of the web view's tab. */ const NATIVE_APP_WEB_VIEW_KEY = 'aglyn:native-app-web-view';
+/** `AglynApp/<version>` as its own token: not inside a longer product name. */ const USER_AGENT_MARKER = new RegExp(`(?:^|[\\s(;])${NATIVE_APP_USER_AGENT_PRODUCT}/[^\\s/]+`);
+/**
+ * The marker the apps append, for the native code's specs and for anyone
+ * reading this file to know the exact shape: `AglynApp/1.4.0 (ios)`.
+ */ export function nativeAppUserAgentMarker(version, platform) {
+    return `${NATIVE_APP_USER_AGENT_PRODUCT}/${version || '0'} (${platform})`;
+}
+/** Whether a user-agent string carries the apps' marker. */ export function userAgentNamesNativeApp(userAgent) {
+    return typeof userAgent === 'string' && USER_AGENT_MARKER.test(userAgent);
+}
+/**
+ * Remember, for this tab, that it is the native apps' web view. Called by the
+ * Besigner entry page the apps open first.
+ */ export function markNativeAppWebView() {
+    try {
+        window.sessionStorage.setItem(NATIVE_APP_WEB_VIEW_KEY, '1');
+    } catch (unused) {
+    // Storage refused: the user-agent marker still answers.
+    }
+}
+/** Whether this page is inside the native apps' web view. */ export function isNativeAppWebView() {
+    var _window_navigator;
+    if (typeof window === 'undefined') return false;
+    if (userAgentNamesNativeApp((_window_navigator = window.navigator) == null ? void 0 : _window_navigator.userAgent)) return true;
+    try {
+        return window.sessionStorage.getItem(NATIVE_APP_WEB_VIEW_KEY) === '1';
+    } catch (unused) {
+        return false;
+    }
+}
+const subscribeNever = ()=>()=>undefined;
+const onServer = ()=>false;
+/**
+ * `isNativeAppWebView()` for a render. The server cannot tell, so it renders
+ * the browser's page and hydration agrees with it; the client then renders
+ * again with the answer. Neither signal changes while a page is open, so
+ * there is nothing to subscribe to.
+ */ export function useIsNativeAppWebView() {
+    return useSyncExternalStore(subscribeNever, isNativeAppWebView, onServer);
+}
+
+//# sourceMappingURL=native-app-web-view.js.map

package/src/lib/app-utils/native-app-web-view.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/native-app-web-view.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 { useSyncExternalStore } from 'react'\n\n/**\n * Whether a page is running inside the native apps' web view (AGL-3894).\n *\n * The Aglyn apps (iPhone, iPad, Mac, Android, Windows) open the Besigner in\n * an in-app web view. Inside it the app owns what a browser tab would offer:\n * its own push notifications, its own Done button, its own window title. The\n * page uses this to leave those web-only extras out.\n *\n * Two signals, either one enough:\n *\n * - **The user-agent marker.** Every app's web view appends\n *   `AglynApp/<version> (<platform>)` to its user agent (WKWebView's\n *   `applicationNameForUserAgent`, Android's `userAgentString`, WebView2's\n *   `UserAgent`). It is there from the first request, whichever page the\n *   view opens first, so it holds even for a build that predates the entry\n *   page below.\n * - **The entry page's session mark.** `/auth/besigner` marks the tab when\n *   the app opens the Besigner through it (AGL-3850). Session storage lives\n *   exactly as long as the web view and never reaches a browser tab.\n *\n * PRESENTATION ONLY. A user agent is whatever the client says it is, so this\n * decides what the page shows (a prompt, a back arrow, a title) and never\n * what anyone may do: no auth, entitlement or security decision reads it.\n */\n\n/** The product token every app's web view adds to its user agent. */\nexport const NATIVE_APP_USER_AGENT_PRODUCT = 'AglynApp'\n\n/** Set by the Besigner entry page for the life of the web view's tab. */\nconst NATIVE_APP_WEB_VIEW_KEY = 'aglyn:native-app-web-view'\n\n/** `AglynApp/<version>` as its own token: not inside a longer product name. */\nconst USER_AGENT_MARKER = new RegExp(\n  `(?:^|[\\\\s(;])${NATIVE_APP_USER_AGENT_PRODUCT}/[^\\\\s/]+`,\n)\n\n/**\n * The marker the apps append, for the native code's specs and for anyone\n * reading this file to know the exact shape: `AglynApp/1.4.0 (ios)`.\n */\nexport function nativeAppUserAgentMarker(\n  version: string,\n  platform: string,\n): string {\n  return `${NATIVE_APP_USER_AGENT_PRODUCT}/${version || '0'} (${platform})`\n}\n\n/** Whether a user-agent string carries the apps' marker. */\nexport function userAgentNamesNativeApp(\n  userAgent: string | null | undefined,\n): boolean {\n  return typeof userAgent === 'string' && USER_AGENT_MARKER.test(userAgent)\n}\n\n/**\n * Remember, for this tab, that it is the native apps' web view. Called by the\n * Besigner entry page the apps open first.\n */\nexport function markNativeAppWebView(): void {\n  try {\n    window.sessionStorage.setItem(NATIVE_APP_WEB_VIEW_KEY, '1')\n  } catch {\n    // Storage refused: the user-agent marker still answers.\n  }\n}\n\n/** Whether this page is inside the native apps' web view. */\nexport function isNativeAppWebView(): boolean {\n  if (typeof window === 'undefined') return false\n  if (userAgentNamesNativeApp(window.navigator?.userAgent)) return true\n  try {\n    return window.sessionStorage.getItem(NATIVE_APP_WEB_VIEW_KEY) === '1'\n  } catch {\n    return false\n  }\n}\n\nconst subscribeNever = (): (() => void) => () => undefined\nconst onServer = (): boolean => false\n\n/**\n * `isNativeAppWebView()` for a render. The server cannot tell, so it renders\n * the browser's page and hydration agrees with it; the client then renders\n * again with the answer. Neither signal changes while a page is open, so\n * there is nothing to subscribe to.\n */\nexport function useIsNativeAppWebView(): boolean {\n  return useSyncExternalStore(subscribeNever, isNativeAppWebView, onServer)\n}\n"],"names":["useSyncExternalStore","NATIVE_APP_USER_AGENT_PRODUCT","NATIVE_APP_WEB_VIEW_KEY","USER_AGENT_MARKER","RegExp","nativeAppUserAgentMarker","version","platform","userAgentNamesNativeApp","userAgent","test","markNativeAppWebView","window","sessionStorage","setItem","isNativeAppWebView","navigator","getItem","subscribeNever","undefined","onServer","useIsNativeAppWebView"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,QAAQ,QAAO;AAE5C;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED,mEAAmE,GACnE,OAAO,MAAMC,gCAAgC,WAAU;AAEvD,uEAAuE,GACvE,MAAMC,0BAA0B;AAEhC,6EAA6E,GAC7E,MAAMC,oBAAoB,IAAIC,OAC5B,CAAC,aAAa,EAAEH,8BAA8B,SAAS,CAAC;AAG1D;;;CAGC,GACD,OAAO,SAASI,yBACdC,OAAe,EACfC,QAAgB;IAEhB,OAAO,GAAGN,8BAA8B,CAAC,EAAEK,WAAW,IAAI,EAAE,EAAEC,SAAS,CAAC,CAAC;AAC3E;AAEA,0DAA0D,GAC1D,OAAO,SAASC,wBACdC,SAAoC;IAEpC,OAAO,OAAOA,cAAc,YAAYN,kBAAkBO,IAAI,CAACD;AACjE;AAEA;;;CAGC,GACD,OAAO,SAASE;IACd,IAAI;QACFC,OAAOC,cAAc,CAACC,OAAO,CAACZ,yBAAyB;IACzD,EAAE,eAAM;IACN,wDAAwD;IAC1D;AACF;AAEA,2DAA2D,GAC3D,OAAO,SAASa;QAEcH;IAD5B,IAAI,OAAOA,WAAW,aAAa,OAAO;IAC1C,IAAIJ,yBAAwBI,oBAAAA,OAAOI,SAAS,qBAAhBJ,kBAAkBH,SAAS,GAAG,OAAO;IACjE,IAAI;QACF,OAAOG,OAAOC,cAAc,CAACI,OAAO,CAACf,6BAA6B;IACpE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,MAAMgB,iBAAiB,IAAoB,IAAMC;AACjD,MAAMC,WAAW,IAAe;AAEhC;;;;;CAKC,GACD,OAAO,SAASC;IACd,OAAOrB,qBAAqBkB,gBAAgBH,oBAAoBK;AAClE"}

package/src/lib/app-utils/notification-sounds.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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 notification sounds a person picks from (Notification settings), the
+ * same on every surface: the console's chime, the APNs `sound` the Apple apps
+ * play and the Android notification channel.
+ *
+ * NO IMPORTS, on purpose: the native apps read this list through the
+ * generated contracts, so it must stay a plain module.
+ *
+ * The audio is synthesized by `tools/notification-sounds/generate.py`, which
+ * writes each sound to the three paths named here; the two lists name the
+ * same ids.
+ */
+/** `users/{uid}.notificationSound`: the id of the sound the person picked. */
+export declare const NOTIFICATION_SOUND_FIELD = "notificationSound";
+export interface NotificationSound {
+    id: string;
+    label: string;
+    /** The console's file, served from `apps/console/public`. */
+    web: string;
+    /** The file in both Apple apps' bundles, named in the APNs payload's `sound`. */
+    apple: string;
+    /**
+     * The Android raw resource and the notification channel that plays it. A
+     * channel's sound cannot change once created, so each sound has its own.
+     */
+    android: string;
+}
+/** In the order the picker lists them; the first is the default. */
+export declare const NOTIFICATION_SOUNDS: readonly NotificationSound[];
+/** What a person hears before they pick one. */
+export declare const DEFAULT_NOTIFICATION_SOUND = "xylophone";
+/** The stored pick as a sound, the default for no pick or an id no longer listed. */
+export declare function notificationSound(value: unknown): NotificationSound;

package/src/lib/app-utils/notification-sounds.js

@@ -0,0 +1,54 @@
+/**
+ * @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 notification sounds a person picks from (Notification settings), the
+ * same on every surface: the console's chime, the APNs `sound` the Apple apps
+ * play and the Android notification channel.
+ *
+ * NO IMPORTS, on purpose: the native apps read this list through the
+ * generated contracts, so it must stay a plain module.
+ *
+ * The audio is synthesized by `tools/notification-sounds/generate.py`, which
+ * writes each sound to the three paths named here; the two lists name the
+ * same ids.
+ */ /** `users/{uid}.notificationSound`: the id of the sound the person picked. */ export const NOTIFICATION_SOUND_FIELD = 'notificationSound';
+function sound(id, label) {
+    return {
+        id,
+        label,
+        web: `/sounds/notifications/${id}.wav`,
+        apple: `aglyn-${id}.caf`,
+        android: `aglyn_sound_${id}`
+    };
+}
+/** In the order the picker lists them; the first is the default. */ export const NOTIFICATION_SOUNDS = [
+    sound('xylophone', 'Xylophone'),
+    sound('signature', 'Signature'),
+    sound('tada', 'Ta-da'),
+    sound('plink', 'Plink'),
+    sound('arcade', 'Arcade'),
+    sound('cowbell', 'Cowbell'),
+    sound('bubbles', 'Bubbles'),
+    sound('steel_pan', 'Steel pan'),
+    sound('cash_register', 'Cash register')
+];
+/** What a person hears before they pick one. */ export const DEFAULT_NOTIFICATION_SOUND = 'xylophone';
+/** The stored pick as a sound, the default for no pick or an id no longer listed. */ export function notificationSound(value) {
+    var _NOTIFICATION_SOUNDS_find;
+    return (_NOTIFICATION_SOUNDS_find = NOTIFICATION_SOUNDS.find((entry)=>entry.id === value)) != null ? _NOTIFICATION_SOUNDS_find : NOTIFICATION_SOUNDS.find((entry)=>entry.id === DEFAULT_NOTIFICATION_SOUND);
+}
+
+//# sourceMappingURL=notification-sounds.js.map

package/src/lib/app-utils/notification-sounds.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/notification-sounds.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 notification sounds a person picks from (Notification settings), the\n * same on every surface: the console's chime, the APNs `sound` the Apple apps\n * play and the Android notification channel.\n *\n * NO IMPORTS, on purpose: the native apps read this list through the\n * generated contracts, so it must stay a plain module.\n *\n * The audio is synthesized by `tools/notification-sounds/generate.py`, which\n * writes each sound to the three paths named here; the two lists name the\n * same ids.\n */\n\n/** `users/{uid}.notificationSound`: the id of the sound the person picked. */\nexport const NOTIFICATION_SOUND_FIELD = 'notificationSound'\n\nexport interface NotificationSound {\n  id: string\n  label: string\n  /** The console's file, served from `apps/console/public`. */\n  web: string\n  /** The file in both Apple apps' bundles, named in the APNs payload's `sound`. */\n  apple: string\n  /**\n   * The Android raw resource and the notification channel that plays it. A\n   * channel's sound cannot change once created, so each sound has its own.\n   */\n  android: string\n}\n\nfunction sound(id: string, label: string): NotificationSound {\n  return {\n    id,\n    label,\n    web: `/sounds/notifications/${id}.wav`,\n    apple: `aglyn-${id}.caf`,\n    android: `aglyn_sound_${id}`,\n  }\n}\n\n/** In the order the picker lists them; the first is the default. */\nexport const NOTIFICATION_SOUNDS: readonly NotificationSound[] = [\n  sound('xylophone', 'Xylophone'),\n  sound('signature', 'Signature'),\n  sound('tada', 'Ta-da'),\n  sound('plink', 'Plink'),\n  sound('arcade', 'Arcade'),\n  sound('cowbell', 'Cowbell'),\n  sound('bubbles', 'Bubbles'),\n  sound('steel_pan', 'Steel pan'),\n  sound('cash_register', 'Cash register'),\n]\n\n/** What a person hears before they pick one. */\nexport const DEFAULT_NOTIFICATION_SOUND = 'xylophone'\n\n/** The stored pick as a sound, the default for no pick or an id no longer listed. */\nexport function notificationSound(value: unknown): NotificationSound {\n  return (\n    NOTIFICATION_SOUNDS.find((entry) => entry.id === value) ??\n    (NOTIFICATION_SOUNDS.find((entry) => entry.id === DEFAULT_NOTIFICATION_SOUND) as NotificationSound)\n  )\n}\n"],"names":["NOTIFICATION_SOUND_FIELD","sound","id","label","web","apple","android","NOTIFICATION_SOUNDS","DEFAULT_NOTIFICATION_SOUND","notificationSound","value","find","entry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;CAWC,GAED,4EAA4E,GAC5E,OAAO,MAAMA,2BAA2B,oBAAmB;AAgB3D,SAASC,MAAMC,EAAU,EAAEC,KAAa;IACtC,OAAO;QACLD;QACAC;QACAC,KAAK,CAAC,sBAAsB,EAAEF,GAAG,IAAI,CAAC;QACtCG,OAAO,CAAC,MAAM,EAAEH,GAAG,IAAI,CAAC;QACxBI,SAAS,CAAC,YAAY,EAAEJ,IAAI;IAC9B;AACF;AAEA,kEAAkE,GAClE,OAAO,MAAMK,sBAAoD;IAC/DN,MAAM,aAAa;IACnBA,MAAM,aAAa;IACnBA,MAAM,QAAQ;IACdA,MAAM,SAAS;IACfA,MAAM,UAAU;IAChBA,MAAM,WAAW;IACjBA,MAAM,WAAW;IACjBA,MAAM,aAAa;IACnBA,MAAM,iBAAiB;CACxB,CAAA;AAED,8CAA8C,GAC9C,OAAO,MAAMO,6BAA6B,YAAW;AAErD,mFAAmF,GACnF,OAAO,SAASC,kBAAkBC,KAAc;QAE5CH;IADF,QACEA,4BAAAA,oBAAoBI,IAAI,CAAC,CAACC,QAAUA,MAAMV,EAAE,KAAKQ,kBAAjDH,4BACCA,oBAAoBI,IAAI,CAAC,CAACC,QAAUA,MAAMV,EAAE,KAAKM;AAEtD"}

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

@@ -349,6 +349,8 @@ export declare const NOTIFICATION_CHANNEL_DEFAULTS: Readonly<Record<Notification
  * see {@link NOTIFICATION_SELF_SENT_EMAIL_TYPES} and the `skipEmail` callers.
  */
 export declare const NOTIFICATION_TYPE_CHANNEL_DEFAULTS: Partial<Record<AglynNotificationType, Partial<Record<NotificationChannel, boolean>>>>;
+/** The words on a notification email's button: the record it opens, else "Open in {product}". */
+export declare function notificationEmailAction(type: AglynNotificationType | string, productName: string): string;
 /** What a type does on a channel when nobody has answered for it or its category. */
 export declare function notificationTypeChannelDefault(type: AglynNotificationType | string, channel: NotificationChannel): boolean;
 /**

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

@@ -443,6 +443,38 @@ export const NOTIFICATION_CHANNEL_DEFAULTS = inCategoryOrder(CORE_CHANNEL_DEFAUL
         email: true
     }
 };
+/**
+ * What a notification email's button says it opens (AGL-3897), by type: the
+ * record the notification links to, named, rather than "Open in Aglyn" on
+ * every one. A type with no entry keeps that general label.
+ */ const NOTIFICATION_EMAIL_ACTIONS = {
+    'content.formSubmission': 'View submission',
+    'content.booking': 'View booking',
+    'content.order': 'View order',
+    'content.lowStock': 'View product',
+    'content.taskAssigned': 'Open task',
+    'content.taskReminder': 'Open task',
+    'content.contactAssigned': 'Open contact',
+    'content.leadAssigned': 'Open lead',
+    'billing.invoice': 'Open billing',
+    'billing.paymentFailed': 'Update payment method',
+    'billing.subscriptionCanceled': 'Open billing',
+    'billing.usage': 'Open billing',
+    'support.ticketOpened': 'Open ticket',
+    'support.ticketReply': 'Open ticket',
+    'marketplace.review': 'Open listing',
+    'staff.userSignedUp': 'Open account',
+    'staff.orgCreated': 'Open workspace',
+    'staff.siteCreated': 'Open site',
+    'staff.subscriptionStarted': 'Open workspace',
+    'staff.subscriptionCanceled': 'Open workspace',
+    'staff.planChanged': 'Open workspace',
+    'staff.paymentFailed': 'Open workspace'
+};
+/** The words on a notification email's button: the record it opens, else "Open in {product}". */ export function notificationEmailAction(type, productName) {
+    var _NOTIFICATION_EMAIL_ACTIONS_type;
+    return (_NOTIFICATION_EMAIL_ACTIONS_type = NOTIFICATION_EMAIL_ACTIONS[type]) != null ? _NOTIFICATION_EMAIL_ACTIONS_type : `Open in ${productName}`;
+}
 /** What a type does on a channel when nobody has answered for it or its category. */ export function notificationTypeChannelDefault(type, channel) {
     var _NOTIFICATION_TYPE_CHANNEL_DEFAULTS_type;
     const own = (_NOTIFICATION_TYPE_CHANNEL_DEFAULTS_type = NOTIFICATION_TYPE_CHANNEL_DEFAULTS[type]) == null ? void 0 : _NOTIFICATION_TYPE_CHANNEL_DEFAULTS_type[channel];