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

package/src/lib/hooks/use-firestore-doc.d.ts

@@ -0,0 +1,42 @@
+import { type DocumentData, type DocumentReference, type FirestoreError } from 'firebase/firestore';
+import { type DependencyList } from 'react';
+export type FirestoreDocStatus = 'loading' | 'success' | 'error';
+export interface UseFirestoreDocOptions {
+    idField?: string;
+}
+export interface UseFirestoreDocResult<T> {
+    data: T | undefined;
+    status: FirestoreDocStatus;
+    error: FirestoreError | undefined;
+    /**
+     * `data` still carries writes this client made that the server has NOT
+     * acknowledged. Carried rather than dropped for the same reason as
+     * `ObservableStatus.hasPendingWrites` — see that comment (AGL-1262).
+     */
+    hasPendingWrites: boolean;
+    /**
+     * `data` came from the local cache and the server has not confirmed it
+     * (AGL-1066). See `ObservableStatus.fromCache` for why this matters and
+     * why it is the signal to reach for rather than `staleSession`.
+     */
+    fromCache: boolean;
+    /**
+     * The server has REFUSED this listen for longer than the retry budget and
+     * no server snapshot has arrived since (AGL-1066) — the reason behind an
+     * `error`, not a duplicate of it. See
+     * `UseFirestoreCollectionResult.serverDenied`.
+     */
+    serverDenied: boolean;
+}
+/**
+ * Single-document counterpart to `useFirestoreCollection` — see that hook's
+ * doc comment for why this exists instead of reactfire's
+ * `useFirestoreDocData` (AGL-216/217).
+ *
+ * `buildRef` is re-invoked from `deps` the same way a `useEffect`/`useMemo`
+ * callback would be — pass the same primitive values (ids, uid, firestore)
+ * you'd put in a `useMemo` dependency array, not the `DocumentReference`
+ * object itself.
+ */
+export declare function useFirestoreDoc<T = DocumentData>(buildRef: () => DocumentReference<DocumentData> | null | undefined, deps: DependencyList, options?: UseFirestoreDocOptions): UseFirestoreDocResult<T>;
+export default useFirestoreDoc;

package/src/lib/hooks/use-firestore-doc.js

@@ -0,0 +1,192 @@
+/**
+ * @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 { onSnapshot } from "firebase/firestore";
+import { useEffect, useRef, useState } from "react";
+import { CONFIRMABLE_LISTEN_OPTIONS } from "./helpers/listen-options.js";
+import { DENIAL_STREAK_TO_REPORT, denialLabelForQuery, reportFirestoreDenial, reportFirestoreServerRead, scheduleRefusedReopen, subscribeFirestoreSessionHeal } from "./firestore-denial-reporter.js";
+const RETRY_DELAY_MS = 400;
+const MAX_RETRIES = 5;
+/**
+ * Single-document counterpart to `useFirestoreCollection` — see that hook's
+ * doc comment for why this exists instead of reactfire's
+ * `useFirestoreDocData` (AGL-216/217).
+ *
+ * `buildRef` is re-invoked from `deps` the same way a `useEffect`/`useMemo`
+ * callback would be — pass the same primitive values (ids, uid, firestore)
+ * you'd put in a `useMemo` dependency array, not the `DocumentReference`
+ * object itself.
+ */ export function useFirestoreDoc(buildRef, deps, options = {}) {
+    const [data, setData] = useState(undefined);
+    const [status, setStatus] = useState('loading');
+    const [error, setError] = useState(undefined);
+    const [hasPendingWrites, setHasPendingWrites] = useState(false);
+    // Un-confirmed until a snapshot says otherwise: a hook that has not heard
+    // from the server yet must not read as server-confirmed.
+    const [fromCache, setFromCache] = useState(true);
+    const [serverDenied, setServerDenied] = useState(false);
+    const buildRefRef = useRef(buildRef);
+    buildRefRef.current = buildRef;
+    const idField = options.idField;
+    useEffect(()=>{
+        setStatus('loading');
+        setError(undefined);
+        // Clear on every dep change (AGL-591): a scope move between two live
+        // refs must not keep showing the previous doc until the new snapshot
+        // arrives. Mirrors use-firestore-collection.
+        setData(undefined);
+        setHasPendingWrites(false);
+        setFromCache(true);
+        setServerDenied(false);
+        const ref = buildRefRef.current();
+        if (!ref) {
+            return;
+        }
+        let cancelled = false;
+        let unsubscribe = null;
+        let timer = null;
+        /** Cancels a pending reopen on the refused cadence (AGL-2944). */ let cancelRefusedReopen = null;
+        let attempt = 0;
+        // Refusals since the last SERVER snapshot (AGL-1066) — see the note on
+        // `DENIAL_STREAK_TO_REPORT` for why this is not `attempt`.
+        let deniedStreak = 0;
+        /** Epoch ms of the current streak's first refusal (AGL-1440). */ let deniedStreakStartedAt = 0;
+        let denialReported = false;
+        /**
+     * The retry budget is spent and the server's last word was a refusal —
+     * what keeps `status: 'error'` from being undone by the cached emission
+     * that precedes every reopened refusal (AGL-1066). See the longer note
+     * on the same variable in `use-firestore-collection`.
+     */ let terminal = false;
+        const denialLabel = denialLabelForQuery(ref);
+        const subscribe = ()=>{
+            unsubscribe = onSnapshot(ref, // Without this the cache→server confirmation is never delivered and
+            // `fromCache` latches true for the life of the listener, refusing
+            // every guarded save on the page (AGL-2486). See `listen-options.ts`.
+            CONFIRMABLE_LISTEN_OPTIONS, (snapshot)=>{
+                if (cancelled) return;
+                if (!terminal) {
+                    setStatus('success');
+                    setError(undefined);
+                }
+                setHasPendingWrites(snapshot.metadata.hasPendingWrites);
+                setFromCache(snapshot.metadata.fromCache);
+                // Only the SERVER answering is evidence the session can read — and
+                // the only thing that refunds the retry budget (AGL-1066). See the
+                // long note on the same gate in `use-firestore-collection`.
+                if (!snapshot.metadata.fromCache) {
+                    attempt = 0;
+                    terminal = false;
+                    setStatus('success');
+                    setError(undefined);
+                    deniedStreak = 0;
+                    denialReported = false;
+                    setServerDenied(false);
+                    // Proof the session can read — stronger than any accumulated
+                    // denial, and what stops a scoped collaborator's by-design
+                    // denials from ever adding up to a re-auth prompt.
+                    reportFirestoreServerRead();
+                } else if (deniedStreak === 0) {
+                    // Cached, but nothing has been refused since the server last
+                    // answered — not the AGL-1066 fault, so the budget is refunded
+                    // exactly as it always was. This is what keeps offline inert:
+                    // `unavailable` never enters `deniedStreak`.
+                    attempt = 0;
+                }
+                if (!snapshot.exists()) {
+                    setData(undefined);
+                    return;
+                }
+                const value = _extends({}, snapshot.data());
+                if (idField) value[idField] = snapshot.id;
+                setData(value);
+            }, (err)=>{
+                if (cancelled) return;
+                unsubscribe == null ? void 0 : unsubscribe();
+                // Say so once per outage, and only for a refusal — a lost network
+                // produces no error callback at all, so this cannot fire offline.
+                if ((err == null ? void 0 : err.code) === 'permission-denied') {
+                    deniedStreak += 1;
+                    if (deniedStreak === 1) deniedStreakStartedAt = Date.now();
+                    if (deniedStreak >= DENIAL_STREAK_TO_REPORT) {
+                        setServerDenied(true);
+                        if (!denialReported) {
+                            denialReported = true;
+                            reportFirestoreDenial(denialLabel);
+                        }
+                    }
+                }
+                if (attempt < MAX_RETRIES) {
+                    attempt += 1;
+                    if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    } else {
+                        timer = setTimeout(subscribe, RETRY_DELAY_MS);
+                    }
+                } else {
+                    terminal = true;
+                    setStatus('error');
+                    setError(err);
+                    // A refusal streak keeps a slow road back for a recovery nobody
+                    // announced — see the same branch in `use-firestore-collection`.
+                    // The cadence splits on session-vs-ref evidence (AGL-1440), grows
+                    // with the streak's age (AGL-2945) and waits while the tab is
+                    // hidden (AGL-2944).
+                    if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    }
+                }
+            });
+        };
+        subscribe();
+        // Reopen when the session heals — see the long note on the same
+        // subscription in `use-firestore-collection` (AGL-1066). Gated on this
+        // listen actually being refused, so a healthy one ignores the broadcast.
+        const unsubscribeHeal = subscribeFirestoreSessionHeal(()=>{
+            if (cancelled || deniedStreak === 0) return;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            cancelRefusedReopen = null;
+            unsubscribe == null ? void 0 : unsubscribe();
+            attempt = 0;
+            denialReported = false;
+            subscribe();
+        });
+        return ()=>{
+            cancelled = true;
+            unsubscribeHeal();
+            if (timer) clearTimeout(timer);
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            unsubscribe == null ? void 0 : unsubscribe();
+        };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+    return {
+        data,
+        status,
+        error,
+        hasPendingWrites,
+        fromCache,
+        serverDenied
+    };
+}
+export default useFirestoreDoc;
+
+//# sourceMappingURL=use-firestore-doc.js.map

package/src/lib/hooks/use-firestore-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-firestore-doc.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 {\n  onSnapshot,\n  type DocumentData,\n  type DocumentReference,\n  type FirestoreError,\n} from 'firebase/firestore'\nimport { useEffect, useRef, useState, type DependencyList } from 'react'\nimport { CONFIRMABLE_LISTEN_OPTIONS } from './helpers/listen-options'\nimport {\n  DENIAL_STREAK_TO_REPORT,\n  denialLabelForQuery,\n  reportFirestoreDenial,\n  reportFirestoreServerRead,\n  scheduleRefusedReopen,\n  subscribeFirestoreSessionHeal,\n} from './firestore-denial-reporter'\n\nconst RETRY_DELAY_MS = 400\nconst MAX_RETRIES = 5\n// The refused cadence is shared policy — see `scheduleRefusedReopen` in\n// `firestore-denial-reporter.ts` (AGL-1066, AGL-1440, AGL-2944, AGL-2945).\n\nexport type FirestoreDocStatus = 'loading' | 'success' | 'error'\n\nexport interface UseFirestoreDocOptions {\n  idField?: string\n}\n\nexport interface UseFirestoreDocResult<T> {\n  data: T | undefined\n  status: FirestoreDocStatus\n  error: FirestoreError | undefined\n  /**\n   * `data` still carries writes this client made that the server has NOT\n   * acknowledged. Carried rather than dropped for the same reason as\n   * `ObservableStatus.hasPendingWrites` — see that comment (AGL-1262).\n   */\n  hasPendingWrites: boolean\n  /**\n   * `data` came from the local cache and the server has not confirmed it\n   * (AGL-1066). See `ObservableStatus.fromCache` for why this matters and\n   * why it is the signal to reach for rather than `staleSession`.\n   */\n  fromCache: boolean\n  /**\n   * The server has REFUSED this listen for longer than the retry budget and\n   * no server snapshot has arrived since (AGL-1066) — the reason behind an\n   * `error`, not a duplicate of it. See\n   * `UseFirestoreCollectionResult.serverDenied`.\n   */\n  serverDenied: boolean\n}\n\n/**\n * Single-document counterpart to `useFirestoreCollection` — see that hook's\n * doc comment for why this exists instead of reactfire's\n * `useFirestoreDocData` (AGL-216/217).\n *\n * `buildRef` is re-invoked from `deps` the same way a `useEffect`/`useMemo`\n * callback would be — pass the same primitive values (ids, uid, firestore)\n * you'd put in a `useMemo` dependency array, not the `DocumentReference`\n * object itself.\n */\nexport function useFirestoreDoc<T = DocumentData>(\n  buildRef: () => DocumentReference<DocumentData> | null | undefined,\n  deps: DependencyList,\n  options: UseFirestoreDocOptions = {},\n): UseFirestoreDocResult<T> {\n  const [data, setData] = useState<T | undefined>(undefined)\n  const [status, setStatus] = useState<FirestoreDocStatus>('loading')\n  const [error, setError] = useState<FirestoreError | undefined>(undefined)\n  const [hasPendingWrites, setHasPendingWrites] = useState(false)\n  // Un-confirmed until a snapshot says otherwise: a hook that has not heard\n  // from the server yet must not read as server-confirmed.\n  const [fromCache, setFromCache] = useState(true)\n  const [serverDenied, setServerDenied] = useState(false)\n  const buildRefRef = useRef(buildRef)\n  buildRefRef.current = buildRef\n  const idField = options.idField\n\n  useEffect(() => {\n    setStatus('loading')\n    setError(undefined)\n    // Clear on every dep change (AGL-591): a scope move between two live\n    // refs must not keep showing the previous doc until the new snapshot\n    // arrives. Mirrors use-firestore-collection.\n    setData(undefined)\n    setHasPendingWrites(false)\n    setFromCache(true)\n    setServerDenied(false)\n\n    const ref = buildRefRef.current()\n    if (!ref) {\n      return\n    }\n\n    let cancelled = false\n    let unsubscribe: (() => void) | null = null\n    let timer: ReturnType<typeof setTimeout> | null = null\n    /** Cancels a pending reopen on the refused cadence (AGL-2944). */\n    let cancelRefusedReopen: (() => void) | null = null\n    let attempt = 0\n    // Refusals since the last SERVER snapshot (AGL-1066) — see the note on\n    // `DENIAL_STREAK_TO_REPORT` for why this is not `attempt`.\n    let deniedStreak = 0\n    /** Epoch ms of the current streak's first refusal (AGL-1440). */\n    let deniedStreakStartedAt = 0\n    let denialReported = false\n    /**\n     * The retry budget is spent and the server's last word was a refusal —\n     * what keeps `status: 'error'` from being undone by the cached emission\n     * that precedes every reopened refusal (AGL-1066). See the longer note\n     * on the same variable in `use-firestore-collection`.\n     */\n    let terminal = false\n    const denialLabel = denialLabelForQuery(ref)\n\n    const subscribe = () => {\n      unsubscribe = onSnapshot(\n        ref,\n        // Without this the cache→server confirmation is never delivered and\n        // `fromCache` latches true for the life of the listener, refusing\n        // every guarded save on the page (AGL-2486). See `listen-options.ts`.\n        CONFIRMABLE_LISTEN_OPTIONS,\n        (snapshot) => {\n          if (cancelled) return\n          if (!terminal) {\n            setStatus('success')\n            setError(undefined)\n          }\n          setHasPendingWrites(snapshot.metadata.hasPendingWrites)\n          setFromCache(snapshot.metadata.fromCache)\n          // Only the SERVER answering is evidence the session can read — and\n          // the only thing that refunds the retry budget (AGL-1066). See the\n          // long note on the same gate in `use-firestore-collection`.\n          if (!snapshot.metadata.fromCache) {\n            attempt = 0\n            terminal = false\n            setStatus('success')\n            setError(undefined)\n            deniedStreak = 0\n            denialReported = false\n            setServerDenied(false)\n            // Proof the session can read — stronger than any accumulated\n            // denial, and what stops a scoped collaborator's by-design\n            // denials from ever adding up to a re-auth prompt.\n            reportFirestoreServerRead()\n          } else if (deniedStreak === 0) {\n            // Cached, but nothing has been refused since the server last\n            // answered — not the AGL-1066 fault, so the budget is refunded\n            // exactly as it always was. This is what keeps offline inert:\n            // `unavailable` never enters `deniedStreak`.\n            attempt = 0\n          }\n          if (!snapshot.exists()) {\n            setData(undefined)\n            return\n          }\n          const value = { ...snapshot.data() } as Record<string, unknown>\n          if (idField) value[idField] = snapshot.id\n          setData(value as T)\n        },\n        (err) => {\n          if (cancelled) return\n          unsubscribe?.()\n          // Say so once per outage, and only for a refusal — a lost network\n          // produces no error callback at all, so this cannot fire offline.\n          if (err?.code === 'permission-denied') {\n            deniedStreak += 1\n            if (deniedStreak === 1) deniedStreakStartedAt = Date.now()\n            if (deniedStreak >= DENIAL_STREAK_TO_REPORT) {\n              setServerDenied(true)\n              if (!denialReported) {\n                denialReported = true\n                reportFirestoreDenial(denialLabel)\n              }\n            }\n          }\n          if (attempt < MAX_RETRIES) {\n            attempt += 1\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            } else {\n              timer = setTimeout(subscribe, RETRY_DELAY_MS)\n            }\n          } else {\n            terminal = true\n            setStatus('error')\n            setError(err)\n            // A refusal streak keeps a slow road back for a recovery nobody\n            // announced — see the same branch in `use-firestore-collection`.\n            // The cadence splits on session-vs-ref evidence (AGL-1440), grows\n            // with the streak's age (AGL-2945) and waits while the tab is\n            // hidden (AGL-2944).\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            }\n          }\n        },\n      )\n    }\n    subscribe()\n\n    // Reopen when the session heals — see the long note on the same\n    // subscription in `use-firestore-collection` (AGL-1066). Gated on this\n    // listen actually being refused, so a healthy one ignores the broadcast.\n    const unsubscribeHeal = subscribeFirestoreSessionHeal(() => {\n      if (cancelled || deniedStreak === 0) return\n      if (timer) {\n        clearTimeout(timer)\n        timer = null\n      }\n      cancelRefusedReopen?.()\n      cancelRefusedReopen = null\n      unsubscribe?.()\n      attempt = 0\n      denialReported = false\n      subscribe()\n    })\n\n    return () => {\n      cancelled = true\n      unsubscribeHeal()\n      if (timer) clearTimeout(timer)\n      cancelRefusedReopen?.()\n      unsubscribe?.()\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, deps)\n\n  return { data, status, error, hasPendingWrites, fromCache, serverDenied }\n}\n\nexport default useFirestoreDoc\n"],"names":["onSnapshot","useEffect","useRef","useState","CONFIRMABLE_LISTEN_OPTIONS","DENIAL_STREAK_TO_REPORT","denialLabelForQuery","reportFirestoreDenial","reportFirestoreServerRead","scheduleRefusedReopen","subscribeFirestoreSessionHeal","RETRY_DELAY_MS","MAX_RETRIES","useFirestoreDoc","buildRef","deps","options","data","setData","undefined","status","setStatus","error","setError","hasPendingWrites","setHasPendingWrites","fromCache","setFromCache","serverDenied","setServerDenied","buildRefRef","current","idField","ref","cancelled","unsubscribe","timer","cancelRefusedReopen","attempt","deniedStreak","deniedStreakStartedAt","denialReported","terminal","denialLabel","subscribe","snapshot","metadata","exists","value","id","err","code","Date","now","setTimeout","unsubscribeHeal","clearTimeout"],"mappings":"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"}

package/src/lib/hooks/use-form-version.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @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 * as Aglyn from '@aglyn/aglyn';
+import type { DocumentReference } from 'firebase/firestore';
+import { type FirestoreDocOptions } from './firebase/firebase-services';
+/**
+ * A form's working version, at
+ * `hosts/{hostId}/forms/{formId}/versions/{versionId}`.
+ *
+ * Compressed at rest, and carrying the same asymmetry a component version
+ * does: the PUBLISHED tree lives on the parent `forms/{formId}` document,
+ * because a placed form has to resolve on the hot path of a page render and
+ * one collection query reaches every form on the site. These documents are
+ * editing history — the besigner's draft surface — and nothing renders from
+ * them.
+ */
+export declare const useFormVersionRef: ({ hostId, formId, versionId, }: {
+    hostId: string;
+    formId: string;
+    versionId: string;
+}) => DocumentReference<Aglyn.FormVersion>;
+export declare const useFormVersion: (data: {
+    hostId: string;
+    formId: string;
+    versionId: string;
+}, options?: FirestoreDocOptions<Aglyn.FormVersion>) => {
+    doc: import("./firebase/firebase-services").ObservableStatus<Aglyn.FormVersion<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+    setDoc: import("./helpers/use-modify-doc-callback").ModifyDocCallback<Aglyn.FormVersion<Aglyn.AglynNodeSchema<Partial<Record<JSX.Key.Any, unknown>>>>>;
+};
+export default useFormVersion;

package/src/lib/hooks/use-form-version.js

@@ -0,0 +1,73 @@
+/**
+ * @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.
+ */ // 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 { compress, decompress } from "@aglyn/aglyn";
+import { Timestamp } from "@aglyn/shared-util-timestamp";
+import { Bytes, doc } from "firebase/firestore";
+import { useFirestore } from "./firebase/firebase-services.js";
+import useDoc from "./helpers/use-doc.js";
+/**
+ * A form's working version, at
+ * `hosts/{hostId}/forms/{formId}/versions/{versionId}`.
+ *
+ * Compressed at rest, and carrying the same asymmetry a component version
+ * does: the PUBLISHED tree lives on the parent `forms/{formId}` document,
+ * because a placed form has to resolve on the hot path of a page render and
+ * one collection query reaches every form on the site. These documents are
+ * editing history — the besigner's draft surface — and nothing renders from
+ * them.
+ */ export const useFormVersionRef = ({ hostId, formId, versionId })=>{
+    const firestore = useFirestore();
+    const ref = doc(firestore, 'hosts', hostId, 'forms', formId, 'versions', versionId);
+    return ref.withConverter({
+        toFirestore (data) {
+            const { $id } = data, rest = _object_without_properties_loose(data, [
+                "$id"
+            ]);
+            // Only emit `nodes` when the write carries them — see the note in
+            // use-screen-version (AGL-1250). A partial write that compressed
+            // `undefined` would replace the stored tree with an empty one.
+            if ((rest == null ? void 0 : rest.nodes) === undefined) return _extends({}, rest, {
+                updatedAt: Timestamp.now()
+            });
+            const nodes = rest.nodes instanceof Bytes ? rest.nodes : Bytes.fromUint8Array(compress(rest.nodes));
+            return _extends({}, rest, {
+                nodes,
+                updatedAt: Timestamp.now()
+            });
+        },
+        fromFirestore (snapshot, options) {
+            if (!snapshot.exists()) return undefined;
+            const data = snapshot.data(options);
+            if ((data == null ? void 0 : data.nodes) instanceof Bytes) {
+                return _extends({}, data, {
+                    nodes: decompress(data.nodes)
+                });
+            }
+            return data;
+        }
+    });
+};
+export const useFormVersion = (data, options)=>{
+    return useDoc(useFormVersionRef(data), options);
+};
+export default useFormVersion;
+
+//# sourceMappingURL=use-form-version.js.map

package/src/lib/hooks/use-form-version.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-form-version.tsx"],"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// 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 { compress, decompress } from '@aglyn/aglyn'\nimport { Timestamp } from '@aglyn/shared-util-timestamp'\nimport type { DocumentReference } from 'firebase/firestore'\nimport { Bytes, doc } from 'firebase/firestore'\nimport {\n  useFirestore,\n  type FirestoreDocOptions,\n} from './firebase/firebase-services'\nimport useDoc from './helpers/use-doc'\n\n/**\n * A form's working version, at\n * `hosts/{hostId}/forms/{formId}/versions/{versionId}`.\n *\n * Compressed at rest, and carrying the same asymmetry a component version\n * does: the PUBLISHED tree lives on the parent `forms/{formId}` document,\n * because a placed form has to resolve on the hot path of a page render and\n * one collection query reaches every form on the site. These documents are\n * editing history — the besigner's draft surface — and nothing renders from\n * them.\n */\nexport const useFormVersionRef = ({\n  hostId,\n  formId,\n  versionId,\n}: {\n  hostId: string\n  formId: string\n  versionId: string\n}) => {\n  const firestore = useFirestore()\n  const ref = doc(\n    firestore,\n    'hosts',\n    hostId,\n    'forms',\n    formId,\n    'versions',\n    versionId,\n  )\n  return ref.withConverter({\n    toFirestore(data) {\n      const { $id, ...rest } = data\n      // Only emit `nodes` when the write carries them — see the note in\n      // use-screen-version (AGL-1250). A partial write that compressed\n      // `undefined` would replace the stored tree with an empty one.\n      if (rest?.nodes === undefined)\n        return { ...rest, updatedAt: Timestamp.now() }\n      const nodes =\n        rest.nodes instanceof Bytes\n          ? rest.nodes\n          : Bytes.fromUint8Array(compress(rest.nodes))\n      return { ...rest, nodes, updatedAt: Timestamp.now() }\n    },\n    fromFirestore(snapshot, options) {\n      if (!snapshot.exists()) return undefined\n      const data = snapshot.data(options)\n      if (data?.nodes instanceof Bytes) {\n        return {\n          ...data,\n          nodes: decompress(data.nodes),\n        } as Aglyn.FormVersion\n      }\n      return data as Aglyn.FormVersion\n    },\n  }) as DocumentReference<Aglyn.FormVersion>\n}\n\nexport const useFormVersion = (\n  data: {\n    hostId: string\n    formId: string\n    versionId: string\n  },\n  options?: FirestoreDocOptions<Aglyn.FormVersion>,\n) => {\n  return useDoc(useFormVersionRef(data), options)\n}\n\nexport default useFormVersion\n"],"names":["compress","decompress","Timestamp","Bytes","doc","useFirestore","useDoc","useFormVersionRef","hostId","formId","versionId","firestore","ref","withConverter","toFirestore","data","$id","rest","nodes","undefined","updatedAt","now","fromUint8Array","fromFirestore","snapshot","options","exists","useFormVersion"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;;;AAExE,SAASA,QAAQ,EAAEC,UAAU,QAAQ,eAAc;AACnD,SAASC,SAAS,QAAQ,+BAA8B;AAExD,SAASC,KAAK,EAAEC,GAAG,QAAQ,qBAAoB;AAC/C,SACEC,YAAY,QAEP,kCAA8B;AACrC,OAAOC,YAAY,uBAAmB;AAEtC;;;;;;;;;;CAUC,GACD,OAAO,MAAMC,oBAAoB,CAAC,EAChCC,MAAM,EACNC,MAAM,EACNC,SAAS,EAKV;IACC,MAAMC,YAAYN;IAClB,MAAMO,MAAMR,IACVO,WACA,SACAH,QACA,SACAC,QACA,YACAC;IAEF,OAAOE,IAAIC,aAAa,CAAC;QACvBC,aAAYC,IAAI;YACd,MAAM,EAAEC,GAAG,EAAW,GAAGD,MAATE,wCAASF;;;YACzB,kEAAkE;YAClE,iEAAiE;YACjE,+DAA+D;YAC/D,IAAIE,CAAAA,wBAAAA,KAAMC,KAAK,MAAKC,WAClB,OAAO,aAAKF;gBAAMG,WAAWlB,UAAUmB,GAAG;;YAC5C,MAAMH,QACJD,KAAKC,KAAK,YAAYf,QAClBc,KAAKC,KAAK,GACVf,MAAMmB,cAAc,CAACtB,SAASiB,KAAKC,KAAK;YAC9C,OAAO,aAAKD;gBAAMC;gBAAOE,WAAWlB,UAAUmB,GAAG;;QACnD;QACAE,eAAcC,QAAQ,EAAEC,OAAO;YAC7B,IAAI,CAACD,SAASE,MAAM,IAAI,OAAOP;YAC/B,MAAMJ,OAAOS,SAAST,IAAI,CAACU;YAC3B,IAAIV,CAAAA,wBAAAA,KAAMG,KAAK,aAAYf,OAAO;gBAChC,OAAO,aACFY;oBACHG,OAAOjB,WAAWc,KAAKG,KAAK;;YAEhC;YACA,OAAOH;QACT;IACF;AACF,EAAC;AAED,OAAO,MAAMY,iBAAiB,CAC5BZ,MAKAU;IAEA,OAAOnB,OAAOC,kBAAkBQ,OAAOU;AACzC,EAAC;AAED,eAAeE,eAAc"}

package/src/lib/hooks/use-host-activity-logger.d.ts

@@ -0,0 +1,35 @@
+/** What an activity entry points at; `id` lets detail pages filter. */
+export interface HostActivityTarget {
+    type: 'host' | 'screen' | 'layout' | 'theme' | 'media' | 'content' | 'variable' | 'function' | 'workflow' | 'member' | 'component' | 'template' | 'contact' | 'company' | 'deal' | 'lead';
+    id?: string;
+    name?: string;
+    /**
+     * Version-addressed targets (screens) record this so the feed can deep-link
+     * straight to the exact version's detail view (AGL-812). Written only when
+     * truthy, like `id`/`name`.
+     */
+    versionId?: string;
+}
+/**
+ * User activity log (AGL-118): fire-and-forget appends to
+ * `hosts/{hostId}/activity` from console mutation points. Never throws —
+ * an audit miss must not break the edit that triggered it. Covered by the
+ * host-admin wildcard rule, so no rules change is needed.
+ *
+ * `activity` is deliberately absent from the host catch-all's create
+ * exclusion list, so a member holding a content role writes here directly.
+ * `cloud/rules-tests/firestore-rules.test.mjs` pins that on both sides —
+ * the roles that may append and the roles that may not.
+ *
+ * An append needs an ACTOR, and the rule that admits it needs one too:
+ * `canWriteHostContent` resolves the writer's host role out of
+ * `memberRoles[request.auth.uid]`, so a request carrying no auth matches no
+ * role and is refused. `useUser()` reports `undefined` until
+ * `onIdTokenChanged` first fires and `null` once it reports a signed-out
+ * tab, and in both states the entry has nobody to attribute — so the append
+ * is skipped rather than sent to be denied. An unattributed audit line is
+ * not a smaller version of an audit line; it records that something happened
+ * and refuses to say who did it, which is the one field the log exists for.
+ */
+export declare function useHostActivityLogger(hostId: string | undefined): (action: string, target: HostActivityTarget) => void;
+export default useHostActivityLogger;

package/src/lib/hooks/use-host-activity-logger.js

@@ -0,0 +1,96 @@
+/**
+ * @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 { reportHandledError } from "@aglyn/aglyn/app-utils/error-beacon";
+import { Timestamp } from "@aglyn/shared-util-timestamp";
+import { addDoc, collection } from "firebase/firestore";
+import { useCallback } from "react";
+import { useFirestore, useUser } from "./firebase/firebase-services.js";
+/** One console line per session, however many appends fail. */ let announced = false;
+/**
+ * What a dropped audit append does instead of nothing.
+ *
+ * The append stays fire-and-forget: an audit miss must never break the edit
+ * that triggered it, and a snackbar about the LOG would be a worse answer to
+ * "your page saved" than silence. But a rejection with nowhere to go is a
+ * feature that can break for months without a single signal, so the failure
+ * leaves by two doors that cost the person nothing.
+ *
+ * The beacon is the durable one — it reaches Cloud Error Reporting, dedupes a
+ * failure that repeats on every edit into one report, and caps itself, so a
+ * permission denial shows up as a graph instead of a support ticket. The
+ * console line is for whoever has devtools open, and fires once: the second
+ * failure carries no information the first did not, and a message per edit
+ * buries the diagnostics that do.
+ */ function reportDroppedEntry(error) {
+    reportHandledError(error, {
+        kind: 'host-activity-write'
+    });
+    if (announced) return;
+    announced = true;
+    console.error('Activity logging failed; entries from this session are being dropped.', error);
+}
+/**
+ * User activity log (AGL-118): fire-and-forget appends to
+ * `hosts/{hostId}/activity` from console mutation points. Never throws —
+ * an audit miss must not break the edit that triggered it. Covered by the
+ * host-admin wildcard rule, so no rules change is needed.
+ *
+ * `activity` is deliberately absent from the host catch-all's create
+ * exclusion list, so a member holding a content role writes here directly.
+ * `cloud/rules-tests/firestore-rules.test.mjs` pins that on both sides —
+ * the roles that may append and the roles that may not.
+ *
+ * An append needs an ACTOR, and the rule that admits it needs one too:
+ * `canWriteHostContent` resolves the writer's host role out of
+ * `memberRoles[request.auth.uid]`, so a request carrying no auth matches no
+ * role and is refused. `useUser()` reports `undefined` until
+ * `onIdTokenChanged` first fires and `null` once it reports a signed-out
+ * tab, and in both states the entry has nobody to attribute — so the append
+ * is skipped rather than sent to be denied. An unattributed audit line is
+ * not a smaller version of an audit line; it records that something happened
+ * and refuses to say who did it, which is the one field the log exists for.
+ */ export function useHostActivityLogger(hostId) {
+    const firestore = useFirestore();
+    const { data: user } = useUser();
+    return useCallback((action, target)=>{
+        var _user_email;
+        if (!hostId || !user) return;
+        void addDoc(collection(firestore, 'hosts', hostId, 'activity'), {
+            actorId: user.uid,
+            actorEmail: (_user_email = user.email) != null ? _user_email : null,
+            action,
+            target: _extends({
+                type: target.type
+            }, target.id ? {
+                id: target.id
+            } : {}, target.name ? {
+                name: target.name
+            } : {}, target.versionId ? {
+                versionId: target.versionId
+            } : {}),
+            createdAt: Timestamp.now()
+        }).catch(reportDroppedEntry);
+    }, [
+        firestore,
+        hostId,
+        user
+    ]);
+}
+export default useHostActivityLogger;
+
+//# sourceMappingURL=use-host-activity-logger.js.map

package/src/lib/hooks/use-host-activity-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/use-host-activity-logger.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 { reportHandledError } from '@aglyn/aglyn/app-utils/error-beacon'\nimport { Timestamp } from '@aglyn/shared-util-timestamp'\nimport { addDoc, collection } from 'firebase/firestore'\nimport { useCallback } from 'react'\nimport { useFirestore, useUser } from './firebase/firebase-services'\n\n/** What an activity entry points at; `id` lets detail pages filter. */\nexport interface HostActivityTarget {\n  type:\n    | 'host'\n    | 'screen'\n    | 'layout'\n    | 'theme'\n    | 'media'\n    | 'content'\n    | 'variable'\n    | 'function'\n    | 'workflow'\n    | 'member'\n    // Standalone editors (AGL-680/681) — both are edited on their own now,\n    // so their saves belong in the same log as screens and layouts.\n    | 'component'\n    | 'template'\n    // A person on the CRM record page (AGL-2596): added by hand, edited, or\n    // removed from the site. The record is org-shared, but the act happened\n    // in THIS site's console and belongs in this site's feed.\n    | 'contact'\n    // The rest of the CRM (AGL-2622): a company or a deal created or deleted\n    // from this site's console — one at a time, or one line per record from\n    // the bulk bars (AGL-2621) — and a lead converted into the three. Org\n    // data all of them, filed under the site whose console did the work for\n    // the reason a contact is.\n    | 'company'\n    | 'deal'\n    | 'lead'\n  id?: string\n  name?: string\n  /**\n   * Version-addressed targets (screens) record this so the feed can deep-link\n   * straight to the exact version's detail view (AGL-812). Written only when\n   * truthy, like `id`/`name`.\n   */\n  versionId?: string\n}\n\n/** One console line per session, however many appends fail. */\nlet announced = false\n\n/**\n * What a dropped audit append does instead of nothing.\n *\n * The append stays fire-and-forget: an audit miss must never break the edit\n * that triggered it, and a snackbar about the LOG would be a worse answer to\n * \"your page saved\" than silence. But a rejection with nowhere to go is a\n * feature that can break for months without a single signal, so the failure\n * leaves by two doors that cost the person nothing.\n *\n * The beacon is the durable one — it reaches Cloud Error Reporting, dedupes a\n * failure that repeats on every edit into one report, and caps itself, so a\n * permission denial shows up as a graph instead of a support ticket. The\n * console line is for whoever has devtools open, and fires once: the second\n * failure carries no information the first did not, and a message per edit\n * buries the diagnostics that do.\n */\nfunction reportDroppedEntry(error: unknown): void {\n  reportHandledError(error, { kind: 'host-activity-write' })\n  if (announced) return\n  announced = true\n  console.error(\n    'Activity logging failed; entries from this session are being dropped.',\n    error,\n  )\n}\n\n/**\n * User activity log (AGL-118): fire-and-forget appends to\n * `hosts/{hostId}/activity` from console mutation points. Never throws —\n * an audit miss must not break the edit that triggered it. Covered by the\n * host-admin wildcard rule, so no rules change is needed.\n *\n * `activity` is deliberately absent from the host catch-all's create\n * exclusion list, so a member holding a content role writes here directly.\n * `cloud/rules-tests/firestore-rules.test.mjs` pins that on both sides —\n * the roles that may append and the roles that may not.\n *\n * An append needs an ACTOR, and the rule that admits it needs one too:\n * `canWriteHostContent` resolves the writer's host role out of\n * `memberRoles[request.auth.uid]`, so a request carrying no auth matches no\n * role and is refused. `useUser()` reports `undefined` until\n * `onIdTokenChanged` first fires and `null` once it reports a signed-out\n * tab, and in both states the entry has nobody to attribute — so the append\n * is skipped rather than sent to be denied. An unattributed audit line is\n * not a smaller version of an audit line; it records that something happened\n * and refuses to say who did it, which is the one field the log exists for.\n */\nexport function useHostActivityLogger(hostId: string | undefined) {\n  const firestore = useFirestore()\n  const { data: user } = useUser()\n  return useCallback(\n    (action: string, target: HostActivityTarget) => {\n      if (!hostId || !user) return\n      void addDoc(collection(firestore, 'hosts', hostId, 'activity'), {\n        actorId: user.uid,\n        actorEmail: user.email ?? null,\n        action,\n        target: {\n          type: target.type,\n          ...(target.id ? { id: target.id } : {}),\n          ...(target.name ? { name: target.name } : {}),\n          ...(target.versionId ? { versionId: target.versionId } : {}),\n        },\n        createdAt: Timestamp.now(),\n      }).catch(reportDroppedEntry)\n    },\n    [firestore, hostId, user],\n  )\n}\n\nexport default useHostActivityLogger\n"],"names":["reportHandledError","Timestamp","addDoc","collection","useCallback","useFirestore","useUser","announced","reportDroppedEntry","error","kind","console","useHostActivityLogger","hostId","firestore","data","user","action","target","actorId","uid","actorEmail","email","type","id","name","versionId","createdAt","now","catch"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SAASA,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,SAAS,QAAQ,+BAA8B;AACxD,SAASC,MAAM,EAAEC,UAAU,QAAQ,qBAAoB;AACvD,SAASC,WAAW,QAAQ,QAAO;AACnC,SAASC,YAAY,EAAEC,OAAO,QAAQ,kCAA8B;AAyCpE,6DAA6D,GAC7D,IAAIC,YAAY;AAEhB;;;;;;;;;;;;;;;CAeC,GACD,SAASC,mBAAmBC,KAAc;IACxCT,mBAAmBS,OAAO;QAAEC,MAAM;IAAsB;IACxD,IAAIH,WAAW;IACfA,YAAY;IACZI,QAAQF,KAAK,CACX,yEACAA;AAEJ;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASG,sBAAsBC,MAA0B;IAC9D,MAAMC,YAAYT;IAClB,MAAM,EAAEU,MAAMC,IAAI,EAAE,GAAGV;IACvB,OAAOF,YACL,CAACa,QAAgBC;YAIDF;QAHd,IAAI,CAACH,UAAU,CAACG,MAAM;QACtB,KAAKd,OAAOC,WAAWW,WAAW,SAASD,QAAQ,aAAa;YAC9DM,SAASH,KAAKI,GAAG;YACjBC,UAAU,GAAEL,cAAAA,KAAKM,KAAK,YAAVN,cAAc;YAC1BC;YACAC,QAAQ;gBACNK,MAAML,OAAOK,IAAI;eACbL,OAAOM,EAAE,GAAG;gBAAEA,IAAIN,OAAOM,EAAE;YAAC,IAAI,CAAC,GACjCN,OAAOO,IAAI,GAAG;gBAAEA,MAAMP,OAAOO,IAAI;YAAC,IAAI,CAAC,GACvCP,OAAOQ,SAAS,GAAG;gBAAEA,WAAWR,OAAOQ,SAAS;YAAC,IAAI,CAAC;YAE5DC,WAAW1B,UAAU2B,GAAG;QAC1B,GAAGC,KAAK,CAACrB;IACX,GACA;QAACM;QAAWD;QAAQG;KAAK;AAE7B;AAEA,eAAeJ,sBAAqB"}

package/src/lib/hooks/use-host-campaigns.d.ts

@@ -0,0 +1,53 @@
+/**
+ * How many campaigns a picker offers.
+ *
+ * The same fifty the campaigns table draws, so a campaign a merchant can see
+ * in the list is a campaign they can file a record under. A picker with a
+ * larger window would offer campaigns the list they came from does not show;
+ * a smaller one would hide campaigns that are plainly there.
+ */
+export declare const HOST_CAMPAIGN_CEILING = 50;
+/** One campaign, as much of it as a picker needs. */
+export interface HostCampaignOption {
+    value: string;
+    label: string;
+    /** The campaign window, for a caller that wants to say when it ran. */
+    startAtMs?: number | null;
+    endAtMs?: number | null;
+}
+export interface HostCampaigns {
+    options: HostCampaignOption[];
+    /** The site holds more campaigns than the ceiling offers. */
+    truncated: boolean;
+    /** The read has answered — false while it is still settling or disabled. */
+    ready: boolean;
+}
+/**
+ * THE SITE'S CAMPAIGNS, for a picker on some other record's page.
+ *
+ * Lives here rather than in the marketing plugin because the console app may
+ * not import a feature plugin — a screen's detail page is an app route — and
+ * the form and contact surfaces that need the same list are two other
+ * libraries again. One read, one shape, three callers.
+ *
+ * ## It is OFF unless a caller asks
+ *
+ * `enabled` defaults to false. The picker this feeds sits on a record's own
+ * page beside fields a reader came for; charging every open of a form, a
+ * screen or a contact for a hundred campaign documents they may not touch is
+ * the read-on-mount this console refuses. The callers turn it on when their
+ * editing surface opens.
+ *
+ * ## Ordered on the document name
+ *
+ * `collectionCeiling`, for the reason it exists: `startAtMs` and `endAtMs`
+ * are both optional on a campaign — an open-ended one carries neither — so
+ * ordering on a date would not mis-sort the picker, it would DROP the
+ * campaigns that have no dates. The labels are sorted by name here, over the
+ * whole ceiling rather than a slice of it, which is the one case sorting a
+ * window is honest.
+ */
+export declare function useHostCampaigns(hostId: string | undefined, options?: {
+    enabled?: boolean;
+}): HostCampaigns;
+export default useHostCampaigns;