@xylex-group/athena 3.6.0 → 3.6.1

package/dist/next/server.d.cts

@@ -0,0 +1,274 @@
+import { ad as AthenaAuthSessionResponse } from '../types-BVKpQmfY.cjs';
+import { r as AthenaClientModelsInput } from '../types-D5dj1v5Z.cjs';
+import { aA as AthenaRequestContext, ai as AthenaClientConfig, ag as AthenaClient } from '../v3-client-DP-qg82X.cjs';
+import { OrganizationLike } from '../organization.cjs';
+export { ActiveOrganizationSessionLike, EnsureActiveOrganizationOptions, EnsureActiveOrganizationResult, ensureActiveOrganization } from '../organization.cjs';
+import { g as AthenaAuthSessionBridgeOptions, h as AthenaAuthSessionBridgePathOptions } from '../payload-DWI1rw-e.cjs';
+export { A as ATHENA_AUTH_SESSION_BRIDGE_ROUTE, a as ATHENA_AUTH_SESSION_COOKIE_NAME, b as ATHENA_AUTH_SESSION_COOKIE_NAMES, c as AthenaAuthSessionBridgeClientOptions, d as AthenaAuthSessionBridgePayload, e as AthenaAuthSessionBridgeSource, f as clearAthenaAuthSessionOnAppHost, p as persistAthenaAuthSessionOnAppHost, r as resolveSessionBridgePayload } from '../payload-DWI1rw-e.cjs';
+export { S as SESSION_COOKIE_PATTERNS, h as hasAuthSessionCookie } from '../session-cookie-detection-BqOp9mO6.cjs';
+export { A as ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM, a as ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_VALUE, b as ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH, c as ATHENA_AUTH_GET_SESSION_PATH, d as ATHENA_AUTH_PATH, e as ATHENA_AUTH_UPSTREAM_ENV_KEYS, f as ATHENA_AUTH_UPSTREAM_URL_ENV_NAMES, g as ATHENA_AUTH_VERIFY_EMAIL_PATH, h as ATHENA_SESSION_DATA_HEADER, i as AUTH_SESSION_PATH, j as AthenaAuthClientBaseUrlOptions, k as AthenaAuthUpstreamEnv, l as AthenaAuthUpstreamEnvKey, D as DEFAULT_ATHENA_AUTH_ORIGIN, m as DEFAULT_ATHENA_AUTH_UPSTREAM_URL, n as DISABLE_COOKIE_CACHE_QUERY_PARAM, o as DISABLE_COOKIE_CACHE_QUERY_VALUE, E as EnvLike, L as LOCAL_DEV_ORIGIN, S as SESSION_DATA_HEADER, p as createFreshSessionLookupUrl, q as isAbsoluteUrl, r as normalizeAthenaAuthBaseUrl, s as readAthenaAuthUpstreamUrlFromEnv, t as resolveAthenaAuthClientBaseUrl, u as resolveAthenaAuthRequestUrl, v as resolveAthenaAuthUpstreamUrl, w as resolveEmailVerificationCallbackUrl } from '../athena-auth-url-C1FbVmN6.cjs';
+export { A as ATHENA_AUTH_COOKIE_PREFIXES, a as AUTHENTICATED_REDIRECT_MODE_SET, b as AUTHENTICATED_REDIRECT_VIEW_SET, c as AUTH_DEFAULT_VIEW, d as AUTH_MODE_REDIRECTS, e as AUTH_MODE_SET, f as AUTH_ROUTES, g as AUTH_TWO_FACTOR_SEGMENT, h as AUTH_VIEW_BY_SEGMENT, i as AthenaRequestHeaderOverrideFields, j as AthenaRequestHeaderProfile, k as AuthMode, l as AuthModeRedirects, m as AuthRoutes, n as AuthView, B as BuildAthenaRequestHeadersInput, C as ClearAuthCookiesOptions, R as ResolvedRequestHeaderOverrides, E as applyAthenaApiKeyHeaders, F as applyAthenaAuthContextHeaders, G as applyAthenaPgUriHeaders, o as asNonEmptyString, p as asString, q as buildAthenaGatewayHeaders, r as buildAthenaRequestHeaders, H as buildServiceRequestHeaders, s as clearAuthCookies, t as createAuthModeRedirects, u as createAuthRoutes, I as hasHeaderIgnoreCase, v as isAuthMode, w as readTrimmedString, x as resolveAuthModeRedirect, y as resolveAuthViewFromSegment, J as resolveHeaderValue, K as resolveRequestHeaderOverrides, z as shouldRedirectAuthenticatedAuthMode, D as shouldRedirectAuthenticatedAuthView } from '../athena-request-headers-BnFN2mbd.cjs';
+export { G as GetOriginFromHeadersOptions, g as getOriginFromHeaders, i as isDynamicServerUsageError, p as proxyRequestHeaders, r as readEnv, a as requireEnv } from '../proxy-request-headers-pIBSn1Fw.cjs';
+export { A as ATHENA_TABLE_SCHEMA_ROUTE, a as AthenaTableCatalogColumn, b as AthenaTableCatalogQueryClient, c as AthenaTableCatalogRelation, d as AthenaTableCatalogResponse, e as AthenaTableCatalogTable, f as AthenaTableSchemaConfig, g as AthenaTableSchemaHandlerOptions, h as AthenaTableShowcaseConfig, F as FetchAthenaTableCatalogOptions, T as TableCatalogColumn, i as TableCatalogRelation, j as TableCatalogResponse, k as TableCatalogTable, l as buildAthenaTableCatalogQueries, m as createAthenaTableSchemaHandlers, n as fetchAthenaTableCatalog, o as fetchTableCatalog, p as handleAthenaTableSchemaPost, q as hasAthenaTableSchemaCredentials, r as isAthenaTableSchemaConfig, s as parseAthenaTableSchemaScope } from '../schema-handlers-Dr8h9Jg-.cjs';
+import '../types-B2RZPivM.cjs';
+import '../module-C_ab-MM1.cjs';
+
+/**
+ * Handle bridge `POST` — set an httpOnly session cookie from JSON body.
+ *
+ * Expected body: `{ "token": string, "expiresAt"?: string }`.
+ *
+ * @param request - Incoming request (JSON body)
+ * @param options - Cookie / route configuration
+ * @returns `200` on success, `400` when token is missing
+ */
+declare function handleAthenaAuthSessionBridgePost(request: Request, options?: AthenaAuthSessionBridgeOptions): Promise<Response>;
+/**
+ * Handle bridge `DELETE` — clear bridged session cookie name variants.
+ *
+ * @param request - Incoming request (used for Secure detection)
+ * @param options - Cookie / route configuration
+ * @returns `200` with clear `Set-Cookie` headers
+ */
+declare function handleAthenaAuthSessionBridgeDelete(request: Request, options?: AthenaAuthSessionBridgeOptions): Response;
+/**
+ * Create dedicated App Router handlers for the session bridge.
+ *
+ * Drop into a route file with no additional wiring:
+ *
+ * @example
+ * ```ts
+ * // app/api/athena-auth/session/route.ts
+ * import { createAthenaAuthSessionBridgeHandlers } from '@xylex-group/athena/next/server'
+ *
+ * export const { POST, DELETE } = createAthenaAuthSessionBridgeHandlers()
+ * ```
+ *
+ * @param options - Optional cookie name, path, SameSite, Secure overrides
+ * @returns Object with `POST` and `DELETE` route handlers
+ */
+declare function createAthenaAuthSessionBridgeHandlers(options?: AthenaAuthSessionBridgeOptions): {
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Response;
+};
+/**
+ * Whether this request should be handled as a session bridge call.
+ *
+ * Returns true when:
+ * - the pathname equals the configured `route`, or
+ * - the final path segment is listed in `matchPaths` (default `session`)
+ *
+ * @param request - Incoming request
+ * @param options - Route + matchPaths configuration
+ */
+declare function isAthenaAuthSessionBridgePath(request: Request, options?: AthenaAuthSessionBridgePathOptions): boolean;
+/**
+ * Create catch-all / `[path]` handlers that only service session-bridge paths.
+ *
+ * Non-matching paths return `404` with `{ error: 'Not found' }` so you can
+ * mount under `/api/auth/[...path]` without implementing a full auth proxy.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[...path]/route.ts
+ * import { createAthenaAuthSessionBridgePathHandlers } from '@xylex-group/athena/next/server'
+ *
+ * export const { POST, DELETE } = createAthenaAuthSessionBridgePathHandlers({
+ *   route: '/api/auth/session',
+ * })
+ * ```
+ *
+ * @param options - Bridge options plus `matchPaths`
+ * @returns Object with `POST` and `DELETE` route handlers
+ */
+declare function createAthenaAuthSessionBridgePathHandlers(options?: AthenaAuthSessionBridgePathOptions): {
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Response;
+};
+
+interface AthenaRequestHeadersBag {
+    get(name: string): string | null;
+}
+interface AthenaRequestCookiesBag {
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+}
+type AthenaRequestHeadersInput = AthenaRequestHeadersBag | Record<string, string | null | undefined>;
+type AthenaRequestCookiesInput = AthenaRequestCookiesBag | string | null | undefined;
+interface AthenaServerRequestOptions {
+    requestHeaders?: AthenaRequestHeadersInput;
+    requestCookies?: AthenaRequestCookiesInput;
+    forceNoCache?: boolean;
+    headers?: Record<string, string>;
+}
+declare function resolveNextRequestContext(options?: AthenaServerRequestOptions): Promise<AthenaRequestContext>;
+
+interface ResolveActiveOrganizationIdArgs {
+    rawActiveOrganizationId: string | null;
+    session: AthenaAuthSessionResponse;
+    userId: string;
+}
+interface GetServerSessionEnsureActiveOptions<TOrganization extends OrganizationLike = OrganizationLike> {
+    listOrganizations: () => Promise<readonly TOrganization[]>;
+    onError?: (error: unknown) => void;
+    selectOrganizationId?: (organizations: readonly TOrganization[]) => string | null;
+    setActiveOrganization: (organizationId: string) => Promise<unknown>;
+}
+interface GetServerSessionOptions extends AthenaServerRequestOptions {
+    /**
+     * Absolute get-session URL. When omitted, built from `appOrigin` via
+     * {@link createFreshSessionLookupUrl}.
+     */
+    authSessionUrl?: string | URL;
+    /**
+     * App origin used to build `/api/auth/get-session?disableCookieCache=true`
+     * when `authSessionUrl` is not set.
+     */
+    appOrigin?: string | URL;
+    /**
+     * Raw middleware-forwarded session JSON (or omit to read
+     * {@link ATHENA_SESSION_DATA_HEADER} from `requestHeaders`).
+     */
+    sessionDataHeader?: string | null;
+    /** Custom fetch (tests / edge). Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * When true (default), skip the network get-session call if cookies and
+     * bearer token are both absent.
+     */
+    skipFetchWithoutCredentials?: boolean;
+    /**
+     * Product org policy. Runs after the raw session is loaded and before
+     * optional ensure-active. Does not replace membership checks in the app.
+     */
+    resolveActiveOrganizationId?: (args: ResolveActiveOrganizationIdArgs) => string | null | Promise<string | null>;
+    /**
+     * Optional bootstrap when the session has no active org. Inject list/set
+     * from your auth client; the package does not own org transport here.
+     */
+    ensureActiveOrganization?: GetServerSessionEnsureActiveOptions;
+}
+interface GetServerSessionResult {
+    session: AthenaAuthSessionResponse | null;
+    userId: string | null;
+    /** Active org id from the auth session payload before product resolution. */
+    rawActiveOrganizationId: string | null;
+    /**
+     * Product-resolved organization id after `resolveActiveOrganizationId` and
+     * optional ensure-active. Prefer this for data client `scope.organizationId`.
+     */
+    organizationId: string | null;
+    didEnsureActiveOrganization: boolean;
+    /** True when the session came from the middleware header without a fetch. */
+    fromSessionDataHeader: boolean;
+}
+/**
+ * Parse a middleware-forwarded session JSON string into a session response.
+ * Returns null for missing, invalid, or incomplete payloads.
+ */
+declare function parseAthenaSessionDataHeader(raw: string | null | undefined): AthenaAuthSessionResponse | null;
+/**
+ * Load the current Athena Auth session for Next.js RSC / route handlers.
+ *
+ * Composition (not a full product policy module):
+ * 1. Optional middleware header (`x-session-data` / {@link ATHENA_SESSION_DATA_HEADER})
+ * 2. Else fetch get-session with request cookies/bearer
+ * 3. Optional product `resolveActiveOrganizationId`
+ * 4. Optional `ensureActiveOrganization` injectables
+ *
+ * Wrap with React `cache()` in the app if you need per-request dedupe:
+ *
+ * ```ts
+ * import { cache } from 'react'
+ * import { getServerSession } from '@xylex-group/athena/next/server'
+ *
+ * export const getSession = cache(() =>
+ *   getServerSession({
+ *     appOrigin: process.env.NEXT_PUBLIC_APP_URL!,
+ *     resolveActiveOrganizationId: ({ userId, rawActiveOrganizationId }) =>
+ *       resolveFormationsOrganizationId(userId, rawActiveOrganizationId),
+ *   }),
+ * )
+ * ```
+ */
+declare function getServerSession(options?: GetServerSessionOptions): Promise<GetServerSessionResult>;
+
+/**
+ * Minimal session shape used to derive gateway identity headers.
+ * Accepts full {@link AthenaAuthSessionResponse} or a partial getSession payload.
+ */
+type AthenaServerSessionInput = {
+    user?: {
+        id?: string | null;
+    } | null;
+    session?: {
+        id?: string | null;
+        activeOrganizationId?: string | null;
+    } | null;
+} | null;
+/**
+ * Explicit gateway identity for request-scoped server clients.
+ *
+ * Maps to `X-User-Id` / `X-Organization-Id` via {@link AthenaRequestContext}.
+ * When both `session` and `scope` are provided, any field present on `scope`
+ * overrides the session-derived value (including explicit `null` to clear).
+ */
+interface AthenaServerScope {
+    userId?: string | null;
+    organizationId?: string | null;
+}
+interface AthenaServerContextOptions extends AthenaServerRequestOptions {
+    session?: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    /**
+     * First-class identity scope. Prefer this over a second `withContext(...)`
+     * call when you already know user/org for the request.
+     */
+    scope?: AthenaServerScope;
+}
+interface AthenaResolvedServerContext {
+    request: AthenaRequestContext;
+    session: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    userId: string | null;
+    organizationId: string | null;
+}
+declare function resolveAthenaServerContext(options?: AthenaServerContextOptions): Promise<AthenaResolvedServerContext>;
+type AthenaBaseServerOptions = AthenaServerRequestOptions & {
+    session?: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    scope?: AthenaServerScope;
+};
+/**
+ * Explicit server config: require url + key at the call site.
+ */
+type AthenaExplicitServerConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaBaseServerOptions & AthenaClientConfig<TModels> & {
+    url: string;
+    key: string;
+};
+/**
+ * Environment server config: require an explicit env object (no silent global process.env).
+ */
+type AthenaEnvironmentServerConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaBaseServerOptions & Omit<AthenaClientConfig<TModels>, 'url' | 'key'> & {
+    env: Record<string, string | undefined>;
+};
+/**
+ * Flat Next server client options: client config fields + request context options.
+ * Requires either `{ url, key }` or `{ env }`.
+ */
+type AthenaServerClientConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaExplicitServerConfig<TModels> | AthenaEnvironmentServerConfig<TModels>;
+/**
+ * Request-scoped Next server façade over {@link createClient}.
+ *
+ * Resolves cookies, bearer tokens, optional session/`scope` identity, and cache
+ * policy on every invocation, merges with any application-level context, then
+ * materializes the client through the singular `createClient` primitive.
+ *
+ * Does not cache clients. Call once per Server Component / Server Action /
+ * Route Handler request (or pass explicit requestHeaders/requestCookies).
+ *
+ * Prefer `session` and/or `scope` for identity headers instead of a follow-up
+ * `withContext({})` that drops org/user fields.
+ */
+declare function createAthenaServerClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(options: AthenaServerClientConfig<TModels>): Promise<AthenaClient<TModels>>;
+
+export { AthenaAuthSessionBridgeOptions, AthenaAuthSessionBridgePathOptions, type AthenaEnvironmentServerConfig, type AthenaExplicitServerConfig, type AthenaRequestCookiesBag, type AthenaRequestCookiesInput, type AthenaRequestHeadersBag, type AthenaRequestHeadersInput, type AthenaResolvedServerContext, type AthenaServerClientConfig, type AthenaServerContextOptions, type AthenaServerRequestOptions, type AthenaServerScope, type AthenaServerSessionInput, type GetServerSessionEnsureActiveOptions, type GetServerSessionOptions, type GetServerSessionResult, OrganizationLike, type ResolveActiveOrganizationIdArgs, createAthenaAuthSessionBridgeHandlers, createAthenaAuthSessionBridgePathHandlers, createAthenaServerClient, getServerSession, handleAthenaAuthSessionBridgeDelete, handleAthenaAuthSessionBridgePost, isAthenaAuthSessionBridgePath, parseAthenaSessionDataHeader, resolveAthenaServerContext, resolveNextRequestContext };

package/dist/next/server.d.ts

@@ -0,0 +1,274 @@
+import { ad as AthenaAuthSessionResponse } from '../types-BVKpQmfY.js';
+import { r as AthenaClientModelsInput } from '../types-S-bTMPiM.js';
+import { aA as AthenaRequestContext, ai as AthenaClientConfig, ag as AthenaClient } from '../v3-client-OAai_JNs.js';
+import { OrganizationLike } from '../organization.js';
+export { ActiveOrganizationSessionLike, EnsureActiveOrganizationOptions, EnsureActiveOrganizationResult, ensureActiveOrganization } from '../organization.js';
+import { g as AthenaAuthSessionBridgeOptions, h as AthenaAuthSessionBridgePathOptions } from '../payload-DWI1rw-e.js';
+export { A as ATHENA_AUTH_SESSION_BRIDGE_ROUTE, a as ATHENA_AUTH_SESSION_COOKIE_NAME, b as ATHENA_AUTH_SESSION_COOKIE_NAMES, c as AthenaAuthSessionBridgeClientOptions, d as AthenaAuthSessionBridgePayload, e as AthenaAuthSessionBridgeSource, f as clearAthenaAuthSessionOnAppHost, p as persistAthenaAuthSessionOnAppHost, r as resolveSessionBridgePayload } from '../payload-DWI1rw-e.js';
+export { S as SESSION_COOKIE_PATTERNS, h as hasAuthSessionCookie } from '../session-cookie-detection-BqOp9mO6.js';
+export { A as ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_PARAM, a as ATHENA_AUTH_DISABLE_COOKIE_CACHE_QUERY_VALUE, b as ATHENA_AUTH_GET_SESSION_ABSOLUTE_PATH, c as ATHENA_AUTH_GET_SESSION_PATH, d as ATHENA_AUTH_PATH, e as ATHENA_AUTH_UPSTREAM_ENV_KEYS, f as ATHENA_AUTH_UPSTREAM_URL_ENV_NAMES, g as ATHENA_AUTH_VERIFY_EMAIL_PATH, h as ATHENA_SESSION_DATA_HEADER, i as AUTH_SESSION_PATH, j as AthenaAuthClientBaseUrlOptions, k as AthenaAuthUpstreamEnv, l as AthenaAuthUpstreamEnvKey, D as DEFAULT_ATHENA_AUTH_ORIGIN, m as DEFAULT_ATHENA_AUTH_UPSTREAM_URL, n as DISABLE_COOKIE_CACHE_QUERY_PARAM, o as DISABLE_COOKIE_CACHE_QUERY_VALUE, E as EnvLike, L as LOCAL_DEV_ORIGIN, S as SESSION_DATA_HEADER, p as createFreshSessionLookupUrl, q as isAbsoluteUrl, r as normalizeAthenaAuthBaseUrl, s as readAthenaAuthUpstreamUrlFromEnv, t as resolveAthenaAuthClientBaseUrl, u as resolveAthenaAuthRequestUrl, v as resolveAthenaAuthUpstreamUrl, w as resolveEmailVerificationCallbackUrl } from '../athena-auth-url-C1FbVmN6.js';
+export { A as ATHENA_AUTH_COOKIE_PREFIXES, a as AUTHENTICATED_REDIRECT_MODE_SET, b as AUTHENTICATED_REDIRECT_VIEW_SET, c as AUTH_DEFAULT_VIEW, d as AUTH_MODE_REDIRECTS, e as AUTH_MODE_SET, f as AUTH_ROUTES, g as AUTH_TWO_FACTOR_SEGMENT, h as AUTH_VIEW_BY_SEGMENT, i as AthenaRequestHeaderOverrideFields, j as AthenaRequestHeaderProfile, k as AuthMode, l as AuthModeRedirects, m as AuthRoutes, n as AuthView, B as BuildAthenaRequestHeadersInput, C as ClearAuthCookiesOptions, R as ResolvedRequestHeaderOverrides, E as applyAthenaApiKeyHeaders, F as applyAthenaAuthContextHeaders, G as applyAthenaPgUriHeaders, o as asNonEmptyString, p as asString, q as buildAthenaGatewayHeaders, r as buildAthenaRequestHeaders, H as buildServiceRequestHeaders, s as clearAuthCookies, t as createAuthModeRedirects, u as createAuthRoutes, I as hasHeaderIgnoreCase, v as isAuthMode, w as readTrimmedString, x as resolveAuthModeRedirect, y as resolveAuthViewFromSegment, J as resolveHeaderValue, K as resolveRequestHeaderOverrides, z as shouldRedirectAuthenticatedAuthMode, D as shouldRedirectAuthenticatedAuthView } from '../athena-request-headers-Dwdkq2WR.js';
+export { G as GetOriginFromHeadersOptions, g as getOriginFromHeaders, i as isDynamicServerUsageError, p as proxyRequestHeaders, r as readEnv, a as requireEnv } from '../proxy-request-headers-CttlcuRb.js';
+export { A as ATHENA_TABLE_SCHEMA_ROUTE, a as AthenaTableCatalogColumn, b as AthenaTableCatalogQueryClient, c as AthenaTableCatalogRelation, d as AthenaTableCatalogResponse, e as AthenaTableCatalogTable, f as AthenaTableSchemaConfig, g as AthenaTableSchemaHandlerOptions, h as AthenaTableShowcaseConfig, F as FetchAthenaTableCatalogOptions, T as TableCatalogColumn, i as TableCatalogRelation, j as TableCatalogResponse, k as TableCatalogTable, l as buildAthenaTableCatalogQueries, m as createAthenaTableSchemaHandlers, n as fetchAthenaTableCatalog, o as fetchTableCatalog, p as handleAthenaTableSchemaPost, q as hasAthenaTableSchemaCredentials, r as isAthenaTableSchemaConfig, s as parseAthenaTableSchemaScope } from '../schema-handlers-CvWqF-dW.js';
+import '../types-B2RZPivM.js';
+import '../module-C_ab-MM1.js';
+
+/**
+ * Handle bridge `POST` — set an httpOnly session cookie from JSON body.
+ *
+ * Expected body: `{ "token": string, "expiresAt"?: string }`.
+ *
+ * @param request - Incoming request (JSON body)
+ * @param options - Cookie / route configuration
+ * @returns `200` on success, `400` when token is missing
+ */
+declare function handleAthenaAuthSessionBridgePost(request: Request, options?: AthenaAuthSessionBridgeOptions): Promise<Response>;
+/**
+ * Handle bridge `DELETE` — clear bridged session cookie name variants.
+ *
+ * @param request - Incoming request (used for Secure detection)
+ * @param options - Cookie / route configuration
+ * @returns `200` with clear `Set-Cookie` headers
+ */
+declare function handleAthenaAuthSessionBridgeDelete(request: Request, options?: AthenaAuthSessionBridgeOptions): Response;
+/**
+ * Create dedicated App Router handlers for the session bridge.
+ *
+ * Drop into a route file with no additional wiring:
+ *
+ * @example
+ * ```ts
+ * // app/api/athena-auth/session/route.ts
+ * import { createAthenaAuthSessionBridgeHandlers } from '@xylex-group/athena/next/server'
+ *
+ * export const { POST, DELETE } = createAthenaAuthSessionBridgeHandlers()
+ * ```
+ *
+ * @param options - Optional cookie name, path, SameSite, Secure overrides
+ * @returns Object with `POST` and `DELETE` route handlers
+ */
+declare function createAthenaAuthSessionBridgeHandlers(options?: AthenaAuthSessionBridgeOptions): {
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Response;
+};
+/**
+ * Whether this request should be handled as a session bridge call.
+ *
+ * Returns true when:
+ * - the pathname equals the configured `route`, or
+ * - the final path segment is listed in `matchPaths` (default `session`)
+ *
+ * @param request - Incoming request
+ * @param options - Route + matchPaths configuration
+ */
+declare function isAthenaAuthSessionBridgePath(request: Request, options?: AthenaAuthSessionBridgePathOptions): boolean;
+/**
+ * Create catch-all / `[path]` handlers that only service session-bridge paths.
+ *
+ * Non-matching paths return `404` with `{ error: 'Not found' }` so you can
+ * mount under `/api/auth/[...path]` without implementing a full auth proxy.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[...path]/route.ts
+ * import { createAthenaAuthSessionBridgePathHandlers } from '@xylex-group/athena/next/server'
+ *
+ * export const { POST, DELETE } = createAthenaAuthSessionBridgePathHandlers({
+ *   route: '/api/auth/session',
+ * })
+ * ```
+ *
+ * @param options - Bridge options plus `matchPaths`
+ * @returns Object with `POST` and `DELETE` route handlers
+ */
+declare function createAthenaAuthSessionBridgePathHandlers(options?: AthenaAuthSessionBridgePathOptions): {
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Response;
+};
+
+interface AthenaRequestHeadersBag {
+    get(name: string): string | null;
+}
+interface AthenaRequestCookiesBag {
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+}
+type AthenaRequestHeadersInput = AthenaRequestHeadersBag | Record<string, string | null | undefined>;
+type AthenaRequestCookiesInput = AthenaRequestCookiesBag | string | null | undefined;
+interface AthenaServerRequestOptions {
+    requestHeaders?: AthenaRequestHeadersInput;
+    requestCookies?: AthenaRequestCookiesInput;
+    forceNoCache?: boolean;
+    headers?: Record<string, string>;
+}
+declare function resolveNextRequestContext(options?: AthenaServerRequestOptions): Promise<AthenaRequestContext>;
+
+interface ResolveActiveOrganizationIdArgs {
+    rawActiveOrganizationId: string | null;
+    session: AthenaAuthSessionResponse;
+    userId: string;
+}
+interface GetServerSessionEnsureActiveOptions<TOrganization extends OrganizationLike = OrganizationLike> {
+    listOrganizations: () => Promise<readonly TOrganization[]>;
+    onError?: (error: unknown) => void;
+    selectOrganizationId?: (organizations: readonly TOrganization[]) => string | null;
+    setActiveOrganization: (organizationId: string) => Promise<unknown>;
+}
+interface GetServerSessionOptions extends AthenaServerRequestOptions {
+    /**
+     * Absolute get-session URL. When omitted, built from `appOrigin` via
+     * {@link createFreshSessionLookupUrl}.
+     */
+    authSessionUrl?: string | URL;
+    /**
+     * App origin used to build `/api/auth/get-session?disableCookieCache=true`
+     * when `authSessionUrl` is not set.
+     */
+    appOrigin?: string | URL;
+    /**
+     * Raw middleware-forwarded session JSON (or omit to read
+     * {@link ATHENA_SESSION_DATA_HEADER} from `requestHeaders`).
+     */
+    sessionDataHeader?: string | null;
+    /** Custom fetch (tests / edge). Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * When true (default), skip the network get-session call if cookies and
+     * bearer token are both absent.
+     */
+    skipFetchWithoutCredentials?: boolean;
+    /**
+     * Product org policy. Runs after the raw session is loaded and before
+     * optional ensure-active. Does not replace membership checks in the app.
+     */
+    resolveActiveOrganizationId?: (args: ResolveActiveOrganizationIdArgs) => string | null | Promise<string | null>;
+    /**
+     * Optional bootstrap when the session has no active org. Inject list/set
+     * from your auth client; the package does not own org transport here.
+     */
+    ensureActiveOrganization?: GetServerSessionEnsureActiveOptions;
+}
+interface GetServerSessionResult {
+    session: AthenaAuthSessionResponse | null;
+    userId: string | null;
+    /** Active org id from the auth session payload before product resolution. */
+    rawActiveOrganizationId: string | null;
+    /**
+     * Product-resolved organization id after `resolveActiveOrganizationId` and
+     * optional ensure-active. Prefer this for data client `scope.organizationId`.
+     */
+    organizationId: string | null;
+    didEnsureActiveOrganization: boolean;
+    /** True when the session came from the middleware header without a fetch. */
+    fromSessionDataHeader: boolean;
+}
+/**
+ * Parse a middleware-forwarded session JSON string into a session response.
+ * Returns null for missing, invalid, or incomplete payloads.
+ */
+declare function parseAthenaSessionDataHeader(raw: string | null | undefined): AthenaAuthSessionResponse | null;
+/**
+ * Load the current Athena Auth session for Next.js RSC / route handlers.
+ *
+ * Composition (not a full product policy module):
+ * 1. Optional middleware header (`x-session-data` / {@link ATHENA_SESSION_DATA_HEADER})
+ * 2. Else fetch get-session with request cookies/bearer
+ * 3. Optional product `resolveActiveOrganizationId`
+ * 4. Optional `ensureActiveOrganization` injectables
+ *
+ * Wrap with React `cache()` in the app if you need per-request dedupe:
+ *
+ * ```ts
+ * import { cache } from 'react'
+ * import { getServerSession } from '@xylex-group/athena/next/server'
+ *
+ * export const getSession = cache(() =>
+ *   getServerSession({
+ *     appOrigin: process.env.NEXT_PUBLIC_APP_URL!,
+ *     resolveActiveOrganizationId: ({ userId, rawActiveOrganizationId }) =>
+ *       resolveFormationsOrganizationId(userId, rawActiveOrganizationId),
+ *   }),
+ * )
+ * ```
+ */
+declare function getServerSession(options?: GetServerSessionOptions): Promise<GetServerSessionResult>;
+
+/**
+ * Minimal session shape used to derive gateway identity headers.
+ * Accepts full {@link AthenaAuthSessionResponse} or a partial getSession payload.
+ */
+type AthenaServerSessionInput = {
+    user?: {
+        id?: string | null;
+    } | null;
+    session?: {
+        id?: string | null;
+        activeOrganizationId?: string | null;
+    } | null;
+} | null;
+/**
+ * Explicit gateway identity for request-scoped server clients.
+ *
+ * Maps to `X-User-Id` / `X-Organization-Id` via {@link AthenaRequestContext}.
+ * When both `session` and `scope` are provided, any field present on `scope`
+ * overrides the session-derived value (including explicit `null` to clear).
+ */
+interface AthenaServerScope {
+    userId?: string | null;
+    organizationId?: string | null;
+}
+interface AthenaServerContextOptions extends AthenaServerRequestOptions {
+    session?: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    /**
+     * First-class identity scope. Prefer this over a second `withContext(...)`
+     * call when you already know user/org for the request.
+     */
+    scope?: AthenaServerScope;
+}
+interface AthenaResolvedServerContext {
+    request: AthenaRequestContext;
+    session: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    userId: string | null;
+    organizationId: string | null;
+}
+declare function resolveAthenaServerContext(options?: AthenaServerContextOptions): Promise<AthenaResolvedServerContext>;
+type AthenaBaseServerOptions = AthenaServerRequestOptions & {
+    session?: AthenaAuthSessionResponse | AthenaServerSessionInput | null;
+    scope?: AthenaServerScope;
+};
+/**
+ * Explicit server config: require url + key at the call site.
+ */
+type AthenaExplicitServerConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaBaseServerOptions & AthenaClientConfig<TModels> & {
+    url: string;
+    key: string;
+};
+/**
+ * Environment server config: require an explicit env object (no silent global process.env).
+ */
+type AthenaEnvironmentServerConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaBaseServerOptions & Omit<AthenaClientConfig<TModels>, 'url' | 'key'> & {
+    env: Record<string, string | undefined>;
+};
+/**
+ * Flat Next server client options: client config fields + request context options.
+ * Requires either `{ url, key }` or `{ env }`.
+ */
+type AthenaServerClientConfig<TModels extends AthenaClientModelsInput | undefined = undefined> = AthenaExplicitServerConfig<TModels> | AthenaEnvironmentServerConfig<TModels>;
+/**
+ * Request-scoped Next server façade over {@link createClient}.
+ *
+ * Resolves cookies, bearer tokens, optional session/`scope` identity, and cache
+ * policy on every invocation, merges with any application-level context, then
+ * materializes the client through the singular `createClient` primitive.
+ *
+ * Does not cache clients. Call once per Server Component / Server Action /
+ * Route Handler request (or pass explicit requestHeaders/requestCookies).
+ *
+ * Prefer `session` and/or `scope` for identity headers instead of a follow-up
+ * `withContext({})` that drops org/user fields.
+ */
+declare function createAthenaServerClient<const TModels extends AthenaClientModelsInput | undefined = undefined>(options: AthenaServerClientConfig<TModels>): Promise<AthenaClient<TModels>>;
+
+export { AthenaAuthSessionBridgeOptions, AthenaAuthSessionBridgePathOptions, type AthenaEnvironmentServerConfig, type AthenaExplicitServerConfig, type AthenaRequestCookiesBag, type AthenaRequestCookiesInput, type AthenaRequestHeadersBag, type AthenaRequestHeadersInput, type AthenaResolvedServerContext, type AthenaServerClientConfig, type AthenaServerContextOptions, type AthenaServerRequestOptions, type AthenaServerScope, type AthenaServerSessionInput, type GetServerSessionEnsureActiveOptions, type GetServerSessionOptions, type GetServerSessionResult, OrganizationLike, type ResolveActiveOrganizationIdArgs, createAthenaAuthSessionBridgeHandlers, createAthenaAuthSessionBridgePathHandlers, createAthenaServerClient, getServerSession, handleAthenaAuthSessionBridgeDelete, handleAthenaAuthSessionBridgePost, isAthenaAuthSessionBridgePath, parseAthenaSessionDataHeader, resolveAthenaServerContext, resolveNextRequestContext };