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

package/src/lib/hooks/use-screen.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */ // A TYPE-only namespace: every `Aglyn.` reference below is a type, and held
+// as a VALUE the namespace pins every module the barrel reaches into the
+// console shell that renders these hooks. `import type` erases instead.
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { Timestamp } from "@aglyn/shared-util-timestamp";
+import { doc } from "firebase/firestore";
+import { useFirestore } from "./firebase/firebase-services.js";
+import useDoc from "./helpers/use-doc.js";
+export const useScreenRef = ({ hostId, screenId })=>{
+    const firestore = useFirestore();
+    const ref = doc(firestore, 'hosts', hostId, 'screens', screenId);
+    return ref.withConverter({
+        toFirestore (data) {
+            const { $id } = data, rest = _object_without_properties_loose(data, [
+                "$id"
+            ]);
+            return _extends({}, rest, {
+                updatedAt: Timestamp.now()
+            });
+        },
+        fromFirestore (snapshot, options) {
+            if (!snapshot.exists()) return undefined;
+            const data = snapshot.data(options);
+            // data.nodes = data.versionRef?.get()
+            return data;
+        }
+    });
+};
+export const useScreen = (data, options)=>{
+    return useDoc(useScreenRef(data), options);
+};
+export default useScreen;
+
+//# sourceMappingURL=use-screen.js.map

package/src/lib/hooks/use-screen.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-screen.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2022 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// A TYPE-only namespace: every `Aglyn.` reference below is a type, and held\n// as a VALUE the namespace pins every module the barrel reaches into the\n// console shell that renders these hooks. `import type` erases instead.\nimport type * as Aglyn from '@aglyn/aglyn'\nimport { Timestamp } from '@aglyn/shared-util-timestamp'\nimport {\n  doc,\n  type DocumentSnapshot,\n  type SnapshotOptions,\n} from 'firebase/firestore'\nimport { useFirestore, type FirestoreDocOptions } from './firebase/firebase-services'\nimport useDoc from './helpers/use-doc'\n\nexport const useScreenRef = ({ hostId, screenId }: { hostId: Aglyn.HostUid; screenId: Aglyn.ScreenUid }) => {\n  const firestore = useFirestore()\n  const ref = doc(firestore, 'hosts', hostId, 'screens', screenId)\n  return ref.withConverter({\n    toFirestore(data: Aglyn.AglynScreen) {\n      const { $id, ...rest } = data\n      return { ...rest, updatedAt: Timestamp.now() }\n    },\n    fromFirestore(\n      snapshot: DocumentSnapshot<Aglyn.AglynScreen>,\n      options: SnapshotOptions,\n    ) {\n      if (!snapshot.exists()) return undefined\n      const data = snapshot.data(options)\n      // data.nodes = data.versionRef?.get()\n      return data as Aglyn.AglynScreen\n    },\n  })\n}\n\nexport const useScreen = (\n  data: {\n    hostId: Aglyn.HostUid\n    screenId: Aglyn.ScreenUid\n  },\n  options?: FirestoreDocOptions<Aglyn.AglynScreen>,\n) => {\n  return useDoc(useScreenRef(data), options)\n}\n\nexport default useScreen\n"],"names":["Timestamp","doc","useFirestore","useDoc","useScreenRef","hostId","screenId","firestore","ref","withConverter","toFirestore","data","$id","rest","updatedAt","now","fromFirestore","snapshot","options","exists","undefined","useScreen"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;;;AAExE,SAASA,SAAS,QAAQ,+BAA8B;AACxD,SACEC,GAAG,QAGE,qBAAoB;AAC3B,SAASC,YAAY,QAAkC,kCAA8B;AACrF,OAAOC,YAAY,uBAAmB;AAEtC,OAAO,MAAMC,eAAe,CAAC,EAAEC,MAAM,EAAEC,QAAQ,EAAwD;IACrG,MAAMC,YAAYL;IAClB,MAAMM,MAAMP,IAAIM,WAAW,SAASF,QAAQ,WAAWC;IACvD,OAAOE,IAAIC,aAAa,CAAC;QACvBC,aAAYC,IAAuB;YACjC,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;YACzB,OAAO,aAAKE;gBAAMC,WAAWd,UAAUe,GAAG;;QAC5C;QACAC,eACEC,QAA6C,EAC7CC,OAAwB;YAExB,IAAI,CAACD,SAASE,MAAM,IAAI,OAAOC;YAC/B,MAAMT,OAAOM,SAASN,IAAI,CAACO;YAC3B,sCAAsC;YACtC,OAAOP;QACT;IACF;AACF,EAAC;AAED,OAAO,MAAMU,YAAY,CACvBV,MAIAO;IAEA,OAAOf,OAAOC,aAAaO,OAAOO;AACpC,EAAC;AAED,eAAeG,UAAS"}

package/src/lib/hooks/use-sending-identity-api.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The client of the console's sending-identity routes (`/api/email/*`).
+ *
+ * Which address a site's mail leaves from, and the domains and senders behind
+ * it, are the platform's mail rail: the console serves the routes, and every
+ * message goes out under that identity whichever plugin wrote it. So the hook
+ * that calls them is here, beside the other client hooks a plugin may import,
+ * and a one-to-one composer reads the identity without importing the plugin
+ * whose settings page edits it.
+ */
+/** What one call answered with. `payload` is `{}` on an unparseable body. */
+export interface SendingApiResult {
+    response: Response;
+    payload: Record<string, any>;
+}
+/** One DNS record, exactly as the server issued it. */
+export interface SendingDnsRecordView {
+    type: 'TXT' | 'MX';
+    name: string;
+    value: string;
+    priority?: number;
+    purpose: 'spf' | 'dkim' | 'return-path' | 'dmarc';
+    required: boolean;
+    note: string;
+}
+/** One org sending domain, as the domains route reports it. */
+export interface SendingDomainView {
+    domain: string;
+    status: 'requested' | 'records-issued' | 'verified' | 'failed';
+    records?: SendingDnsRecordView[];
+    lines?: string[];
+    lastMissing?: string[] | null;
+    lastIssueError?: string | null;
+    verifiedAtMs?: number | null;
+    lastCheckedAtMs?: number | null;
+    dmarc?: {
+        policy: 'reject' | 'quarantine' | 'none' | 'absent';
+        record: string | null;
+        consequence: string;
+    } | null;
+    dmarcSuggestion?: SendingDnsRecordView | null;
+    pendingProvider?: boolean;
+    providerDetail?: string | null;
+}
+/**
+ * One sender this site holds — `hosts/{hostId}/senders/{senderId}`.
+ *
+ * `from` is the whole address, assembled by the server for the reason
+ * `IdentityOption.from` is: a surface that built `${localPart}@${domain}`
+ * itself would be a second derivation of the address, and the two would
+ * disagree the first time either moved. It is `null` for a row whose mailbox
+ * is not in effect — a site on the pooled Aglyn address has one fixed mailbox,
+ * shared with the other sites on it.
+ */
+export interface HostSenderView {
+    id: string;
+    localPart: string;
+    fromName: string | null;
+    replyTo: string | null;
+    /** Whether an email that names no sender goes out as this one. */
+    isDefault: boolean;
+    from: string | null;
+}
+/** What this site sends as, and what it is allowed to send as. */
+export interface SendingIdentityView {
+    orgId: string | null;
+    selected: string;
+    /**
+     * The site's own provisioned domain inside the platform mail apex, or `''`
+     * when it has none and its transactional mail rides the shared pool.
+     */
+    platformDomain: string;
+    /**
+     * The plan that carries sending as a domain the CUSTOMER owns, and the plan
+     * that carries a domain the platform provisions for the site — as names
+     * ready to print, `null` when no plan carries that gate.
+     *
+     * Both come from the server because both are derived from the entitlement
+     * tables there. A tier name written into this component would be pricing
+     * copy that keeps rendering after the gate beneath it moves.
+     */
+    customDomainPlan: string | null;
+    dedicatedDomainPlan: string | null;
+    /** The mailbox this site sends as — the part before the `@`. */
+    localPart: string;
+    /**
+     * Whether that mailbox is the one actually in use.
+     *
+     * False for a site on the pooled Aglyn address, whose mailbox is fixed. The
+     * stored value is real and is kept; it takes effect when the site has a
+     * domain of its own, and until then the card says so rather than showing a
+     * name that no recipient will see.
+     */
+    localPartInUse: boolean;
+    /** The site's default sender name, or null. Composers start from it. */
+    fromName: string | null;
+    /** The site's default reply address, or null. */
+    replyTo: string | null;
+    /**
+     * Every sender this site may send as, the default among them.
+     *
+     * Never empty: a site with no `senders` subcollection has exactly one
+     * sender, and the server synthesizes it from the three fields the host
+     * document has always carried rather than reporting an absence.
+     */
+    senders: HostSenderView[];
+    identity: string;
+    /**
+     * `'custom'` for a domain this site has verified, `'shared'` for the pooled
+     * Aglyn address a site uses until it has one, `null` when the send is
+     * refused. `'platform'` is in the union because the resolver can return it,
+     * and never reaches this view: it is Aglyn's own `aglyn.com` identity, which
+     * a host-scoped resolution cannot produce.
+     */
+    identitySource: 'custom' | 'shared' | 'platform' | null;
+    refusal: {
+        code: string;
+        domain: string | null;
+        message: string;
+        missing: string[];
+    } | null;
+    options: {
+        value: string;
+        from: string | null;
+        selectable: boolean;
+        status: string;
+    }[];
+    domains: {
+        domain: string;
+        status: SendingDomainView['status'];
+        verifiedAtMs: number | null;
+        lastCheckedAtMs: number | null;
+        /**
+         * Why the last attempt to issue a key produced none, or `null`.
+         *
+         * Carried in the LIST and not only on the domain's own page, because one
+         * of its values is not a fault: a claim held at the mail provider's domain
+         * allowance is `requested` with a reason, and a list that could not see
+         * the reason would label it "Waiting on a signing key" — a state whose
+         * whole instruction is to press a button that will not move it.
+         */
+        lastIssueError?: string | null;
+    }[];
+    canManage: boolean;
+    entitled: boolean;
+    /**
+     * The OFFER of a platform sending domain — never the fact of having one,
+     * which `platformDomain` above answers.
+     *
+     * A dedicated subdomain is no longer issued on upgrade: it costs a provider
+     * domain slot and three records in Aglyn's own zone, so it is requested by
+     * somebody who wants it rather than handed to every paying site.
+     *
+     * Optional because a console deployment can be older than the field. A
+     * surface reading it must treat its absence as "no offer to show", never as
+     * "the offer was refused".
+     */
+    dedicated?: {
+        /** The plan carries one and this site has none. */
+        available: boolean;
+        /** The name a request would most likely take. Not a reservation. */
+        proposed: string | null;
+    };
+}
+/**
+ * ONE AUTHORIZED CALL TO THE SENDING-IDENTITY AND SENDING-DOMAIN ROUTES.
+ *
+ * The same shape as `useCampaignSendApi`, including why the user is held in a
+ * ref: this callback is a dependency of effects that load on open, and the
+ * user object is a new object on most renders, so depending on it directly
+ * would re-issue the request on every render of the surface. The token is
+ * fetched at call time either way.
+ *
+ * The two paths are fixed here rather than taken as an argument, for the
+ * reason the campaign hook gives: a hook that accepted a URL from a component
+ * would be a way to post the console's credentials somewhere the console does
+ * not own.
+ *
+ * The token is obtained under a deadline, for the reason `useCampaignApi`
+ * gives: it is awaited in front of the request, so an unbounded refresh is a
+ * call that never reaches `fetch` and never reports anything.
+ *
+ * ## An unobtainable token ANSWERS here rather than throwing
+ *
+ * Unlike the campaign hook, whose callers must tell a send that never left
+ * the browser apart from one the route refused. Everything on this side reads
+ * or edits a configuration surface, where both are the same news to the
+ * reader — and every caller already renders `payload.error` on a refusal, so
+ * answering in that shape is what puts the real reason on screen and leaves
+ * the button that started the call usable.
+ */
+export declare function useSendingApi(): (options: {
+    path: "sending-identity" | "sending-domains";
+    method: "GET" | "POST" | "DELETE";
+    query?: Record<string, string>;
+    body?: Record<string, unknown>;
+}) => Promise<SendingApiResult>;

package/src/lib/hooks/use-sending-identity-api.js

@@ -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.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { useUser } from "./firebase/firebase-services.js";
+import { useCallback, useRef } from "react";
+import { describeCallFailure, resolveIdToken } from "@aglyn/shared-util-http/authorized-token";
+/**
+ * A refusal the caller reads the same way it reads the route's own.
+ *
+ * `401` because that is what the request would have been answered with had it
+ * gone out, and the reason travels in `payload.error`, which is the field
+ * every caller already renders.
+ */ const refusedForCaller = (message)=>({
+        response: {
+            ok: false,
+            status: 401,
+            json: async ()=>({
+                    error: message
+                })
+        },
+        payload: {
+            error: message
+        }
+    });
+/**
+ * ONE AUTHORIZED CALL TO THE SENDING-IDENTITY AND SENDING-DOMAIN ROUTES.
+ *
+ * The same shape as `useCampaignSendApi`, including why the user is held in a
+ * ref: this callback is a dependency of effects that load on open, and the
+ * user object is a new object on most renders, so depending on it directly
+ * would re-issue the request on every render of the surface. The token is
+ * fetched at call time either way.
+ *
+ * The two paths are fixed here rather than taken as an argument, for the
+ * reason the campaign hook gives: a hook that accepted a URL from a component
+ * would be a way to post the console's credentials somewhere the console does
+ * not own.
+ *
+ * The token is obtained under a deadline, for the reason `useCampaignApi`
+ * gives: it is awaited in front of the request, so an unbounded refresh is a
+ * call that never reaches `fetch` and never reports anything.
+ *
+ * ## An unobtainable token ANSWERS here rather than throwing
+ *
+ * Unlike the campaign hook, whose callers must tell a send that never left
+ * the browser apart from one the route refused. Everything on this side reads
+ * or edits a configuration surface, where both are the same news to the
+ * reader — and every caller already renders `payload.error` on a refusal, so
+ * answering in that shape is what puts the real reason on screen and leaves
+ * the button that started the call usable.
+ */ export function useSendingApi() {
+    const { data: user } = useUser();
+    const userRef = useRef(user);
+    userRef.current = user;
+    return useCallback(async (options)=>{
+        var _options_query;
+        let idToken;
+        try {
+            idToken = await resolveIdToken(userRef.current);
+        } catch (error) {
+            return refusedForCaller(describeCallFailure(error, 'Your sign-in could not be confirmed'));
+        }
+        const search = new URLSearchParams((_options_query = options.query) != null ? _options_query : {}).toString();
+        const response = await fetch(`/api/email/${options.path}${search ? `?${search}` : ''}`, _extends({
+            method: options.method,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${idToken}`
+            }
+        }, options.body ? {
+            body: JSON.stringify(options.body)
+        } : {}));
+        const json = await response.json().catch(()=>({}));
+        return {
+            response,
+            payload: json
+        };
+    }, []);
+}
+
+//# sourceMappingURL=use-sending-identity-api.js.map

package/src/lib/hooks/use-sending-identity-api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-sending-identity-api.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 { useUser } from './firebase/firebase-services'\nimport { useCallback, useRef } from 'react'\nimport {\n  describeCallFailure,\n  resolveIdToken,\n  type TokenSource,\n} from '@aglyn/shared-util-http/authorized-token'\n\n/**\n * The client of the console's sending-identity routes (`/api/email/*`).\n *\n * Which address a site's mail leaves from, and the domains and senders behind\n * it, are the platform's mail rail: the console serves the routes, and every\n * message goes out under that identity whichever plugin wrote it. So the hook\n * that calls them is here, beside the other client hooks a plugin may import,\n * and a one-to-one composer reads the identity without importing the plugin\n * whose settings page edits it.\n */\n\n/** What one call answered with. `payload` is `{}` on an unparseable body. */\nexport interface SendingApiResult {\n  response: Response\n  payload: Record<string, any>\n}\n\n/**\n * A refusal the caller reads the same way it reads the route's own.\n *\n * `401` because that is what the request would have been answered with had it\n * gone out, and the reason travels in `payload.error`, which is the field\n * every caller already renders.\n */\nconst refusedForCaller = (message: string): SendingApiResult => ({\n  response: {\n    ok: false,\n    status: 401,\n    json: async () => ({ error: message }),\n  } as unknown as Response,\n  payload: { error: message },\n})\n\n/** One DNS record, exactly as the server issued it. */\nexport interface SendingDnsRecordView {\n  type: 'TXT' | 'MX'\n  name: string\n  value: string\n  priority?: number\n  purpose: 'spf' | 'dkim' | 'return-path' | 'dmarc'\n  required: boolean\n  note: string\n}\n\n/** One org sending domain, as the domains route reports it. */\nexport interface SendingDomainView {\n  domain: string\n  status: 'requested' | 'records-issued' | 'verified' | 'failed'\n  records?: SendingDnsRecordView[]\n  lines?: string[]\n  lastMissing?: string[] | null\n  lastIssueError?: string | null\n  verifiedAtMs?: number | null\n  lastCheckedAtMs?: number | null\n  dmarc?: {\n    policy: 'reject' | 'quarantine' | 'none' | 'absent'\n    record: string | null\n    consequence: string\n  } | null\n  dmarcSuggestion?: SendingDnsRecordView | null\n  pendingProvider?: boolean\n  providerDetail?: string | null\n}\n\n/**\n * One sender this site holds — `hosts/{hostId}/senders/{senderId}`.\n *\n * `from` is the whole address, assembled by the server for the reason\n * `IdentityOption.from` is: a surface that built `${localPart}@${domain}`\n * itself would be a second derivation of the address, and the two would\n * disagree the first time either moved. It is `null` for a row whose mailbox\n * is not in effect — a site on the pooled Aglyn address has one fixed mailbox,\n * shared with the other sites on it.\n */\nexport interface HostSenderView {\n  id: string\n  localPart: string\n  fromName: string | null\n  replyTo: string | null\n  /** Whether an email that names no sender goes out as this one. */\n  isDefault: boolean\n  from: string | null\n}\n\n/** What this site sends as, and what it is allowed to send as. */\nexport interface SendingIdentityView {\n  orgId: string | null\n  selected: string\n  /**\n   * The site's own provisioned domain inside the platform mail apex, or `''`\n   * when it has none and its transactional mail rides the shared pool.\n   */\n  platformDomain: string\n  /**\n   * The plan that carries sending as a domain the CUSTOMER owns, and the plan\n   * that carries a domain the platform provisions for the site — as names\n   * ready to print, `null` when no plan carries that gate.\n   *\n   * Both come from the server because both are derived from the entitlement\n   * tables there. A tier name written into this component would be pricing\n   * copy that keeps rendering after the gate beneath it moves.\n   */\n  customDomainPlan: string | null\n  dedicatedDomainPlan: string | null\n  /** The mailbox this site sends as — the part before the `@`. */\n  localPart: string\n  /**\n   * Whether that mailbox is the one actually in use.\n   *\n   * False for a site on the pooled Aglyn address, whose mailbox is fixed. The\n   * stored value is real and is kept; it takes effect when the site has a\n   * domain of its own, and until then the card says so rather than showing a\n   * name that no recipient will see.\n   */\n  localPartInUse: boolean\n  /** The site's default sender name, or null. Composers start from it. */\n  fromName: string | null\n  /** The site's default reply address, or null. */\n  replyTo: string | null\n  /**\n   * Every sender this site may send as, the default among them.\n   *\n   * Never empty: a site with no `senders` subcollection has exactly one\n   * sender, and the server synthesizes it from the three fields the host\n   * document has always carried rather than reporting an absence.\n   */\n  senders: HostSenderView[]\n  identity: string\n  /**\n   * `'custom'` for a domain this site has verified, `'shared'` for the pooled\n   * Aglyn address a site uses until it has one, `null` when the send is\n   * refused. `'platform'` is in the union because the resolver can return it,\n   * and never reaches this view: it is Aglyn's own `aglyn.com` identity, which\n   * a host-scoped resolution cannot produce.\n   */\n  identitySource: 'custom' | 'shared' | 'platform' | null\n  refusal: {\n    code: string\n    domain: string | null\n    message: string\n    missing: string[]\n  } | null\n  options: {\n    value: string\n    from: string | null\n    selectable: boolean\n    status: string\n  }[]\n  domains: {\n    domain: string\n    status: SendingDomainView['status']\n    verifiedAtMs: number | null\n    lastCheckedAtMs: number | null\n    /**\n     * Why the last attempt to issue a key produced none, or `null`.\n     *\n     * Carried in the LIST and not only on the domain's own page, because one\n     * of its values is not a fault: a claim held at the mail provider's domain\n     * allowance is `requested` with a reason, and a list that could not see\n     * the reason would label it \"Waiting on a signing key\" — a state whose\n     * whole instruction is to press a button that will not move it.\n     */\n    lastIssueError?: string | null\n  }[]\n  canManage: boolean\n  entitled: boolean\n  /**\n   * The OFFER of a platform sending domain — never the fact of having one,\n   * which `platformDomain` above answers.\n   *\n   * A dedicated subdomain is no longer issued on upgrade: it costs a provider\n   * domain slot and three records in Aglyn's own zone, so it is requested by\n   * somebody who wants it rather than handed to every paying site.\n   *\n   * Optional because a console deployment can be older than the field. A\n   * surface reading it must treat its absence as \"no offer to show\", never as\n   * \"the offer was refused\".\n   */\n  dedicated?: {\n    /** The plan carries one and this site has none. */\n    available: boolean\n    /** The name a request would most likely take. Not a reservation. */\n    proposed: string | null\n  }\n}\n\n/**\n * ONE AUTHORIZED CALL TO THE SENDING-IDENTITY AND SENDING-DOMAIN ROUTES.\n *\n * The same shape as `useCampaignSendApi`, including why the user is held in a\n * ref: this callback is a dependency of effects that load on open, and the\n * user object is a new object on most renders, so depending on it directly\n * would re-issue the request on every render of the surface. The token is\n * fetched at call time either way.\n *\n * The two paths are fixed here rather than taken as an argument, for the\n * reason the campaign hook gives: a hook that accepted a URL from a component\n * would be a way to post the console's credentials somewhere the console does\n * not own.\n *\n * The token is obtained under a deadline, for the reason `useCampaignApi`\n * gives: it is awaited in front of the request, so an unbounded refresh is a\n * call that never reaches `fetch` and never reports anything.\n *\n * ## An unobtainable token ANSWERS here rather than throwing\n *\n * Unlike the campaign hook, whose callers must tell a send that never left\n * the browser apart from one the route refused. Everything on this side reads\n * or edits a configuration surface, where both are the same news to the\n * reader — and every caller already renders `payload.error` on a refusal, so\n * answering in that shape is what puts the real reason on screen and leaves\n * the button that started the call usable.\n */\nexport function useSendingApi() {\n  const { data: user } = useUser()\n  const userRef = useRef(user)\n  userRef.current = user\n\n  return useCallback(\n    async (options: {\n      path: 'sending-identity' | 'sending-domains'\n      method: 'GET' | 'POST' | 'DELETE'\n      query?: Record<string, string>\n      body?: Record<string, unknown>\n    }): Promise<SendingApiResult> => {\n      let idToken: string\n      try {\n        idToken = await resolveIdToken(\n          userRef.current as TokenSource | null | undefined,\n        )\n      } catch (error) {\n        return refusedForCaller(\n          describeCallFailure(error, 'Your sign-in could not be confirmed'),\n        )\n      }\n      const search = new URLSearchParams(options.query ?? {}).toString()\n      const response = await fetch(\n        `/api/email/${options.path}${search ? `?${search}` : ''}`,\n        {\n          method: options.method,\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${idToken}`,\n          },\n          ...(options.body ? { body: JSON.stringify(options.body) } : {}),\n        },\n      )\n      const json = await response.json().catch(() => ({}))\n      return { response, payload: json as Record<string, any> }\n    },\n    [],\n  )\n}\n"],"names":["useUser","useCallback","useRef","describeCallFailure","resolveIdToken","refusedForCaller","message","response","ok","status","json","error","payload","useSendingApi","data","user","userRef","current","options","idToken","search","URLSearchParams","query","toString","fetch","path","method","headers","Authorization","body","JSON","stringify","catch"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SAASA,OAAO,QAAQ,kCAA8B;AACtD,SAASC,WAAW,EAAEC,MAAM,QAAQ,QAAO;AAC3C,SACEC,mBAAmB,EACnBC,cAAc,QAET,2CAA0C;AAmBjD;;;;;;CAMC,GACD,MAAMC,mBAAmB,CAACC,UAAuC,CAAA;QAC/DC,UAAU;YACRC,IAAI;YACJC,QAAQ;YACRC,MAAM,UAAa,CAAA;oBAAEC,OAAOL;gBAAQ,CAAA;QACtC;QACAM,SAAS;YAAED,OAAOL;QAAQ;IAC5B,CAAA;AA2JA;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,SAASO;IACd,MAAM,EAAEC,MAAMC,IAAI,EAAE,GAAGf;IACvB,MAAMgB,UAAUd,OAAOa;IACvBC,QAAQC,OAAO,GAAGF;IAElB,OAAOd,YACL,OAAOiB;YAgB8BA;QAVnC,IAAIC;QACJ,IAAI;YACFA,UAAU,MAAMf,eACdY,QAAQC,OAAO;QAEnB,EAAE,OAAON,OAAO;YACd,OAAON,iBACLF,oBAAoBQ,OAAO;QAE/B;QACA,MAAMS,SAAS,IAAIC,iBAAgBH,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiB,CAAC,GAAGK,QAAQ;QAChE,MAAMhB,WAAW,MAAMiB,MACrB,CAAC,WAAW,EAAEN,QAAQO,IAAI,GAAGL,SAAS,CAAC,CAAC,EAAEA,QAAQ,GAAG,IAAI,EACzD;YACEM,QAAQR,QAAQQ,MAAM;YACtBC,SAAS;gBACP,gBAAgB;gBAChBC,eAAe,CAAC,OAAO,EAAET,SAAS;YACpC;WACID,QAAQW,IAAI,GAAG;YAAEA,MAAMC,KAAKC,SAAS,CAACb,QAAQW,IAAI;QAAE,IAAI,CAAC;QAGjE,MAAMnB,OAAO,MAAMH,SAASG,IAAI,GAAGsB,KAAK,CAAC,IAAO,CAAA,CAAC,CAAA;QACjD,OAAO;YAAEzB;YAAUK,SAASF;QAA4B;IAC1D,GACA,EAAE;AAEN"}

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

@@ -0,0 +1,48 @@
+import type { DocumentData, Query } from 'firebase/firestore';
+import { type DependencyList } from 'react';
+import { type CollectionSort } from './sorted-collection-window';
+import { type UseFirestoreCollectionOptions } from './use-firestore-collection';
+import type { UsePagedCollectionResult } from './use-paged-collection';
+export interface UseSortedPagedCollectionOptions extends UseFirestoreCollectionOptions {
+    /**
+     * Required: the keyed and unkeyed segments are two listeners, and a
+     * document moving between them is recognized by its id.
+     */
+    idField: string;
+    /** Rows per page. Defaults to the console-wide smallest option. */
+    pageSize?: number;
+    /**
+     * The fields `buildBase` pins by EQUALITY. A sort on one of them needs no
+     * unkeyed segment — see `sortFieldIsTotal`.
+     */
+    equalityFields?: readonly string[];
+}
+/**
+ * A paged window over a live collection SORTED BY A FIELD, which still drops
+ * no document that lacks the field (AGL-2853).
+ *
+ * The same contract as `usePagedCollection` — the window is the query, one
+ * page plus a probe row, `hasMore` a fact — over the two-segment walk in
+ * `sorted-collection-window.ts`: the documents that carry the sort field in
+ * its order, then the ones that do not, in name order. See that module for why
+ * both segments are needed and what the second one costs.
+ *
+ * `buildBase` returns the collection with any EQUALITY predicates and nothing
+ * else; the ordering and the limits are this hook's. `deps` identify the
+ * subject as they do for `useFirestoreCollection`. A new subject, sort or
+ * filter starts again from page one.
+ *
+ * ```ts
+ * useSortedPagedCollection<Entry>(
+ *   () => query(
+ *     collection(firestore, 'hosts', hostId, 'collections', collectionId, 'entries'),
+ *     where('status', '==', status),
+ *   ),
+ *   { field: 'publishedAt', direction: 'desc' },
+ *   [firestore, hostId, collectionId, status],
+ *   { idField: '$id', equalityFields: ['status'] },
+ * )
+ * ```
+ */
+export declare function useSortedPagedCollection<T = DocumentData>(buildBase: () => Query<DocumentData> | null | undefined, sort: CollectionSort, deps: DependencyList, options: UseSortedPagedCollectionOptions): UsePagedCollectionResult<T>;
+export default useSortedPagedCollection;

package/src/lib/hooks/use-sorted-paged-collection.js

@@ -0,0 +1,213 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { TABLE_PAGE_SIZE_DEFAULT } from "@aglyn/shared-ui-jsx/const/table-pagination";
+import { planKeyedSegment, planSortedWindow, sortedKeyedQuery, sortedScanLimit, sortedUnkeyedQuery, sortFieldIsTotal } from "./sorted-collection-window.js";
+import { useFirestoreCollection } from "./use-firestore-collection.js";
+/** `Object.is` over two dependency lists, the comparison React itself uses. */ const sameDeps = (a, b)=>a.length === b.length && a.every((value, index)=>Object.is(value, b[index]));
+/**
+ * The request a read's CURRENT rows were delivered for.
+ *
+ * `useFirestoreCollection` re-subscribes in an effect, so the render in which
+ * its inputs change still returns the previous subscription's rows — rows for
+ * another limit, sort or subject. Planning on them would judge a window by a
+ * read that was never made for it: page two's window measured against page
+ * one's eleven rows looks like a walk that ran out.
+ *
+ * So rows are labeled with the request that was current when they ARRIVED,
+ * which is the render their array first appears in, and a render whose request
+ * has since moved on treats them as unread. Held as state and adjusted during
+ * render — the pattern React documents for state that follows a prop — so no
+ * render ever pairs a request with rows read for another.
+ */ function useCurrentRows(rows, request) {
+    const [delivered, setDelivered] = useState(()=>({
+            rows,
+            request
+        }));
+    if (delivered.rows !== rows) {
+        setDelivered({
+            rows,
+            request
+        });
+        return true;
+    }
+    return sameDeps(delivered.request, request);
+}
+/**
+ * A paged window over a live collection SORTED BY A FIELD, which still drops
+ * no document that lacks the field (AGL-2853).
+ *
+ * The same contract as `usePagedCollection` — the window is the query, one
+ * page plus a probe row, `hasMore` a fact — over the two-segment walk in
+ * `sorted-collection-window.ts`: the documents that carry the sort field in
+ * its order, then the ones that do not, in name order. See that module for why
+ * both segments are needed and what the second one costs.
+ *
+ * `buildBase` returns the collection with any EQUALITY predicates and nothing
+ * else; the ordering and the limits are this hook's. `deps` identify the
+ * subject as they do for `useFirestoreCollection`. A new subject, sort or
+ * filter starts again from page one.
+ *
+ * ```ts
+ * useSortedPagedCollection<Entry>(
+ *   () => query(
+ *     collection(firestore, 'hosts', hostId, 'collections', collectionId, 'entries'),
+ *     where('status', '==', status),
+ *   ),
+ *   { field: 'publishedAt', direction: 'desc' },
+ *   [firestore, hostId, collectionId, status],
+ *   { idField: '$id', equalityFields: ['status'] },
+ * )
+ * ```
+ */ export function useSortedPagedCollection(buildBase, sort, deps, options) {
+    var _keyedRead_error;
+    const { pageSize: initialPageSize = TABLE_PAGE_SIZE_DEFAULT, equalityFields = [] } = options, collectionOptions = _object_without_properties_loose(options, [
+        "pageSize",
+        "equalityFields"
+    ]);
+    const idField = options.idField;
+    const [pageSize, setPageSizeState] = useState(initialPageSize);
+    const buildBaseRef = useRef(buildBase);
+    buildBaseRef.current = buildBase;
+    const equalityKey = equalityFields.join('\n');
+    const subject = [
+        ...deps,
+        sort.field,
+        sort.direction,
+        equalityKey
+    ];
+    /*
+   * The reader's position belongs to ONE subject. It resets in the render the
+   * subject changes in, not in an effect after it: an effect would let that
+   * render subscribe the new sort at the old page's limit, and a sort change
+   * on page four would bill forty-one documents to show ten.
+   */ const [cursor, setCursor] = useState(()=>({
+            subject,
+            page: 0,
+            widenedTo: 0
+        }));
+    const sameSubject = sameDeps(cursor.subject, subject);
+    const position = sameSubject ? cursor : {
+        subject,
+        page: 0,
+        widenedTo: 0
+    };
+    if (!sameSubject) setCursor(position);
+    const { page } = position;
+    const keyedIsTotal = sortFieldIsTotal(sort, equalityFields);
+    const { keyedLimit } = planKeyedSegment({
+        page,
+        pageSize,
+        keyed: undefined,
+        keyedSettled: false,
+        keyedIsTotal
+    });
+    const keyedRequest = [
+        ...subject,
+        keyedLimit
+    ];
+    const keyedRead = useFirestoreCollection(()=>{
+        const base = buildBaseRef.current();
+        return base ? sortedKeyedQuery(base, sort, keyedLimit, equalityFields) : null;
+    }, keyedRequest, collectionOptions);
+    const keyedCurrent = useCurrentRows(keyedRead.data, keyedRequest);
+    const keyed = keyedCurrent && keyedRead.status !== 'loading' ? keyedRead.data : undefined;
+    const keyedSettled = keyedCurrent && keyedRead.status === 'success' && !keyedRead.fromCache;
+    const keyedPlan = planKeyedSegment({
+        page,
+        pageSize,
+        keyed,
+        keyedSettled,
+        keyedIsTotal
+    });
+    const scanLimit = sortedScanLimit(keyedPlan, position.widenedTo);
+    const scanRequest = [
+        ...subject,
+        scanLimit
+    ];
+    const scanRead = useFirestoreCollection(()=>{
+        if (scanLimit <= 0) return null;
+        const base = buildBaseRef.current();
+        return base ? sortedUnkeyedQuery(base, scanLimit) : null;
+    }, scanRequest, collectionOptions);
+    const scanCurrent = useCurrentRows(scanRead.data, scanRequest);
+    const scanOpen = scanLimit > 0;
+    const sorted = planSortedWindow({
+        page,
+        pageSize,
+        sort,
+        keyedIsTotal,
+        keyed,
+        keyedSettled,
+        scan: scanOpen && scanCurrent && scanRead.status !== 'loading' ? scanRead.data : undefined,
+        scanSettled: scanOpen && scanCurrent && scanRead.status === 'success' && !scanRead.fromCache,
+        scanLimit,
+        idOf: (row)=>String(row[idField])
+    });
+    /*
+   * Widening is remembered for the subject, so paging back to where the scan
+   * is not needed and forward again re-opens it at the width it reached
+   * instead of doubling its way back up.
+   */ const widenTo = sorted.scanLimit;
+    useEffect(()=>{
+        if (widenTo <= position.widenedTo) return;
+        setCursor((previous)=>sameDeps(previous.subject, position.subject) && widenTo > previous.widenedTo ? _extends({}, previous, {
+                widenedTo: widenTo
+            }) : previous);
+    }, [
+        widenTo,
+        position.widenedTo,
+        position.subject
+    ]);
+    const setPage = useCallback((next)=>{
+        setCursor((previous)=>_extends({}, previous, {
+                page: next
+            }));
+    }, []);
+    const setPageSize = useCallback((next)=>{
+        setPageSizeState(next);
+        // Page four of a ten-row list does not exist once the reader asks for
+        // fifty at a time, and an out-of-range page renders as an empty list.
+        setCursor((previous)=>_extends({}, previous, {
+                page: 0
+            }));
+    }, []);
+    /*
+   * A short window is a claim that the list ENDS here, so it is `loading`
+   * until the server has confirmed both segments. A window holding its probe
+   * row claims only that more exists, which a cached read can say.
+   */ const errored = keyedRead.status === 'error' || scanOpen && scanRead.status === 'error';
+    const status = errored ? 'error' : keyed === undefined ? 'loading' : sorted.hasMore || sorted.settled ? 'success' : 'loading';
+    return {
+        data: sorted.ordered,
+        rows: sorted.rows,
+        hasMore: sorted.hasMore,
+        page,
+        setPage,
+        pageSize,
+        setPageSize,
+        status,
+        error: (_keyedRead_error = keyedRead.error) != null ? _keyedRead_error : scanOpen ? scanRead.error : undefined,
+        fromCache: keyedRead.fromCache || scanOpen && scanRead.fromCache,
+        serverDenied: keyedRead.serverDenied || scanOpen && scanRead.serverDenied
+    };
+}
+export default useSortedPagedCollection;
+
+//# sourceMappingURL=use-sorted-paged-collection.js.map