@dontcode2/backend 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -4,11 +4,16 @@ interface TransportConfig {
     apiKey?: string;
     /** Gateway origin, already normalized (no trailing slash). */
     baseUrl: string;
+    /** Per-request timeout in ms. Defaults to `DEFAULT_TIMEOUT_MS`; `0` (or any
+     *  non-positive value) disables it. */
+    timeoutMs?: number;
 }
 interface RequestOptions {
     /** End-user access token, sent as `X-Access-Token` (separate from the
      *  project API key). Required by signed-in auth calls. */
     accessToken?: string;
+    /** Override the client's timeout for this one call (ms). `0` disables it. */
+    timeoutMs?: number;
 }
 /**
  * The single place network requests are made. Everything else in the SDK is a
@@ -20,6 +25,15 @@ declare class Transport {
     constructor(config: TransportConfig);
     private headers;
     private url;
+    private timeout;
+    /**
+     * One fetch, with a timeout that turns "hung socket" into a fast, typed
+     * failure. A timeout surfaces as `DontCodeError` with status 408 / code
+     * `Timeout`; any other transport failure (DNS, refused, offline) as status
+     * 0 / code `NetworkError`. Both are distinct from a real `401`, so an auth
+     * guard can tell "backend is down" apart from "user is signed out".
+     */
+    private send;
     /** POST a JSON body and parse the JSON response. */
     json<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
     /** PUT a multipart form (file uploads). The runtime sets the boundary. */
@@ -188,6 +202,107 @@ interface TemporaryUrlResult {
 /** Bytes the SDK can turn into an upload body. */
 type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
 
+/**
+ * Session helpers, framework-agnostic by design. They never touch a request or
+ * response object; they take a token (or a cookie header) and return plain
+ * data, so they slot into any framework's guard (Next middleware, SvelteKit
+ * hooks, Express, a worker) without an adapter.
+ *
+ * The point of the module: an auth guard must not make a network round-trip on
+ * every navigation, or a slow gateway stalls the page and a swallowed timeout
+ * reads as "signed out". So there are two modes:
+ *
+ *   - optimistic — decode the token locally (no signature check, no network)
+ *     and trust its claims for routing. Instant. Used for the common gate.
+ *   - verified   — call the gateway's `me` once, cache the result for a short
+ *     TTL, and hard-timeout the request. Used for sensitive actions.
+ *
+ * The trade-offs (no signature verification, revocation lag) are documented on
+ * `getSession` and in the public BYOC docs; read them before choosing a mode.
+ */
+/** A JWT payload decoded WITHOUT verifying its signature. Trust accordingly. */
+interface DecodedSession {
+    /** Subject — the user id. */
+    sub: string;
+    email?: string;
+    role?: string;
+    claims?: Record<string, unknown>;
+    /** Expiry, seconds since the epoch (standard JWT `exp`). */
+    exp?: number;
+    /** Issued-at, seconds since the epoch (standard JWT `iat`). */
+    iat?: number;
+    [key: string]: unknown;
+}
+type SessionStatus = 
+/** A usable session: a present, unexpired token (verified or optimistic). */
+'active'
+/** The token is present but past its `exp`. */
+ | 'expired'
+/** No token, or an unparseable one. */
+ | 'anonymous'
+/** Verified mode could not reach the gateway (timeout/network/5xx). The
+ *  optimistically-decoded `user` is still returned so the caller can choose
+ *  to fail open during an outage instead of logging everyone out. */
+ | 'unavailable';
+interface SessionResult {
+    status: SessionStatus;
+    /** The signed-in user, or `null` when anonymous/expired. In `verified` mode
+     *  this came from the gateway; in `optimistic` (or `unavailable`) it was
+     *  decoded from the token's own claims. */
+    user: CurrentUser | null;
+    /** True only when `user` was confirmed by a gateway `me` call this request
+     *  (or from a fresh cache entry of one). False for optimistic decodes. */
+    verified: boolean;
+    /** The token's `exp` (seconds since epoch), when present. */
+    expiresAt?: number;
+}
+interface GetSessionInput {
+    accessToken: string;
+    /** `optimistic` (default): decode locally, zero network. `verified`: confirm
+     *  against the gateway with caching + a hard timeout. */
+    mode?: 'optimistic' | 'verified';
+}
+/** A place to cache verified sessions. Swap the default in-memory store for a
+ *  shared one (Redis, KV) when running multiple instances. */
+interface SessionCache {
+    get(token: string): SessionResult | undefined;
+    set(token: string, value: SessionResult, ttlMs: number): void;
+    delete?(token: string): void;
+}
+interface SessionOptions {
+    /** Cache for verified sessions. Defaults to a per-process `InMemorySessionCache`. */
+    cache?: SessionCache;
+    /** How long a verified session stays cached. Default 60_000 (60s). Keep it
+     *  short: a cached session can outlive a server-side revocation by up to
+     *  this long. */
+    ttlMs?: number;
+    /** Timeout for the `me` call made by `verified` mode (ms). Default 5_000. */
+    verifyTimeoutMs?: number;
+}
+/** Default cache: a `Map` with per-entry TTL. Lives for the life of the process
+ *  (and is shared across requests on a reused serverless instance). */
+declare class InMemorySessionCache implements SessionCache {
+    private readonly store;
+    get(token: string): SessionResult | undefined;
+    set(token: string, value: SessionResult, ttlMs: number): void;
+    delete(token: string): void;
+}
+/**
+ * Decode a JWT access token's payload WITHOUT verifying its signature, or
+ * return `null` if it is not a parseable JWT. This is deliberately cheap and
+ * offline; it is not proof the token is genuine. DontCode tokens are signed
+ * with a secret the gateway never shares, so the only authority on a token is
+ * the gateway's `me` endpoint — use `getSession({ mode: 'verified' })` when you
+ * need that authority.
+ */
+declare function decodeAccessToken(token: string): DecodedSession | null;
+/** True when a token (or already-decoded payload) is past its `exp`. A token
+ *  with no `exp` is treated as not expired (the caller cannot prove otherwise
+ *  offline). `skewSeconds` widens the window to absorb clock drift. */
+declare function isSessionExpired(input: string | DecodedSession | null, opts?: {
+    skewSeconds?: number;
+}): boolean;
+
 /**
  * MFA is per-user and opt-in. `enroll`/`enrollConfirm`/`disable` act as the
  * signed-in user, so they need the end-user access token. `challenge` does
@@ -221,7 +336,8 @@ declare class MfaApi {
 declare class AuthApi {
     private readonly transport;
     readonly mfa: MfaApi;
-    constructor(transport: Transport);
+    private readonly sessions;
+    constructor(transport: Transport, sessionOptions?: SessionOptions);
     /** Create an account. If the project requires email verification the
      *  response has `verification_required: true` and NO tokens; collect a
      *  code and call `verifyEmail`, then `login`. */
@@ -230,10 +346,39 @@ declare class AuthApi {
      *  challenge (finish via `mfa.challenge`); otherwise `tokens` is your
      *  session. A 403 `EmailNotVerified` means the email step isn't done. */
     login(input: LoginInput): Promise<LoginResult>;
-    /** Resolve the signed-in user from their access token, or `{ user: null }`. */
+    /** Resolve the signed-in user from their access token, or `{ user: null }`.
+     *  This is a network round-trip; for a per-navigation guard prefer
+     *  `getSession`, which can answer offline and caches verified results. */
     me(input: {
         accessToken: string;
+        timeoutMs?: number;
     }): Promise<MeResult>;
+    /**
+     * Resolve an access token into a session for a route guard, the one call
+     * that replaces "hit `me` on every navigation". Two modes:
+     *
+     *   - `'optimistic'` (default): decode the token locally and trust its
+     *     claims. Zero network, zero stall. The right default for gating page
+     *     loads. It does NOT verify the signature and will not notice a
+     *     server-side revocation until the token's own `exp`.
+     *   - `'verified'`: confirm against the gateway's `me`, cached for a short
+     *     TTL with a hard timeout. Use it before sensitive actions. On a
+     *     timeout/outage it returns `status: 'unavailable'` with the optimistic
+     *     user, so you choose whether to fail open rather than the SDK guessing.
+     *
+     * See the BYOC docs ("Sessions") for the full reasoning and best practices.
+     */
+    getSession(input: GetSessionInput): Promise<SessionResult>;
+    /** Read the access token from a `Cookie` request header and resolve it, in
+     *  one call. `name` defaults to `dc_access_token`. Returns the anonymous
+     *  session when no cookie is present. */
+    sessionFromCookies(cookieHeader: string | null | undefined, options?: {
+        mode?: GetSessionInput['mode'];
+        cookieName?: string;
+    }): Promise<SessionResult>;
+    /** Decode an access token's claims locally without a network call or any
+     *  signature check. Convenience re-export of `decodeAccessToken`. */
+    decodeToken(token: string): DecodedSession | null;
     /** Confirm the 6-digit code emailed at signup. */
     verifyEmail(input: VerifyEmailInput): Promise<SimpleResult>;
     forgotPassword(input: ForgotPasswordInput): Promise<SimpleResult>;
@@ -339,6 +484,12 @@ interface DontCodeClientOptions {
     /** Gateway origin. Defaults to `process.env.DONTCODE_API_URL`, then to
      *  `https://backend.dontcode.co`. */
     baseUrl?: string;
+    /** Per-request network timeout in ms. Defaults to 10_000; `0` disables it.
+     *  Without one, a slow gateway can hang a request for the full socket
+     *  timeout, the worst case for an auth guard. */
+    timeoutMs?: number;
+    /** Caching + timeout policy for `auth.getSession` / `auth.sessionFromCookies`. */
+    session?: SessionOptions;
 }
 interface DontCodeClient {
     auth: AuthApi;
@@ -367,6 +518,11 @@ declare function dontcode(options?: DontCodeClientOptions): DontCodeClient;
  * Note: many "one more step" auth states (signup needing email verification,
  * login returning `mfa_required`) are 2xx successes, NOT errors; inspect the
  * resolved value for those. Errors are reserved for actual failures.
+ *
+ * Transport failures (no HTTP response at all) also surface as a DontCodeError
+ * so callers have one error type: a timeout is status 408 / code `Timeout`, and
+ * any other network failure is status 0 / code `NetworkError`. Neither is a
+ * `401`, so a guard can distinguish "backend unavailable" from "signed out".
  */
 interface DontCodeErrorBody {
     error?: string;
@@ -392,4 +548,41 @@ declare class DontCodeError extends Error {
 /** Cross-bundle-safe check; works even if two copies of the SDK are loaded. */
 declare function isDontCodeError(err: unknown): err is DontCodeError;
 
-export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, type DbClient, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, type ListResult, type LoginInput, type LoginResult, type MeResult, MfaApi, type MfaChallengeInput, type MfaDisableInput, type MfaEnrollConfirmInput, type MfaEnrollResult, type MigrateInput, type MigrateResult, type OrderByClause, type PresignResult, PublicBucketClient, type QueryOptions, type ResetPasswordInput, type SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, createStorage, dontcode, isDontCodeError };
+/**
+ * Cookie helpers, framework-agnostic by design. They return strings: a
+ * `Set-Cookie` header value to write, or a parsed token to read. Your framework
+ * applies them (`headers.append('Set-Cookie', …)`, SvelteKit `cookies.set`, a
+ * Next `Response` cookie, etc.). The SDK never owns a request or response.
+ *
+ * Defaults match how DontCode's own apps store the session: an httpOnly cookie
+ * so JavaScript can't read the token, `Secure`, `SameSite=Lax`, path `/`, and a
+ * 7-day max age. Cross-site setups (your app and the gateway on different sites)
+ * need `sameSite: 'none'`, which forces `Secure` on.
+ */
+/** Default cookie name for the end-user access token. */
+declare const DEFAULT_SESSION_COOKIE_NAME = "dc_access_token";
+interface SessionCookieOptions {
+    /** Cookie name. Default `dc_access_token`. */
+    name?: string;
+    /** Lifetime in seconds. Default one week. Pass the token's `ExpiresIn` to
+     *  keep the cookie and the token in lockstep. */
+    maxAge?: number;
+    /** Default `/`. */
+    path?: string;
+    domain?: string;
+    /** Default `true`. */
+    secure?: boolean;
+    /** Default `true`. Keep the token unreadable from client JavaScript. */
+    httpOnly?: boolean;
+    /** Default `'lax'`. Use `'none'` for cross-site (it forces `Secure`). */
+    sameSite?: 'lax' | 'strict' | 'none';
+}
+/** Build a `Set-Cookie` value that stores the access token. */
+declare function serializeSessionCookie(token: string, options?: SessionCookieOptions): string;
+/** Build a `Set-Cookie` value that clears the access token (logout). */
+declare function clearSessionCookie(options?: SessionCookieOptions): string;
+/** Read the access token out of a `Cookie` request header, or `null`. Pass the
+ *  raw header string (`name=value; name2=value2`). */
+declare function readSessionToken(cookieHeader: string | null | undefined, name?: string): string | null;
+
+export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, DEFAULT_SESSION_COOKIE_NAME, type DbClient, type DecodedSession, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, type GetSessionInput, InMemorySessionCache, type ListResult, type LoginInput, type LoginResult, type MeResult, MfaApi, type MfaChallengeInput, type MfaDisableInput, type MfaEnrollConfirmInput, type MfaEnrollResult, type MigrateInput, type MigrateResult, type OrderByClause, type PresignResult, PublicBucketClient, type QueryOptions, type ResetPasswordInput, type SessionCache, type SessionCookieOptions, type SessionOptions, type SessionResult, type SessionStatus, type SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, clearSessionCookie, createStorage, decodeAccessToken, dontcode, isDontCodeError, isSessionExpired, readSessionToken, serializeSessionCookie };

package/dist/index.d.ts

@@ -4,11 +4,16 @@ interface TransportConfig {
     apiKey?: string;
     /** Gateway origin, already normalized (no trailing slash). */
     baseUrl: string;
+    /** Per-request timeout in ms. Defaults to `DEFAULT_TIMEOUT_MS`; `0` (or any
+     *  non-positive value) disables it. */
+    timeoutMs?: number;
 }
 interface RequestOptions {
     /** End-user access token, sent as `X-Access-Token` (separate from the
      *  project API key). Required by signed-in auth calls. */
     accessToken?: string;
+    /** Override the client's timeout for this one call (ms). `0` disables it. */
+    timeoutMs?: number;
 }
 /**
  * The single place network requests are made. Everything else in the SDK is a
@@ -20,6 +25,15 @@ declare class Transport {
     constructor(config: TransportConfig);
     private headers;
     private url;
+    private timeout;
+    /**
+     * One fetch, with a timeout that turns "hung socket" into a fast, typed
+     * failure. A timeout surfaces as `DontCodeError` with status 408 / code
+     * `Timeout`; any other transport failure (DNS, refused, offline) as status
+     * 0 / code `NetworkError`. Both are distinct from a real `401`, so an auth
+     * guard can tell "backend is down" apart from "user is signed out".
+     */
+    private send;
     /** POST a JSON body and parse the JSON response. */
     json<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
     /** PUT a multipart form (file uploads). The runtime sets the boundary. */
@@ -188,6 +202,107 @@ interface TemporaryUrlResult {
 /** Bytes the SDK can turn into an upload body. */
 type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
 
+/**
+ * Session helpers, framework-agnostic by design. They never touch a request or
+ * response object; they take a token (or a cookie header) and return plain
+ * data, so they slot into any framework's guard (Next middleware, SvelteKit
+ * hooks, Express, a worker) without an adapter.
+ *
+ * The point of the module: an auth guard must not make a network round-trip on
+ * every navigation, or a slow gateway stalls the page and a swallowed timeout
+ * reads as "signed out". So there are two modes:
+ *
+ *   - optimistic — decode the token locally (no signature check, no network)
+ *     and trust its claims for routing. Instant. Used for the common gate.
+ *   - verified   — call the gateway's `me` once, cache the result for a short
+ *     TTL, and hard-timeout the request. Used for sensitive actions.
+ *
+ * The trade-offs (no signature verification, revocation lag) are documented on
+ * `getSession` and in the public BYOC docs; read them before choosing a mode.
+ */
+/** A JWT payload decoded WITHOUT verifying its signature. Trust accordingly. */
+interface DecodedSession {
+    /** Subject — the user id. */
+    sub: string;
+    email?: string;
+    role?: string;
+    claims?: Record<string, unknown>;
+    /** Expiry, seconds since the epoch (standard JWT `exp`). */
+    exp?: number;
+    /** Issued-at, seconds since the epoch (standard JWT `iat`). */
+    iat?: number;
+    [key: string]: unknown;
+}
+type SessionStatus = 
+/** A usable session: a present, unexpired token (verified or optimistic). */
+'active'
+/** The token is present but past its `exp`. */
+ | 'expired'
+/** No token, or an unparseable one. */
+ | 'anonymous'
+/** Verified mode could not reach the gateway (timeout/network/5xx). The
+ *  optimistically-decoded `user` is still returned so the caller can choose
+ *  to fail open during an outage instead of logging everyone out. */
+ | 'unavailable';
+interface SessionResult {
+    status: SessionStatus;
+    /** The signed-in user, or `null` when anonymous/expired. In `verified` mode
+     *  this came from the gateway; in `optimistic` (or `unavailable`) it was
+     *  decoded from the token's own claims. */
+    user: CurrentUser | null;
+    /** True only when `user` was confirmed by a gateway `me` call this request
+     *  (or from a fresh cache entry of one). False for optimistic decodes. */
+    verified: boolean;
+    /** The token's `exp` (seconds since epoch), when present. */
+    expiresAt?: number;
+}
+interface GetSessionInput {
+    accessToken: string;
+    /** `optimistic` (default): decode locally, zero network. `verified`: confirm
+     *  against the gateway with caching + a hard timeout. */
+    mode?: 'optimistic' | 'verified';
+}
+/** A place to cache verified sessions. Swap the default in-memory store for a
+ *  shared one (Redis, KV) when running multiple instances. */
+interface SessionCache {
+    get(token: string): SessionResult | undefined;
+    set(token: string, value: SessionResult, ttlMs: number): void;
+    delete?(token: string): void;
+}
+interface SessionOptions {
+    /** Cache for verified sessions. Defaults to a per-process `InMemorySessionCache`. */
+    cache?: SessionCache;
+    /** How long a verified session stays cached. Default 60_000 (60s). Keep it
+     *  short: a cached session can outlive a server-side revocation by up to
+     *  this long. */
+    ttlMs?: number;
+    /** Timeout for the `me` call made by `verified` mode (ms). Default 5_000. */
+    verifyTimeoutMs?: number;
+}
+/** Default cache: a `Map` with per-entry TTL. Lives for the life of the process
+ *  (and is shared across requests on a reused serverless instance). */
+declare class InMemorySessionCache implements SessionCache {
+    private readonly store;
+    get(token: string): SessionResult | undefined;
+    set(token: string, value: SessionResult, ttlMs: number): void;
+    delete(token: string): void;
+}
+/**
+ * Decode a JWT access token's payload WITHOUT verifying its signature, or
+ * return `null` if it is not a parseable JWT. This is deliberately cheap and
+ * offline; it is not proof the token is genuine. DontCode tokens are signed
+ * with a secret the gateway never shares, so the only authority on a token is
+ * the gateway's `me` endpoint — use `getSession({ mode: 'verified' })` when you
+ * need that authority.
+ */
+declare function decodeAccessToken(token: string): DecodedSession | null;
+/** True when a token (or already-decoded payload) is past its `exp`. A token
+ *  with no `exp` is treated as not expired (the caller cannot prove otherwise
+ *  offline). `skewSeconds` widens the window to absorb clock drift. */
+declare function isSessionExpired(input: string | DecodedSession | null, opts?: {
+    skewSeconds?: number;
+}): boolean;
+
 /**
  * MFA is per-user and opt-in. `enroll`/`enrollConfirm`/`disable` act as the
  * signed-in user, so they need the end-user access token. `challenge` does
@@ -221,7 +336,8 @@ declare class MfaApi {
 declare class AuthApi {
     private readonly transport;
     readonly mfa: MfaApi;
-    constructor(transport: Transport);
+    private readonly sessions;
+    constructor(transport: Transport, sessionOptions?: SessionOptions);
     /** Create an account. If the project requires email verification the
      *  response has `verification_required: true` and NO tokens; collect a
      *  code and call `verifyEmail`, then `login`. */
@@ -230,10 +346,39 @@ declare class AuthApi {
      *  challenge (finish via `mfa.challenge`); otherwise `tokens` is your
      *  session. A 403 `EmailNotVerified` means the email step isn't done. */
     login(input: LoginInput): Promise<LoginResult>;
-    /** Resolve the signed-in user from their access token, or `{ user: null }`. */
+    /** Resolve the signed-in user from their access token, or `{ user: null }`.
+     *  This is a network round-trip; for a per-navigation guard prefer
+     *  `getSession`, which can answer offline and caches verified results. */
     me(input: {
         accessToken: string;
+        timeoutMs?: number;
     }): Promise<MeResult>;
+    /**
+     * Resolve an access token into a session for a route guard, the one call
+     * that replaces "hit `me` on every navigation". Two modes:
+     *
+     *   - `'optimistic'` (default): decode the token locally and trust its
+     *     claims. Zero network, zero stall. The right default for gating page
+     *     loads. It does NOT verify the signature and will not notice a
+     *     server-side revocation until the token's own `exp`.
+     *   - `'verified'`: confirm against the gateway's `me`, cached for a short
+     *     TTL with a hard timeout. Use it before sensitive actions. On a
+     *     timeout/outage it returns `status: 'unavailable'` with the optimistic
+     *     user, so you choose whether to fail open rather than the SDK guessing.
+     *
+     * See the BYOC docs ("Sessions") for the full reasoning and best practices.
+     */
+    getSession(input: GetSessionInput): Promise<SessionResult>;
+    /** Read the access token from a `Cookie` request header and resolve it, in
+     *  one call. `name` defaults to `dc_access_token`. Returns the anonymous
+     *  session when no cookie is present. */
+    sessionFromCookies(cookieHeader: string | null | undefined, options?: {
+        mode?: GetSessionInput['mode'];
+        cookieName?: string;
+    }): Promise<SessionResult>;
+    /** Decode an access token's claims locally without a network call or any
+     *  signature check. Convenience re-export of `decodeAccessToken`. */
+    decodeToken(token: string): DecodedSession | null;
     /** Confirm the 6-digit code emailed at signup. */
     verifyEmail(input: VerifyEmailInput): Promise<SimpleResult>;
     forgotPassword(input: ForgotPasswordInput): Promise<SimpleResult>;
@@ -339,6 +484,12 @@ interface DontCodeClientOptions {
     /** Gateway origin. Defaults to `process.env.DONTCODE_API_URL`, then to
      *  `https://backend.dontcode.co`. */
     baseUrl?: string;
+    /** Per-request network timeout in ms. Defaults to 10_000; `0` disables it.
+     *  Without one, a slow gateway can hang a request for the full socket
+     *  timeout, the worst case for an auth guard. */
+    timeoutMs?: number;
+    /** Caching + timeout policy for `auth.getSession` / `auth.sessionFromCookies`. */
+    session?: SessionOptions;
 }
 interface DontCodeClient {
     auth: AuthApi;
@@ -367,6 +518,11 @@ declare function dontcode(options?: DontCodeClientOptions): DontCodeClient;
  * Note: many "one more step" auth states (signup needing email verification,
  * login returning `mfa_required`) are 2xx successes, NOT errors; inspect the
  * resolved value for those. Errors are reserved for actual failures.
+ *
+ * Transport failures (no HTTP response at all) also surface as a DontCodeError
+ * so callers have one error type: a timeout is status 408 / code `Timeout`, and
+ * any other network failure is status 0 / code `NetworkError`. Neither is a
+ * `401`, so a guard can distinguish "backend unavailable" from "signed out".
  */
 interface DontCodeErrorBody {
     error?: string;
@@ -392,4 +548,41 @@ declare class DontCodeError extends Error {
 /** Cross-bundle-safe check; works even if two copies of the SDK are loaded. */
 declare function isDontCodeError(err: unknown): err is DontCodeError;
 
-export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, type DbClient, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, type ListResult, type LoginInput, type LoginResult, type MeResult, MfaApi, type MfaChallengeInput, type MfaDisableInput, type MfaEnrollConfirmInput, type MfaEnrollResult, type MigrateInput, type MigrateResult, type OrderByClause, type PresignResult, PublicBucketClient, type QueryOptions, type ResetPasswordInput, type SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, createStorage, dontcode, isDontCodeError };
+/**
+ * Cookie helpers, framework-agnostic by design. They return strings: a
+ * `Set-Cookie` header value to write, or a parsed token to read. Your framework
+ * applies them (`headers.append('Set-Cookie', …)`, SvelteKit `cookies.set`, a
+ * Next `Response` cookie, etc.). The SDK never owns a request or response.
+ *
+ * Defaults match how DontCode's own apps store the session: an httpOnly cookie
+ * so JavaScript can't read the token, `Secure`, `SameSite=Lax`, path `/`, and a
+ * 7-day max age. Cross-site setups (your app and the gateway on different sites)
+ * need `sameSite: 'none'`, which forces `Secure` on.
+ */
+/** Default cookie name for the end-user access token. */
+declare const DEFAULT_SESSION_COOKIE_NAME = "dc_access_token";
+interface SessionCookieOptions {
+    /** Cookie name. Default `dc_access_token`. */
+    name?: string;
+    /** Lifetime in seconds. Default one week. Pass the token's `ExpiresIn` to
+     *  keep the cookie and the token in lockstep. */
+    maxAge?: number;
+    /** Default `/`. */
+    path?: string;
+    domain?: string;
+    /** Default `true`. */
+    secure?: boolean;
+    /** Default `true`. Keep the token unreadable from client JavaScript. */
+    httpOnly?: boolean;
+    /** Default `'lax'`. Use `'none'` for cross-site (it forces `Secure`). */
+    sameSite?: 'lax' | 'strict' | 'none';
+}
+/** Build a `Set-Cookie` value that stores the access token. */
+declare function serializeSessionCookie(token: string, options?: SessionCookieOptions): string;
+/** Build a `Set-Cookie` value that clears the access token (logout). */
+declare function clearSessionCookie(options?: SessionCookieOptions): string;
+/** Read the access token out of a `Cookie` request header, or `null`. Pass the
+ *  raw header string (`name=value; name2=value2`). */
+declare function readSessionToken(cookieHeader: string | null | undefined, name?: string): string | null;
+
+export { AuthApi, type AuthTokens, BucketClient, type CurrentUser, DEFAULT_SESSION_COOKIE_NAME, type DbClient, type DecodedSession, type DeleteInput, type DontCodeClient, type DontCodeClientOptions, DontCodeError, type DontCodeErrorBody, type DownloadResult, type ForgotPasswordInput, type GetSessionInput, InMemorySessionCache, type ListResult, type LoginInput, type LoginResult, type MeResult, MfaApi, type MfaChallengeInput, type MfaDisableInput, type MfaEnrollConfirmInput, type MfaEnrollResult, type MigrateInput, type MigrateResult, type OrderByClause, type PresignResult, PublicBucketClient, type QueryOptions, type ResetPasswordInput, type SessionCache, type SessionCookieOptions, type SessionOptions, type SessionResult, type SessionStatus, type SignupInput, type SignupResult, type SimpleResult, type StorageBucket, type StorageClient, type StorageObject, TableQuery, type TemporaryUrlResult, type UpdateInput, type UploadBody, type VerifyEmailInput, type WhereClause, type WhereOperator, clearSessionCookie, createStorage, decodeAccessToken, dontcode, isDontCodeError, isSessionExpired, readSessionToken, serializeSessionCookie };