@aglyn/tenant-feature-instance 1.0.0-beta.143

package/src/lib/hooks/use-live-artifact-count.js

@@ -0,0 +1,102 @@
+/**
+ * @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.
+ */ 'use client';
+import { Timestamp } from "@aglyn/shared-util-timestamp";
+import { collection, getCountFromServer, query, where } from "firebase/firestore";
+import { useEffect, useState } from "react";
+import { useFirestore } from "./firebase/firebase-services.js";
+/**
+ * Every timestamp is greater than this one, and no `null` is.
+ *
+ * Firestore orders values by TYPE before value, and `null` sorts below every
+ * number, string and timestamp — so an inequality against the epoch selects
+ * exactly the documents whose `deletedAt` holds a real timestamp. Documents
+ * with no `deletedAt` field are excluded from an inequality outright, which
+ * is the other half of the same answer.
+ *
+ * Built where it is used rather than at module scope. This module is reached
+ * through the library's barrel, so a `Timestamp` call up here runs for every
+ * consumer of every hook in it — including the many that stand a stub in for
+ * `@aglyn/shared-util-timestamp` and never touch this one.
+ */ const beforeEveryTombstone = ()=>Timestamp.fromMillis(0);
+/**
+ * How many artifacts of a kind a site actually holds — a server aggregate,
+ * not the length of a page (AGL-1716, the AGL-1706 shape).
+ *
+ * A list that pages holds ten rows. Handing that ten to a quota readout is a
+ * confident wrong number in the flattering direction: "10/10 layouts on your
+ * plan" on a site with sixty of them reads as room to spare, right up until
+ * `/api/hosts/resources` refuses the create. The list and the count are
+ * different questions and are asked separately — one aggregate per mount,
+ * re-asked when `epoch` moves.
+ *
+ * ## Why two aggregates rather than one
+ *
+ * Deleting an artifact stamps `deletedAt` and leaves the document in place,
+ * so a published tenant page keeps grafting until its next revalidate. The
+ * enforcing route counts the LIVE ones — `/api/hosts/resources` reads the
+ * collection with a `deletedAt` projection and keeps the entries where it is
+ * `== null` — so a console count over the whole collection would quote a cap
+ * usage the server does not enforce, and would disagree with the list beside
+ * it row for row.
+ *
+ * Firestore cannot express "field is absent" as a predicate, and the two live
+ * shapes are not one value: an artifact created through the resources route
+ * carries no `deletedAt` at all, while one installed from the marketplace
+ * carries an explicit `deletedAt: null` (`install.ts` writes it). So
+ * `where('deletedAt', '==', null)` would return the marketplace copies alone.
+ * Counting the TOMBSTONES instead is exact, because there is only one shape
+ * of tombstone — a `Timestamp` — and subtracting them from the total leaves
+ * precisely the documents the server calls live.
+ *
+ * Both aggregates bill one document read each at these collection sizes.
+ *
+ * @returns the live count, or `null` while it is pending or if it was
+ * refused. A caller must fall back to something that can only UNDERSTATE the
+ * truth, never to `0`: an entitlement check answers from whatever it is
+ * handed, and zero used is the one wrong answer that opens a gate.
+ */ export function useLiveArtifactCount(hostId, artifact, epoch = 0) {
+    const firestore = useFirestore();
+    const [count, setCount] = useState(null);
+    useEffect(()=>{
+        let active = true;
+        const artifacts = collection(firestore, 'hosts', hostId, artifact);
+        void Promise.all([
+            getCountFromServer(artifacts),
+            getCountFromServer(query(artifacts, where('deletedAt', '>', beforeEveryTombstone())))
+        ]).then(([total, tombstones])=>{
+            if (!active) return;
+            // Never below zero: the two aggregates are separate round-trips and a
+            // delete landing between them can make the second the larger read.
+            setCount(Math.max(0, total.data().count - tombstones.data().count));
+        }).catch(()=>{
+        // The caller's fallback stands. Deliberately not 0 — see the return
+        // contract above.
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        firestore,
+        hostId,
+        artifact,
+        epoch
+    ]);
+    return count;
+}
+export default useLiveArtifactCount;
+
+//# sourceMappingURL=use-live-artifact-count.js.map

package/src/lib/hooks/use-live-artifact-count.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-live-artifact-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'use client'\n\nimport { Timestamp } from '@aglyn/shared-util-timestamp'\nimport { collection, getCountFromServer, query, where } from 'firebase/firestore'\nimport { useEffect, useState } from 'react'\nimport { useFirestore } from './firebase/firebase-services'\n\n/**\n * The per-site artifact collections that render as a console list.\n *\n * `forms` is one of them: it is created through the same resources route,\n * keyed by the same generated uid, and listed by the same table. Its cap is\n * enforced over the WHOLE collection rather than over live documents — a form\n * is deleted outright, and its submissions keep their `formId` either way —\n * so the aggregate below matches what `/api/hosts/resources` counts, with the\n * tombstone subtraction a no-op because nothing writes `deletedAt` on a form.\n */\nexport type HostArtifactCollection =\n  | 'screens'\n  | 'layouts'\n  | 'components'\n  | 'templates'\n  | 'forms'\n\n/**\n * Every timestamp is greater than this one, and no `null` is.\n *\n * Firestore orders values by TYPE before value, and `null` sorts below every\n * number, string and timestamp — so an inequality against the epoch selects\n * exactly the documents whose `deletedAt` holds a real timestamp. Documents\n * with no `deletedAt` field are excluded from an inequality outright, which\n * is the other half of the same answer.\n *\n * Built where it is used rather than at module scope. This module is reached\n * through the library's barrel, so a `Timestamp` call up here runs for every\n * consumer of every hook in it — including the many that stand a stub in for\n * `@aglyn/shared-util-timestamp` and never touch this one.\n */\nconst beforeEveryTombstone = () => Timestamp.fromMillis(0)\n\n/**\n * How many artifacts of a kind a site actually holds — a server aggregate,\n * not the length of a page (AGL-1716, the AGL-1706 shape).\n *\n * A list that pages holds ten rows. Handing that ten to a quota readout is a\n * confident wrong number in the flattering direction: \"10/10 layouts on your\n * plan\" on a site with sixty of them reads as room to spare, right up until\n * `/api/hosts/resources` refuses the create. The list and the count are\n * different questions and are asked separately — one aggregate per mount,\n * re-asked when `epoch` moves.\n *\n * ## Why two aggregates rather than one\n *\n * Deleting an artifact stamps `deletedAt` and leaves the document in place,\n * so a published tenant page keeps grafting until its next revalidate. The\n * enforcing route counts the LIVE ones — `/api/hosts/resources` reads the\n * collection with a `deletedAt` projection and keeps the entries where it is\n * `== null` — so a console count over the whole collection would quote a cap\n * usage the server does not enforce, and would disagree with the list beside\n * it row for row.\n *\n * Firestore cannot express \"field is absent\" as a predicate, and the two live\n * shapes are not one value: an artifact created through the resources route\n * carries no `deletedAt` at all, while one installed from the marketplace\n * carries an explicit `deletedAt: null` (`install.ts` writes it). So\n * `where('deletedAt', '==', null)` would return the marketplace copies alone.\n * Counting the TOMBSTONES instead is exact, because there is only one shape\n * of tombstone — a `Timestamp` — and subtracting them from the total leaves\n * precisely the documents the server calls live.\n *\n * Both aggregates bill one document read each at these collection sizes.\n *\n * @returns the live count, or `null` while it is pending or if it was\n * refused. A caller must fall back to something that can only UNDERSTATE the\n * truth, never to `0`: an entitlement check answers from whatever it is\n * handed, and zero used is the one wrong answer that opens a gate.\n */\nexport function useLiveArtifactCount(\n  hostId: string,\n  artifact: HostArtifactCollection,\n  epoch = 0,\n): number | null {\n  const firestore = useFirestore()\n  const [count, setCount] = useState<number | null>(null)\n\n  useEffect(() => {\n    let active = true\n    const artifacts = collection(firestore, 'hosts', hostId, artifact)\n    void Promise.all([\n      getCountFromServer(artifacts),\n      getCountFromServer(\n        query(artifacts, where('deletedAt', '>', beforeEveryTombstone())),\n      ),\n    ])\n      .then(([total, tombstones]) => {\n        if (!active) return\n        // Never below zero: the two aggregates are separate round-trips and a\n        // delete landing between them can make the second the larger read.\n        setCount(\n          Math.max(0, total.data().count - tombstones.data().count),\n        )\n      })\n      .catch(() => {\n        // The caller's fallback stands. Deliberately not 0 — see the return\n        // contract above.\n      })\n    return () => {\n      active = false\n    }\n  }, [firestore, hostId, artifact, epoch])\n\n  return count\n}\n\nexport default useLiveArtifactCount\n"],"names":["Timestamp","collection","getCountFromServer","query","where","useEffect","useState","useFirestore","beforeEveryTombstone","fromMillis","useLiveArtifactCount","hostId","artifact","epoch","firestore","count","setCount","active","artifacts","Promise","all","then","total","tombstones","Math","max","data","catch"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,SAAS,QAAQ,+BAA8B;AACxD,SAASC,UAAU,EAAEC,kBAAkB,EAAEC,KAAK,EAAEC,KAAK,QAAQ,qBAAoB;AACjF,SAASC,SAAS,EAAEC,QAAQ,QAAQ,QAAO;AAC3C,SAASC,YAAY,QAAQ,kCAA8B;AAmB3D;;;;;;;;;;;;;CAaC,GACD,MAAMC,uBAAuB,IAAMR,UAAUS,UAAU,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GACD,OAAO,SAASC,qBACdC,MAAc,EACdC,QAAgC,EAChCC,QAAQ,CAAC;IAET,MAAMC,YAAYP;IAClB,MAAM,CAACQ,OAAOC,SAAS,GAAGV,SAAwB;IAElDD,UAAU;QACR,IAAIY,SAAS;QACb,MAAMC,YAAYjB,WAAWa,WAAW,SAASH,QAAQC;QACzD,KAAKO,QAAQC,GAAG,CAAC;YACflB,mBAAmBgB;YACnBhB,mBACEC,MAAMe,WAAWd,MAAM,aAAa,KAAKI;SAE5C,EACEa,IAAI,CAAC,CAAC,CAACC,OAAOC,WAAW;YACxB,IAAI,CAACN,QAAQ;YACb,sEAAsE;YACtE,mEAAmE;YACnED,SACEQ,KAAKC,GAAG,CAAC,GAAGH,MAAMI,IAAI,GAAGX,KAAK,GAAGQ,WAAWG,IAAI,GAAGX,KAAK;QAE5D,GACCY,KAAK,CAAC;QACL,oEAAoE;QACpE,kBAAkB;QACpB;QACF,OAAO;YACLV,SAAS;QACX;IACF,GAAG;QAACH;QAAWH;QAAQC;QAAUC;KAAM;IAEvC,OAAOE;AACT;AAEA,eAAeL,qBAAoB"}

package/src/lib/hooks/use-org-member-options.d.ts

@@ -0,0 +1,57 @@
+import type { AglynOrgMember } from '@aglyn/aglyn';
+/** One team member, as much of them as a picker needs. */
+export interface OrgMemberOption {
+    /** The account uid — what a record's `ownerUid` stores. */
+    uid: string;
+    /** The name a colleague recognizes: display name, else address, else uid. */
+    label: string;
+    email?: string;
+}
+export interface OrgMemberOptions {
+    options: OrgMemberOption[];
+    /** The read has answered, one way or the other — false while settling or disabled. */
+    ready: boolean;
+    /** Why the roster is empty, when it is empty because the route refused. */
+    error: string | null;
+}
+/**
+ * The roster as picker options, sorted by how they read.
+ *
+ * Exported on its own so the mapping has one definition: a bulk "set owner"
+ * on the contacts list and an audience rule's owner filter must show the
+ * same names for the same people, or a merchant assigning contacts to "Ada"
+ * on one screen would be filtering for "ada@example.com" on the other.
+ */
+export declare function orgMemberOptions(members: ReadonlyArray<Partial<AglynOrgMember> & {
+    $id: string;
+}>): OrgMemberOption[];
+/**
+ * THE ORG'S TEAM, for an owner picker on some record's page (AGL-2603).
+ *
+ * ## Through the members route, not the collection
+ *
+ * `orgs/{orgId}/members` is readable by an org-wide member and by nobody
+ * else: the rules evaluate a list against the QUERY, so a collaborator scoped
+ * to one site reading the roster gets `permission-denied`, not a shorter
+ * roster. `GET /api/orgs/members?orgId=` re-derives membership with the Admin
+ * SDK and answers any member of the org, which is who assigns an owner.
+ *
+ * ## It is OFF unless a caller asks
+ *
+ * `enabled` defaults to false, the way `useHostCampaigns` does and for the
+ * same reason: the picker this feeds sits on surfaces a reader opens for
+ * something else, and a roster fetched on every arrival at the contacts list
+ * is a request for a control nobody has opened. Callers turn it on when the
+ * owner control is actually on screen.
+ *
+ * ## A refusal is reported, never rendered as an empty team
+ *
+ * An org with no members is impossible — it has an owner — so an empty list
+ * with no error would always be a lie. `authorizedFetch` refuses to send a
+ * request it cannot authorize and answers a 401 carrying the reason; that
+ * reason, or the route's own, is what `error` holds.
+ */
+export declare function useOrgMemberOptions(orgId: string | undefined, options?: {
+    enabled?: boolean;
+}): OrgMemberOptions;
+export default useOrgMemberOptions;

package/src/lib/hooks/use-org-member-options.js

@@ -0,0 +1,112 @@
+/**
+ * @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.
+ */ 'use client';
+import { authorizedFetch } from "@aglyn/shared-util-http/authorized-token";
+import { useEffect, useMemo, useState } from "react";
+import { useUser } from "./firebase/firebase-services.js";
+/**
+ * The roster as picker options, sorted by how they read.
+ *
+ * Exported on its own so the mapping has one definition: a bulk "set owner"
+ * on the contacts list and an audience rule's owner filter must show the
+ * same names for the same people, or a merchant assigning contacts to "Ada"
+ * on one screen would be filtering for "ada@example.com" on the other.
+ */ export function orgMemberOptions(members) {
+    return members.map((member)=>({
+            uid: String(member.$id),
+            label: String(member.displayName || member.email || member.$id),
+            email: member.email ? String(member.email) : undefined
+        })).sort((a, b)=>a.label.localeCompare(b.label));
+}
+/**
+ * THE ORG'S TEAM, for an owner picker on some record's page (AGL-2603).
+ *
+ * ## Through the members route, not the collection
+ *
+ * `orgs/{orgId}/members` is readable by an org-wide member and by nobody
+ * else: the rules evaluate a list against the QUERY, so a collaborator scoped
+ * to one site reading the roster gets `permission-denied`, not a shorter
+ * roster. `GET /api/orgs/members?orgId=` re-derives membership with the Admin
+ * SDK and answers any member of the org, which is who assigns an owner.
+ *
+ * ## It is OFF unless a caller asks
+ *
+ * `enabled` defaults to false, the way `useHostCampaigns` does and for the
+ * same reason: the picker this feeds sits on surfaces a reader opens for
+ * something else, and a roster fetched on every arrival at the contacts list
+ * is a request for a control nobody has opened. Callers turn it on when the
+ * owner control is actually on screen.
+ *
+ * ## A refusal is reported, never rendered as an empty team
+ *
+ * An org with no members is impossible — it has an owner — so an empty list
+ * with no error would always be a lie. `authorizedFetch` refuses to send a
+ * request it cannot authorize and answers a 401 carrying the reason; that
+ * reason, or the route's own, is what `error` holds.
+ */ export function useOrgMemberOptions(orgId, options) {
+    var _ref;
+    const enabled = (_ref = options == null ? void 0 : options.enabled) != null ? _ref : false;
+    const { data: user } = useUser();
+    const [state, setState] = useState({
+        orgId: null,
+        members: [],
+        error: null
+    });
+    useEffect(()=>{
+        if (!enabled || !orgId) return;
+        let active = true;
+        void (async ()=>{
+            let members = [];
+            let error = null;
+            try {
+                const response = await authorizedFetch(user, `/api/orgs/members?orgId=${encodeURIComponent(orgId)}`);
+                const payload = await response.json().catch(()=>({}));
+                if (!response.ok) {
+                    var _ref;
+                    error = String((_ref = payload == null ? void 0 : payload.error) != null ? _ref : 'The team could not be read.');
+                } else {
+                    members = orgMemberOptions(Array.isArray(payload == null ? void 0 : payload.members) ? payload.members : []);
+                }
+            } catch (unused) {
+                error = 'The team could not be read.';
+            }
+            if (active) setState({
+                orgId,
+                members,
+                error
+            });
+        })();
+        return ()=>{
+            active = false;
+        };
+    }, [
+        enabled,
+        orgId,
+        user
+    ]);
+    return useMemo(()=>({
+            options: state.orgId === orgId ? state.members : [],
+            ready: enabled && Boolean(orgId) && state.orgId === orgId,
+            error: state.orgId === orgId ? state.error : null
+        }), [
+        state,
+        orgId,
+        enabled
+    ]);
+}
+export default useOrgMemberOptions;
+
+//# sourceMappingURL=use-org-member-options.js.map

package/src/lib/hooks/use-org-member-options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-org-member-options.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'use client'\n\nimport type { AglynOrgMember } from '@aglyn/aglyn'\nimport { authorizedFetch } from '@aglyn/shared-util-http/authorized-token'\nimport { useEffect, useMemo, useState } from 'react'\nimport { useUser } from './firebase/firebase-services'\n\n/** One team member, as much of them as a picker needs. */\nexport interface OrgMemberOption {\n  /** The account uid — what a record's `ownerUid` stores. */\n  uid: string\n  /** The name a colleague recognizes: display name, else address, else uid. */\n  label: string\n  email?: string\n}\n\nexport interface OrgMemberOptions {\n  options: OrgMemberOption[]\n  /** The read has answered, one way or the other — false while settling or disabled. */\n  ready: boolean\n  /** Why the roster is empty, when it is empty because the route refused. */\n  error: string | null\n}\n\n/**\n * The roster as picker options, sorted by how they read.\n *\n * Exported on its own so the mapping has one definition: a bulk \"set owner\"\n * on the contacts list and an audience rule's owner filter must show the\n * same names for the same people, or a merchant assigning contacts to \"Ada\"\n * on one screen would be filtering for \"ada@example.com\" on the other.\n */\nexport function orgMemberOptions(\n  members: ReadonlyArray<Partial<AglynOrgMember> & { $id: string }>,\n): OrgMemberOption[] {\n  return members\n    .map((member) => ({\n      uid: String(member.$id),\n      label: String(member.displayName || member.email || member.$id),\n      email: member.email ? String(member.email) : undefined,\n    }))\n    .sort((a, b) => a.label.localeCompare(b.label))\n}\n\n/**\n * THE ORG'S TEAM, for an owner picker on some record's page (AGL-2603).\n *\n * ## Through the members route, not the collection\n *\n * `orgs/{orgId}/members` is readable by an org-wide member and by nobody\n * else: the rules evaluate a list against the QUERY, so a collaborator scoped\n * to one site reading the roster gets `permission-denied`, not a shorter\n * roster. `GET /api/orgs/members?orgId=` re-derives membership with the Admin\n * SDK and answers any member of the org, which is who assigns an owner.\n *\n * ## It is OFF unless a caller asks\n *\n * `enabled` defaults to false, the way `useHostCampaigns` does and for the\n * same reason: the picker this feeds sits on surfaces a reader opens for\n * something else, and a roster fetched on every arrival at the contacts list\n * is a request for a control nobody has opened. Callers turn it on when the\n * owner control is actually on screen.\n *\n * ## A refusal is reported, never rendered as an empty team\n *\n * An org with no members is impossible — it has an owner — so an empty list\n * with no error would always be a lie. `authorizedFetch` refuses to send a\n * request it cannot authorize and answers a 401 carrying the reason; that\n * reason, or the route's own, is what `error` holds.\n */\nexport function useOrgMemberOptions(\n  orgId: string | undefined,\n  options?: { enabled?: boolean },\n): OrgMemberOptions {\n  const enabled = options?.enabled ?? false\n  const { data: user } = useUser()\n  const [state, setState] = useState<{\n    orgId: string | null\n    members: OrgMemberOption[]\n    error: string | null\n  }>({ orgId: null, members: [], error: null })\n\n  useEffect(() => {\n    if (!enabled || !orgId) return\n    let active = true\n    void (async () => {\n      let members: OrgMemberOption[] = []\n      let error: string | null = null\n      try {\n        const response = await authorizedFetch(\n          user,\n          `/api/orgs/members?orgId=${encodeURIComponent(orgId)}`,\n        )\n        const payload = await response.json().catch(() => ({}))\n        if (!response.ok) {\n          error = String(payload?.error ?? 'The team could not be read.')\n        } else {\n          members = orgMemberOptions(\n            Array.isArray(payload?.members) ? payload.members : [],\n          )\n        }\n      } catch {\n        error = 'The team could not be read.'\n      }\n      if (active) setState({ orgId, members, error })\n    })()\n    return () => {\n      active = false\n    }\n  }, [enabled, orgId, user])\n\n  return useMemo(\n    () => ({\n      options: state.orgId === orgId ? state.members : [],\n      ready: enabled && Boolean(orgId) && state.orgId === orgId,\n      error: state.orgId === orgId ? state.error : null,\n    }),\n    [state, orgId, enabled],\n  )\n}\n\nexport default useOrgMemberOptions\n"],"names":["authorizedFetch","useEffect","useMemo","useState","useUser","orgMemberOptions","members","map","member","uid","String","$id","label","displayName","email","undefined","sort","a","b","localeCompare","useOrgMemberOptions","orgId","options","enabled","data","user","state","setState","error","active","response","encodeURIComponent","payload","json","catch","ok","Array","isArray","ready","Boolean"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAGA,SAASA,eAAe,QAAQ,2CAA0C;AAC1E,SAASC,SAAS,EAAEC,OAAO,EAAEC,QAAQ,QAAQ,QAAO;AACpD,SAASC,OAAO,QAAQ,kCAA8B;AAmBtD;;;;;;;CAOC,GACD,OAAO,SAASC,iBACdC,OAAiE;IAEjE,OAAOA,QACJC,GAAG,CAAC,CAACC,SAAY,CAAA;YAChBC,KAAKC,OAAOF,OAAOG,GAAG;YACtBC,OAAOF,OAAOF,OAAOK,WAAW,IAAIL,OAAOM,KAAK,IAAIN,OAAOG,GAAG;YAC9DG,OAAON,OAAOM,KAAK,GAAGJ,OAAOF,OAAOM,KAAK,IAAIC;QAC/C,CAAA,GACCC,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEL,KAAK,CAACO,aAAa,CAACD,EAAEN,KAAK;AACjD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,SAASQ,oBACdC,KAAyB,EACzBC,OAA+B;;IAE/B,MAAMC,kBAAUD,2BAAAA,QAASC,OAAO,mBAAI;IACpC,MAAM,EAAEC,MAAMC,IAAI,EAAE,GAAGrB;IACvB,MAAM,CAACsB,OAAOC,SAAS,GAAGxB,SAIvB;QAAEkB,OAAO;QAAMf,SAAS,EAAE;QAAEsB,OAAO;IAAK;IAE3C3B,UAAU;QACR,IAAI,CAACsB,WAAW,CAACF,OAAO;QACxB,IAAIQ,SAAS;QACb,KAAK,AAAC,CAAA;YACJ,IAAIvB,UAA6B,EAAE;YACnC,IAAIsB,QAAuB;YAC3B,IAAI;gBACF,MAAME,WAAW,MAAM9B,gBACrByB,MACA,CAAC,wBAAwB,EAAEM,mBAAmBV,QAAQ;gBAExD,MAAMW,UAAU,MAAMF,SAASG,IAAI,GAAGC,KAAK,CAAC,IAAO,CAAA,CAAC,CAAA;gBACpD,IAAI,CAACJ,SAASK,EAAE,EAAE;;oBAChBP,QAAQlB,eAAOsB,2BAAAA,QAASJ,KAAK,mBAAI;gBACnC,OAAO;oBACLtB,UAAUD,iBACR+B,MAAMC,OAAO,CAACL,2BAAAA,QAAS1B,OAAO,IAAI0B,QAAQ1B,OAAO,GAAG,EAAE;gBAE1D;YACF,EAAE,eAAM;gBACNsB,QAAQ;YACV;YACA,IAAIC,QAAQF,SAAS;gBAAEN;gBAAOf;gBAASsB;YAAM;QAC/C,CAAA;QACA,OAAO;YACLC,SAAS;QACX;IACF,GAAG;QAACN;QAASF;QAAOI;KAAK;IAEzB,OAAOvB,QACL,IAAO,CAAA;YACLoB,SAASI,MAAML,KAAK,KAAKA,QAAQK,MAAMpB,OAAO,GAAG,EAAE;YACnDgC,OAAOf,WAAWgB,QAAQlB,UAAUK,MAAML,KAAK,KAAKA;YACpDO,OAAOF,MAAML,KAAK,KAAKA,QAAQK,MAAME,KAAK,GAAG;QAC/C,CAAA,GACA;QAACF;QAAOL;QAAOE;KAAQ;AAE3B;AAEA,eAAeH,oBAAmB"}

package/src/lib/hooks/use-org-plan.d.ts

@@ -0,0 +1,46 @@
+export interface OrgPlanState {
+    /** The owning org's doc, once it has arrived. */
+    org: Record<string, unknown> | undefined;
+    /**
+     * Whether `org` is trustworthy. FALSE means the answer is still in
+     * flight — hold rather than resolve entitlements, because an absent org
+     * is indistinguishable from the free tier to every `Aglyn.checkQuota` /
+     * `checkEntitlement` call.
+     */
+    ready: boolean;
+}
+/**
+ * A host's owning org doc, for plan quotas and entitlements, with an honest
+ * `ready` flag (AGL-1064).
+ *
+ * This existed as a copy-pasted pair in five commerce console cards:
+ *
+ * ```ts
+ * const orgId = useHostOrgId(hostId)
+ * const { data: org } = useFirestoreDoc(
+ *   () => doc(firestore, 'orgs', orgId ?? '-pending-'), [firestore, orgId])
+ * const quota = Aglyn.checkQuota(org, 'posRegisters', registers.length)
+ * ```
+ *
+ * `useHostOrgId` returns null while the `hostIndex` lookup is in flight, so
+ * `org` is undefined for the first render or two of every mount — and
+ * `checkQuota(undefined, …)` does not mean "unknown", it resolves the FREE
+ * tier (`posRegisters: 0`, `productsPerHost: 0`, `inventoryLocations: 1`).
+ * A paying customer clicking Add inside that window was told their plan does
+ * not include what they bought.
+ *
+ * Same defect shape as {@link useOrgDataScope} (AGL-1061) and
+ * `useScopeTokens` (AGL-1047): a hook handing out a resolved-looking value
+ * before it has resolved. Callers gate their controls on `ready` rather than
+ * letting an absent org answer a billing question.
+ *
+ * The `'-pending-'` sentinel goes with it. Addressing `orgs/-pending-` was a
+ * guaranteed-denied read on every mount; this holds the ref at null instead,
+ * so no query is issued until there is a real org to ask about.
+ *
+ * Not to be confused with the console's `useOrgPlans` (plural), which reads
+ * the plan of every org the user belongs to for the switcher. This one is
+ * the single owning org of a HOST.
+ */
+export declare function useOrgPlan(hostId: string | undefined): OrgPlanState;
+export default useOrgPlan;

package/src/lib/hooks/use-org-plan.js

@@ -0,0 +1,86 @@
+/**
+ * @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.
+ */ 'use client';
+import { doc } from "firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "./firebase/firebase-services.js";
+import { useFirestoreDoc } from "./use-firestore-doc.js";
+import { useHostOrgIdState } from "./use-host-org-id.js";
+/**
+ * A host's owning org doc, for plan quotas and entitlements, with an honest
+ * `ready` flag (AGL-1064).
+ *
+ * This existed as a copy-pasted pair in five commerce console cards:
+ *
+ * ```ts
+ * const orgId = useHostOrgId(hostId)
+ * const { data: org } = useFirestoreDoc(
+ *   () => doc(firestore, 'orgs', orgId ?? '-pending-'), [firestore, orgId])
+ * const quota = Aglyn.checkQuota(org, 'posRegisters', registers.length)
+ * ```
+ *
+ * `useHostOrgId` returns null while the `hostIndex` lookup is in flight, so
+ * `org` is undefined for the first render or two of every mount — and
+ * `checkQuota(undefined, …)` does not mean "unknown", it resolves the FREE
+ * tier (`posRegisters: 0`, `productsPerHost: 0`, `inventoryLocations: 1`).
+ * A paying customer clicking Add inside that window was told their plan does
+ * not include what they bought.
+ *
+ * Same defect shape as {@link useOrgDataScope} (AGL-1061) and
+ * `useScopeTokens` (AGL-1047): a hook handing out a resolved-looking value
+ * before it has resolved. Callers gate their controls on `ready` rather than
+ * letting an absent org answer a billing question.
+ *
+ * The `'-pending-'` sentinel goes with it. Addressing `orgs/-pending-` was a
+ * guaranteed-denied read on every mount; this holds the ref at null instead,
+ * so no query is issued until there is a real org to ask about.
+ *
+ * Not to be confused with the console's `useOrgPlans` (plural), which reads
+ * the plan of every org the user belongs to for the switcher. This one is
+ * the single owning org of a HOST.
+ */ export function useOrgPlan(hostId) {
+    const firestore = useFirestore();
+    const { orgId, loaded } = useHostOrgIdState(hostId);
+    const { data: org, status } = useFirestoreDoc(()=>orgId ? doc(firestore, 'orgs', orgId) : null, [
+        firestore,
+        orgId
+    ]);
+    return useMemo(()=>({
+            org,
+            // A host with no owning org is SETTLED, not pending — there is no
+            // org doc coming, and holding forever would leave the card
+            // permanently disabled. `status` only moves off 'loading' once a
+            // ref exists, so it cannot answer that case.
+            //
+            // `'success'` and not `!== 'loading'` (AGL-1066). A refused listen can
+            // now reach `'error'`, and `'error'` satisfies `!== 'loading'` while
+            // leaving `org` undefined — so this hook would have handed out
+            // `ready: true` with no org, and `checkQuota(undefined, …)` does not
+            // mean "unknown", it resolves the FREE tier. That is the exact fault
+            // this hook was written to close, arriving through a different door:
+            // a paying org rendered as Free for as long as its session stayed
+            // stale. Pending is the right answer to a question we cannot read.
+            ready: loaded && (!orgId || status === 'success')
+        }), [
+        org,
+        loaded,
+        orgId,
+        status
+    ]);
+}
+export default useOrgPlan;
+
+//# sourceMappingURL=use-org-plan.js.map

package/src/lib/hooks/use-org-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-org-plan.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'use client'\n\nimport { doc } from 'firebase/firestore'\nimport { useMemo } from 'react'\nimport { useFirestore } from './firebase/firebase-services'\nimport { useFirestoreDoc } from './use-firestore-doc'\nimport { useHostOrgIdState } from './use-host-org-id'\n\nexport interface OrgPlanState {\n  /** The owning org's doc, once it has arrived. */\n  org: Record<string, unknown> | undefined\n  /**\n   * Whether `org` is trustworthy. FALSE means the answer is still in\n   * flight — hold rather than resolve entitlements, because an absent org\n   * is indistinguishable from the free tier to every `Aglyn.checkQuota` /\n   * `checkEntitlement` call.\n   */\n  ready: boolean\n}\n\n/**\n * A host's owning org doc, for plan quotas and entitlements, with an honest\n * `ready` flag (AGL-1064).\n *\n * This existed as a copy-pasted pair in five commerce console cards:\n *\n * ```ts\n * const orgId = useHostOrgId(hostId)\n * const { data: org } = useFirestoreDoc(\n *   () => doc(firestore, 'orgs', orgId ?? '-pending-'), [firestore, orgId])\n * const quota = Aglyn.checkQuota(org, 'posRegisters', registers.length)\n * ```\n *\n * `useHostOrgId` returns null while the `hostIndex` lookup is in flight, so\n * `org` is undefined for the first render or two of every mount — and\n * `checkQuota(undefined, …)` does not mean \"unknown\", it resolves the FREE\n * tier (`posRegisters: 0`, `productsPerHost: 0`, `inventoryLocations: 1`).\n * A paying customer clicking Add inside that window was told their plan does\n * not include what they bought.\n *\n * Same defect shape as {@link useOrgDataScope} (AGL-1061) and\n * `useScopeTokens` (AGL-1047): a hook handing out a resolved-looking value\n * before it has resolved. Callers gate their controls on `ready` rather than\n * letting an absent org answer a billing question.\n *\n * The `'-pending-'` sentinel goes with it. Addressing `orgs/-pending-` was a\n * guaranteed-denied read on every mount; this holds the ref at null instead,\n * so no query is issued until there is a real org to ask about.\n *\n * Not to be confused with the console's `useOrgPlans` (plural), which reads\n * the plan of every org the user belongs to for the switcher. This one is\n * the single owning org of a HOST.\n */\nexport function useOrgPlan(hostId: string | undefined): OrgPlanState {\n  const firestore = useFirestore()\n  const { orgId, loaded } = useHostOrgIdState(hostId)\n  const { data: org, status } = useFirestoreDoc<Record<string, unknown>>(\n    () => (orgId ? doc(firestore, 'orgs', orgId) : null),\n    [firestore, orgId],\n  )\n  return useMemo(\n    () => ({\n      org,\n      // A host with no owning org is SETTLED, not pending — there is no\n      // org doc coming, and holding forever would leave the card\n      // permanently disabled. `status` only moves off 'loading' once a\n      // ref exists, so it cannot answer that case.\n      //\n      // `'success'` and not `!== 'loading'` (AGL-1066). A refused listen can\n      // now reach `'error'`, and `'error'` satisfies `!== 'loading'` while\n      // leaving `org` undefined — so this hook would have handed out\n      // `ready: true` with no org, and `checkQuota(undefined, …)` does not\n      // mean \"unknown\", it resolves the FREE tier. That is the exact fault\n      // this hook was written to close, arriving through a different door:\n      // a paying org rendered as Free for as long as its session stayed\n      // stale. Pending is the right answer to a question we cannot read.\n      ready: loaded && (!orgId || status === 'success'),\n    }),\n    [org, loaded, orgId, status],\n  )\n}\n\nexport default useOrgPlan\n"],"names":["doc","useMemo","useFirestore","useFirestoreDoc","useHostOrgIdState","useOrgPlan","hostId","firestore","orgId","loaded","data","org","status","ready"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,GAAG,QAAQ,qBAAoB;AACxC,SAASC,OAAO,QAAQ,QAAO;AAC/B,SAASC,YAAY,QAAQ,kCAA8B;AAC3D,SAASC,eAAe,QAAQ,yBAAqB;AACrD,SAASC,iBAAiB,QAAQ,uBAAmB;AAcrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,SAASC,WAAWC,MAA0B;IACnD,MAAMC,YAAYL;IAClB,MAAM,EAAEM,KAAK,EAAEC,MAAM,EAAE,GAAGL,kBAAkBE;IAC5C,MAAM,EAAEI,MAAMC,GAAG,EAAEC,MAAM,EAAE,GAAGT,gBAC5B,IAAOK,QAAQR,IAAIO,WAAW,QAAQC,SAAS,MAC/C;QAACD;QAAWC;KAAM;IAEpB,OAAOP,QACL,IAAO,CAAA;YACLU;YACA,kEAAkE;YAClE,2DAA2D;YAC3D,iEAAiE;YACjE,6CAA6C;YAC7C,EAAE;YACF,uEAAuE;YACvE,qEAAqE;YACrE,+DAA+D;YAC/D,qEAAqE;YACrE,qEAAqE;YACrE,qEAAqE;YACrE,kEAAkE;YAClE,mEAAmE;YACnEE,OAAOJ,UAAW,CAAA,CAACD,SAASI,WAAW,SAAQ;QACjD,CAAA,GACA;QAACD;QAAKF;QAAQD;QAAOI;KAAO;AAEhC;AAEA,eAAeP,WAAU"}

package/src/lib/hooks/use-paged-collection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 { DocumentData, Query } from 'firebase/firestore';
+import { type DependencyList } from 'react';
+import { type UseFirestoreCollectionOptions, type UseFirestoreCollectionResult } from './use-firestore-collection';
+export interface UsePagedCollectionOptions extends UseFirestoreCollectionOptions {
+    /**
+     * Rows per page. Defaults to the console-wide smallest option — a list
+     * that picks its own number is how five different ones appear, and on a
+     * query bounded by its page size the smallest page is the smallest bill.
+     */
+    pageSize?: number;
+}
+export interface UsePagedCollectionResult<T> extends UseFirestoreCollectionResult<T> {
+    /** The current page's rows. `data` holds the probe row; this never does. */
+    rows: T[];
+    /** A further page exists. A FACT from the probe row, not a guess. */
+    hasMore: boolean;
+    /** Zero-based, to match `ListPagination` and MUI. */
+    page: number;
+    setPage: (page: number) => void;
+    pageSize: number;
+    setPageSize: (pageSize: number) => void;
+}
+/**
+ * A paged window over a live collection, instead of a big read sliced small.
+ *
+ * ## The shape this replaces
+ *
+ * A card would listen with `limit(300)` and render `rows.slice(0, 50)`. That
+ * is wrong twice over. Two hundred and fifty documents are read, billed and
+ * discarded on every mount — and the rows past the slice are not merely
+ * wasted, they are UNREACHABLE, because nothing renders them and no control
+ * asks for more. A merchant with sixty gift cards sees fifty and no
+ * indication that ten more exist; past three hundred, a card issued this
+ * morning cannot be reached at all.
+ *
+ * Here the window IS the query, and it is expressed in PAGES so the same
+ * `ListPagination` footer serves this and a cursor feed. The listener is
+ * widened to cover every page up to the one being read, so paging BACK costs
+ * nothing — the rows are already in the snapshot — and paging forward costs
+ * one page more.
+ *
+ * ## Why the window covers page 0..n rather than page n alone
+ *
+ * This is a live `onSnapshot`, not a fetch. Firestore cursors need a document
+ * snapshot to resume from, which a listener that has never read page n - 1
+ * does not have. Widening the limit is what makes forward and backward
+ * symmetrical without a second read path, and the cost is bounded by how deep
+ * the reader actually goes — with the shared default of ten, page three is
+ * thirty-one documents, and most readers never leave page one.
+ *
+ * ## Why over-fetch by one
+ *
+ * `hasMore` has to be a fact. Comparing `length === limit` is wrong exactly
+ * when the count is an even multiple of the page size — the case that offers
+ * a "next page" leading nowhere, or hides one that leads somewhere. The probe
+ * row answers it outright and is never rendered.
+ *
+ * ## Why the window resets on `deps`
+ *
+ * `deps` identify the SUBJECT being listened to. Without the reset, a card
+ * paged three deep on one site opens the next site three pages in — a read
+ * the reader never asked for, charged to whoever they switched to.
+ *
+ * `buildQuery` receives the limit to apply, so the caller keeps ownership of
+ * ordering and predicates:
+ *
+ * ```ts
+ * usePagedCollection<Card>(
+ *   (pageLimit) =>
+ *     hostId
+ *       ? query(collection(firestore, 'hosts', hostId, 'giftCards'),
+ *               orderBy('createdAt', 'desc'), limit(pageLimit))
+ *       : null,
+ *   [firestore, hostId],
+ *   { idField: '$id' },
+ * )
+ * ```
+ */
+export declare function usePagedCollection<T = DocumentData>(buildQuery: (pageLimit: number) => Query<DocumentData> | null | undefined, deps: DependencyList, options?: UsePagedCollectionOptions): UsePagedCollectionResult<T>;