katanakit-js 6.2.0 → 6.6.1

package/README.md

@@ -29,7 +29,7 @@ In the browser, use jsDelivr **`/+esm`** so named exports and dependencies resol
 | **esm.sh**                         | `https://esm.sh/katanakit-js`                                                           |
 | **Raw ESM file**                   | `https://cdn.jsdelivr.net/npm/katanakit-js/dist/index.js` (needs bundler or import map) |
 
-Pin a version in production (e.g. `@6.1.0/+esm`). There is no IIFE/UMD build.
+Pin a version in production (e.g. `@6.6.1/+esm`). There is no IIFE/UMD build.
 
 ## Quick Start
 
@@ -361,11 +361,12 @@ const stop = useKatanaWatch(newProduct, () => checkValidations(), { deep: true }
 - **Zod validation everywhere** — `types/` is the single source of truth, inferred from Zod schemas via `z.infer`; `useValidate()` turns any schema into a Safe Result and API adapters validate every response at the boundary
 - **Zero side effects** — importing any module is safe. No `fetch` calls, no `console.log`, no storage writes
 - **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
-- **Tree-shakeable** — destructured re-exports from Singleton facades
+- **Design patterns** — services are Singleton classes (`getInstance()`) with swappable Strategy implementations (`AccessService`, `AgentService`), a `QueryClientFactory` for per-request SSR clients, and composable Decorators exported from the main barrel: `RetryDecorator`, `CacheDecorator` (TTL memoization) and `LoggerDecorator` (timing traces)
+- **Tree-shakeable** — stable `use*` wrapper functions over the Singleton facades
 - **SSR-safe** — all infrastructure adapters guard or fall back gracefully in server environments
 - **Filesystem (Node/Bun)** — `useReadFile`, `useWriteFile`, `useReadJsonFile`, `useReadModuleJson`, `useHashFile` and friends return Safe Results with native errno codes, loaded lazily through dynamic `import()` and guarded by `useIsNode()`
 - **Fake data (optional)** — `useFakeVehicle`, `useFakeEmail`, `useFakeList`, … via an optional, lazy-loaded `@faker-js/faker` peer
-- **Katana UI** — framework-agnostic component foundations (`useButton`, `useInput`, `useCard`, `useBadge`, `useAlert`) live in the private `@katanakit/ui` workspace, styled with `katanakit-css` (see [UI Kit](https://docs.senseikatana.com/ui-kit/))
+- **Katana UI** — framework-agnostic component foundations (`useButton`, `useInput`, `useCard`, `useBadge`, `useAlert`) live in the private `@katanakit/ui` workspace, styled with the SCSS framework vendored in `katanakit-js` (see [UI Kit](https://docs.senseikatana.com/ui-kit/))
 
 ## Filesystem (Node/Bun)
 
@@ -819,6 +820,13 @@ See [Getting Started](https://docs.senseikatana.com/guides/getting-started) for
 | **Telegram**  | `katanakit-js/adapters/telegram`                | BotFather bot (`defineTelegramConfig`, `useStartTelegramPolling`) |
 | **WhatsApp**  | `katanakit-js/adapters/whatsapp`                | Meta Cloud API (`defineWhatsAppConfig`, `useStartWhatsApp`)  |
 
+## UI and Auth Adapters
+
+| Adapter         | Import                                   | Description                                                    |
+| --------------- | ---------------------------------------- | -------------------------------------------------------------- |
+| **PhotoSwipe**  | `katanakit-js/adapters/photoswipe`       | Lightbox bound by CSS selectors, Safe Result, SSR-safe          |
+| **Better Auth** | `katanakit-js/adapters/better-auth`      | Auth client (vanilla/react/vue/svelte/solid) + session helpers  |
+
 ## REST API Adapters
 
 Typed adapters for popular REST APIs with auth, pagination helpers, and full TypeScript types.

package/dist/adapters/better-auth/better-auth.service.d.ts

@@ -0,0 +1,83 @@
+import type { Auth, Session, User } from "better-auth";
+import type { AuthResult } from "./client.js";
+/** What `auth.api.getSession()` resolves to when a session exists. */
+export interface AuthSessionData {
+    user: User;
+    session: Session;
+    /** Plugins append their own fields (organization, roles, …). */
+    [key: string]: unknown;
+}
+/** The shape `Astro.locals` (or any framework's request context) ends up with. */
+export interface AuthLocals {
+    user: User | null;
+    session: Session | null;
+}
+/** Anything that carries request headers: a `Request`, `Headers` or `{ headers }`. */
+export type HeadersLike = Headers | Request | {
+    headers: Headers;
+};
+/**
+ * Reads the current session server-side without throwing.
+ *
+ * Returns `data: null` with `ok: true` for an anonymous visitor — only a real
+ * failure (bad config, network, malformed response) turns into `ok: false`.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - A `Request`, its `Headers`, or any object exposing `headers`
+ * @returns Safe result with the session (or `null`)
+ *
+ * @example
+ * ```ts
+ * const session = await useAuthSession(auth, request);
+ * if (session.ok && session.data) console.log(session.data.user.email);
+ * ```
+ */
+export declare function useAuthSession(auth: Auth, request: HeadersLike): Promise<AuthResult<AuthSessionData | null>>;
+/**
+ * Runs Better Auth's request handler (`auth.handler`) for a catch-all route.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - The incoming `Request`
+ * @returns Safe result with the handler's `Response`
+ *
+ * @example Astro — `src/pages/api/auth/[...all].ts`
+ * ```ts
+ * import type { APIRoute } from "astro";
+ * import { auth } from "~/auth";
+ * import { useAuthHandler } from "katanakit-js/adapters/better-auth";
+ *
+ * export const ALL: APIRoute = async ({ request }) => {
+ *   const result = await useAuthHandler(auth, request);
+ *   return result.ok ? result.data : new Response("Auth unavailable", { status: 500 });
+ * };
+ * ```
+ */
+export declare function useAuthHandler(auth: Auth, request: Request): Promise<AuthResult<Response>>;
+/**
+ * Builds the `user` / `session` pair middleware puts into the request context.
+ *
+ * Mirrors Better Auth's Astro middleware: anonymous visitors get `null` for
+ * both fields instead of an error, so a page can branch on `locals.user`.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - The incoming `Request` (or anything carrying its headers)
+ * @returns Safe result with `{ user, session }`
+ *
+ * @example Astro — `src/middleware.ts`
+ * ```ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { auth } from "~/auth";
+ * import { useAstroAuthLocals } from "katanakit-js/adapters/better-auth";
+ *
+ * export const onRequest = defineMiddleware(async (context, next) => {
+ *   const locals = await useAstroAuthLocals(auth, context.request);
+ *   if (locals.ok) {
+ *     context.locals.user = locals.data.user;
+ *     context.locals.session = locals.data.session;
+ *   }
+ *   return next();
+ * });
+ * ```
+ */
+export declare function useAstroAuthLocals(auth: Auth, request: HeadersLike): Promise<AuthResult<AuthLocals>>;
+//# sourceMappingURL=better-auth.service.d.ts.map

package/dist/adapters/better-auth/better-auth.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/better-auth/better-auth.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAQnE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAa7C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAWhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CASjC"}

package/dist/adapters/better-auth/better-auth.service.js

@@ -0,0 +1,110 @@
+function toHeaders(input) {
+    if (input instanceof Headers)
+        return input;
+    if (input && typeof input === "object" && "headers" in input)
+        return input.headers;
+    return new Headers();
+}
+/**
+ * Reads the current session server-side without throwing.
+ *
+ * Returns `data: null` with `ok: true` for an anonymous visitor — only a real
+ * failure (bad config, network, malformed response) turns into `ok: false`.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - A `Request`, its `Headers`, or any object exposing `headers`
+ * @returns Safe result with the session (or `null`)
+ *
+ * @example
+ * ```ts
+ * const session = await useAuthSession(auth, request);
+ * if (session.ok && session.data) console.log(session.data.user.email);
+ * ```
+ */
+export async function useAuthSession(auth, request) {
+    try {
+        const data = (await auth.api.getSession({
+            headers: toHeaders(request),
+        }));
+        return { data, error: null, ok: true };
+    }
+    catch (cause) {
+        return {
+            data: null,
+            error: { message: `[BetterAuth] getSession failed: ${toMessage(cause)}`, details: cause },
+            ok: false,
+        };
+    }
+}
+/**
+ * Runs Better Auth's request handler (`auth.handler`) for a catch-all route.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - The incoming `Request`
+ * @returns Safe result with the handler's `Response`
+ *
+ * @example Astro — `src/pages/api/auth/[...all].ts`
+ * ```ts
+ * import type { APIRoute } from "astro";
+ * import { auth } from "~/auth";
+ * import { useAuthHandler } from "katanakit-js/adapters/better-auth";
+ *
+ * export const ALL: APIRoute = async ({ request }) => {
+ *   const result = await useAuthHandler(auth, request);
+ *   return result.ok ? result.data : new Response("Auth unavailable", { status: 500 });
+ * };
+ * ```
+ */
+export async function useAuthHandler(auth, request) {
+    try {
+        const response = await auth.handler(request);
+        return { data: response, error: null, ok: true };
+    }
+    catch (cause) {
+        return {
+            data: null,
+            error: { message: `[BetterAuth] handler failed: ${toMessage(cause)}`, details: cause },
+            ok: false,
+        };
+    }
+}
+/**
+ * Builds the `user` / `session` pair middleware puts into the request context.
+ *
+ * Mirrors Better Auth's Astro middleware: anonymous visitors get `null` for
+ * both fields instead of an error, so a page can branch on `locals.user`.
+ *
+ * @param auth - The `betterAuth()` server instance
+ * @param request - The incoming `Request` (or anything carrying its headers)
+ * @returns Safe result with `{ user, session }`
+ *
+ * @example Astro — `src/middleware.ts`
+ * ```ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { auth } from "~/auth";
+ * import { useAstroAuthLocals } from "katanakit-js/adapters/better-auth";
+ *
+ * export const onRequest = defineMiddleware(async (context, next) => {
+ *   const locals = await useAstroAuthLocals(auth, context.request);
+ *   if (locals.ok) {
+ *     context.locals.user = locals.data.user;
+ *     context.locals.session = locals.data.session;
+ *   }
+ *   return next();
+ * });
+ * ```
+ */
+export async function useAstroAuthLocals(auth, request) {
+    const session = await useAuthSession(auth, request);
+    if (!session.ok)
+        return session;
+    return {
+        data: { user: session.data?.user ?? null, session: session.data?.session ?? null },
+        error: null,
+        ok: true,
+    };
+}
+function toMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=better-auth.service.js.map

package/dist/adapters/better-auth/better-auth.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.service.js","sourceRoot":"","sources":["../../../src/adapters/better-auth/better-auth.service.ts"],"names":[],"mappings":"AAqBA,SAAS,SAAS,CAAC,KAAkB;IACpC,IAAI,KAAK,YAAY,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACnF,OAAO,IAAI,OAAO,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,IAAU,EACV,OAAoB;IAEpB,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;YACvC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;SAC3B,CAAC,CAA2B,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO;YACN,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,EAAE,OAAO,EAAE,mCAAmC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;YACzF,EAAE,EAAE,KAAK;SACT,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAU,EAAE,OAAgB;IAChE,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO;YACN,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,EAAE,OAAO,EAAE,gCAAgC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;YACtF,EAAE,EAAE,KAAK;SACT,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,IAAU,EACV,OAAoB;IAEpB,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC;IAEhC,OAAO;QACN,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,IAAI,IAAI,EAAE;QAClF,KAAK,EAAE,IAAI;QACX,EAAE,EAAE,IAAI;KACR,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAChC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC"}

package/dist/adapters/better-auth/client.d.ts

@@ -0,0 +1,51 @@
+import type { AuthClient, BetterAuthClientOptions } from "better-auth/client";
+import type { ReactAuthClient } from "better-auth/react";
+import type { SolidAuthClient } from "better-auth/solid";
+import type { SvelteAuthClient } from "better-auth/svelte";
+import type { VueAuthClient } from "better-auth/vue";
+import type { SafeResult } from "../../types/index.js";
+/** Framework clients shipped by Better Auth — one `createAuthClient` per entry. */
+export type AuthFramework = "vanilla" | "react" | "vue" | "svelte" | "solid";
+export type { AuthClient, BetterAuthClientOptions };
+/** Client type the requested framework's `createAuthClient` returns. */
+export type AuthClientFor<F extends AuthFramework, O extends BetterAuthClientOptions = BetterAuthClientOptions> = F extends "vue" ? VueAuthClient<O> : F extends "react" ? ReactAuthClient<O> : F extends "svelte" ? SvelteAuthClient<O> : F extends "solid" ? SolidAuthClient<O> : AuthClient<O>;
+export interface AuthClientOptions<F extends AuthFramework = "vanilla"> extends BetterAuthClientOptions {
+    /**
+     * Which Better Auth client entry to load.
+     *
+     * @defaultValue `"vanilla"`
+     */
+    framework?: F;
+}
+export type AuthError = {
+    message: string;
+    details?: unknown;
+};
+export type AuthResult<T> = SafeResult<T, AuthError>;
+/**
+ * Creates the Better Auth client for the requested framework, importing only
+ * that entry — the other four never reach the bundle.
+ *
+ * @param options - `BetterAuthClientOptions` (`baseURL`, `plugins`, …) plus `framework`
+ * @returns Safe result with the framework's typed client; never throws
+ *
+ * @example Vue / Nuxt — `lib/auth-client.ts`
+ * ```ts
+ * import { useAuthClient } from "katanakit-js/adapters/better-auth";
+ *
+ * export const authClient = await useAuthClient({ framework: "vue" });
+ * export const { signIn, signUp, signOut, useSession } = authClient;
+ * ```
+ *
+ * @example React
+ * ```ts
+ * const authClient = await useAuthClient({ framework: "react", baseURL: "https://auth.example.com" });
+ * ```
+ *
+ * @example Vanilla (Astro island-free pages, plain `<script>`)
+ * ```ts
+ * const authClient = await useAuthClient();
+ * ```
+ */
+export declare function useAuthClient<F extends AuthFramework = "vanilla">(options?: AuthClientOptions<F>): Promise<AuthResult<AuthClientFor<F>>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/adapters/better-auth/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/adapters/better-auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,YAAY,EAAE,UAAU,EAAE,uBAAuB,EAAE,CAAC;AAEpD,wEAAwE;AACxE,MAAM,MAAM,aAAa,CACxB,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,uBAAuB,GAAG,uBAAuB,IACxD,CAAC,SAAS,KAAK,GAChB,aAAa,CAAC,CAAC,CAAC,GAChB,CAAC,SAAS,OAAO,GAChB,eAAe,CAAC,CAAC,CAAC,GAClB,CAAC,SAAS,QAAQ,GACjB,gBAAgB,CAAC,CAAC,CAAC,GACnB,CAAC,SAAS,OAAO,GAChB,eAAe,CAAC,CAAC,CAAC,GAClB,UAAU,CAAC,CAAC,CAAC,CAAC;AAEpB,MAAM,WAAW,iBAAiB,CACjC,CAAC,SAAS,aAAa,GAAG,SAAS,CAClC,SAAQ,uBAAuB;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAC/D,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,aAAa,GAAG,SAAS,EACtE,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAwCvC"}

package/dist/adapters/better-auth/client.js

@@ -0,0 +1,67 @@
+/**
+ * Creates the Better Auth client for the requested framework, importing only
+ * that entry — the other four never reach the bundle.
+ *
+ * @param options - `BetterAuthClientOptions` (`baseURL`, `plugins`, …) plus `framework`
+ * @returns Safe result with the framework's typed client; never throws
+ *
+ * @example Vue / Nuxt — `lib/auth-client.ts`
+ * ```ts
+ * import { useAuthClient } from "katanakit-js/adapters/better-auth";
+ *
+ * export const authClient = await useAuthClient({ framework: "vue" });
+ * export const { signIn, signUp, signOut, useSession } = authClient;
+ * ```
+ *
+ * @example React
+ * ```ts
+ * const authClient = await useAuthClient({ framework: "react", baseURL: "https://auth.example.com" });
+ * ```
+ *
+ * @example Vanilla (Astro island-free pages, plain `<script>`)
+ * ```ts
+ * const authClient = await useAuthClient();
+ * ```
+ */
+export async function useAuthClient(options) {
+    const { framework, ...clientOptions } = (options ?? {});
+    try {
+        switch (framework) {
+            case "vue": {
+                const { createAuthClient } = await import("better-auth/vue");
+                return ok(createAuthClient(clientOptions));
+            }
+            case "react": {
+                const { createAuthClient } = await import("better-auth/react");
+                return ok(createAuthClient(clientOptions));
+            }
+            case "svelte": {
+                const { createAuthClient } = await import("better-auth/svelte");
+                return ok(createAuthClient(clientOptions));
+            }
+            case "solid": {
+                const { createAuthClient } = await import("better-auth/solid");
+                return ok(createAuthClient(clientOptions));
+            }
+            default: {
+                const { createAuthClient } = await import("better-auth/client");
+                return ok(createAuthClient(clientOptions));
+            }
+        }
+    }
+    catch (cause) {
+        return {
+            data: null,
+            error: {
+                message: `[BetterAuth] cannot load the "${framework ?? "vanilla"}" client — ` +
+                    "install it with `bun add better-auth`.",
+                details: cause,
+            },
+            ok: false,
+        };
+    }
+}
+function ok(data) {
+    return { data, error: null, ok: true };
+}
+//# sourceMappingURL=client.js.map

package/dist/adapters/better-auth/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/adapters/better-auth/client.ts"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,OAA8B;IAE9B,MAAM,EAAE,SAAS,EAAE,GAAG,aAAa,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAErD,CAAC;IAEF,IAAI,CAAC;QACJ,QAAQ,SAAS,EAAE,CAAC;YACnB,KAAK,KAAK,CAAC,CAAC,CAAC;gBACZ,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;gBAC7D,OAAO,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAqB,CAAC,CAAC;YAChE,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACd,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;gBAC/D,OAAO,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAqB,CAAC,CAAC;YAChE,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACf,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;gBAChE,OAAO,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAqB,CAAC,CAAC;YAChE,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACd,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;gBAC/D,OAAO,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAqB,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACT,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;gBAChE,OAAO,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAqB,CAAC,CAAC;YAChE,CAAC;QACF,CAAC;IACF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO;YACN,IAAI,EAAE,IAAI;YACV,KAAK,EAAE;gBACN,OAAO,EACN,iCAAiC,SAAS,IAAI,SAAS,aAAa;oBACpE,wCAAwC;gBACzC,OAAO,EAAE,KAAK;aACd;YACD,EAAE,EAAE,KAAK;SACT,CAAC;IACH,CAAC;AACF,CAAC;AAED,SAAS,EAAE,CAAI,IAAO;IACrB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/dist/adapters/better-auth/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./better-auth.service.js";
+export * from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/better-auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/better-auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC"}

package/dist/adapters/better-auth/index.js

@@ -0,0 +1,3 @@
+export * from "./better-auth.service.js";
+export * from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/better-auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/better-auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC"}

package/dist/adapters/express/server.d.ts

@@ -1,4 +1,136 @@
 import { type Application, type Request } from "express";
+/**
+ * ExpressService - Singleton para el servidor Express.
+ *
+ * Aplica el patrón Singleton: una única instancia centraliza la creación,
+ * configuración de middlewares, rutas, manejo de errores y ciclo de vida del
+ * servidor HTTP (start/stop). Idempotente: crear, finalizar y arrancar son
+ * operaciones seguras de repetir.
+ *
+ * @example
+ * ```ts
+ * const app = ExpressService.getInstance().useCreate();
+ * app.use("/assistant", useCreateAssistantRouter());
+ * ExpressService.getInstance().useStart(3000, "localhost");
+ * ```
+ */
+export declare class ExpressService {
+    private static instance;
+    /** Express application instance. */
+    private app;
+    /** Whether the HTTP server has been started. */
+    private started;
+    /** Whether the error handler / 404 catch-all has been registered. */
+    private finalized;
+    /**
+     * Constructor privado - enforce singleton.
+     */
+    private constructor();
+    /**
+     * Obtiene la instancia única del ExpressService (Singleton).
+     *
+     * @returns La instancia única de {@link ExpressService}.
+     */
+    static getInstance(): ExpressService;
+    /**
+     * Returns the raw request body buffer captured by the JSON parser, if any.
+     * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
+     *
+     * @param request - The Express request.
+     * @returns The raw body buffer, or `undefined` when not available.
+     */
+    useGetRawBody(request: Request): Buffer | undefined;
+    /**
+     * Set up CORS, JSON body parser and URL-encoded middleware.
+     * The JSON parser also captures the raw body for signature verification.
+     *
+     * @param expressApp - Express application instance
+     *
+     * @example
+     * ```ts
+     * const expressApp = express();
+     * useExpressSetupMiddlewares(expressApp);
+     * ```
+     */
+    private useSetupMiddlewares;
+    /**
+     * Set up health check and application routes.
+     *
+     * @param expressApp - Express application instance
+     *
+     * @example
+     * ```ts
+     * useExpressSetupRoutes(expressApp);
+     * // GET /health returns { status: "ok", timestamp: "..." }
+     * ```
+     */
+    private useSetupRoutes;
+    /**
+     * Set up global error handling and 404 fallback. Register this AFTER all
+     * channel routers are mounted so it does not shadow them.
+     *
+     * @param expressApp - Express application instance
+     *
+     * @example
+     * ```ts
+     * useExpressSetupErrorHandling(expressApp);
+     * // Unhandled errors return 500, unknown routes return 404
+     * ```
+     */
+    private useSetupErrorHandling;
+    /**
+     * Create and configure the Express application. Mount channel routers on the
+     * returned app BEFORE calling {@link useFinalize} / {@link useStart},
+     * otherwise the 404 catch-all will shadow them.
+     *
+     * @returns Configured Express Application instance
+     *
+     * @example
+     * ```ts
+     * const expressApp = ExpressService.getInstance().useCreate();
+     * expressApp.use("/assistant", useCreateAssistantRouter());
+     * ```
+     */
+    useCreate(): Application;
+    /**
+     * Registers the error handler and 404 catch-all. Idempotent. Call this after
+     * mounting every channel router so it runs last. {@link useStart}
+     * invokes it automatically.
+     *
+     * @example
+     * ```ts
+     * ExpressService.getInstance().useGetApp().use("/assistant", useCreateAssistantRouter());
+     * ExpressService.getInstance().useFinalize();
+     * ```
+     */
+    useFinalize(): void;
+    /**
+     * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
+     * Finalizes error handling before listening.
+     *
+     * @param port - Port to listen on (default: 3000)
+     * @param host - Host to bind to (default: "localhost")
+     *
+     * @example
+     * ```ts
+     * ExpressService.getInstance().useStart(3000, "localhost");
+     * // Server running on http://localhost:3000
+     * ```
+     */
+    useStart(port?: number, host?: string): void;
+    /**
+     * Get the Express application instance. Creates it if it doesn't exist.
+     *
+     * @returns Express Application instance
+     *
+     * @example
+     * ```ts
+     * const expressApp = ExpressService.getInstance().useGetApp();
+     * expressApp.get("/custom", (req, res) => res.json({ ok: true }));
+     * ```
+     */
+    useGetApp(): Application;
+}
 /**
  * Returns the raw request body buffer captured by the JSON parser, if any.
  * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
@@ -35,7 +167,7 @@ export declare const useExpressCreate: () => Application;
  */
 export declare const useExpressFinalize: () => void;
 /**
- * Start the Express HTTP server. Idempotent — subsequent calls are no-ops.
+ * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
  * Finalizes error handling before listening.
  *
  * @param port - Port to listen on (default: 3000)

package/dist/adapters/express/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,WAAW,EAAqB,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAapG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAkFD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAQnC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAIrC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,aAAW,EAAE,aAAkB,KAAG,IAUjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAiC,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,WAAW,EAAqB,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAQpG;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IAExC,oCAAoC;IACpC,OAAO,CAAC,GAAG,CAA4B;IACvC,gDAAgD;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,qEAAqE;IACrE,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO;IAEP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,cAAc;IAOpC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAInD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,WAAW;IAUxB;;;;;;;;;;OAUG;IACH,WAAW,IAAI,IAAI;IAMnB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,SAAO,EAAE,IAAI,SAAc,GAAG,IAAI;IAY/C;;;;;;;;;;OAUG;IACH,SAAS,IAAI,WAAW;CAGxB;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAuD,CAAC;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAAkD,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,aAAW,EAAE,aAAkB,KAAG,IAChB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAuD,CAAC"}