@faable/auth-js 1.6.1 → 1.6.2-next.1

package/README.md

@@ -9,7 +9,7 @@
   <a href="https://faable.com">
     <h1 align="center">auth-js</h1>
   </a>
-  <p align="center">An isomorphic Javascript library for Faable Auth</p>
+  <p align="center">An isomorphic JavaScript client for Faable Auth.</p>
 </p>
 
 <p align="center">
@@ -18,33 +18,226 @@
   </a>
 </p>
 
+## Features
+
+- OAuth social connections (Google, GitHub, …) with PKCE and implicit flows
+- Username + password login
+- Passwordless: email magic link and OTP code
+- Automatic token refresh with cross-tab synchronization via `BroadcastChannel`
+- Pluggable storage adapters (`localStorage`, cookies, or custom)
+- Server-side session helpers for Next.js
+
 ## Install
 
 ```bash
- npm install @faable/auth-js
+npm install @faable/auth-js
+```
+
+Requires Node.js `>=22.8` for development. The published bundle runs in any
+modern browser and in Node/SSR environments.
+
+## Quick start
+
+```ts
+import { createClient } from '@faable/auth-js'
+
+export const auth = createClient({
+  domain: '<faableauth_domain>',
+  clientId: '<client_id>',
+  redirectUri: window.location.origin
+})
+
+// Trigger a social login
+await auth.signInWithOauthConnection({ connection: 'google' })
+```
+
+## Configuration
+
+`createClient(config)` accepts:
+
+| Option          | Type               | Description                                                           |
+| --------------- | ------------------ | --------------------------------------------------------------------- |
+| `domain`        | `string`           | **Required.** Your Faable Auth tenant domain.                         |
+| `clientId`      | `string`           | **Required.** Application client ID.                                  |
+| `redirectUri`   | `string`           | Default callback URL. Falls back to `window.location.origin`.         |
+| `scope`         | `string`           | Space-separated scopes. Defaults to `openid profile email`.           |
+| `storage`       | `SupportedStorage` | Custom storage adapter. Defaults to `localStorage`.                   |
+| `storageKey`    | `string`           | Prefix for the storage key. Final key is `${storageKey}-${clientId}`. |
+| `cookieOptions` | `CookieOptions`    | When set, switches storage to the cookie adapter.                     |
+| `lock`          | `LockFunc`         | Custom locking primitive for concurrent refreshes.                    |
+| `debug`         | `boolean`          | Enables verbose logging.                                              |
+
+## Authentication flows
+
+### OAuth / social connection
+
+```ts
+// Use the default connection configured on the tenant
+await auth.signInWithOauthConnection({})
+
+// Or pick a specific provider (by name or connection_id)
+await auth.signInWithOauthConnection({
+  connection_id: 'conn_01HX…', // preferred when known; falls back to `connection` for legacy tenants
+  redirectTo: 'https://app.example.com/callback',
+  scopes: 'openid profile email',
+  queryParams: { prompt: 'select_account' }
+})
+```
+
+In browsers the SDK uses the PKCE flow by default and exchanges the `code` for a
+session on the callback page. The first call to `createClient` automatically
+processes the URL when the user lands back on the redirect target.
+
+### Username + password
+
+```ts
+await auth.signInWithUsernamePassword({
+  username: 'user@example.com',
+  password: '••••••••',
+  redirectTo: 'https://app.example.com/callback'
+})
+```
+
+### Passwordless (magic link or OTP)
+
+```ts
+// Step 1 — request a code or link
+await auth.signInWithPasswordless({
+  email: 'user@example.com',
+  type: 'code' // or "link"
+})
+
+// Step 2 — complete the login with the OTP the user received
+const { data, error } = await auth.signInWithOtp({
+  username: 'user@example.com',
+  otp: '123456'
+})
+```
+
+### Password reset
+
+```ts
+await auth.changePassword({ email: 'user@example.com' })
+```
+
+### Sign out
+
+```ts
+await auth.signOut() // global — all sessions for this user
+await auth.signOut({ scope: 'local' }) // only this device
+```
+
+## Sessions and state changes
+
+```ts
+// Get the current session (refreshes if needed)
+const {
+  data: { session }
+} = await auth.getSession()
+
+// Subscribe to auth events
+const {
+  data: { subscription }
+} = auth.onAuthStateChange((event, session) => {
+  // event: INITIAL_SESSION | SIGNED_IN | SIGNED_OUT | TOKEN_REFRESHED | PASSWORD_RECOVERY | USER_UPDATED
+})
+
+// Stop listening
+subscription.unsubscribe()
+
+// Force a refresh
+await auth.refreshSession()
 ```
 
-## Configure
+Auth events are broadcast across tabs using `BroadcastChannel`, so a sign-in or
+sign-out in one tab is reflected in every other tab using the same `storageKey`.
+
+## Storage adapters
+
+### Trade-offs
+
+Refresh tokens are sensitive: anyone who reads them can impersonate the user
+until the token is revoked. The storage you pick decides where they live:
+
+- **`localStorage` (default)** — simple and supports cross-tab sync via
+  `BroadcastChannel`, but any script running on the same origin can read it. **A
+  single XSS lets an attacker exfiltrate the refresh token.** Acceptable for
+  low-risk apps and prototypes; not recommended when the surface has third-party
+  scripts, user-generated HTML, or strict compliance requirements.
+- **Cookies** — required for SSR (server reads them on every request) and the
+  only adapter that lets you scope storage with `Secure`, `SameSite`, and
+  `Domain`. Note that this library writes cookies from JavaScript, so they
+  cannot be marked `HttpOnly`; an XSS can still read them, but cookies make CSRF
+  and same-site policies enforceable in a way `localStorage` does not.
+- **Custom adapter** — use for in-memory storage (tokens lost on reload, safest
+  against XSS), Web Workers, or platform-specific keychains.
 
-```js
-import { createClient } from "@faable/auth-js";
+If your app is exposed to untrusted content, prefer cookies with `Secure: true`
+and `SameSite: "Lax"` (or `"Strict"`), and treat XSS prevention (CSP, escaping,
+framework guarantees) as a hard requirement regardless of which adapter you
+pick.
+
+### localStorage (default)
+
+Used automatically in browsers. No configuration required.
+
+### Cookies
+
+Useful for SSR setups where the server must read the session from the request.
+
+```ts
+import { createClient } from '@faable/auth-js'
 
 export const auth = createClient({
-  domain: "<faableauth_domain>",
-  clientId: "<client_id>",
-});
+  domain: '<faableauth_domain>',
+  clientId: '<client_id>',
+  cookieOptions: {
+    domain: '.example.com',
+    path: '/',
+    sameSite: 'Lax',
+    secure: true,
+    maxAge: 60 * 60 * 24 * 7
+  }
+})
 ```
 
-## Login
+### Custom adapter
 
-To login with a specific connection (Google, Facebook, etc.), you can set it once on your client instance.
+Provide any object that implements `getItem`, `setItem`, and `removeItem` (sync
+or async). Set `isServer: true` if values may come from an untrusted source such
+as request cookies.
 
-```js
-// Sign in using default connection
-auth.signInWithOauthConnection();
+```ts
+const memoryStorage = {
+  store: new Map<string, string>(),
+  getItem: (k: string) => memoryStorage.store.get(k) ?? null,
+  setItem: (k: string, v: string) => void memoryStorage.store.set(k, v),
+  removeItem: (k: string) => void memoryStorage.store.delete(k)
+}
 
-// Or use specific connection
-auth.signInWithOauthConnection({
-  connection: "<connection_id>",
-});
+createClient({ domain, clientId, storage: memoryStorage })
 ```
+
+## Next.js / server-side
+
+Use cookie storage on the client, then read the session from `next/headers` on
+the server:
+
+```ts
+// app/page.tsx
+import { cookies } from "next/headers";
+import { getSessionFromCookies } from "@faable/auth-js";
+
+export default async function Page() {
+  const session = getSessionFromCookies(cookies(), "faable.auth.token-<client_id>");
+  if (!session) return <SignIn />;
+  return <Dashboard user={session.user} />;
+}
+```
+
+The storage key follows the pattern
+`${storageKey ?? "faable.auth.token"}-${clientId}`.
+
+## License
+
+See [LICENSE.md](LICENSE.md).

package/dist/dts/Base.d.ts

@@ -1,4 +1,4 @@
-import { BaseLog, BaseLogOptions } from "./BaseLog";
+import { BaseLog, BaseLogOptions } from './BaseLog';
 export declare abstract class Base extends BaseLog {
     private static nextInstanceID;
     private instanceID;

package/dist/dts/FaableAuthApi.d.ts

@@ -1,5 +1,5 @@
-import { BaseLog, BaseLogOptions } from "./BaseLog";
-import { AuthError } from "./lib/errors";
+import { BaseLog, BaseLogOptions } from './BaseLog';
+import { AuthError } from './lib/errors';
 export default class FaableAuthApi extends BaseLog {
     base_url: string;
     constructor(base_url: string, config: BaseLogOptions);

package/dist/dts/FaableAuthClient.d.ts

@@ -1,18 +1,19 @@
-import { SupportedStorage, SignInWithOAuthConnection, OAuthResponse, Subscription, InitializeResult, CallRefreshTokenResult } from "./lib/types";
-import { FaableAuthClientConfig, AuthResponse, AuthChangeEvent } from "./lib/types";
-import { Session, SignOut } from "./lib/types";
-import { Deferred } from "./lib/helpers";
-import { cookieStorageAdapter } from "./lib/storage/cookie-storage";
-import { getSessionFromCookies } from "./lib/nextjs";
+import { Base } from './Base';
+import FaableAuthApi from './FaableAuthApi';
+import { BroadcastSync } from './lib/broadcast_sync';
+import { AuthError } from './lib/errors';
+import { Deferred } from './lib/helpers';
+import { getSessionFromCookies } from './lib/nextjs';
+import { cookieStorageAdapter } from './lib/storage/cookie-storage';
+import { AuthFlowType, CallRefreshTokenResult, InitializeResult, OAuthResponse, SignInWithOAuthConnection, Subscription, SupportedStorage } from './lib/types';
+import { AuthChangeEvent, AuthResponse, FaableAuthClientConfig } from './lib/types';
+import { Session, SignOut } from './lib/types';
+import { Lock } from './lock/Lock';
 export { cookieStorageAdapter, getSessionFromCookies };
-import { AuthError } from "./lib/errors";
-import FaableAuthApi from "./FaableAuthApi";
-import { Base } from "./Base";
-import { Lock } from "./lock/Lock";
 export declare class FaableAuthClient extends Base {
     domainUrl: string;
     tokenIssuer: string;
-    redirect_uri: string;
+    redirectUri: string;
     scope?: string;
     sessionCheckExpiryDays: number;
     protected initializePromise: Promise<InitializeResult> | null;
@@ -26,11 +27,16 @@ export declare class FaableAuthClient extends Base {
     protected visibilityChangedCallback: (() => Promise<any>) | null;
     protected refreshingDeferred: Deferred<CallRefreshTokenResult> | null;
     /**
-     * Used to broadcast state change events to other tabs listening.
+     * Cross-tab broadcaster + local subscriber registry for state changes.
      */
-    protected broadcastChannel: BroadcastChannel | null;
-    protected stateChangeEmitters: Map<string, Subscription>;
+    protected broadcastSync: BroadcastSync;
     protected _session: Session | null;
+    /**
+     * Initiation flow to use when redirecting to /authorize. Defaults to
+     * PKCE in browsers (recommended for SPAs) and implicit otherwise.
+     * Distinct from the callback-side flow which is detected from URL params.
+     */
+    protected flowType: AuthFlowType;
     protected lock: Lock;
     constructor(config: FaableAuthClientConfig);
     /**
@@ -83,8 +89,8 @@ export declare class FaableAuthClient extends Base {
      * refresh the session. If refreshing fails it will be retried for as long as
      * necessary.
      *
-     * If you set the {@link GoTrueClientOptions#autoRefreshToken} you don't need
-     * to call this function, it will be called for you.
+     * If `autoRefreshToken` is enabled in the client config you don't need to
+     * call this function, it will be called for you.
      *
      * On browsers the refresh process works only when the tab/window is in the
      * foreground to conserve resources as well as prevent race conditions and
@@ -121,9 +127,12 @@ export declare class FaableAuthClient extends Base {
     signInWithUsernamePassword(data: {
         username: string;
         password: string;
-        redirect_uri?: string;
+        redirectTo?: string;
         state?: string;
-    }): Promise<void>;
+    }): Promise<{
+        data: null;
+        error: AuthError | null;
+    }>;
     /**
      * Completes a passwordless login using an OTP code.
      * @param data The username and OTP code.
@@ -138,14 +147,17 @@ export declare class FaableAuthClient extends Base {
      */
     signInWithPasswordless(data: {
         email: string;
-        type: "code" | "link";
+        type: 'code' | 'link';
     }): Promise<{
         data: any;
         error: AuthError | null;
     }>;
     changePassword(params: {
         email: string;
-    }): Promise<unknown>;
+    }): Promise<{
+        data: unknown;
+        error: AuthError | null;
+    }>;
     buildAuthorizeUrl(options?: {
         connection?: string;
         redirectTo?: string;
@@ -210,7 +222,6 @@ export declare class FaableAuthClient extends Base {
      */
     private __loadSession;
     private _removeSession;
-    private _isValidSession;
     protected _setSession(currentSession: {
         access_token: string;
         refresh_token: string;
@@ -239,9 +250,7 @@ export declare class FaableAuthClient extends Base {
     signOut(options?: SignOut): Promise<{
         error: AuthError | null;
     }>;
-    protected _signOut({ scope, returnTo }?: SignOut & {
-        returnTo?: string;
-    }): Promise<{
+    protected _signOut({ scope }?: SignOut): Promise<{
         error: AuthError | null;
     }>;
     /**

package/dist/dts/createClient.d.ts

@@ -1,3 +1,3 @@
-import { FaableAuthClient } from "./FaableAuthClient";
-import { FaableAuthClientConfig } from "./lib/types";
+import { FaableAuthClient } from './FaableAuthClient';
+import { FaableAuthClientConfig } from './lib/types';
 export declare const createClient: (config: FaableAuthClientConfig) => FaableAuthClient;

package/dist/dts/entry.d.ts

@@ -0,0 +1,7 @@
+import { FaableAuthClient, cookieStorageAdapter, getSessionFromCookies } from './FaableAuthClient';
+import { createClient } from './createClient';
+import { AuthError } from './lib/errors';
+import { Session, User } from './lib/types';
+import type { AuthChangeEvent, AuthFlowType, AuthResponse, CookieOptions, FaableAuthClientConfig, OAuthResponse, Provider, SignInWithOAuthConnection, SignOut, Subscription, SupportedStorage } from './lib/types';
+export { Session, User, FaableAuthClient, AuthError, createClient, cookieStorageAdapter, getSessionFromCookies };
+export type { FaableAuthClientConfig, SignInWithOAuthConnection, AuthResponse, AuthChangeEvent, Subscription, SignOut, SupportedStorage, CookieOptions, OAuthResponse, AuthFlowType, Provider };

package/dist/dts/entrypoints/faableauth.d.ts

@@ -1,5 +1 @@
-import { FaableAuthClient } from "../FaableAuthClient";
-import { Session, User } from "../lib/types";
-import { AuthError } from "../lib/errors";
-import { createClient } from "../createClient";
-export { Session, User, FaableAuthClient, AuthError, createClient };
+export * from '../entry';

package/dist/dts/entrypoints/main.es.d.ts

@@ -1,5 +1 @@
-import { FaableAuthClient } from "../FaableAuthClient";
-import { Session, User } from "../lib/types";
-import { AuthError } from "../lib/errors";
-import { createClient } from "../createClient";
-export { Session, User, FaableAuthClient, AuthError, createClient };
+export * from '../entry';

package/dist/dts/lib/auth_helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Picks the OAuth `response_type` for an authorize request.
+ *
+ * Browsers default to the authorization code flow (PKCE); non-browser
+ * environments default to the implicit token flow. A caller-provided
+ * value always wins.
+ */
+export declare const resolveResponseType: (options: {
+    response_type?: string;
+}, isBrowserEnv: boolean) => string;
+/**
+ * Renders an HTML form returned by the authorization server and submits it,
+ * triggering the browser navigation that completes the username/password
+ * login flow.
+ */
+export declare const buildAndSubmitForm: (formHtml: string, doc: Document) => void;

package/dist/dts/lib/broadcast_sync.d.ts

@@ -0,0 +1,22 @@
+import type { AuthChangeEvent, Session, Subscription } from './types';
+type Listener = (event: AuthChangeEvent, session: Session | null) => void | Promise<void>;
+type DebugFn = (message: string, ...args: unknown[]) => void;
+/**
+ * Wraps a BroadcastChannel plus an in-process subscriber registry so the
+ * auth client can fan out state changes to local subscribers and other tabs
+ * in one call. Cross-tab messages are delivered to local subscribers but
+ * NOT re-broadcast, to avoid echo loops.
+ */
+export declare class BroadcastSync {
+    private debug;
+    private channel;
+    private subscribers;
+    constructor(channelName: string, debug: DebugFn);
+    subscribe(callback: Listener): {
+        subscription: Subscription;
+    };
+    notify(event: AuthChangeEvent, session: Session | null, broadcast?: boolean): Promise<void>;
+    private dispatch;
+    close(): void;
+}
+export {};

package/dist/dts/lib/constants.d.ts

@@ -1,9 +1,8 @@
-export declare const GOTRUE_URL = "http://localhost:9999";
 export declare const STORAGE_KEY = "faableauth";
 export declare const EXPIRY_MARGIN = 10;
 export declare const API_VERSION_HEADER_NAME = "X-Faableauth-Api-Version";
 export declare const API_VERSIONS: {
-    "2024-01-01": {
+    '2024-01-01': {
         timestamp: number;
         name: string;
     };

package/dist/dts/lib/errors.d.ts

@@ -3,7 +3,7 @@
  * not included in this list (if the client library is older than the version
  * on the server).
  */
-export type ErrorCode = "unexpected_failure" | "validation_failed" | "bad_json" | "email_exists" | "phone_exists" | "bad_jwt" | "not_admin" | "no_authorization" | "user_not_found" | "session_not_found" | "flow_state_not_found" | "flow_state_expired" | "signup_disabled" | "user_banned" | "provider_email_needs_verification" | "invite_not_found" | "bad_oauth_state" | "bad_oauth_callback" | "oauth_provider_not_supported" | "unexpected_audience" | "single_identity_not_deletable" | "email_conflict_identity_not_deletable" | "identity_already_exists" | "email_provider_disabled" | "phone_provider_disabled" | "too_many_enrolled_mfa_factors" | "mfa_factor_name_conflict" | "mfa_factor_not_found" | "mfa_ip_address_mismatch" | "mfa_challenge_expired" | "mfa_verification_failed" | "mfa_verification_rejected" | "insufficient_aal" | "captcha_failed" | "saml_provider_disabled" | "manual_linking_disabled" | "sms_send_failed" | "email_not_confirmed" | "phone_not_confirmed" | "reauth_nonce_missing" | "saml_relay_state_not_found" | "saml_relay_state_expired" | "saml_idp_not_found" | "saml_assertion_no_user_id" | "saml_assertion_no_email" | "user_already_exists" | "sso_provider_not_found" | "saml_metadata_fetch_failed" | "saml_idp_already_exists" | "sso_domain_already_exists" | "saml_entity_id_mismatch" | "conflict" | "provider_disabled" | "user_sso_managed" | "reauthentication_needed" | "same_password" | "reauthentication_not_valid" | "otp_expired" | "otp_disabled" | "identity_not_found" | "weak_password" | "over_request_rate_limit" | "over_email_send_rate_limit" | "over_sms_send_rate_limit" | "bad_code_verifier";
+export type ErrorCode = 'unexpected_failure' | 'validation_failed' | 'bad_json' | 'email_exists' | 'phone_exists' | 'bad_jwt' | 'not_admin' | 'no_authorization' | 'user_not_found' | 'session_not_found' | 'flow_state_not_found' | 'flow_state_expired' | 'signup_disabled' | 'user_banned' | 'provider_email_needs_verification' | 'invite_not_found' | 'bad_oauth_state' | 'bad_oauth_callback' | 'oauth_provider_not_supported' | 'unexpected_audience' | 'single_identity_not_deletable' | 'email_conflict_identity_not_deletable' | 'identity_already_exists' | 'email_provider_disabled' | 'phone_provider_disabled' | 'too_many_enrolled_mfa_factors' | 'mfa_factor_name_conflict' | 'mfa_factor_not_found' | 'mfa_ip_address_mismatch' | 'mfa_challenge_expired' | 'mfa_verification_failed' | 'mfa_verification_rejected' | 'insufficient_aal' | 'captcha_failed' | 'saml_provider_disabled' | 'manual_linking_disabled' | 'sms_send_failed' | 'email_not_confirmed' | 'phone_not_confirmed' | 'reauth_nonce_missing' | 'saml_relay_state_not_found' | 'saml_relay_state_expired' | 'saml_idp_not_found' | 'saml_assertion_no_user_id' | 'saml_assertion_no_email' | 'user_already_exists' | 'sso_provider_not_found' | 'saml_metadata_fetch_failed' | 'saml_idp_already_exists' | 'sso_domain_already_exists' | 'saml_entity_id_mismatch' | 'conflict' | 'provider_disabled' | 'user_sso_managed' | 'reauthentication_needed' | 'same_password' | 'reauthentication_not_valid' | 'otp_expired' | 'otp_disabled' | 'identity_not_found' | 'weak_password' | 'over_request_rate_limit' | 'over_email_send_rate_limit' | 'over_sms_send_rate_limit' | 'bad_code_verifier';
 export declare class AuthError extends Error {
     /**
      * Error code associated with the error. Most errors coming from

package/dist/dts/lib/helpers.d.ts

@@ -1,5 +1,5 @@
-import { AuthResponse, SupportedStorage, User } from "./types";
-import { JsonResponse } from "./fetch";
+import { JsonResponse } from './fetch';
+import { AuthResponse, SupportedStorage, User } from './types';
 export declare function decodeBase64URL(value: string): string;
 export declare function generatePKCEVerifier(): string;
 export declare function generatePKCEChallenge(verifier: string): Promise<string>;
@@ -19,7 +19,7 @@ export type RawAuthResponse = {
     token_type: string;
 };
 export declare function expiresAt(expiresIn: number): number;
-export declare function _sessionResponse({ data, }: JsonResponse<Partial<RawAuthResponse>>): AuthResponse;
+export declare function _sessionResponse({ data }: JsonResponse<Partial<RawAuthResponse>>): AuthResponse;
 /**
  * A deferred represents some asynchronous work that is not yet finished, which
  * may or may not culminate in a value.
@@ -42,7 +42,7 @@ export declare function retryable<T>(fn: (attempt: number) => Promise<T>, isRetr
  * Creates a promise that resolves to null after some time.
  */
 export declare function sleep(time: number): Promise<null>;
-export declare const checkExpiresInTime: ({ expires_in, expires_at, refreshTick, }: {
+export declare const checkExpiresInTime: ({ expires_in, expires_at, refreshTick }: {
     expires_in: string;
     expires_at?: string;
     refreshTick: number;

package/dist/dts/lib/nextjs.d.ts

@@ -1,4 +1,4 @@
-import { Session } from "./types";
+import { Session } from './types';
 /**
  * Helper for Next.js to get the session from the server-side cookies.
  * This can be used in API routes or Server Components.

package/dist/dts/lib/pkce_storage.d.ts

@@ -0,0 +1,15 @@
+import type { SupportedStorage } from './types';
+export declare const CODE_VERIFIER_TTL_MS: number;
+type LoadedCodeVerifier = {
+    verifier: string;
+    redirectType?: string;
+};
+export declare const saveCodeVerifier: (storage: SupportedStorage, key: string, { verifier, redirectType, now }: {
+    verifier: string;
+    redirectType?: string;
+    now?: number;
+}) => Promise<void>;
+export declare const loadCodeVerifier: (storage: SupportedStorage, key: string, { now }?: {
+    now?: number;
+}) => Promise<LoadedCodeVerifier | null>;
+export {};

package/dist/dts/lib/session_helpers.d.ts

@@ -0,0 +1,7 @@
+import type { Session } from './types';
+/**
+ * Type guard for a stored session blob — checks the presence of the fields
+ * the client needs to consider the value usable. Does not validate the
+ * cryptographic signature of the access/refresh tokens.
+ */
+export declare const isValidSession: (value: unknown) => value is Session;

package/dist/dts/lib/storage/cookie-storage.d.ts

@@ -1,14 +1,20 @@
-import { SupportedStorage } from "../types";
-interface CookieOptions {
-    domain?: string;
-    path?: string;
-    sameSite?: "Lax" | "Strict" | "None";
-    secure?: boolean;
-    maxAge?: number;
+import { SupportedStorage } from '../types';
+import { CookieAttributes } from './cookie_helpers';
+export type CookieOptions = CookieAttributes;
+/**
+ * Document-like surface the cookie adapter needs. Accepting a minimal shape
+ * (instead of the full DOM `Document`) keeps the adapter testable without
+ * jsdom and works in any environment that exposes a `cookie` property.
+ */
+export interface CookieJar {
+    cookie: string;
 }
 /**
- * A storage adapter that uses document.cookie to persist data.
- * This is useful for SSR as cookies are sent to the server on every request.
+ * A storage adapter that uses `document.cookie` to persist sessions. Useful
+ * in SSR setups where the server reads the cookie on every request.
+ *
+ * The optional `jar` parameter lets tests inject a fake document; production
+ * code passes nothing and the adapter uses the real `document` in browsers
+ * (and no-ops on the server).
  */
-export declare const cookieStorageAdapter: (options?: CookieOptions) => SupportedStorage;
-export {};
+export declare const cookieStorageAdapter: (options?: CookieOptions, jar?: CookieJar | null) => SupportedStorage;

package/dist/dts/lib/storage/cookie_helpers.d.ts

@@ -0,0 +1,25 @@
+export interface CookieAttributes {
+    domain?: string;
+    path?: string;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    secure?: boolean;
+    maxAge?: number;
+}
+/**
+ * Parses a raw cookie string (the shape of `document.cookie`) into a Map of
+ * decoded name → value. Splitting happens BEFORE decoding so encoded `;` and
+ * `=` characters inside a value don't break the parser.
+ */
+export declare const parseCookies: (cookieString: string) => Map<string, string>;
+/**
+ * Builds a `name=value; Attr=...` string suitable for assignment to
+ * `document.cookie`. Encodes name and value per RFC 6265 and forces `Secure`
+ * when `SameSite=None` (browsers reject the cookie otherwise).
+ */
+export declare const serializeCookie: (name: string, value: string, attrs: CookieAttributes) => string;
+/**
+ * Builds the cookie string that clears `name`. Browsers will only remove a
+ * cookie when the deletion attributes (Domain, Path, SameSite, Secure) match
+ * those used at write time, so we mirror them here.
+ */
+export declare const serializeCookieRemoval: (name: string, attrs: CookieAttributes) => string;

package/dist/dts/lib/storage/local-storage.d.ts

@@ -1,4 +1,4 @@
-import { SupportedStorage } from "../types";
+import { SupportedStorage } from '../types';
 /**
  * Provides safe access to the globalThis.localStorage property.
  */

package/dist/dts/lib/storage_helpers.d.ts

@@ -1,3 +1,3 @@
-import { SupportedStorage } from "./types";
+import { SupportedStorage } from './types';
 export declare const setItemAsync: (storage: SupportedStorage, key: string, data: any) => Promise<void>;
 export declare const getItemAsync: (storage: SupportedStorage, key: string) => Promise<unknown>;