@aglyn/aglyn 1.0.0-beta.230 → 1.0.0-beta.231

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

@@ -0,0 +1,400 @@
+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 { mediaSearchToken } from "./media-metadata.js";
+import { nameSearchNormalizers } from "./name-search.js";
+import { planListQuery } from "@aglyn/shared-util-tools/list-query/list-query-plan";
+/*
+ * What the media library filters and searches by, declared for the
+ * console's list query plan (AGL-3327).
+ *
+ * The library composes every clause and the search word onto ONE Firestore
+ * query through `planListQuery` (AGL-3321) — nothing is matched over the
+ * pages already read. What one query cannot hold (a second array clause, a
+ * second range, more than thirty disjunctions) the plan refuses by name and
+ * the library says so; the rest still stands.
+ *
+ * Every field is stored on the media document by every writer
+ * (`mediaFilterKeys` in `@aglyn/aglyn/app-utils/media-metadata`) and by the
+ * backfill for the documents written before (`backfill-media-filter-keys`):
+ *
+ *   type         `kind`, the family (image, video, pdf, document)
+ *   tags         `tags`, lower-cased by every writer, matched whole
+ *   uploaded     `createdAt`
+ *   size         `sizeBytes`, asked in megabytes
+ *   uploadedBy   `uploadedBy`, a uid, or `api:<key id>` from the REST API
+ *   alt          `hasAlt`, so "missing" is a value a query can find
+ *   orientation  `orientation`, from the stored pixel size
+ *   name         `nameLower`, for the Name sort and "starts with"
+ *   search       `nameTokens`, the word prefixes of the file name
+ *
+ * Not offered, because no query serves them: custom metadata (its keys are
+ * the reader's own, and each would need composites of its own), the width
+ * and the height as ranges (each a range field that would have to lead the
+ * order, with composites for every other field — Orientation answers the
+ * question people ask of them), and "contains" on the alt text itself.
+ *
+ * Firestore merges one `[field, sort]` composite per field for any
+ * combination of equalities; `media-scope-indexes.spec.ts` holds the index
+ * file to `listQueryIndexes` of this declaration.
+ */ /** The family a file belongs to, as the Type filter offers it. */ export const MEDIA_TYPE_OPTIONS = [
+    {
+        value: 'image',
+        label: 'Images'
+    },
+    {
+        value: 'video',
+        label: 'Video'
+    },
+    {
+        value: 'pdf',
+        label: 'PDF'
+    },
+    {
+        value: 'document',
+        label: 'Other documents'
+    }
+];
+/** Orientation, as the stored `orientation` names it. */ export const MEDIA_ORIENTATION_OPTIONS = [
+    {
+        value: 'landscape',
+        label: 'Landscape'
+    },
+    {
+        value: 'portrait',
+        label: 'Portrait'
+    },
+    {
+        value: 'square',
+        label: 'Square'
+    }
+];
+/** Alt text, as the two answers a query can give about it. */ export const MEDIA_ALT_OPTIONS = [
+    {
+        value: 'false',
+        label: 'Missing'
+    },
+    {
+        value: 'true',
+        label: 'Set'
+    }
+];
+const MB = 1024 * 1024;
+/**
+ * The fields the Filters panel offers, each as the query serves it.
+ *
+ * Tags is an array matched whole: `exact` with its `tokensPath`, so `contains`
+ * is `array-contains` and `isAnyOf` is `array-contains-any` — the panel shows
+ * `contains` as the select's "is" (`MEDIA_TAGS_CODEC`). Size is asked in
+ * megabytes and served in bytes (`mediaQueryRequest`).
+ */ export const MEDIA_FILTER_FIELDS = [
+    {
+        column: 'type',
+        kind: 'exact',
+        path: 'kind',
+        operators: [
+            'equals',
+            'isAnyOf'
+        ]
+    },
+    {
+        column: 'tags',
+        kind: 'exact',
+        path: 'tags',
+        tokensPath: 'tags',
+        operators: [
+            'contains',
+            'isAnyOf'
+        ]
+    },
+    {
+        column: 'uploaded',
+        kind: 'date',
+        path: 'createdAt',
+        presence: 'always'
+    },
+    {
+        column: 'sizeMb',
+        kind: 'number',
+        path: 'sizeBytes',
+        operators: [
+            '>',
+            '>=',
+            '<',
+            '<='
+        ]
+    },
+    {
+        column: 'uploadedBy',
+        kind: 'exact',
+        path: 'uploadedBy',
+        operators: [
+            'equals',
+            'isAnyOf'
+        ]
+    },
+    {
+        column: 'alt',
+        kind: 'boolean',
+        path: 'hasAlt',
+        operators: [
+            'equals'
+        ]
+    },
+    {
+        column: 'orientation',
+        kind: 'exact',
+        path: 'orientation',
+        operators: [
+            'equals',
+            'isAnyOf'
+        ]
+    },
+    {
+        column: 'fileName',
+        kind: 'text',
+        path: 'fileName',
+        lowerPath: 'nameLower',
+        operators: [
+            'startsWith'
+        ]
+    }
+];
+export const MEDIA_FILTER_HEADERS = {
+    type: 'Type',
+    tags: 'Tags',
+    uploaded: 'Uploaded',
+    sizeMb: 'Size (MB)',
+    uploadedBy: 'Uploaded by',
+    alt: 'Alt text',
+    orientation: 'Orientation',
+    fileName: 'Name'
+};
+/** The fields one library offers. */ export function mediaFilterFields(options) {
+    return MEDIA_FILTER_FIELDS.filter((field)=>!(options.typeLocked && field.column === 'type') && !(options.scoped && field.column === 'tags'));
+}
+export const MEDIA_SORTS = [
+    'newest',
+    'oldest',
+    'name',
+    'size'
+];
+/** What each sort orders by, and the List view column that sorts it. */ export const MEDIA_SORT_ORDER = {
+    newest: {
+        path: 'createdAt',
+        direction: 'desc',
+        column: 'uploaded'
+    },
+    oldest: {
+        path: 'createdAt',
+        direction: 'asc',
+        column: 'uploaded'
+    },
+    // `nameLower`, so the order ignores case, and a "starts with" range — the
+    // name's own range — orders the list the way this sort already does.
+    name: {
+        path: 'nameLower',
+        direction: 'asc',
+        column: 'fileName'
+    },
+    size: {
+        path: 'sizeBytes',
+        direction: 'desc',
+        column: 'size'
+    }
+};
+export const MEDIA_SORT_LABELS = {
+    newest: 'Newest',
+    oldest: 'Oldest',
+    name: 'Name',
+    size: 'Largest'
+};
+/** The library's sort for a query order, or null for one it does not offer. */ export function mediaSortOf(order) {
+    const found = MEDIA_SORTS.find((sort)=>MEDIA_SORT_ORDER[sort].path === order.path && MEDIA_SORT_ORDER[sort].direction === order.direction);
+    return found != null ? found : null;
+}
+// ---------------------------------------------------------------------------
+// The query
+// ---------------------------------------------------------------------------
+/**
+ * The library as the list query plan reads it. Newest first is the default,
+ * and every sort is one the index file holds for every field.
+ */ export const MEDIA_LIST_QUERY = {
+    fields: MEDIA_FILTER_FIELDS,
+    sorts: MEDIA_SORTS.map((sort)=>MEDIA_SORT_ORDER[sort]),
+    search: {
+        tokensPath: 'nameTokens'
+    }
+};
+/**
+ * The normalizers the media writers stamped the name fields with: the
+ * platform's name search, except that a file name's words are split at every
+ * separator (`mediaSearchToken`), so `hero-banner.png` is found by "banner".
+ */ export const MEDIA_NAME_NORMALIZERS = _extends({}, nameSearchNormalizers, {
+    token: (value)=>mediaSearchToken(value)
+});
+/** The predicates every query of one library view carries, before any clause. */ export function mediaBaseFilters(input) {
+    const { folder, scopeTokens } = input;
+    return [
+        ...folder === 'root' ? [
+            {
+                path: 'folderId',
+                op: '==',
+                value: null
+            }
+        ] : folder === 'all' ? [] : folder.length === 1 ? [
+            {
+                path: 'folderId',
+                op: '==',
+                value: folder[0]
+            }
+        ] : [
+            {
+                path: 'folderId',
+                op: 'in',
+                value: [
+                    ...folder
+                ]
+            }
+        ],
+        ...scopeTokens ? [
+            {
+                path: 'visibleTo',
+                op: 'array-contains-any',
+                value: [
+                    ...scopeTokens
+                ]
+            }
+        ] : []
+    ];
+}
+/** The scope predicates, as `listQueryIndexes` enumerates them. */ export const MEDIA_BASE_INDEX_FIELDS = [
+    {
+        path: 'folderId'
+    },
+    {
+        path: 'visibleTo',
+        array: true
+    }
+];
+/** Firestore's cap on disjunctions: the product of every `in` and `-any`. */ export const MEDIA_DISJUNCTION_LIMIT = 30;
+/** A clause as the query asks it: a size in bytes, the rest as written. */ export function mediaQueryRequest(clause) {
+    if (clause.field !== 'sizeMb') return clause;
+    const megabytes = Number(clause.value);
+    return Number.isFinite(megabytes) && String(clause.value).trim() !== '' ? _extends({}, clause, {
+        value: String(Math.round(megabytes * MB))
+    }) : clause;
+}
+/** Said when a scoped reader's search is served as a name range. */ export const MEDIA_SCOPED_SEARCH_NOTICE = 'In a library limited to some sites, search finds files whose name ' + 'starts with what you type.';
+/**
+ * A scoped reader's search, as the clause their query can serve (AGL-3327).
+ *
+ * The quick search is `array-contains` on `nameTokens`, and the scope clause
+ * a scoped reader's query must carry (`visibleTo array-contains-any`,
+ * AGL-1042) is the query's one array filter, so the two cannot share one
+ * query. Folding the word into the scope clause (`search.scoped` in the list
+ * query plan) cannot be used here either: the security rules prove a scoped
+ * reader's list from its `visibleTo` clause, and a query that asks only for
+ * `<scope>~<word>` tokens proves nothing about `visibleTo`, so Firestore
+ * refuses it outright (probed against the emulator, AGL-3327). What the rules
+ * and one query can both hold is a range on `nameLower` beside the scope
+ * clause: the files whose name starts with what was typed, claimed first so
+ * a date or size range gives way to it rather than the other way round.
+ */ export function mediaScopedSearchClause(search) {
+    const typed = search.map((word)=>word.trim()).filter(Boolean).join(' ');
+    return typed ? {
+        field: 'fileName',
+        op: 'startsWith',
+        value: typed
+    } : null;
+}
+/**
+ * The one query a view of the library reads (AGL-3327).
+ *
+ * The folder and the scope clause are the base every query carries. A range
+ * filter orders the query by its own field; where the reader's sort is on
+ * that field already (Oldest under an Uploaded filter), its direction stands.
+ * Under the scope clause the search is a name range
+ * (`mediaScopedSearchClause`), and the library says so.
+ */ export function mediaQuery(input) {
+    var _ref;
+    const { sort, scopeTokens } = input;
+    const scopedSearch = scopeTokens ? mediaScopedSearchClause(input.search) : null;
+    const clauses = scopedSearch ? [
+        scopedSearch,
+        ...input.clauses
+    ] : input.clauses;
+    const search = scopedSearch ? [] : input.search;
+    const tokens = (_ref = scopeTokens == null ? void 0 : scopeTokens.length) != null ? _ref : 1;
+    const subfoldersDropped = Array.isArray(input.folder) && input.folder.length > 1 && input.folder.length * tokens > MEDIA_DISJUNCTION_LIMIT;
+    const folder = subfoldersDropped && Array.isArray(input.folder) ? [
+        input.folder[0]
+    ] : input.folder;
+    const asked = MEDIA_SORT_ORDER[sort];
+    const plan = planListQuery(MEDIA_LIST_QUERY, {
+        base: mediaBaseFilters({
+            folder,
+            scopeTokens
+        }),
+        clauses: clauses.map(mediaQueryRequest),
+        search,
+        sort: asked
+    }, MEDIA_NAME_NORMALIZERS);
+    const orderBy = plan.orderBy.path === asked.path && plan.orderBy.direction !== asked.direction ? asked : plan.orderBy;
+    const notices = scopedSearch ? [
+        MEDIA_SCOPED_SEARCH_NOTICE,
+        ...plan.notices
+    ] : plan.notices;
+    return {
+        plan: _extends({}, plan, {
+            orderBy,
+            notices
+        }),
+        subfoldersDropped
+    };
+}
+/**
+ * Every folder at or under `folderId`, the folder itself first. Walks the
+ * parent links downward and never revisits one, so a cycle a stale write
+ * left behind cannot loop.
+ */ export function mediaFolderDescendants(folderId, folders) {
+    const children = new Map();
+    for (const folder of folders){
+        var _folder_parentId, _children_get;
+        const parent = (_folder_parentId = folder.parentId) != null ? _folder_parentId : null;
+        if (!parent) continue;
+        children.set(parent, [
+            ...(_children_get = children.get(parent)) != null ? _children_get : [],
+            folder.$id
+        ]);
+    }
+    const ids = [];
+    const queue = [
+        folderId
+    ];
+    const seen = new Set();
+    while(queue.length){
+        var _children_get1;
+        const next = queue.shift();
+        if (seen.has(next)) continue;
+        seen.add(next);
+        ids.push(next);
+        queue.push(...(_children_get1 = children.get(next)) != null ? _children_get1 : []);
+    }
+    return ids;
+}
+
+//# sourceMappingURL=media-filter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/media-filter.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 { mediaSearchToken } from './media-metadata'\nimport { nameSearchNormalizers } from './name-search'\nimport type {\n  ListFilterField,\n  ListFilterRequest,\n} from '@aglyn/shared-util-tools/list-query/list-filter'\nimport type { ListFilterOption } from '@aglyn/shared-util-tools/list-query/list-filter-codecs'\nimport {\n  type ListQueryDeclaration,\n  type ListQueryFilter,\n  type ListQueryNormalizers,\n  type ListQueryPlan,\n  type ListQuerySort,\n  planListQuery,\n} from '@aglyn/shared-util-tools/list-query/list-query-plan'\n\n/*\n * What the media library filters and searches by, declared for the\n * console's list query plan (AGL-3327).\n *\n * The library composes every clause and the search word onto ONE Firestore\n * query through `planListQuery` (AGL-3321) — nothing is matched over the\n * pages already read. What one query cannot hold (a second array clause, a\n * second range, more than thirty disjunctions) the plan refuses by name and\n * the library says so; the rest still stands.\n *\n * Every field is stored on the media document by every writer\n * (`mediaFilterKeys` in `@aglyn/aglyn/app-utils/media-metadata`) and by the\n * backfill for the documents written before (`backfill-media-filter-keys`):\n *\n *   type         `kind`, the family (image, video, pdf, document)\n *   tags         `tags`, lower-cased by every writer, matched whole\n *   uploaded     `createdAt`\n *   size         `sizeBytes`, asked in megabytes\n *   uploadedBy   `uploadedBy`, a uid, or `api:<key id>` from the REST API\n *   alt          `hasAlt`, so \"missing\" is a value a query can find\n *   orientation  `orientation`, from the stored pixel size\n *   name         `nameLower`, for the Name sort and \"starts with\"\n *   search       `nameTokens`, the word prefixes of the file name\n *\n * Not offered, because no query serves them: custom metadata (its keys are\n * the reader's own, and each would need composites of its own), the width\n * and the height as ranges (each a range field that would have to lead the\n * order, with composites for every other field — Orientation answers the\n * question people ask of them), and \"contains\" on the alt text itself.\n *\n * Firestore merges one `[field, sort]` composite per field for any\n * combination of equalities; `media-scope-indexes.spec.ts` holds the index\n * file to `listQueryIndexes` of this declaration.\n */\n\n/** The family a file belongs to, as the Type filter offers it. */\nexport const MEDIA_TYPE_OPTIONS: readonly ListFilterOption[] = [\n  { value: 'image', label: 'Images' },\n  { value: 'video', label: 'Video' },\n  { value: 'pdf', label: 'PDF' },\n  { value: 'document', label: 'Other documents' },\n]\n\n/** Orientation, as the stored `orientation` names it. */\nexport const MEDIA_ORIENTATION_OPTIONS: readonly ListFilterOption[] = [\n  { value: 'landscape', label: 'Landscape' },\n  { value: 'portrait', label: 'Portrait' },\n  { value: 'square', label: 'Square' },\n]\n\n/** Alt text, as the two answers a query can give about it. */\nexport const MEDIA_ALT_OPTIONS: readonly ListFilterOption[] = [\n  { value: 'false', label: 'Missing' },\n  { value: 'true', label: 'Set' },\n]\n\nconst MB = 1024 * 1024\n\n/**\n * The fields the Filters panel offers, each as the query serves it.\n *\n * Tags is an array matched whole: `exact` with its `tokensPath`, so `contains`\n * is `array-contains` and `isAnyOf` is `array-contains-any` — the panel shows\n * `contains` as the select's \"is\" (`MEDIA_TAGS_CODEC`). Size is asked in\n * megabytes and served in bytes (`mediaQueryRequest`).\n */\nexport const MEDIA_FILTER_FIELDS: readonly ListFilterField[] = [\n  { column: 'type', kind: 'exact', path: 'kind', operators: ['equals', 'isAnyOf'] },\n  {\n    column: 'tags',\n    kind: 'exact',\n    path: 'tags',\n    tokensPath: 'tags',\n    operators: ['contains', 'isAnyOf'],\n  },\n  { column: 'uploaded', kind: 'date', path: 'createdAt', presence: 'always' },\n  { column: 'sizeMb', kind: 'number', path: 'sizeBytes', operators: ['>', '>=', '<', '<='] },\n  { column: 'uploadedBy', kind: 'exact', path: 'uploadedBy', operators: ['equals', 'isAnyOf'] },\n  { column: 'alt', kind: 'boolean', path: 'hasAlt', operators: ['equals'] },\n  {\n    column: 'orientation',\n    kind: 'exact',\n    path: 'orientation',\n    operators: ['equals', 'isAnyOf'],\n  },\n  {\n    column: 'fileName',\n    kind: 'text',\n    path: 'fileName',\n    lowerPath: 'nameLower',\n    operators: ['startsWith'],\n  },\n]\n\nexport const MEDIA_FILTER_HEADERS: Readonly<Record<string, string>> = {\n  type: 'Type',\n  tags: 'Tags',\n  uploaded: 'Uploaded',\n  sizeMb: 'Size (MB)',\n  uploadedBy: 'Uploaded by',\n  alt: 'Alt text',\n  orientation: 'Orientation',\n  fileName: 'Name',\n}\n\n/** The fields one library offers. */\nexport function mediaFilterFields(options: {\n  /** A picker's fixed kind (AGL-2953): Type is not the reader's to change. */\n  typeLocked: boolean\n  /**\n   * The query carries the scope clause (AGL-1042), which is its one array\n   * clause, so Tags could never be applied and is not offered.\n   */\n  scoped: boolean\n}): ListFilterField[] {\n  return MEDIA_FILTER_FIELDS.filter(\n    (field) =>\n      !(options.typeLocked && field.column === 'type') &&\n      !(options.scoped && field.column === 'tags'),\n  )\n}\n\n// ---------------------------------------------------------------------------\n// The sorts\n// ---------------------------------------------------------------------------\n\nexport type MediaSort = 'newest' | 'oldest' | 'name' | 'size'\n\nexport const MEDIA_SORTS: readonly MediaSort[] = ['newest', 'oldest', 'name', 'size']\n\n/** What each sort orders by, and the List view column that sorts it. */\nexport const MEDIA_SORT_ORDER: Readonly<Record<MediaSort, ListQuerySort>> = {\n  newest: { path: 'createdAt', direction: 'desc', column: 'uploaded' },\n  oldest: { path: 'createdAt', direction: 'asc', column: 'uploaded' },\n  // `nameLower`, so the order ignores case, and a \"starts with\" range — the\n  // name's own range — orders the list the way this sort already does.\n  name: { path: 'nameLower', direction: 'asc', column: 'fileName' },\n  size: { path: 'sizeBytes', direction: 'desc', column: 'size' },\n}\n\nexport const MEDIA_SORT_LABELS: Readonly<Record<MediaSort, string>> = {\n  newest: 'Newest',\n  oldest: 'Oldest',\n  name: 'Name',\n  size: 'Largest',\n}\n\n/** The library's sort for a query order, or null for one it does not offer. */\nexport function mediaSortOf(order: ListQuerySort): MediaSort | null {\n  const found = MEDIA_SORTS.find(\n    (sort) =>\n      MEDIA_SORT_ORDER[sort].path === order.path &&\n      MEDIA_SORT_ORDER[sort].direction === order.direction,\n  )\n  return found ?? null\n}\n\n// ---------------------------------------------------------------------------\n// The query\n// ---------------------------------------------------------------------------\n\n/**\n * The library as the list query plan reads it. Newest first is the default,\n * and every sort is one the index file holds for every field.\n */\nexport const MEDIA_LIST_QUERY: ListQueryDeclaration = {\n  fields: MEDIA_FILTER_FIELDS,\n  sorts: MEDIA_SORTS.map((sort) => MEDIA_SORT_ORDER[sort]),\n  search: { tokensPath: 'nameTokens' },\n}\n\n/**\n * The normalizers the media writers stamped the name fields with: the\n * platform's name search, except that a file name's words are split at every\n * separator (`mediaSearchToken`), so `hero-banner.png` is found by \"banner\".\n */\nexport const MEDIA_NAME_NORMALIZERS: ListQueryNormalizers = {\n  ...nameSearchNormalizers,\n  token: (value) => mediaSearchToken(value),\n}\n\n/** The predicates every query of one library view carries, before any clause. */\nexport function mediaBaseFilters(input: {\n  /** Every file, the files in no folder, or the files in these folders. */\n  folder: 'all' | 'root' | readonly string[]\n  /** The scope clause a scoped reader's query must carry (AGL-1042), or null. */\n  scopeTokens: readonly string[] | null\n}): ListQueryFilter[] {\n  const { folder, scopeTokens } = input\n  return [\n    ...(folder === 'root'\n      ? [{ path: 'folderId', op: '==' as const, value: null }]\n      : folder === 'all'\n        ? []\n        : folder.length === 1\n          ? [{ path: 'folderId', op: '==' as const, value: folder[0] }]\n          : [{ path: 'folderId', op: 'in' as const, value: [...folder] }]),\n    ...(scopeTokens\n      ? [{ path: 'visibleTo', op: 'array-contains-any' as const, value: [...scopeTokens] }]\n      : []),\n  ]\n}\n\n/** The scope predicates, as `listQueryIndexes` enumerates them. */\nexport const MEDIA_BASE_INDEX_FIELDS = [\n  { path: 'folderId' },\n  { path: 'visibleTo', array: true },\n] as const\n\n/** Firestore's cap on disjunctions: the product of every `in` and `-any`. */\nexport const MEDIA_DISJUNCTION_LIMIT = 30\n\n/** A clause as the query asks it: a size in bytes, the rest as written. */\nexport function mediaQueryRequest(clause: ListFilterRequest): ListFilterRequest {\n  if (clause.field !== 'sizeMb') return clause\n  const megabytes = Number(clause.value)\n  return Number.isFinite(megabytes) && String(clause.value).trim() !== ''\n    ? { ...clause, value: String(Math.round(megabytes * MB)) }\n    : clause\n}\n\nexport interface MediaQueryInput {\n  /** Every clause in force, a picker's fixed kind included. */\n  clauses: readonly ListFilterRequest[]\n  sort: MediaSort\n  folder: 'all' | 'root' | readonly string[]\n  scopeTokens: readonly string[] | null\n  /** The quick search's words. */\n  search: readonly string[]\n}\n\nexport interface MediaQuery {\n  plan: ListQueryPlan\n  /**\n   * Whether Include subfolders had to give way to the open folder alone:\n   * its subfolders times the scope's tokens pass Firestore's thirty\n   * disjunctions.\n   */\n  subfoldersDropped: boolean\n}\n\n/** Said when a scoped reader's search is served as a name range. */\nexport const MEDIA_SCOPED_SEARCH_NOTICE =\n  'In a library limited to some sites, search finds files whose name ' +\n  'starts with what you type.'\n\n/**\n * A scoped reader's search, as the clause their query can serve (AGL-3327).\n *\n * The quick search is `array-contains` on `nameTokens`, and the scope clause\n * a scoped reader's query must carry (`visibleTo array-contains-any`,\n * AGL-1042) is the query's one array filter, so the two cannot share one\n * query. Folding the word into the scope clause (`search.scoped` in the list\n * query plan) cannot be used here either: the security rules prove a scoped\n * reader's list from its `visibleTo` clause, and a query that asks only for\n * `<scope>~<word>` tokens proves nothing about `visibleTo`, so Firestore\n * refuses it outright (probed against the emulator, AGL-3327). What the rules\n * and one query can both hold is a range on `nameLower` beside the scope\n * clause: the files whose name starts with what was typed, claimed first so\n * a date or size range gives way to it rather than the other way round.\n */\nexport function mediaScopedSearchClause(\n  search: readonly string[],\n): ListFilterRequest | null {\n  const typed = search.map((word) => word.trim()).filter(Boolean).join(' ')\n  return typed ? { field: 'fileName', op: 'startsWith', value: typed } : null\n}\n\n/**\n * The one query a view of the library reads (AGL-3327).\n *\n * The folder and the scope clause are the base every query carries. A range\n * filter orders the query by its own field; where the reader's sort is on\n * that field already (Oldest under an Uploaded filter), its direction stands.\n * Under the scope clause the search is a name range\n * (`mediaScopedSearchClause`), and the library says so.\n */\nexport function mediaQuery(input: MediaQueryInput): MediaQuery {\n  const { sort, scopeTokens } = input\n  const scopedSearch = scopeTokens ? mediaScopedSearchClause(input.search) : null\n  const clauses = scopedSearch ? [scopedSearch, ...input.clauses] : input.clauses\n  const search = scopedSearch ? [] : input.search\n  const tokens = scopeTokens?.length ?? 1\n  const subfoldersDropped =\n    Array.isArray(input.folder) &&\n    input.folder.length > 1 &&\n    input.folder.length * tokens > MEDIA_DISJUNCTION_LIMIT\n  const folder =\n    subfoldersDropped && Array.isArray(input.folder) ? [input.folder[0]] : input.folder\n  const asked = MEDIA_SORT_ORDER[sort]\n  const plan = planListQuery(\n    MEDIA_LIST_QUERY,\n    {\n      base: mediaBaseFilters({ folder, scopeTokens }),\n      clauses: clauses.map(mediaQueryRequest),\n      search,\n      sort: asked,\n    },\n    MEDIA_NAME_NORMALIZERS,\n  )\n  const orderBy =\n    plan.orderBy.path === asked.path && plan.orderBy.direction !== asked.direction\n      ? asked\n      : plan.orderBy\n  const notices = scopedSearch ? [MEDIA_SCOPED_SEARCH_NOTICE, ...plan.notices] : plan.notices\n  return { plan: { ...plan, orderBy, notices }, subfoldersDropped }\n}\n\n/**\n * Every folder at or under `folderId`, the folder itself first. Walks the\n * parent links downward and never revisits one, so a cycle a stale write\n * left behind cannot loop.\n */\nexport function mediaFolderDescendants(\n  folderId: string,\n  folders: ReadonlyArray<{ $id: string; parentId?: string | null }>,\n): string[] {\n  const children = new Map<string, string[]>()\n  for (const folder of folders) {\n    const parent = folder.parentId ?? null\n    if (!parent) continue\n    children.set(parent, [...(children.get(parent) ?? []), folder.$id])\n  }\n  const ids: string[] = []\n  const queue = [folderId]\n  const seen = new Set<string>()\n  while (queue.length) {\n    const next = queue.shift() as string\n    if (seen.has(next)) continue\n    seen.add(next)\n    ids.push(next)\n    queue.push(...(children.get(next) ?? []))\n  }\n  return ids\n}\n"],"names":["mediaSearchToken","nameSearchNormalizers","planListQuery","MEDIA_TYPE_OPTIONS","value","label","MEDIA_ORIENTATION_OPTIONS","MEDIA_ALT_OPTIONS","MB","MEDIA_FILTER_FIELDS","column","kind","path","operators","tokensPath","presence","lowerPath","MEDIA_FILTER_HEADERS","type","tags","uploaded","sizeMb","uploadedBy","alt","orientation","fileName","mediaFilterFields","options","filter","field","typeLocked","scoped","MEDIA_SORTS","MEDIA_SORT_ORDER","newest","direction","oldest","name","size","MEDIA_SORT_LABELS","mediaSortOf","order","found","find","sort","MEDIA_LIST_QUERY","fields","sorts","map","search","MEDIA_NAME_NORMALIZERS","token","mediaBaseFilters","input","folder","scopeTokens","op","length","MEDIA_BASE_INDEX_FIELDS","array","MEDIA_DISJUNCTION_LIMIT","mediaQueryRequest","clause","megabytes","Number","isFinite","String","trim","Math","round","MEDIA_SCOPED_SEARCH_NOTICE","mediaScopedSearchClause","typed","word","Boolean","join","mediaQuery","scopedSearch","clauses","tokens","subfoldersDropped","Array","isArray","asked","plan","base","orderBy","notices","mediaFolderDescendants","folderId","folders","children","Map","parent","parentId","set","get","$id","ids","queue","seen","Set","next","shift","has","add","push"],"mappings":"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"}

package/src/lib/app-utils/mobile-push.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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 mobile push channel's shapes (AGL-3620, AGL-3651), for the server
+ * fan-out and the native apps alike.
+ *
+ * NO IMPORTS, not even types, on purpose: the native apps compile this file
+ * with their own compiler, and a type import would drag the core's whole
+ * type graph into it. The full per-scope resolution lives in
+ * `notification-push.ts`, which the server reads; the app needs only the
+ * account scope its settings screen edits, `accountPushSwitch` below, which
+ * a spec holds to the full resolver.
+ */
+/** `users/{uid}/devices/{installId}`: one row per app install, written by its owner. */
+export declare const MOBILE_DEVICES_COLLECTION = "devices";
+export type MobileDevicePlatform = 'ios' | 'android' | 'macos';
+/** The two native apps (bundle `com.aglyn.app` and `com.aglyn.pos`). */
+export type MobileDeviceApp = 'aglyn' | 'aglyn-pos';
+/** Each app's bundle id: the APNs topic its pushes are addressed to. */
+export declare const MOBILE_APP_BUNDLES: Readonly<Record<MobileDeviceApp, string>>;
+/** How a device is reached: Apple's APNs (iOS, macOS) or Google's FCM (Android). */
+export type MobilePushTransport = 'apns' | 'fcm';
+/** The APNs environment a device token was minted in; a token only works in its own. */
+export type ApnsEnvironment = 'sandbox' | 'production';
+export interface MobileDevice {
+    /** An APNs device token (hex) or an FCM registration token, per `transport`. */
+    token: string;
+    transport: MobilePushTransport;
+    /** APNs only: which gateway the token belongs to. */
+    apnsEnvironment?: ApnsEnvironment;
+    platform: MobileDevicePlatform;
+    app: MobileDeviceApp;
+    appVersion?: string;
+    /** Server time of the app's last launch while signed in. */
+    lastSeen?: unknown;
+}
+/** A device not seen for this long is not pushed to (and is pruned by the fan-out). */
+export declare const MOBILE_DEVICE_STALE_MS: number;
+/** The most devices one person's push fan-out reads. */
+export declare const MOBILE_DEVICES_PER_USER = 20;
+/** An APNs device token: hex, 64 to 200 characters (the Firestore rules hold the same). */
+export declare function isApnsDeviceToken(value: unknown): value is string;
+/** An FCM registration token: `[A-Za-z0-9_:-]`, 100 to 4096 characters (the rules hold the same). */
+export declare function isFcmRegistrationToken(value: unknown): value is string;
+/** Whether `token` is a token of `transport`'s shape. */
+export declare function isMobilePushToken(transport: unknown, token: unknown): boolean;
+/**
+ * What a push carries for the app to act on when it is tapped. The app
+ * resolves `link` the way it resolves a feed row: natively when a plugin
+ * registered a deep link for it, else in the console WebView.
+ */
+export interface MobilePushData {
+    type: string;
+    link?: string;
+    orgId?: string;
+    hostId?: string;
+}
+export declare function mobilePushData(payload: {
+    type: string;
+    link?: string | null;
+    orgId?: string | null;
+    hostId?: string | null;
+}): MobilePushData;
+/** Read a tapped push's data back, refusing anything that is not ours. */
+export declare function readMobilePushData(data: unknown): MobilePushData | null;
+type ChannelAnswers = {
+    console?: boolean;
+    push?: boolean;
+} | undefined;
+/** The account-scope slice of `NotificationSettings` the app's switch reads. */
+export interface AccountPushSettings {
+    account?: Record<string, ChannelAnswers>;
+    accountTypes?: Record<string, ChannelAnswers>;
+}
+/**
+ * What the app's per-type push switch shows: the account's push answer for
+ * the type, then for its category, and otherwise what the console feed does
+ * for it at the account scope (its console answers, the legacy category
+ * mute, then `consoleDefault`, the type's console default from the catalog).
+ * Equal to `notificationPushEnabled` with no scope; a spec holds the two
+ * together.
+ */
+export declare function accountPushSwitch(settings: AccountPushSettings | null | undefined, type: string, category: string, consoleDefault: boolean, legacyPrefs?: Record<string, boolean> | null): boolean;
+export {};

package/src/lib/app-utils/mobile-push.js

@@ -0,0 +1,97 @@
+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.
+ */ /**
+ * The mobile push channel's shapes (AGL-3620, AGL-3651), for the server
+ * fan-out and the native apps alike.
+ *
+ * NO IMPORTS, not even types, on purpose: the native apps compile this file
+ * with their own compiler, and a type import would drag the core's whole
+ * type graph into it. The full per-scope resolution lives in
+ * `notification-push.ts`, which the server reads; the app needs only the
+ * account scope its settings screen edits, `accountPushSwitch` below, which
+ * a spec holds to the full resolver.
+ */ /** `users/{uid}/devices/{installId}`: one row per app install, written by its owner. */ export const MOBILE_DEVICES_COLLECTION = 'devices';
+/** Each app's bundle id: the APNs topic its pushes are addressed to. */ export const MOBILE_APP_BUNDLES = {
+    aglyn: 'com.aglyn.app',
+    'aglyn-pos': 'com.aglyn.pos'
+};
+/** A device not seen for this long is not pushed to (and is pruned by the fan-out). */ export const MOBILE_DEVICE_STALE_MS = 60 * 24 * 60 * 60 * 1000;
+/** The most devices one person's push fan-out reads. */ export const MOBILE_DEVICES_PER_USER = 20;
+const HEX = /^[0-9A-Fa-f]+$/;
+const FCM_TOKEN = /^[A-Za-z0-9_:-]+$/;
+/** An APNs device token: hex, 64 to 200 characters (the Firestore rules hold the same). */ export function isApnsDeviceToken(value) {
+    return typeof value === 'string' && value.length >= 64 && value.length <= 200 && HEX.test(value);
+}
+/** An FCM registration token: `[A-Za-z0-9_:-]`, 100 to 4096 characters (the rules hold the same). */ export function isFcmRegistrationToken(value) {
+    return typeof value === 'string' && value.length >= 100 && value.length <= 4096 && FCM_TOKEN.test(value);
+}
+/** Whether `token` is a token of `transport`'s shape. */ export function isMobilePushToken(transport, token) {
+    if (transport === 'apns') return isApnsDeviceToken(token);
+    if (transport === 'fcm') return isFcmRegistrationToken(token);
+    return false;
+}
+export function mobilePushData(payload) {
+    return _extends({
+        type: payload.type
+    }, payload.link ? {
+        link: payload.link
+    } : {}, payload.orgId ? {
+        orgId: payload.orgId
+    } : {}, payload.hostId ? {
+        hostId: payload.hostId
+    } : {});
+}
+/** Read a tapped push's data back, refusing anything that is not ours. */ export function readMobilePushData(data) {
+    if (!data || typeof data !== 'object') return null;
+    const record = data;
+    if (typeof record['type'] !== 'string' || !record['type']) return null;
+    const text = (value)=>typeof value === 'string' && value ? value : undefined;
+    const link = text(record['link']);
+    return mobilePushData({
+        type: record['type'],
+        // Only a console path or an https URL; never a scheme the app would hand to the OS.
+        link: link && (link.startsWith('/') || link.startsWith('https://')) ? link : undefined,
+        orgId: text(record['orgId']),
+        hostId: text(record['hostId'])
+    });
+}
+/**
+ * What the app's per-type push switch shows: the account's push answer for
+ * the type, then for its category, and otherwise what the console feed does
+ * for it at the account scope (its console answers, the legacy category
+ * mute, then `consoleDefault`, the type's console default from the catalog).
+ * Equal to `notificationPushEnabled` with no scope; a spec holds the two
+ * together.
+ */ export function accountPushSwitch(settings, type, category, consoleDefault, legacyPrefs) {
+    var _settings_accountTypes_type, _settings_accountTypes, _settings_account_category, _settings_account, _settings_accountTypes_type1, _settings_accountTypes1, _settings_account_category1, _settings_account1;
+    for (const answer of [
+        settings == null ? void 0 : (_settings_accountTypes = settings.accountTypes) == null ? void 0 : (_settings_accountTypes_type = _settings_accountTypes[type]) == null ? void 0 : _settings_accountTypes_type.push,
+        settings == null ? void 0 : (_settings_account = settings.account) == null ? void 0 : (_settings_account_category = _settings_account[category]) == null ? void 0 : _settings_account_category.push
+    ]){
+        if (typeof answer === 'boolean') return answer;
+    }
+    for (const answer of [
+        settings == null ? void 0 : (_settings_accountTypes1 = settings.accountTypes) == null ? void 0 : (_settings_accountTypes_type1 = _settings_accountTypes1[type]) == null ? void 0 : _settings_accountTypes_type1.console,
+        settings == null ? void 0 : (_settings_account1 = settings.account) == null ? void 0 : (_settings_account_category1 = _settings_account1[category]) == null ? void 0 : _settings_account_category1.console
+    ]){
+        if (typeof answer === 'boolean') return answer;
+    }
+    if ((legacyPrefs == null ? void 0 : legacyPrefs[category]) === false) return false;
+    return consoleDefault;
+}
+
+//# sourceMappingURL=mobile-push.js.map

package/src/lib/app-utils/mobile-push.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/mobile-push.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 mobile push channel's shapes (AGL-3620, AGL-3651), for the server\n * fan-out and the native apps alike.\n *\n * NO IMPORTS, not even types, on purpose: the native apps compile this file\n * with their own compiler, and a type import would drag the core's whole\n * type graph into it. The full per-scope resolution lives in\n * `notification-push.ts`, which the server reads; the app needs only the\n * account scope its settings screen edits, `accountPushSwitch` below, which\n * a spec holds to the full resolver.\n */\n\n/** `users/{uid}/devices/{installId}`: one row per app install, written by its owner. */\nexport const MOBILE_DEVICES_COLLECTION = 'devices'\n\nexport type MobileDevicePlatform = 'ios' | 'android' | 'macos'\n\n/** The two native apps (bundle `com.aglyn.app` and `com.aglyn.pos`). */\nexport type MobileDeviceApp = 'aglyn' | 'aglyn-pos'\n\n/** Each app's bundle id: the APNs topic its pushes are addressed to. */\nexport const MOBILE_APP_BUNDLES: Readonly<Record<MobileDeviceApp, string>> = {\n  aglyn: 'com.aglyn.app',\n  'aglyn-pos': 'com.aglyn.pos',\n}\n\n/** How a device is reached: Apple's APNs (iOS, macOS) or Google's FCM (Android). */\nexport type MobilePushTransport = 'apns' | 'fcm'\n\n/** The APNs environment a device token was minted in; a token only works in its own. */\nexport type ApnsEnvironment = 'sandbox' | 'production'\n\nexport interface MobileDevice {\n  /** An APNs device token (hex) or an FCM registration token, per `transport`. */\n  token: string\n  transport: MobilePushTransport\n  /** APNs only: which gateway the token belongs to. */\n  apnsEnvironment?: ApnsEnvironment\n  platform: MobileDevicePlatform\n  app: MobileDeviceApp\n  appVersion?: string\n  /** Server time of the app's last launch while signed in. */\n  lastSeen?: unknown\n}\n\n/** A device not seen for this long is not pushed to (and is pruned by the fan-out). */\nexport const MOBILE_DEVICE_STALE_MS = 60 * 24 * 60 * 60 * 1000\n\n/** The most devices one person's push fan-out reads. */\nexport const MOBILE_DEVICES_PER_USER = 20\n\nconst HEX = /^[0-9A-Fa-f]+$/\nconst FCM_TOKEN = /^[A-Za-z0-9_:-]+$/\n\n/** An APNs device token: hex, 64 to 200 characters (the Firestore rules hold the same). */\nexport function isApnsDeviceToken(value: unknown): value is string {\n  return typeof value === 'string' && value.length >= 64 && value.length <= 200 && HEX.test(value)\n}\n\n/** An FCM registration token: `[A-Za-z0-9_:-]`, 100 to 4096 characters (the rules hold the same). */\nexport function isFcmRegistrationToken(value: unknown): value is string {\n  return typeof value === 'string' && value.length >= 100 && value.length <= 4096 && FCM_TOKEN.test(value)\n}\n\n/** Whether `token` is a token of `transport`'s shape. */\nexport function isMobilePushToken(transport: unknown, token: unknown): boolean {\n  if (transport === 'apns') return isApnsDeviceToken(token)\n  if (transport === 'fcm') return isFcmRegistrationToken(token)\n  return false\n}\n\n/**\n * What a push carries for the app to act on when it is tapped. The app\n * resolves `link` the way it resolves a feed row: natively when a plugin\n * registered a deep link for it, else in the console WebView.\n */\nexport interface MobilePushData {\n  type: string\n  link?: string\n  orgId?: string\n  hostId?: string\n}\n\nexport function mobilePushData(payload: {\n  type: string\n  link?: string | null\n  orgId?: string | null\n  hostId?: string | null\n}): MobilePushData {\n  return {\n    type: payload.type,\n    ...(payload.link ? { link: payload.link } : {}),\n    ...(payload.orgId ? { orgId: payload.orgId } : {}),\n    ...(payload.hostId ? { hostId: payload.hostId } : {}),\n  }\n}\n\n/** Read a tapped push's data back, refusing anything that is not ours. */\nexport function readMobilePushData(data: unknown): MobilePushData | null {\n  if (!data || typeof data !== 'object') return null\n  const record = data as Record<string, unknown>\n  if (typeof record['type'] !== 'string' || !record['type']) return null\n  const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined)\n  const link = text(record['link'])\n  return mobilePushData({\n    type: record['type'],\n    // Only a console path or an https URL; never a scheme the app would hand to the OS.\n    link: link && (link.startsWith('/') || link.startsWith('https://')) ? link : undefined,\n    orgId: text(record['orgId']),\n    hostId: text(record['hostId']),\n  })\n}\n\ntype ChannelAnswers = { console?: boolean; push?: boolean } | undefined\n\n/** The account-scope slice of `NotificationSettings` the app's switch reads. */\nexport interface AccountPushSettings {\n  account?: Record<string, ChannelAnswers>\n  accountTypes?: Record<string, ChannelAnswers>\n}\n\n/**\n * What the app's per-type push switch shows: the account's push answer for\n * the type, then for its category, and otherwise what the console feed does\n * for it at the account scope (its console answers, the legacy category\n * mute, then `consoleDefault`, the type's console default from the catalog).\n * Equal to `notificationPushEnabled` with no scope; a spec holds the two\n * together.\n */\nexport function accountPushSwitch(\n  settings: AccountPushSettings | null | undefined,\n  type: string,\n  category: string,\n  consoleDefault: boolean,\n  legacyPrefs?: Record<string, boolean> | null,\n): boolean {\n  for (const answer of [settings?.accountTypes?.[type]?.push, settings?.account?.[category]?.push]) {\n    if (typeof answer === 'boolean') return answer\n  }\n  for (const answer of [settings?.accountTypes?.[type]?.console, settings?.account?.[category]?.console]) {\n    if (typeof answer === 'boolean') return answer\n  }\n  if (legacyPrefs?.[category] === false) return false\n  return consoleDefault\n}\n"],"names":["MOBILE_DEVICES_COLLECTION","MOBILE_APP_BUNDLES","aglyn","MOBILE_DEVICE_STALE_MS","MOBILE_DEVICES_PER_USER","HEX","FCM_TOKEN","isApnsDeviceToken","value","length","test","isFcmRegistrationToken","isMobilePushToken","transport","token","mobilePushData","payload","type","link","orgId","hostId","readMobilePushData","data","record","text","undefined","startsWith","accountPushSwitch","settings","category","consoleDefault","legacyPrefs","answer","accountTypes","push","account","console"],"mappings":"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"}