@alneas/appkit-react 0.1.0 → 0.3.0

package/dist/tools/components/auth/auth-session.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth-session.cjs","names":["CancelledError","_tanstack_react_query","createAuthSession","principal","revision","epoch","active","listeners","sessionFilter","accept","nextPrincipal","user","filter","query","queryClient","queryKey","listener","publish","started","adapter","signal","result","action","loggedOut"],"sources":["../../../../src/tools/components/auth/auth-session.ts"],"sourcesContent":["import { CancelledError, type QueryClient } from '@tanstack/react-query';\nimport type { AuthAdapter, User } from './types';\n\n/** Internal session coordinator. Only verified adapter results determine principal changes. */\nexport function createAuthSession(\n  queryClient: QueryClient,\n  adapter: AuthAdapter,\n  queryKey: readonly string[],\n) {\n  let principal: string | null | undefined;\n  let revision = 0;\n  let epoch = 0;\n  let active = true;\n  const listeners = new Set<() => void>();\n  const sessionFilter = { queryKey, exact: true };\n\n  const accept = (user: User | null) => {\n    const nextPrincipal = user?.id ?? null;\n    if (principal !== nextPrincipal) {\n      // A QueryClient is an auth boundary: arbitrary application query keys can contain private data.\n      // Preserve other isolated session queries, but cancel/remove all application queries before\n      // exposing the new principal. Cancellation prevents even signal-ignoring promises writing back.\n      const filter = {\n        predicate: (query: { queryKey: readonly unknown[] }) =>\n          !(query.queryKey[0] === 'session' && query.queryKey[1] === 'react-tools.auth'),\n      };\n      void queryClient.cancelQueries(filter);\n      queryClient.removeQueries(filter);\n      principal = nextPrincipal;\n      epoch += 1;\n      queryClient.setQueryData(queryKey, user);\n      listeners.forEach((listener) => listener());\n    } else {\n      queryClient.setQueryData(queryKey, user);\n    }\n    return user;\n  };\n\n  const publish = (user: User | null) => {\n    if (!active) return;\n    revision += 1;\n    void queryClient.cancelQueries(sessionFilter);\n    accept(user);\n  };\n\n  return {\n    queryKey,\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getSnapshot: () => epoch,\n    getServerSnapshot: () => 0,\n    activate() {\n      active = true;\n    },\n    deactivate() {\n      active = false;\n      revision += 1;\n      void queryClient.cancelQueries(sessionFilter);\n    },\n    publish,\n    async read(signal: AbortSignal) {\n      const started = revision;\n      const user = await adapter.getCurrentUser();\n      if (!active || signal.aborted || revision !== started) {\n        throw new CancelledError({ revert: true });\n      }\n      return accept(user);\n    },\n    async run<T extends User | null | void>(\n      action: () => Promise<T>,\n      loggedOut = false,\n    ): Promise<T> {\n      const started = ++revision;\n      void queryClient.cancelQueries(sessionFilter);\n      try {\n        const result = await action();\n        // An intervening auth event/action is newer than this operation's result.\n        if (active && revision === started) {\n          if (loggedOut) publish(null);\n          else if (result) publish(result);\n        }\n        return result;\n      } finally {\n        // Failed actions or redirect-only OAuth results must not strand the cancelled initial read.\n        if (active && revision === started) {\n          void queryClient.invalidateQueries(sessionFilter);\n        }\n      }\n    },\n  };\n}\n"],"mappings":"A,uHAIA,SAAgBE,EACd,EACA,EACA,EACA,CACA,IAAIC,EACAC,EAAW,EACXC,EAAQ,EACRC,EAAS,GACPC,EAAY,IAAI,IAChBC,EAAgB,CAAE,WAAU,MAAO,EAAK,EAExCC,EAAU,GAAsB,CACpC,IAAMC,EAAgBC,GAAM,IAAM,KAClC,GAAIR,IAAcO,EAAe,CAI/B,IAAME,EAAS,CACb,UAAY,GACRC,EAAM,SAAS,KAAO,WAAaA,EAAM,SAAS,KAAO,kBAC/D,EACAC,EAAiB,cAAcF,CAAM,EACrCE,EAAY,cAAcF,CAAM,EAChC,EAAYF,EACZ,GAAS,EACTI,EAAY,aAAaC,EAAUJ,CAAI,EACvCJ,EAAU,QAAS,GAAaS,EAAS,CAAC,CAC5C,MACEF,EAAY,aAAaC,EAAUJ,CAAI,EAEzC,OAAOA,CACT,EAEMM,EAAW,GAAsB,CAChCX,IACL,GAAY,EACZQ,EAAiB,cAAcN,CAAa,EAC5CC,EAAOE,CAAI,EACb,EAEA,MAAO,CACL,WACA,UAAU,EAAsB,CAE9B,OADAJ,EAAU,IAAIS,CAAQ,MACT,CACXT,EAAU,OAAOS,CAAQ,CAC3B,CACF,EACA,gBAAmBX,EACnB,sBAAyB,EACzB,UAAW,CACT,EAAS,EACX,EACA,YAAa,CACX,EAAS,GACT,GAAY,EACZS,EAAiB,cAAcN,CAAa,CAC9C,EACA,UACA,MAAM,KAAK,EAAqB,CAC9B,IAAMU,EAAUd,EACVO,EAAO,MAAMQ,EAAQ,eAAe,EAC1C,GAAI,CAACb,GAAUc,EAAO,SAAWhB,IAAac,EAC5C,MAAM,IAAIlB,EAAAA,eAAe,CAAE,OAAQ,EAAK,CAAC,EAE3C,OAAOS,EAAOE,CAAI,CACpB,EACA,MAAM,IACJ,EACA,EAAY,GACA,CACZ,IAAMO,EAAU,EAAEd,EAClBU,EAAiB,cAAcN,CAAa,EAC5C,GAAI,CACF,IAAMa,EAAS,MAAMC,EAAO,EAM5B,OAJIhB,GAAUF,IAAac,IACrBK,EAAWN,EAAQ,IAAI,EAClBI,GAAQJ,EAAQI,CAAM,GAE1BA,CACT,QAAU,CAEJf,GAAUF,IAAac,GACzBJ,EAAiB,kBAAkBN,CAAa,CAEpD,CACF,CACF,CACF,C"}
+{"version":3,"file":"auth-session.cjs","names":["CancelledError","_tanstack_react_query","createAuthSession","principal","revision","epoch","active","listeners","sessionFilter","accept","nextPrincipal","user","filter","query","queryClient","queryKey","listener","publish","started","adapter","signal","result","action","loggedOut"],"sources":["../../../../src/tools/components/auth/auth-session.ts"],"sourcesContent":["import { CancelledError, type QueryClient } from '@tanstack/react-query';\nimport type { AuthAdapter, User } from './types';\n\n/**\n * Creates a principal-transition coordinator for one AuthProvider session query.\n *\n * @param queryClient - Auth-domain query cache; application queries are removed on initial/principal verification.\n *\n * @param adapter - Host authentication adapter supplying the verified user.\n *\n * @param queryKey - Exact session query key owned by this coordinator.\n *\n * @returns Coordinator with subscription, epoch snapshots, lifecycle, verified reads and tracked actions.\n *\n * @remarks Although exported, this is a low-level provider helper. Principal changes cancel\n * and remove non-session queries, then publish the user and increment epoch. Same-user\n * refreshes preserve application state. Revisions discard stale reads/actions but cannot\n * undo backend work. Backend authorization is host-owned. No styles are required.\n *\n * @example\n * ```ts\n * import { QueryClient } from '@tanstack/react-query';\n * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n * export async function verify(adapter: AuthAdapter) {\n *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n *   try { return await session.read(new AbortController().signal); }\n *   finally { session.deactivate(); }\n * }\n * ```\n */\nexport function createAuthSession(\n  queryClient: QueryClient,\n  adapter: AuthAdapter,\n  queryKey: readonly string[],\n) {\n  let principal: string | null | undefined;\n  let revision = 0;\n  let epoch = 0;\n  let active = true;\n  const listeners = new Set<() => void>();\n  const sessionFilter = { queryKey, exact: true };\n\n  const accept = (user: User | null) => {\n    const nextPrincipal = user?.id ?? null;\n    if (principal !== nextPrincipal) {\n      // A QueryClient is an auth boundary: arbitrary application query keys can contain private data.\n      // Preserve other isolated session queries, but cancel/remove all application queries before\n      // exposing the new principal. Cancellation prevents even signal-ignoring promises writing back.\n      const filter = {\n        predicate: (query: { queryKey: readonly unknown[] }) =>\n          !(query.queryKey[0] === 'session' && query.queryKey[1] === 'react-tools.auth'),\n      };\n      void queryClient.cancelQueries(filter);\n      queryClient.removeQueries(filter);\n      principal = nextPrincipal;\n      epoch += 1;\n      queryClient.setQueryData(queryKey, user);\n      listeners.forEach((listener) => listener());\n    } else {\n      queryClient.setQueryData(queryKey, user);\n    }\n    return user;\n  };\n\n/**\n * Accepts a verified adapter event when active, superseding any pending session read.\n *\n * @param user - Adapter-confirmed user or null.\n *\n * @returns No value; inactive coordinators ignore the event.\n *\n * @remarks Current-user changes reset application query state; backend validity is host-owned.\n *\n * @example\n * ```ts\n * import { QueryClient } from '@tanstack/react-query';\n * import { createAuthSession, type AuthAdapter, type User } from '@alneas/appkit-react/tools/auth';\n * export function publishVerified(adapter: AuthAdapter, user: User | null) {\n *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'events']);\n *   session.publish(user);\n *   session.deactivate();\n * }\n * ```\n */\n  const publish = (user: User | null) => {\n    if (!active) return;\n    revision += 1;\n    void queryClient.cancelQueries(sessionFilter);\n    accept(user);\n  };\n\n  return {\n    /**\n     * Exact session query key supplied by the caller.\n     */\n    queryKey,\n    /**\n     * Observe principal epoch changes.\n     *\n     * @param listener - Synchronous callback after a changed principal is accepted.\n     *\n     * @returns Cleanup removing this listener.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     const stop = session.subscribe(() => console.log(session.getSnapshot()));\n     *   stop();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    /**\n     * Read the current principal-transition epoch.\n     *\n     * @returns Monotonic epoch starting at zero.\n     */\n    getSnapshot: () => epoch,\n    /**\n     * Supply the stable server epoch.\n     *\n     * @returns Zero for SSR.\n     */\n    getServerSnapshot: () => 0,\n    /**\n     * Enable publication of adapter results.\n     *\n     * @returns No value; future verified reads/events may publish.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     session.activate();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    activate() {\n      active = true;\n    },\n    /**\n     * Disable publication and cancel this session query.\n     *\n     * @returns No value; in-flight backend work is not rolled back.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     session.deactivate();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    deactivate() {\n      active = false;\n      revision += 1;\n      void queryClient.cancelQueries(sessionFilter);\n    },\n    /**\n     * Publish an adapter auth event when active, cancelling any older session read.\n     *\n     * @param user - Verified user or null supplied by the adapter.\n     *\n     * @returns No value.\n     */\n    publish,\n    /**\n     * Read and accept the latest adapter user.\n     *\n     * @param signal - Query abort signal checked after the adapter request completes.\n     *\n     * @returns Verified user or null.\n     *\n     * @throws Rejects on adapter errors or cancellation/stale revision via CancelledError.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     await session.read(new AbortController().signal);\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    async read(signal: AbortSignal) {\n      const started = revision;\n      const user = await adapter.getCurrentUser();\n      if (!active || signal.aborted || revision !== started) {\n        throw new CancelledError({ revert: true });\n      }\n      return accept(user);\n    },\n    /**\n     * Run a host auth action and publish its result if still current.\n     *\n     * @typeParam T - User, null or void result of the host auth action.\n     *\n     * @param action - Asynchronous adapter operation, invoked once.\n     *\n     * @param loggedOut - Publish null on success instead of a user result; defaults to false.\n     *\n     * @returns Original host operation result, even if a newer revision prevents publication.\n     *\n     * @throws Rejects with the host action error; pending verification is invalidated afterward.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     await session.run(() => adapter.getCurrentUser());\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    async run<T extends User | null | void>(\n      action: () => Promise<T>,\n      loggedOut = false,\n    ): Promise<T> {\n      const started = ++revision;\n      void queryClient.cancelQueries(sessionFilter);\n      try {\n        const result = await action();\n        // An intervening auth event/action is newer than this operation's result.\n        if (active && revision === started) {\n          if (loggedOut) publish(null);\n          else if (result) publish(result);\n        }\n        return result;\n      } finally {\n        // Failed actions or redirect-only OAuth results must not strand the cancelled initial read.\n        if (active && revision === started) {\n          void queryClient.invalidateQueries(sessionFilter);\n        }\n      }\n    },\n  };\n}\n"],"mappings":"A,uHA8BA,SAAgBE,EACd,EACA,EACA,EACA,CACA,IAAIC,EACAC,EAAW,EACXC,EAAQ,EACRC,EAAS,GACPC,EAAY,IAAI,IAChBC,EAAgB,CAAE,WAAU,MAAO,EAAK,EAExCC,EAAU,GAAsB,CACpC,IAAMC,EAAgBC,GAAM,IAAM,KAClC,GAAIR,IAAcO,EAAe,CAI/B,IAAME,EAAS,CACb,UAAY,GACRC,EAAM,SAAS,KAAO,WAAaA,EAAM,SAAS,KAAO,kBAC/D,EACAC,EAAiB,cAAcF,CAAM,EACrCE,EAAY,cAAcF,CAAM,EAChC,EAAYF,EACZ,GAAS,EACTI,EAAY,aAAaC,EAAUJ,CAAI,EACvCJ,EAAU,QAAS,GAAaS,EAAS,CAAC,CAC5C,MACEF,EAAY,aAAaC,EAAUJ,CAAI,EAEzC,OAAOA,CACT,EAsBMM,EAAW,GAAsB,CAChCX,IACL,GAAY,EACZQ,EAAiB,cAAcN,CAAa,EAC5CC,EAAOE,CAAI,EACb,EAEA,MAAO,CAIL,WAqBA,UAAU,EAAsB,CAE9B,OADAJ,EAAU,IAAIS,CAAQ,MACT,CACXT,EAAU,OAAOS,CAAQ,CAC3B,CACF,EAMA,gBAAmBX,EAMnB,sBAAyB,EAkBzB,UAAW,CACT,EAAS,EACX,EAkBA,YAAa,CACX,EAAS,GACT,GAAY,EACZS,EAAiB,cAAcN,CAAa,CAC9C,EAQA,UAsBA,MAAM,KAAK,EAAqB,CAC9B,IAAMU,EAAUd,EACVO,EAAO,MAAMQ,EAAQ,eAAe,EAC1C,GAAI,CAACb,GAAUc,EAAO,SAAWhB,IAAac,EAC5C,MAAM,IAAIlB,EAAAA,eAAe,CAAE,OAAQ,EAAK,CAAC,EAE3C,OAAOS,EAAOE,CAAI,CACpB,EA0BA,MAAM,IACJ,EACA,EAAY,GACA,CACZ,IAAMO,EAAU,EAAEd,EAClBU,EAAiB,cAAcN,CAAa,EAC5C,GAAI,CACF,IAAMa,EAAS,MAAMC,EAAO,EAM5B,OAJIhB,GAAUF,IAAac,IACrBK,EAAWN,EAAQ,IAAI,EAClBI,GAAQJ,EAAQI,CAAM,GAE1BA,CACT,QAAU,CAEJf,GAAUF,IAAac,GACzBJ,EAAiB,kBAAkBN,CAAa,CAEpD,CACF,CACF,CACF,C"}

package/dist/tools/components/auth/auth-session.d.cts

@@ -1,14 +1,135 @@
 import { QueryClient } from '@tanstack/react-query';
 import { AuthAdapter, User } from './types.cjs';
-/** Internal session coordinator. Only verified adapter results determine principal changes. */
+/**
+ * Creates a principal-transition coordinator for one AuthProvider session query.
+ *
+ * @param queryClient - Auth-domain query cache; application queries are removed on initial/principal verification.
+ *
+ * @param adapter - Host authentication adapter supplying the verified user.
+ *
+ * @param queryKey - Exact session query key owned by this coordinator.
+ *
+ * @returns Coordinator with subscription, epoch snapshots, lifecycle, verified reads and tracked actions.
+ *
+ * @remarks Although exported, this is a low-level provider helper. Principal changes cancel
+ * and remove non-session queries, then publish the user and increment epoch. Same-user
+ * refreshes preserve application state. Revisions discard stale reads/actions but cannot
+ * undo backend work. Backend authorization is host-owned. No styles are required.
+ *
+ * @example
+ * ```ts
+ * import { QueryClient } from '@tanstack/react-query';
+ * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+ * export async function verify(adapter: AuthAdapter) {
+ *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+ *   try { return await session.read(new AbortController().signal); }
+ *   finally { session.deactivate(); }
+ * }
+ * ```
+ */
 export declare function createAuthSession(queryClient: QueryClient, adapter: AuthAdapter, queryKey: readonly string[]): {
+    /**
+     * Exact session query key supplied by the caller.
+     */
     queryKey: readonly string[];
+    /**
+     * Observe principal epoch changes.
+     *
+     * @param listener - Synchronous callback after a changed principal is accepted.
+     *
+     * @returns Cleanup removing this listener.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     const stop = session.subscribe(() => console.log(session.getSnapshot()));
+     *   stop();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     subscribe(listener: () => void): () => void;
+    /**
+     * Read the current principal-transition epoch.
+     *
+     * @returns Monotonic epoch starting at zero.
+     */
     getSnapshot: () => number;
+    /**
+     * Supply the stable server epoch.
+     *
+     * @returns Zero for SSR.
+     */
     getServerSnapshot: () => number;
+    /**
+     * Enable publication of adapter results.
+     *
+     * @returns No value; future verified reads/events may publish.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     session.activate();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     activate(): void;
+    /**
+     * Disable publication and cancel this session query.
+     *
+     * @returns No value; in-flight backend work is not rolled back.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     session.deactivate();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     deactivate(): void;
+    /**
+     * Publish an adapter auth event when active, cancelling any older session read.
+     *
+     * @param user - Verified user or null supplied by the adapter.
+     *
+     * @returns No value.
+     */
     publish: (user: User | null) => void;
+    /**
+     * Read and accept the latest adapter user.
+     *
+     * @param signal - Query abort signal checked after the adapter request completes.
+     *
+     * @returns Verified user or null.
+     *
+     * @throws Rejects on adapter errors or cancellation/stale revision via CancelledError.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     await session.read(new AbortController().signal);
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     read(signal: AbortSignal): Promise<{
         id: string;
         email: string;
@@ -18,5 +139,30 @@ export declare function createAuthSession(queryClient: QueryClient, adapter: Aut
         emailVerified?: boolean | undefined;
         metadata?: Record<string, any> | undefined;
     } | null>;
+    /**
+     * Run a host auth action and publish its result if still current.
+     *
+     * @typeParam T - User, null or void result of the host auth action.
+     *
+     * @param action - Asynchronous adapter operation, invoked once.
+     *
+     * @param loggedOut - Publish null on success instead of a user result; defaults to false.
+     *
+     * @returns Original host operation result, even if a newer revision prevents publication.
+     *
+     * @throws Rejects with the host action error; pending verification is invalidated afterward.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     await session.run(() => adapter.getCurrentUser());
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     run<T extends User | null | void>(action: () => Promise<T>, loggedOut?: boolean): Promise<T>;
 };

package/dist/tools/components/auth/auth-session.d.ts

@@ -1,14 +1,135 @@
 import { QueryClient } from '@tanstack/react-query';
 import { AuthAdapter, User } from './types.js';
-/** Internal session coordinator. Only verified adapter results determine principal changes. */
+/**
+ * Creates a principal-transition coordinator for one AuthProvider session query.
+ *
+ * @param queryClient - Auth-domain query cache; application queries are removed on initial/principal verification.
+ *
+ * @param adapter - Host authentication adapter supplying the verified user.
+ *
+ * @param queryKey - Exact session query key owned by this coordinator.
+ *
+ * @returns Coordinator with subscription, epoch snapshots, lifecycle, verified reads and tracked actions.
+ *
+ * @remarks Although exported, this is a low-level provider helper. Principal changes cancel
+ * and remove non-session queries, then publish the user and increment epoch. Same-user
+ * refreshes preserve application state. Revisions discard stale reads/actions but cannot
+ * undo backend work. Backend authorization is host-owned. No styles are required.
+ *
+ * @example
+ * ```ts
+ * import { QueryClient } from '@tanstack/react-query';
+ * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+ * export async function verify(adapter: AuthAdapter) {
+ *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+ *   try { return await session.read(new AbortController().signal); }
+ *   finally { session.deactivate(); }
+ * }
+ * ```
+ */
 export declare function createAuthSession(queryClient: QueryClient, adapter: AuthAdapter, queryKey: readonly string[]): {
+    /**
+     * Exact session query key supplied by the caller.
+     */
     queryKey: readonly string[];
+    /**
+     * Observe principal epoch changes.
+     *
+     * @param listener - Synchronous callback after a changed principal is accepted.
+     *
+     * @returns Cleanup removing this listener.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     const stop = session.subscribe(() => console.log(session.getSnapshot()));
+     *   stop();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     subscribe(listener: () => void): () => void;
+    /**
+     * Read the current principal-transition epoch.
+     *
+     * @returns Monotonic epoch starting at zero.
+     */
     getSnapshot: () => number;
+    /**
+     * Supply the stable server epoch.
+     *
+     * @returns Zero for SSR.
+     */
     getServerSnapshot: () => number;
+    /**
+     * Enable publication of adapter results.
+     *
+     * @returns No value; future verified reads/events may publish.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     session.activate();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     activate(): void;
+    /**
+     * Disable publication and cancel this session query.
+     *
+     * @returns No value; in-flight backend work is not rolled back.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     session.deactivate();
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     deactivate(): void;
+    /**
+     * Publish an adapter auth event when active, cancelling any older session read.
+     *
+     * @param user - Verified user or null supplied by the adapter.
+     *
+     * @returns No value.
+     */
     publish: (user: User | null) => void;
+    /**
+     * Read and accept the latest adapter user.
+     *
+     * @param signal - Query abort signal checked after the adapter request completes.
+     *
+     * @returns Verified user or null.
+     *
+     * @throws Rejects on adapter errors or cancellation/stale revision via CancelledError.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     await session.read(new AbortController().signal);
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     read(signal: AbortSignal): Promise<{
         id: string;
         email: string;
@@ -18,5 +139,30 @@ export declare function createAuthSession(queryClient: QueryClient, adapter: Aut
         emailVerified?: boolean | undefined;
         metadata?: Record<string, any> | undefined;
     } | null>;
+    /**
+     * Run a host auth action and publish its result if still current.
+     *
+     * @typeParam T - User, null or void result of the host auth action.
+     *
+     * @param action - Asynchronous adapter operation, invoked once.
+     *
+     * @param loggedOut - Publish null on success instead of a user result; defaults to false.
+     *
+     * @returns Original host operation result, even if a newer revision prevents publication.
+     *
+     * @throws Rejects with the host action error; pending verification is invalidated afterward.
+     *
+     * @example
+     * ```ts
+     * import { QueryClient } from '@tanstack/react-query';
+     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';
+     * export async function coordinate(adapter: AuthAdapter) {
+     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);
+     *   try {
+     *     await session.run(() => adapter.getCurrentUser());
+     *   } finally { session.deactivate(); }
+     * }
+     * ```
+     */
     run<T extends User | null | void>(action: () => Promise<T>, loggedOut?: boolean): Promise<T>;
 };

package/dist/tools/components/auth/auth-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-session.js","names":["createAuthSession","principal","revision","epoch","active","listeners","sessionFilter","accept","nextPrincipal","user","filter","query","queryClient","queryKey","listener","publish","started","adapter","signal","CancelledError","result","action","loggedOut"],"sources":["../../../../src/tools/components/auth/auth-session.ts"],"sourcesContent":["import { CancelledError, type QueryClient } from '@tanstack/react-query';\nimport type { AuthAdapter, User } from './types';\n\n/** Internal session coordinator. Only verified adapter results determine principal changes. */\nexport function createAuthSession(\n  queryClient: QueryClient,\n  adapter: AuthAdapter,\n  queryKey: readonly string[],\n) {\n  let principal: string | null | undefined;\n  let revision = 0;\n  let epoch = 0;\n  let active = true;\n  const listeners = new Set<() => void>();\n  const sessionFilter = { queryKey, exact: true };\n\n  const accept = (user: User | null) => {\n    const nextPrincipal = user?.id ?? null;\n    if (principal !== nextPrincipal) {\n      // A QueryClient is an auth boundary: arbitrary application query keys can contain private data.\n      // Preserve other isolated session queries, but cancel/remove all application queries before\n      // exposing the new principal. Cancellation prevents even signal-ignoring promises writing back.\n      const filter = {\n        predicate: (query: { queryKey: readonly unknown[] }) =>\n          !(query.queryKey[0] === 'session' && query.queryKey[1] === 'react-tools.auth'),\n      };\n      void queryClient.cancelQueries(filter);\n      queryClient.removeQueries(filter);\n      principal = nextPrincipal;\n      epoch += 1;\n      queryClient.setQueryData(queryKey, user);\n      listeners.forEach((listener) => listener());\n    } else {\n      queryClient.setQueryData(queryKey, user);\n    }\n    return user;\n  };\n\n  const publish = (user: User | null) => {\n    if (!active) return;\n    revision += 1;\n    void queryClient.cancelQueries(sessionFilter);\n    accept(user);\n  };\n\n  return {\n    queryKey,\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getSnapshot: () => epoch,\n    getServerSnapshot: () => 0,\n    activate() {\n      active = true;\n    },\n    deactivate() {\n      active = false;\n      revision += 1;\n      void queryClient.cancelQueries(sessionFilter);\n    },\n    publish,\n    async read(signal: AbortSignal) {\n      const started = revision;\n      const user = await adapter.getCurrentUser();\n      if (!active || signal.aborted || revision !== started) {\n        throw new CancelledError({ revert: true });\n      }\n      return accept(user);\n    },\n    async run<T extends User | null | void>(\n      action: () => Promise<T>,\n      loggedOut = false,\n    ): Promise<T> {\n      const started = ++revision;\n      void queryClient.cancelQueries(sessionFilter);\n      try {\n        const result = await action();\n        // An intervening auth event/action is newer than this operation's result.\n        if (active && revision === started) {\n          if (loggedOut) publish(null);\n          else if (result) publish(result);\n        }\n        return result;\n      } finally {\n        // Failed actions or redirect-only OAuth results must not strand the cancelled initial read.\n        if (active && revision === started) {\n          void queryClient.invalidateQueries(sessionFilter);\n        }\n      }\n    },\n  };\n}\n"],"mappings":";;;AAIA,SAAgBA,EACd,GACA,GACA,GACA;CACA,IAAIC,GACAC,IAAW,GACXC,IAAQ,GACRC,IAAS,IACPC,oBAAY,IAAI,IAAgB,GAChCC,IAAgB;EAAE;EAAU,OAAO;CAAK,GAExCC,KAAU,MAAsB;EACpC,IAAMC,IAAgBC,GAAM,MAAM;EAClC,IAAIR,MAAcO,GAAe;GAI/B,IAAME,IAAS,EACb,YAAY,MACRC,EAAM,SAAS,OAAO,aAAaA,EAAM,SAAS,OAAO,mBAC/D;GAMA,AALAC,EAAiB,cAAcF,CAAM,GACrCE,EAAY,cAAcF,CAAM,GAChC,IAAYF,GACZ,KAAS,GACTI,EAAY,aAAaC,GAAUJ,CAAI,GACvCJ,EAAU,SAAS,MAAaS,EAAS,CAAC;EAC5C,OACE,EAAY,aAAaD,GAAUJ,CAAI;EAEzC,OAAOA;CACT,GAEMM,KAAW,MAAsB;EACrC,AAAKX,MACL,KAAY,GACZQ,EAAiB,cAAcN,CAAa,GAC5CC,EAAOE,CAAI;CACb;CAEA,OAAO;EACL;EACA,UAAU,GAAsB;GAE9B,OADAJ,EAAU,IAAIS,CAAQ,SACT;IACX,EAAU,OAAOA,CAAQ;GAC3B;EACF;EACA,mBAAmBX;EACnB,yBAAyB;EACzB,WAAW;GACT,IAAS;EACX;EACA,aAAa;GAGX,AAFA,IAAS,IACT,KAAY,GACZS,EAAiB,cAAcN,CAAa;EAC9C;EACA;EACA,MAAM,KAAK,GAAqB;GAC9B,IAAMU,IAAUd,GACVO,IAAO,MAAMQ,EAAQ,eAAe;GAC1C,IAAI,CAACb,KAAUc,EAAO,WAAWhB,MAAac,GAC5C,MAAM,IAAIG,EAAe,EAAE,QAAQ,GAAK,CAAC;GAE3C,OAAOZ,EAAOE,CAAI;EACpB;EACA,MAAM,IACJ,GACA,IAAY,IACA;GACZ,IAAMO,IAAU,EAAEd;GAClB,EAAiB,cAAcI,CAAa;GAC5C,IAAI;IACF,IAAMc,IAAS,MAAMC,EAAO;IAM5B,OAJIjB,KAAUF,MAAac,MACrBM,IAAWP,EAAQ,IAAI,IAClBK,KAAQL,EAAQK,CAAM,IAE1BA;GACT,UAAU;IAER,AAAIhB,KAAUF,MAAac,KACzBJ,EAAiB,kBAAkBN,CAAa;GAEpD;EACF;CACF;AACF"}
+{"version":3,"file":"auth-session.js","names":["createAuthSession","principal","revision","epoch","active","listeners","sessionFilter","accept","nextPrincipal","user","filter","query","queryClient","queryKey","listener","publish","started","adapter","signal","CancelledError","result","action","loggedOut"],"sources":["../../../../src/tools/components/auth/auth-session.ts"],"sourcesContent":["import { CancelledError, type QueryClient } from '@tanstack/react-query';\nimport type { AuthAdapter, User } from './types';\n\n/**\n * Creates a principal-transition coordinator for one AuthProvider session query.\n *\n * @param queryClient - Auth-domain query cache; application queries are removed on initial/principal verification.\n *\n * @param adapter - Host authentication adapter supplying the verified user.\n *\n * @param queryKey - Exact session query key owned by this coordinator.\n *\n * @returns Coordinator with subscription, epoch snapshots, lifecycle, verified reads and tracked actions.\n *\n * @remarks Although exported, this is a low-level provider helper. Principal changes cancel\n * and remove non-session queries, then publish the user and increment epoch. Same-user\n * refreshes preserve application state. Revisions discard stale reads/actions but cannot\n * undo backend work. Backend authorization is host-owned. No styles are required.\n *\n * @example\n * ```ts\n * import { QueryClient } from '@tanstack/react-query';\n * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n * export async function verify(adapter: AuthAdapter) {\n *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n *   try { return await session.read(new AbortController().signal); }\n *   finally { session.deactivate(); }\n * }\n * ```\n */\nexport function createAuthSession(\n  queryClient: QueryClient,\n  adapter: AuthAdapter,\n  queryKey: readonly string[],\n) {\n  let principal: string | null | undefined;\n  let revision = 0;\n  let epoch = 0;\n  let active = true;\n  const listeners = new Set<() => void>();\n  const sessionFilter = { queryKey, exact: true };\n\n  const accept = (user: User | null) => {\n    const nextPrincipal = user?.id ?? null;\n    if (principal !== nextPrincipal) {\n      // A QueryClient is an auth boundary: arbitrary application query keys can contain private data.\n      // Preserve other isolated session queries, but cancel/remove all application queries before\n      // exposing the new principal. Cancellation prevents even signal-ignoring promises writing back.\n      const filter = {\n        predicate: (query: { queryKey: readonly unknown[] }) =>\n          !(query.queryKey[0] === 'session' && query.queryKey[1] === 'react-tools.auth'),\n      };\n      void queryClient.cancelQueries(filter);\n      queryClient.removeQueries(filter);\n      principal = nextPrincipal;\n      epoch += 1;\n      queryClient.setQueryData(queryKey, user);\n      listeners.forEach((listener) => listener());\n    } else {\n      queryClient.setQueryData(queryKey, user);\n    }\n    return user;\n  };\n\n/**\n * Accepts a verified adapter event when active, superseding any pending session read.\n *\n * @param user - Adapter-confirmed user or null.\n *\n * @returns No value; inactive coordinators ignore the event.\n *\n * @remarks Current-user changes reset application query state; backend validity is host-owned.\n *\n * @example\n * ```ts\n * import { QueryClient } from '@tanstack/react-query';\n * import { createAuthSession, type AuthAdapter, type User } from '@alneas/appkit-react/tools/auth';\n * export function publishVerified(adapter: AuthAdapter, user: User | null) {\n *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'events']);\n *   session.publish(user);\n *   session.deactivate();\n * }\n * ```\n */\n  const publish = (user: User | null) => {\n    if (!active) return;\n    revision += 1;\n    void queryClient.cancelQueries(sessionFilter);\n    accept(user);\n  };\n\n  return {\n    /**\n     * Exact session query key supplied by the caller.\n     */\n    queryKey,\n    /**\n     * Observe principal epoch changes.\n     *\n     * @param listener - Synchronous callback after a changed principal is accepted.\n     *\n     * @returns Cleanup removing this listener.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     const stop = session.subscribe(() => console.log(session.getSnapshot()));\n     *   stop();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    subscribe(listener: () => void) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    /**\n     * Read the current principal-transition epoch.\n     *\n     * @returns Monotonic epoch starting at zero.\n     */\n    getSnapshot: () => epoch,\n    /**\n     * Supply the stable server epoch.\n     *\n     * @returns Zero for SSR.\n     */\n    getServerSnapshot: () => 0,\n    /**\n     * Enable publication of adapter results.\n     *\n     * @returns No value; future verified reads/events may publish.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     session.activate();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    activate() {\n      active = true;\n    },\n    /**\n     * Disable publication and cancel this session query.\n     *\n     * @returns No value; in-flight backend work is not rolled back.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     session.deactivate();\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    deactivate() {\n      active = false;\n      revision += 1;\n      void queryClient.cancelQueries(sessionFilter);\n    },\n    /**\n     * Publish an adapter auth event when active, cancelling any older session read.\n     *\n     * @param user - Verified user or null supplied by the adapter.\n     *\n     * @returns No value.\n     */\n    publish,\n    /**\n     * Read and accept the latest adapter user.\n     *\n     * @param signal - Query abort signal checked after the adapter request completes.\n     *\n     * @returns Verified user or null.\n     *\n     * @throws Rejects on adapter errors or cancellation/stale revision via CancelledError.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     await session.read(new AbortController().signal);\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    async read(signal: AbortSignal) {\n      const started = revision;\n      const user = await adapter.getCurrentUser();\n      if (!active || signal.aborted || revision !== started) {\n        throw new CancelledError({ revert: true });\n      }\n      return accept(user);\n    },\n    /**\n     * Run a host auth action and publish its result if still current.\n     *\n     * @typeParam T - User, null or void result of the host auth action.\n     *\n     * @param action - Asynchronous adapter operation, invoked once.\n     *\n     * @param loggedOut - Publish null on success instead of a user result; defaults to false.\n     *\n     * @returns Original host operation result, even if a newer revision prevents publication.\n     *\n     * @throws Rejects with the host action error; pending verification is invalidated afterward.\n     *\n     * @example\n     * ```ts\n     * import { QueryClient } from '@tanstack/react-query';\n     * import { createAuthSession, type AuthAdapter } from '@alneas/appkit-react/tools/auth';\n     * export async function coordinate(adapter: AuthAdapter) {\n     *   const session = createAuthSession(new QueryClient(), adapter, ['session', 'react-tools.auth', 'example']);\n     *   try {\n     *     await session.run(() => adapter.getCurrentUser());\n     *   } finally { session.deactivate(); }\n     * }\n     * ```\n     */\n    async run<T extends User | null | void>(\n      action: () => Promise<T>,\n      loggedOut = false,\n    ): Promise<T> {\n      const started = ++revision;\n      void queryClient.cancelQueries(sessionFilter);\n      try {\n        const result = await action();\n        // An intervening auth event/action is newer than this operation's result.\n        if (active && revision === started) {\n          if (loggedOut) publish(null);\n          else if (result) publish(result);\n        }\n        return result;\n      } finally {\n        // Failed actions or redirect-only OAuth results must not strand the cancelled initial read.\n        if (active && revision === started) {\n          void queryClient.invalidateQueries(sessionFilter);\n        }\n      }\n    },\n  };\n}\n"],"mappings":";;;AA8BA,SAAgBA,EACd,GACA,GACA,GACA;CACA,IAAIC,GACAC,IAAW,GACXC,IAAQ,GACRC,IAAS,IACPC,oBAAY,IAAI,IAAgB,GAChCC,IAAgB;EAAE;EAAU,OAAO;CAAK,GAExCC,KAAU,MAAsB;EACpC,IAAMC,IAAgBC,GAAM,MAAM;EAClC,IAAIR,MAAcO,GAAe;GAI/B,IAAME,IAAS,EACb,YAAY,MACRC,EAAM,SAAS,OAAO,aAAaA,EAAM,SAAS,OAAO,mBAC/D;GAMA,AALAC,EAAiB,cAAcF,CAAM,GACrCE,EAAY,cAAcF,CAAM,GAChC,IAAYF,GACZ,KAAS,GACTI,EAAY,aAAaC,GAAUJ,CAAI,GACvCJ,EAAU,SAAS,MAAaS,EAAS,CAAC;EAC5C,OACE,EAAY,aAAaD,GAAUJ,CAAI;EAEzC,OAAOA;CACT,GAsBMM,KAAW,MAAsB;EACrC,AAAKX,MACL,KAAY,GACZQ,EAAiB,cAAcN,CAAa,GAC5CC,EAAOE,CAAI;CACb;CAEA,OAAO;EAIL;EAqBA,UAAU,GAAsB;GAE9B,OADAJ,EAAU,IAAIS,CAAQ,SACT;IACX,EAAU,OAAOA,CAAQ;GAC3B;EACF;EAMA,mBAAmBX;EAMnB,yBAAyB;EAkBzB,WAAW;GACT,IAAS;EACX;EAkBA,aAAa;GAGX,AAFA,IAAS,IACT,KAAY,GACZS,EAAiB,cAAcN,CAAa;EAC9C;EAQA;EAsBA,MAAM,KAAK,GAAqB;GAC9B,IAAMU,IAAUd,GACVO,IAAO,MAAMQ,EAAQ,eAAe;GAC1C,IAAI,CAACb,KAAUc,EAAO,WAAWhB,MAAac,GAC5C,MAAM,IAAIG,EAAe,EAAE,QAAQ,GAAK,CAAC;GAE3C,OAAOZ,EAAOE,CAAI;EACpB;EA0BA,MAAM,IACJ,GACA,IAAY,IACA;GACZ,IAAMO,IAAU,EAAEd;GAClB,EAAiB,cAAcI,CAAa;GAC5C,IAAI;IACF,IAAMc,IAAS,MAAMC,EAAO;IAM5B,OAJIjB,KAAUF,MAAac,MACrBM,IAAWP,EAAQ,IAAI,IAClBK,KAAQL,EAAQK,CAAM,IAE1BA;GACT,UAAU;IAER,AAAIhB,KAAUF,MAAac,KACzBJ,EAAiB,kBAAkBN,CAAa;GAEpD;EACF;CACF;AACF"}

package/dist/tools/components/auth/session-cache.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"session-cache.cjs","names":["DEFAULT_KEY","DEFAULT_TTL","createSessionCache","key","options","ttl","read","raw","parsed","entry","hit","subscribeSessionCacheStorageEvent","handler","e","onChanged"],"sources":["../../../../src/tools/components/auth/session-cache.ts"],"sourcesContent":["import type { User } from './types';\n\n/**\n * 楽観セッションキャッシュ（stale-while-revalidate）\n *\n * 認証は httpOnly クッキー等で実体を持つため、クライアントはセッション状態を知りません。\n * そのままだとリロードのたびにサーバー検証（whoami 等）が終わるまで画面がブロックされます。\n *\n * このモジュールは「最後に確定したセッション状態」を localStorage に保持し、\n * 次回ロード時に即座に描画（楽観表示）しつつ、裏で検証させるためのヘルパーです。\n *\n * 保存するのは表示用プロフィール（`User`）のみ。トークン等の機密は含めません。\n * クッキーが無効なら検証時に即座にログイン画面へフォールバックします。\n *\n * @example\n * ```ts\n * const cache = createSessionCache({ ttl: 7 * 24 * 60 * 60 * 1000 });\n * cache.write(user);   // ログイン成功 / 検証成功時\n * cache.writeLoggedOut(); // 明示的な未ログイン確定時\n * const hit = cache.read(); // { user: User|null, exp: number } | null\n * ```\n */\n\nexport interface SessionCacheEntry {\n  /** 最後に確定したユーザー。null は「明示的に未ログイン」を意味する */\n  user: User | null;\n  /** 有効期限のエポックミリ秒 */\n  exp: number;\n}\n\nexport interface SessionCacheOptions {\n  /** localStorage キー（デフォルト: dataarthub.auth.last-session） */\n  key?: string;\n  /** キャッシュの有効期間（ミリ秒）。デフォルト 7 日 */\n  ttl?: number;\n}\n\nconst DEFAULT_KEY = 'dataarthub.auth.last-session';\nconst DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000;\n\nexport interface SessionCache {\n  readonly key: string;\n  read(): SessionCacheEntry | null;\n  write(user: User | null): void;\n  clear(): void;\n  /** キャッシュが存在し、かつ未期限切れなら true */\n  hasValid(): boolean;\n}\n\n/**\n *\n */\nexport function createSessionCache(options: SessionCacheOptions = {}): SessionCache {\n  const key = options.key ?? DEFAULT_KEY;\n  const ttl = options.ttl ?? DEFAULT_TTL;\n\n  const read = (): SessionCacheEntry | null => {\n    if (typeof window === 'undefined') return null;\n    try {\n      const raw = window.localStorage.getItem(key);\n      if (!raw) return null;\n      const parsed = JSON.parse(raw) as SessionCacheEntry;\n      if (typeof parsed?.exp !== 'number') return null;\n      return parsed;\n    } catch {\n      return null;\n    }\n  };\n\n  const write = (user: User | null): void => {\n    if (typeof window === 'undefined') return;\n    try {\n      const entry: SessionCacheEntry = { user, exp: Date.now() + ttl };\n      window.localStorage.setItem(key, JSON.stringify(entry));\n    } catch {\n      /* storage が無効 (private mode 等) でも致命的ではない */\n    }\n  };\n\n  const clear = (): void => {\n    if (typeof window === 'undefined') return;\n    try {\n      window.localStorage.removeItem(key);\n    } catch {\n      /* noop */\n    }\n  };\n\n  return {\n    key,\n    read,\n    write,\n    clear,\n    hasValid: () => {\n      const hit = read();\n      return hit != null && hit.exp > Date.now();\n    },\n  };\n}\n\n/**\n * 他タブでのログアウト/ログインを検知するための storage イベント監視。\n *\n * @returns クリーンアップ関数\n */\nexport function subscribeSessionCacheStorageEvent(\n  key: string,\n  onChanged: () => void,\n): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const handler = (e: StorageEvent) => {\n    if (e.key === key) onChanged();\n  };\n  window.addEventListener('storage', handler);\n  return () => window.removeEventListener('storage', handler);\n}\n"],"mappings":"A,gFAqCA,IAAMA,EAAc,+BACdC,EAAc,OAcpB,SAAgBC,EAAmB,EAA+B,CAAC,EAAiB,CAClF,IAAMC,EAAMC,EAAQ,KAAOJ,EACrBK,EAAMD,EAAQ,KAAOH,EAErBK,MAAuC,CAC3C,GAAI,OAAO,OAAW,IAAa,OAAO,KAC1C,GAAI,CACF,IAAMC,EAAM,OAAO,aAAa,QAAQJ,CAAG,EAC3C,GAAI,CAACI,EAAK,OAAO,KACjB,IAAMC,EAAS,KAAK,MAAMD,CAAG,EAE7B,OADI,OAAOC,GAAQ,KAAQ,SACpBA,EADqC,IAE9C,MAAQ,CACN,OAAO,IACT,CACF,EAqBA,MAAO,CACL,MACA,OACA,MAtBa,GAA4B,CACzC,GAAI,OAAO,OAAW,IACtB,GAAI,CACF,IAAMC,EAA2B,CAAE,OAAM,IAAK,KAAK,IAAI,EAAIJ,CAAI,EAC/D,OAAO,aAAa,QAAQF,EAAK,KAAK,UAAUM,CAAK,CAAC,CACxD,MAAQ,CAER,CACF,EAeE,UAbwB,CACxB,GAAI,OAAO,OAAW,IACtB,GAAI,CACF,OAAO,aAAa,WAAWN,CAAG,CACpC,MAAQ,CAER,CACF,EAOE,aAAgB,CACd,IAAMO,EAAMJ,EAAK,EACjB,OAAOI,GAAO,MAAQA,EAAI,IAAM,KAAK,IAAI,CAC3C,CACF,CACF,CAOA,SAAgBC,EACd,EACA,EACY,CACZ,GAAI,OAAO,OAAW,IAAa,UAAa,CAAC,EACjD,IAAMC,EAAW,GAAoB,CAC/BC,EAAE,MAAQV,GAAKW,EAAU,CAC/B,EAEA,OADA,OAAO,iBAAiB,UAAWF,CAAO,MAC7B,OAAO,oBAAoB,UAAWA,CAAO,CAC5D,C"}
+{"version":3,"file":"session-cache.cjs","names":["DEFAULT_KEY","DEFAULT_TTL","createSessionCache","key","options","ttl","read","raw","parsed","entry","hit","subscribeSessionCacheStorageEvent","handler","e","onChanged"],"sources":["../../../../src/tools/components/auth/session-cache.ts"],"sourcesContent":["import type { User } from './types';\n\n/**\n * A stored display snapshot, not proof of a valid authenticated session.\n * See createSessionCache for writes, expiration checks and host verification.\n *\n * @see createSessionCache for the canonical usage example.\n */\nexport interface SessionCacheEntry {\n  /** Last confirmed display user; null records an explicitly logged-out state. */\n  user: User | null;\n  /** Expiration timestamp in milliseconds since the Unix epoch. */\n  exp: number;\n}\n\n/**\n * Storage settings for createSessionCache; no providers or CSS are required.\n * @see createSessionCache for the canonical usage example.\n */\nexport interface SessionCacheOptions {\n  /** localStorage key; defaults to dataarthub.auth.last-session. */\n  key?: string;\n  /** Snapshot lifetime in milliseconds; defaults to seven days. */\n  ttl?: number;\n}\n\nconst DEFAULT_KEY = 'dataarthub.auth.last-session';\nconst DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000;\n\n/**\n * Best-effort browser snapshot storage; see createSessionCache for usage.\n * @see createSessionCache for the canonical usage example.\n */\nexport interface SessionCache {\n  /** Resolved storage key shared with storage-event subscribers. */\n  readonly key: string;\n  /**\n   * Read the stored snapshot without enforcing expiration.\n   *\n   * @returns Parsed entry (possibly expired), or null on server, missing data or parse/storage failure.\n   *\n   * @remarks See createSessionCache for the write/read usage pattern.\n   */\n  read(): SessionCacheEntry | null;\n  /**\n   * Store display state with a fresh expiration.\n   *\n   * @param user - Display user or null for confirmed logout; exclude secrets.\n   *\n   * @returns No value; storage failures and server writes are ignored.\n   *\n   * @remarks See createSessionCache for the write/read usage pattern.\n   */\n  write(user: User | null): void;\n  /**\n   * Remove the snapshot for this key.\n   *\n   * @returns No value; server calls and storage failures are ignored.\n   *\n   * @remarks Obtain this helper from createSessionCache, then call cache.clear().\n   */\n  clear(): void;\n  /**\n   * Check whether the stored expiration is still in the future.\n   *\n   * @returns True for a readable snapshot with exp greater than Date.now(), including a logged-out snapshot.\n   *\n   * @remarks See createSessionCache for a guarded read example.\n   */\n  hasValid(): boolean;\n}\n\n/**\n * Creates best-effort localStorage helpers for optimistic session display.\n *\n * @param options - Optional storage key and lifetime; defaults to the shared key and seven days.\n *\n * @returns Helpers that read, write, clear and check expiration without authenticating a user.\n *\n * @remarks read() validates only the numeric exp field and does not reject expired data;\n * hasValid() checks expiration. Server reads return null and writes/clears do nothing.\n * Browser storage/JSON failures are swallowed. Store display fields only, never tokens\n * or secrets; verify the actual session with the backend before allowing protected work.\n *\n * @example\n * ```ts\n * import { createSessionCache, type User } from '@alneas/appkit-react/tools/auth';\n * export function rememberSession(user: User | null) {\n *   const cache = createSessionCache({ ttl: 24 * 60 * 60 * 1000 });\n *   cache.write(user); // null records confirmed logout.\n *   const snapshot = cache.hasValid() ? cache.read() : null;\n *   return snapshot;\n * }\n * ```\n */\nexport function createSessionCache(options: SessionCacheOptions = {}): SessionCache {\n  const key = options.key ?? DEFAULT_KEY;\n  const ttl = options.ttl ?? DEFAULT_TTL;\n\n  const read = (): SessionCacheEntry | null => {\n    if (typeof window === 'undefined') return null;\n    try {\n      const raw = window.localStorage.getItem(key);\n      if (!raw) return null;\n      const parsed = JSON.parse(raw) as SessionCacheEntry;\n      if (typeof parsed?.exp !== 'number') return null;\n      return parsed;\n    } catch {\n      return null;\n    }\n  };\n\n  const write = (user: User | null): void => {\n    if (typeof window === 'undefined') return;\n    try {\n      const entry: SessionCacheEntry = { user, exp: Date.now() + ttl };\n      window.localStorage.setItem(key, JSON.stringify(entry));\n    } catch {\n      /* storage が無効 (private mode 等) でも致命的ではない */\n    }\n  };\n\n  const clear = (): void => {\n    if (typeof window === 'undefined') return;\n    try {\n      window.localStorage.removeItem(key);\n    } catch {\n      /* noop */\n    }\n  };\n\n  return {\n    key,\n    read,\n    write,\n    clear,\n    hasValid: () => {\n      const hit = read();\n      return hit != null && hit.exp > Date.now();\n    },\n  };\n}\n\n/**\n * Subscribes to browser storage events for one session-cache key.\n *\n * @param key - Exact localStorage key to observe.\n *\n * @param onChanged - Synchronous callback invoked when a storage event has this exact key.\n *\n * @returns Cleanup that removes the listener; a no-op function on the server.\n *\n * @remarks Browser storage events generally come from other documents, not the writing\n * window. Events with key null (including storage.clear()) do not match. The callback\n * should reverify the session; its errors are not caught by this listener.\n *\n * @example\n * ```ts\n * import {\n *   createSessionCache, subscribeSessionCacheStorageEvent,\n * } from '@alneas/appkit-react/tools/auth';\n * export function watchSession(reverify: () => void) {\n *   const cache = createSessionCache();\n *   return subscribeSessionCacheStorageEvent(cache.key, reverify);\n * }\n * // Call the returned cleanup when the host subscription is disposed.\n * ```\n */\nexport function subscribeSessionCacheStorageEvent(\n  key: string,\n  onChanged: () => void,\n): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const handler = (e: StorageEvent) => {\n    if (e.key === key) onChanged();\n  };\n  window.addEventListener('storage', handler);\n  return () => window.removeEventListener('storage', handler);\n}\n"],"mappings":"A,gFA0BA,IAAMA,EAAc,+BACdC,EAAc,OAoEpB,SAAgBC,EAAmB,EAA+B,CAAC,EAAiB,CAClF,IAAMC,EAAMC,EAAQ,KAAOJ,EACrBK,EAAMD,EAAQ,KAAOH,EAErBK,MAAuC,CAC3C,GAAI,OAAO,OAAW,IAAa,OAAO,KAC1C,GAAI,CACF,IAAMC,EAAM,OAAO,aAAa,QAAQJ,CAAG,EAC3C,GAAI,CAACI,EAAK,OAAO,KACjB,IAAMC,EAAS,KAAK,MAAMD,CAAG,EAE7B,OADI,OAAOC,GAAQ,KAAQ,SACpBA,EADqC,IAE9C,MAAQ,CACN,OAAO,IACT,CACF,EAqBA,MAAO,CACL,MACA,OACA,MAtBa,GAA4B,CACzC,GAAI,OAAO,OAAW,IACtB,GAAI,CACF,IAAMC,EAA2B,CAAE,OAAM,IAAK,KAAK,IAAI,EAAIJ,CAAI,EAC/D,OAAO,aAAa,QAAQF,EAAK,KAAK,UAAUM,CAAK,CAAC,CACxD,MAAQ,CAER,CACF,EAeE,UAbwB,CACxB,GAAI,OAAO,OAAW,IACtB,GAAI,CACF,OAAO,aAAa,WAAWN,CAAG,CACpC,MAAQ,CAER,CACF,EAOE,aAAgB,CACd,IAAMO,EAAMJ,EAAK,EACjB,OAAOI,GAAO,MAAQA,EAAI,IAAM,KAAK,IAAI,CAC3C,CACF,CACF,CA2BA,SAAgBC,EACd,EACA,EACY,CACZ,GAAI,OAAO,OAAW,IAAa,UAAa,CAAC,EACjD,IAAMC,EAAW,GAAoB,CAC/BC,EAAE,MAAQV,GAAKW,EAAU,CAC/B,EAEA,OADA,OAAO,iBAAiB,UAAWF,CAAO,MAC7B,OAAO,oBAAoB,UAAWA,CAAO,CAC5D,C"}

package/dist/tools/components/auth/session-cache.d.cts

@@ -1,51 +1,115 @@
 import { User } from './types.cjs';
 /**
- * 楽観セッションキャッシュ（stale-while-revalidate）
+ * A stored display snapshot, not proof of a valid authenticated session.
+ * See createSessionCache for writes, expiration checks and host verification.
  *
- * 認証は httpOnly クッキー等で実体を持つため、クライアントはセッション状態を知りません。
- * そのままだとリロードのたびにサーバー検証（whoami 等）が終わるまで画面がブロックされます。
- *
- * このモジュールは「最後に確定したセッション状態」を localStorage に保持し、
- * 次回ロード時に即座に描画（楽観表示）しつつ、裏で検証させるためのヘルパーです。
- *
- * 保存するのは表示用プロフィール（`User`）のみ。トークン等の機密は含めません。
- * クッキーが無効なら検証時に即座にログイン画面へフォールバックします。
- *
- * @example
- * ```ts
- * const cache = createSessionCache({ ttl: 7 * 24 * 60 * 60 * 1000 });
- * cache.write(user);   // ログイン成功 / 検証成功時
- * cache.writeLoggedOut(); // 明示的な未ログイン確定時
- * const hit = cache.read(); // { user: User|null, exp: number } | null
- * ```
+ * @see createSessionCache for the canonical usage example.
  */
 export interface SessionCacheEntry {
-    /** 最後に確定したユーザー。null は「明示的に未ログイン」を意味する */
+    /** Last confirmed display user; null records an explicitly logged-out state. */
     user: User | null;
-    /** 有効期限のエポックミリ秒 */
+    /** Expiration timestamp in milliseconds since the Unix epoch. */
     exp: number;
 }
+/**
+ * Storage settings for createSessionCache; no providers or CSS are required.
+ * @see createSessionCache for the canonical usage example.
+ */
 export interface SessionCacheOptions {
-    /** localStorage キー（デフォルト: dataarthub.auth.last-session） */
+    /** localStorage key; defaults to dataarthub.auth.last-session. */
     key?: string;
-    /** キャッシュの有効期間（ミリ秒）。デフォルト 7 日 */
+    /** Snapshot lifetime in milliseconds; defaults to seven days. */
     ttl?: number;
 }
+/**
+ * Best-effort browser snapshot storage; see createSessionCache for usage.
+ * @see createSessionCache for the canonical usage example.
+ */
 export interface SessionCache {
+    /** Resolved storage key shared with storage-event subscribers. */
     readonly key: string;
+    /**
+     * Read the stored snapshot without enforcing expiration.
+     *
+     * @returns Parsed entry (possibly expired), or null on server, missing data or parse/storage failure.
+     *
+     * @remarks See createSessionCache for the write/read usage pattern.
+     */
     read(): SessionCacheEntry | null;
+    /**
+     * Store display state with a fresh expiration.
+     *
+     * @param user - Display user or null for confirmed logout; exclude secrets.
+     *
+     * @returns No value; storage failures and server writes are ignored.
+     *
+     * @remarks See createSessionCache for the write/read usage pattern.
+     */
     write(user: User | null): void;
+    /**
+     * Remove the snapshot for this key.
+     *
+     * @returns No value; server calls and storage failures are ignored.
+     *
+     * @remarks Obtain this helper from createSessionCache, then call cache.clear().
+     */
     clear(): void;
-    /** キャッシュが存在し、かつ未期限切れなら true */
+    /**
+     * Check whether the stored expiration is still in the future.
+     *
+     * @returns True for a readable snapshot with exp greater than Date.now(), including a logged-out snapshot.
+     *
+     * @remarks See createSessionCache for a guarded read example.
+     */
     hasValid(): boolean;
 }
 /**
+ * Creates best-effort localStorage helpers for optimistic session display.
+ *
+ * @param options - Optional storage key and lifetime; defaults to the shared key and seven days.
+ *
+ * @returns Helpers that read, write, clear and check expiration without authenticating a user.
  *
+ * @remarks read() validates only the numeric exp field and does not reject expired data;
+ * hasValid() checks expiration. Server reads return null and writes/clears do nothing.
+ * Browser storage/JSON failures are swallowed. Store display fields only, never tokens
+ * or secrets; verify the actual session with the backend before allowing protected work.
+ *
+ * @example
+ * ```ts
+ * import { createSessionCache, type User } from '@alneas/appkit-react/tools/auth';
+ * export function rememberSession(user: User | null) {
+ *   const cache = createSessionCache({ ttl: 24 * 60 * 60 * 1000 });
+ *   cache.write(user); // null records confirmed logout.
+ *   const snapshot = cache.hasValid() ? cache.read() : null;
+ *   return snapshot;
+ * }
+ * ```
  */
 export declare function createSessionCache(options?: SessionCacheOptions): SessionCache;
 /**
- * 他タブでのログアウト/ログインを検知するための storage イベント監視。
+ * Subscribes to browser storage events for one session-cache key.
+ *
+ * @param key - Exact localStorage key to observe.
+ *
+ * @param onChanged - Synchronous callback invoked when a storage event has this exact key.
  *
- * @returns クリーンアップ関数
+ * @returns Cleanup that removes the listener; a no-op function on the server.
+ *
+ * @remarks Browser storage events generally come from other documents, not the writing
+ * window. Events with key null (including storage.clear()) do not match. The callback
+ * should reverify the session; its errors are not caught by this listener.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createSessionCache, subscribeSessionCacheStorageEvent,
+ * } from '@alneas/appkit-react/tools/auth';
+ * export function watchSession(reverify: () => void) {
+ *   const cache = createSessionCache();
+ *   return subscribeSessionCacheStorageEvent(cache.key, reverify);
+ * }
+ * // Call the returned cleanup when the host subscription is disposed.
+ * ```
  */
 export declare function subscribeSessionCacheStorageEvent(key: string, onChanged: () => void): () => void;