@insforge/sdk 1.4.0 → 1.4.2

package/README.md

@@ -56,6 +56,19 @@ const admin = createAdminClient({
 
 `apiKey` belongs in `createAdminClient()`. Public and user-scoped clients use `anonKey`.
 
+### Acting as a User on the Server
+
+In edge functions or other server code that receives a user's JWT, seed the client with it via `accessToken`:
+
+```javascript
+const insforge = createClient({
+  baseUrl: "http://localhost:7130",
+  accessToken: userJwt, // e.g. from the request's Authorization header
+});
+```
+
+All requests run as that user (RLS applies). The token is used as-is — the SDK does not refresh it. `edgeFunctionToken` is a deprecated alias for this option.
+
 ### Authentication
 
 ```javascript
@@ -353,6 +366,11 @@ import { createBrowserClient } from "@insforge/sdk/ssr";
 export const insforge = createBrowserClient();
 ```
 
+`createBrowserClient()` is for Client Components that consume an existing SSR
+session. Its TypeScript surface does not include auth mutations such as
+`signInWithPassword()`, `signUp()`, or `signOut()`. Run auth mutations on the
+server so the app can write server-owned auth cookies.
+
 ```typescript
 // app/lib/insforge/server.ts
 import { cookies } from "next/headers";
@@ -370,18 +388,126 @@ import { createRefreshAuthRouter } from "@insforge/sdk/ssr";
 export const { POST } = createRefreshAuthRouter();
 ```
 
-For server-owned refresh cookies, run sign-in in a Route Handler or Server Action and use `setAuthCookies()` from `@insforge/sdk/ssr` with the framework cookie writer. In Next.js Route Handlers, pass `response.cookies`:
+For sign-in, sign-up, and sign-out, use `createAuthActions()` in a Server
+Action file. Server Actions are stable in Next.js 14+. Do not return raw auth
+responses from Server Actions; return only the user or app-specific safe fields
+so access and refresh tokens stay server-owned.
 
 ```typescript
-import { NextResponse } from "next/server";
-import { setAuthCookies } from "@insforge/sdk/ssr";
+// app/actions.ts
+"use server";
 
-const response = NextResponse.json({ user: data.user });
-setAuthCookies(response.cookies, {
-  accessToken: data.accessToken,
-  refreshToken: data.refreshToken,
-});
-return response;
+import { cookies } from "next/headers";
+import { createAuthActions } from "@insforge/sdk/ssr";
+
+export async function signIn(formData: FormData) {
+  const auth = createAuthActions({ cookies: await cookies() });
+
+  const { data, error } = await auth.signInWithPassword({
+    email: String(formData.get("email")),
+    password: String(formData.get("password")),
+  });
+
+  return { user: data?.user ?? null, error };
+}
+```
+
+For OAuth in SSR apps, start and finish the flow on the server. Store the PKCE
+verifier in an httpOnly app cookie and exchange the callback code with
+`createAuthActions()`:
+
+```typescript
+// app/actions.ts
+"use server";
+
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { createAuthActions } from "@insforge/sdk/ssr";
+
+export async function signInWithGoogle() {
+  const cookieStore = await cookies();
+  const auth = createAuthActions({ cookies: cookieStore });
+  const { data, error } = await auth.signInWithOAuth("google", {
+    redirectTo: new URL(
+      "/api/auth/callback",
+      process.env.NEXT_PUBLIC_APP_URL
+    ).toString(),
+    skipBrowserRedirect: true,
+  });
+
+  if (error || !data.url || !data.codeVerifier) {
+    throw new Error(error?.message ?? "OAuth init failed");
+  }
+
+  cookieStore.set("insforge_code_verifier", data.codeVerifier, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: 600,
+  });
+
+  redirect(data.url);
+}
+```
+
+```typescript
+// app/api/auth/callback/route.ts
+import { cookies } from "next/headers";
+import { NextResponse, type NextRequest } from "next/server";
+import { createAuthActions } from "@insforge/sdk/ssr";
+
+export async function GET(request: NextRequest) {
+  const code = request.nextUrl.searchParams.get("insforge_code");
+  const verifier = (await cookies()).get("insforge_code_verifier")?.value;
+  if (!code || !verifier) {
+    return NextResponse.redirect(new URL("/login?error=oauth", request.url));
+  }
+
+  const response = NextResponse.redirect(new URL("/dashboard", request.url));
+  const auth = createAuthActions({
+    requestCookies: request.cookies,
+    responseCookies: response.cookies,
+  });
+  const { error } = await auth.exchangeOAuthCode(code, verifier);
+  if (error) {
+    return NextResponse.redirect(new URL("/login?error=oauth", request.url));
+  }
+
+  response.cookies.delete("insforge_code_verifier");
+  return response;
+}
+```
+
+SSR browser clients do not exchange OAuth callbacks automatically. OAuth
+callbacks must be completed on the server so the refresh token lands in the
+httpOnly app cookie.
+
+For Route Handlers, pass request cookies for reading the current session and
+response cookies for writing the next session:
+
+```typescript
+// app/api/auth/sign-out/route.ts
+import { NextResponse, type NextRequest } from "next/server";
+import { createAuthActions } from "@insforge/sdk/ssr";
+
+export async function POST(request: NextRequest) {
+  const response = NextResponse.json({ ok: true });
+  const auth = createAuthActions({
+    requestCookies: request.cookies,
+    responseCookies: response.cookies,
+  });
+
+  const { error } = await auth.signOut();
+  if (error) {
+    return NextResponse.json(
+      { error: error.error, message: error.message },
+      { status: error.statusCode }
+    );
+  }
+
+  return response;
+}
 ```
 
 If your refresh route needs custom side effects:
@@ -401,7 +527,7 @@ For Next.js Proxy/Middleware, refresh before Server Components render:
 ```typescript
 // proxy.ts on Next.js 16+, middleware.ts on Next.js 15 and earlier
 import { NextResponse, type NextRequest } from "next/server";
-import { updateSession } from "@insforge/sdk/ssr";
+import { updateSession } from "@insforge/sdk/ssr/middleware";
 
 export async function proxy(request: NextRequest) {
   const response = NextResponse.next({ request });
@@ -415,6 +541,9 @@ export async function proxy(request: NextRequest) {
 }
 ```
 
+Use the `/ssr/middleware` subpath in Proxy/Middleware files. It only includes
+the session refresh helpers and avoids bundling the full SDK client.
+
 ## TypeScript Support
 
 The SDK is written in TypeScript and provides full type definitions:

package/SDK-REFERENCE.md

@@ -59,6 +59,10 @@ const insforge = createBrowserClient({
 
 The browser client reads the access-token cookie, uses it for Database, Storage, Functions, and Realtime, and calls the refresh route when the access token is missing or near expiry.
 
+The browser client consumes an existing SSR session. Its TypeScript surface does
+not include auth mutations such as `signInWithPassword()`, `signUp()`, or
+`signOut()`.
+
 ### `createServerClient()`
 
 ```typescript
@@ -81,34 +85,40 @@ import { createRefreshAuthRouter } from "@insforge/sdk/ssr";
 export const { POST } = createRefreshAuthRouter();
 ```
 
-For server-owned refresh cookies, sign-in should also run through a Route Handler or Server Action that can set cookies:
+For server-owned refresh cookies, sign-in, sign-up, and sign-out should run
+through a Server Action or Route Handler that can set cookies. Do not return
+raw auth responses from Server Actions; return only the user or app-specific
+safe fields.
 
 ```typescript
-import { NextResponse } from "next/server";
-import { createServerClient, setAuthCookies } from "@insforge/sdk/ssr";
+// app/actions.ts
+"use server";
 
-export async function POST(request: Request) {
-  const client = createServerClient();
-  const { data, error } = await client.auth.signInWithPassword(
-    await request.json(),
-  );
-  if (error || !data?.accessToken) {
-    return Response.json(error, { status: error?.statusCode ?? 400 });
-  }
+import { cookies } from "next/headers";
+import { createAuthActions } from "@insforge/sdk/ssr";
 
-  const response = NextResponse.json({
-    accessToken: data.accessToken,
-    user: data.user,
-  });
-  setAuthCookies(response.cookies, {
-    accessToken: data.accessToken,
-    refreshToken: data.refreshToken,
+export async function signIn(formData: FormData) {
+  const auth = createAuthActions({ cookies: await cookies() });
+
+  const { data, error } = await auth.signInWithPassword({
+    email: String(formData.get("email")),
+    password: String(formData.get("password")),
   });
 
-  return response;
+  return { user: data?.user ?? null, error };
 }
 ```
 
+In Route Handlers, pass `requestCookies` and `responseCookies` to the same
+helper when request and response cookie stores are separate.
+
+For OAuth, initiate and exchange on the server. Use
+`createAuthActions().signInWithOAuth(provider, { redirectTo, skipBrowserRedirect: true })`
+in a Server Action, store the returned `codeVerifier` in an httpOnly app cookie,
+redirect to `data.url`, then call `createAuthActions().exchangeOAuthCode(code,
+codeVerifier)` from the callback Route Handler. SSR browser clients do not
+auto-exchange OAuth callbacks.
+
 Use `refreshAuth()` directly when the route needs app-specific logic:
 
 ```typescript
@@ -124,10 +134,14 @@ export async function POST(request: Request) {
 
 ### `updateSession()`
 
+Import `updateSession()` from `@insforge/sdk/ssr/middleware` in Proxy/Middleware
+files. This subpath only includes the session refresh helpers and avoids
+bundling the full SDK client.
+
 ```typescript
 // proxy.ts on Next.js 16+, middleware.ts on Next.js 15 and earlier
 import { NextResponse, type NextRequest } from "next/server";
-import { updateSession } from "@insforge/sdk/ssr";
+import { updateSession } from "@insforge/sdk/ssr/middleware";
 
 export async function proxy(request: NextRequest) {
   const response = NextResponse.next({ request });

package/dist/{client-CqfpCc8Z.d.mts → client-BR9o-WUm.d.ts}

@@ -1,114 +1,7 @@
-import { UserSchema, ErrorCode, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, RefreshSessionResponse, GetProfileResponse, SendVerificationEmailRequest, VerifyEmailRequest, VerifyEmailResponse, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, ExchangeResetPasswordTokenResponse, ResetPasswordResponse, GetPublicAuthConfigResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, EmbeddingsRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse, StripeEnvironment, CreateCheckoutSessionBody, CreateCheckoutSessionResponse, CreateCustomerPortalSessionBody, CreateCustomerPortalSessionResponse, RazorpayEnvironment, CreateRazorpayOrderBody, CreateRazorpayOrderResponse, VerifyRazorpayOrderBody, VerifyRazorpayOrderResponse, CreateRazorpaySubscriptionBody, CreateRazorpaySubscriptionResponse, VerifyRazorpaySubscriptionBody, VerifyRazorpaySubscriptionResponse, CancelRazorpaySubscriptionBodyInput, CancelRazorpaySubscriptionResponse, PauseRazorpaySubscriptionResponse, ResumeRazorpaySubscriptionResponse } from '@insforge/shared-schemas';
+import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-Dk-44JJf.js';
+import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, RefreshSessionResponse, GetProfileResponse, SendVerificationEmailRequest, VerifyEmailRequest, VerifyEmailResponse, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, ExchangeResetPasswordTokenResponse, ResetPasswordResponse, GetPublicAuthConfigResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, EmbeddingsRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse, StripeEnvironment, CreateCheckoutSessionBody, CreateCheckoutSessionResponse, CreateCustomerPortalSessionBody, CreateCustomerPortalSessionResponse, RazorpayEnvironment, CreateRazorpayOrderBody, CreateRazorpayOrderResponse, VerifyRazorpayOrderBody, VerifyRazorpayOrderResponse, CreateRazorpaySubscriptionBody, CreateRazorpaySubscriptionResponse, VerifyRazorpaySubscriptionBody, VerifyRazorpaySubscriptionResponse, CancelRazorpaySubscriptionBodyInput, CancelRazorpaySubscriptionResponse, PauseRazorpaySubscriptionResponse, ResumeRazorpaySubscriptionResponse } from '@insforge/shared-schemas';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
-/**
- * InsForge SDK Types - only SDK-specific types here
- * Use @insforge/shared-schemas directly for API types
- */
-
-type InsForgeErrorCode = ErrorCode | (string & {});
-interface InsForgeConfig {
-    /**
-     * The base URL of the InsForge backend API
-     * @default "http://localhost:7130"
-     */
-    baseUrl?: string;
-    /**
-     * Anonymous API key (optional)
-     * Used for public/unauthenticated requests when no user token is set
-     */
-    anonKey?: string;
-    /**
-     * Edge Function Token (optional)
-     * Use this when running in edge functions/serverless with a user's JWT token
-     * This token will be used for all authenticated requests
-     */
-    edgeFunctionToken?: string;
-    /**
-     * Direct URL to Deno Subhosting functions (optional)
-     * When provided, SDK will try this URL first for function invocations.
-     * Falls back to proxy URL if subhosting returns 404.
-     * @example "https://{appKey}.functions.insforge.app"
-     */
-    functionsUrl?: string;
-    /**
-     * Custom fetch implementation (useful for Node.js environments)
-     */
-    fetch?: typeof fetch;
-    /**
-     * Enable server-side auth mode (SSR/Node runtime)
-     * In this mode auth endpoints use `client_type=mobile` and refresh_token body flow.
-     *
-     * @deprecated Use `createServerClient()`, `createBrowserClient()`, and
-     * `updateSession()` from `@insforge/sdk/ssr` for SSR apps.
-     * @default false
-     */
-    isServerMode?: boolean;
-    /**
-     * Custom headers to include with every request
-     */
-    headers?: Record<string, string>;
-    /**
-     * Enable debug logging for HTTP requests and responses.
-     * When true, request/response details are logged to the console.
-     * Can also be a custom log function for advanced use cases.
-     * @default false
-     */
-    debug?: boolean | ((message: string, ...args: any[]) => void);
-    /**
-     * Request timeout in milliseconds.
-     * Requests that exceed this duration will be aborted.
-     * Set to 0 to disable timeout.
-     * @default 30000
-     */
-    timeout?: number;
-    /**
-     * Maximum number of retry attempts for failed requests.
-     * Retries are triggered on network errors and server errors (5xx).
-     * Client errors (4xx) are never retried.
-     * Set to 0 to disable retries.
-     * @default 3
-     */
-    retryCount?: number;
-    /**
-     * Initial delay in milliseconds before the first retry.
-     * The delay doubles with each subsequent attempt (exponential backoff)
-     * with ±15% jitter to prevent thundering herd.
-     * @default 500
-     */
-    retryDelay?: number;
-}
-type InsForgeAdminConfig = Omit<InsForgeConfig, 'anonKey' | 'edgeFunctionToken' | 'isServerMode'> & {
-    /**
-     * Project admin API key. Keep this server-side only.
-     */
-    apiKey: string;
-};
-interface AuthSession {
-    user: UserSchema;
-    accessToken: string;
-    expiresAt?: Date;
-}
-interface AuthRefreshResponse {
-    user: UserSchema;
-    accessToken: string;
-    csrfToken?: string;
-    refreshToken?: string;
-}
-interface ApiError {
-    error: InsForgeErrorCode;
-    message: string;
-    statusCode: number;
-    nextActions?: string;
-}
-declare class InsForgeError extends Error {
-    statusCode: number;
-    error: InsForgeErrorCode;
-    nextActions?: string;
-    constructor(message: string, statusCode: number, error: InsForgeErrorCode, nextActions?: string);
-    static fromApiError(apiError: ApiError): InsForgeError;
-}
-
 type LogFunction = (message: string, ...args: any[]) => void;
 /**
  * Debug logger for the InsForge SDK.
@@ -311,6 +204,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;
@@ -572,10 +466,57 @@ declare class StorageBucket {
         error: InsForgeError | null;
     }>;
     /**
-     * Get public URL for a file
+     * Get the public URL for an object in a public bucket.
+     *
+     * Pure string construction — no network call, no auth. The URL only resolves
+     * if the bucket is public; for private objects use {@link createSignedUrl}.
+     *
+     * @param path - The object key/path
+     * @returns `{ data: { publicUrl }, error }` — matches the external SDK pattern,
+     *   so `const { data } = getPublicUrl(path)` then `data.publicUrl`.
+     */
+    getPublicUrl(path: string): StorageResponse<{
+        publicUrl: string;
+    }>;
+    /**
+     * Resolve a download strategy (signed or direct URL) for an object with a
+     * caller-supplied TTL. Prefers the canonical GET route and falls back to the
+     * legacy POST alias so signed-URL creation still works against older backends
+     * that predate the GET route (they return 404/405 for it). A genuine
+     * "object not found" (STORAGE_NOT_FOUND) is not retried.
+     */
+    private requestDownloadStrategy;
+    /**
+     * Create a signed URL for an object.
+     *
+     * Returns a time-limited, credential-free URL that can be handed directly to
+     * a browser (`<img src>`), an email, or a third party — no SDK or session is
+     * needed to fetch it. Authorization is enforced when the URL is minted (the
+     * caller must be allowed to read the object), so the resulting link is a
+     * pre-authorized capability scoped to this one object until it expires.
+     *
      * @param path - The object key/path
+     * @param expiresIn - Lifetime in seconds (default 3600 = 1h, max 604800 = 7d).
+     *   Honored for private buckets; public buckets return their long-lived URL.
+     */
+    createSignedUrl(path: string, expiresIn?: number): Promise<StorageResponse<{
+        signedUrl: string;
+        expiresAt: string | null;
+    }>>;
+    /**
+     * Create signed URLs for multiple objects in a single call.
+     *
+     * Each entry resolves independently: a failure on one key (not found / not
+     * permitted) is reported on that entry's `error` without failing the rest.
+     *
+     * @param paths - The object keys/paths
+     * @param expiresIn - Lifetime in seconds (default 3600 = 1h, max 604800 = 7d)
      */
-    getPublicUrl(path: string): string;
+    createSignedUrls(paths: string[], expiresIn?: number): Promise<StorageResponse<Array<{
+        path: string;
+        signedUrl: string | null;
+        error: string | null;
+    }>>>;
     /**
      * List objects in the bucket
      * @param prefix - Filter by key prefix
@@ -1165,4 +1106,4 @@ declare class InsForgeClient {
     setAccessToken(token: string | null): void;
 }
 
-export { type AuthSession as A, type ConnectionState as C, Database as D, Emails as E, Functions as F, HttpClient as H, InsForgeClient as I, Logger as L, Payments as P, Realtime as R, Storage as S, TokenManager as T, type InsForgeConfig as a, type InsForgeAdminConfig as b, type ApiError as c, type InsForgeErrorCode as d, InsForgeError as e, Auth as f, StorageBucket as g, type StorageResponse as h, AI as i, type FunctionInvokeOptions as j, type PaymentsResponse as k, type EventCallback as l, type AuthRefreshResponse as m };
+export { Auth as A, type ConnectionState as C, Database as D, Emails as E, Functions as F, HttpClient as H, InsForgeClient as I, Logger as L, Payments as P, Realtime as R, Storage as S, TokenManager as T, StorageBucket as a, type StorageResponse as b, AI as c, type FunctionInvokeOptions as d, type PaymentsResponse as e, type EventCallback as f };

package/dist/{client-CqfpCc8Z.d.ts → client-C-qBRoea.d.mts}

@@ -1,114 +1,7 @@
-import { UserSchema, ErrorCode, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, RefreshSessionResponse, GetProfileResponse, SendVerificationEmailRequest, VerifyEmailRequest, VerifyEmailResponse, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, ExchangeResetPasswordTokenResponse, ResetPasswordResponse, GetPublicAuthConfigResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, EmbeddingsRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse, StripeEnvironment, CreateCheckoutSessionBody, CreateCheckoutSessionResponse, CreateCustomerPortalSessionBody, CreateCustomerPortalSessionResponse, RazorpayEnvironment, CreateRazorpayOrderBody, CreateRazorpayOrderResponse, VerifyRazorpayOrderBody, VerifyRazorpayOrderResponse, CreateRazorpaySubscriptionBody, CreateRazorpaySubscriptionResponse, VerifyRazorpaySubscriptionBody, VerifyRazorpaySubscriptionResponse, CancelRazorpaySubscriptionBodyInput, CancelRazorpaySubscriptionResponse, PauseRazorpaySubscriptionResponse, ResumeRazorpaySubscriptionResponse } from '@insforge/shared-schemas';
+import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-Dk-44JJf.mjs';
+import { UserSchema, CreateUserRequest, CreateUserResponse, CreateSessionRequest, CreateSessionResponse, OAuthProvidersSchema, RefreshSessionResponse, GetProfileResponse, SendVerificationEmailRequest, VerifyEmailRequest, VerifyEmailResponse, SendResetPasswordEmailRequest, ExchangeResetPasswordTokenRequest, ExchangeResetPasswordTokenResponse, ResetPasswordResponse, GetPublicAuthConfigResponse, StorageFileSchema, ListObjectsResponseSchema, ChatCompletionRequest, ImageGenerationRequest, EmbeddingsRequest, SubscribeResponse, SocketMessage, SendRawEmailRequest, SendEmailResponse, StripeEnvironment, CreateCheckoutSessionBody, CreateCheckoutSessionResponse, CreateCustomerPortalSessionBody, CreateCustomerPortalSessionResponse, RazorpayEnvironment, CreateRazorpayOrderBody, CreateRazorpayOrderResponse, VerifyRazorpayOrderBody, VerifyRazorpayOrderResponse, CreateRazorpaySubscriptionBody, CreateRazorpaySubscriptionResponse, VerifyRazorpaySubscriptionBody, VerifyRazorpaySubscriptionResponse, CancelRazorpaySubscriptionBodyInput, CancelRazorpaySubscriptionResponse, PauseRazorpaySubscriptionResponse, ResumeRazorpaySubscriptionResponse } from '@insforge/shared-schemas';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
-/**
- * InsForge SDK Types - only SDK-specific types here
- * Use @insforge/shared-schemas directly for API types
- */
-
-type InsForgeErrorCode = ErrorCode | (string & {});
-interface InsForgeConfig {
-    /**
-     * The base URL of the InsForge backend API
-     * @default "http://localhost:7130"
-     */
-    baseUrl?: string;
-    /**
-     * Anonymous API key (optional)
-     * Used for public/unauthenticated requests when no user token is set
-     */
-    anonKey?: string;
-    /**
-     * Edge Function Token (optional)
-     * Use this when running in edge functions/serverless with a user's JWT token
-     * This token will be used for all authenticated requests
-     */
-    edgeFunctionToken?: string;
-    /**
-     * Direct URL to Deno Subhosting functions (optional)
-     * When provided, SDK will try this URL first for function invocations.
-     * Falls back to proxy URL if subhosting returns 404.
-     * @example "https://{appKey}.functions.insforge.app"
-     */
-    functionsUrl?: string;
-    /**
-     * Custom fetch implementation (useful for Node.js environments)
-     */
-    fetch?: typeof fetch;
-    /**
-     * Enable server-side auth mode (SSR/Node runtime)
-     * In this mode auth endpoints use `client_type=mobile` and refresh_token body flow.
-     *
-     * @deprecated Use `createServerClient()`, `createBrowserClient()`, and
-     * `updateSession()` from `@insforge/sdk/ssr` for SSR apps.
-     * @default false
-     */
-    isServerMode?: boolean;
-    /**
-     * Custom headers to include with every request
-     */
-    headers?: Record<string, string>;
-    /**
-     * Enable debug logging for HTTP requests and responses.
-     * When true, request/response details are logged to the console.
-     * Can also be a custom log function for advanced use cases.
-     * @default false
-     */
-    debug?: boolean | ((message: string, ...args: any[]) => void);
-    /**
-     * Request timeout in milliseconds.
-     * Requests that exceed this duration will be aborted.
-     * Set to 0 to disable timeout.
-     * @default 30000
-     */
-    timeout?: number;
-    /**
-     * Maximum number of retry attempts for failed requests.
-     * Retries are triggered on network errors and server errors (5xx).
-     * Client errors (4xx) are never retried.
-     * Set to 0 to disable retries.
-     * @default 3
-     */
-    retryCount?: number;
-    /**
-     * Initial delay in milliseconds before the first retry.
-     * The delay doubles with each subsequent attempt (exponential backoff)
-     * with ±15% jitter to prevent thundering herd.
-     * @default 500
-     */
-    retryDelay?: number;
-}
-type InsForgeAdminConfig = Omit<InsForgeConfig, 'anonKey' | 'edgeFunctionToken' | 'isServerMode'> & {
-    /**
-     * Project admin API key. Keep this server-side only.
-     */
-    apiKey: string;
-};
-interface AuthSession {
-    user: UserSchema;
-    accessToken: string;
-    expiresAt?: Date;
-}
-interface AuthRefreshResponse {
-    user: UserSchema;
-    accessToken: string;
-    csrfToken?: string;
-    refreshToken?: string;
-}
-interface ApiError {
-    error: InsForgeErrorCode;
-    message: string;
-    statusCode: number;
-    nextActions?: string;
-}
-declare class InsForgeError extends Error {
-    statusCode: number;
-    error: InsForgeErrorCode;
-    nextActions?: string;
-    constructor(message: string, statusCode: number, error: InsForgeErrorCode, nextActions?: string);
-    static fromApiError(apiError: ApiError): InsForgeError;
-}
-
 type LogFunction = (message: string, ...args: any[]) => void;
 /**
  * Debug logger for the InsForge SDK.
@@ -311,6 +204,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;
@@ -572,10 +466,57 @@ declare class StorageBucket {
         error: InsForgeError | null;
     }>;
     /**
-     * Get public URL for a file
+     * Get the public URL for an object in a public bucket.
+     *
+     * Pure string construction — no network call, no auth. The URL only resolves
+     * if the bucket is public; for private objects use {@link createSignedUrl}.
+     *
+     * @param path - The object key/path
+     * @returns `{ data: { publicUrl }, error }` — matches the external SDK pattern,
+     *   so `const { data } = getPublicUrl(path)` then `data.publicUrl`.
+     */
+    getPublicUrl(path: string): StorageResponse<{
+        publicUrl: string;
+    }>;
+    /**
+     * Resolve a download strategy (signed or direct URL) for an object with a
+     * caller-supplied TTL. Prefers the canonical GET route and falls back to the
+     * legacy POST alias so signed-URL creation still works against older backends
+     * that predate the GET route (they return 404/405 for it). A genuine
+     * "object not found" (STORAGE_NOT_FOUND) is not retried.
+     */
+    private requestDownloadStrategy;
+    /**
+     * Create a signed URL for an object.
+     *
+     * Returns a time-limited, credential-free URL that can be handed directly to
+     * a browser (`<img src>`), an email, or a third party — no SDK or session is
+     * needed to fetch it. Authorization is enforced when the URL is minted (the
+     * caller must be allowed to read the object), so the resulting link is a
+     * pre-authorized capability scoped to this one object until it expires.
+     *
      * @param path - The object key/path
+     * @param expiresIn - Lifetime in seconds (default 3600 = 1h, max 604800 = 7d).
+     *   Honored for private buckets; public buckets return their long-lived URL.
+     */
+    createSignedUrl(path: string, expiresIn?: number): Promise<StorageResponse<{
+        signedUrl: string;
+        expiresAt: string | null;
+    }>>;
+    /**
+     * Create signed URLs for multiple objects in a single call.
+     *
+     * Each entry resolves independently: a failure on one key (not found / not
+     * permitted) is reported on that entry's `error` without failing the rest.
+     *
+     * @param paths - The object keys/paths
+     * @param expiresIn - Lifetime in seconds (default 3600 = 1h, max 604800 = 7d)
      */
-    getPublicUrl(path: string): string;
+    createSignedUrls(paths: string[], expiresIn?: number): Promise<StorageResponse<Array<{
+        path: string;
+        signedUrl: string | null;
+        error: string | null;
+    }>>>;
     /**
      * List objects in the bucket
      * @param prefix - Filter by key prefix
@@ -1165,4 +1106,4 @@ declare class InsForgeClient {
     setAccessToken(token: string | null): void;
 }
 
-export { type AuthSession as A, type ConnectionState as C, Database as D, Emails as E, Functions as F, HttpClient as H, InsForgeClient as I, Logger as L, Payments as P, Realtime as R, Storage as S, TokenManager as T, type InsForgeConfig as a, type InsForgeAdminConfig as b, type ApiError as c, type InsForgeErrorCode as d, InsForgeError as e, Auth as f, StorageBucket as g, type StorageResponse as h, AI as i, type FunctionInvokeOptions as j, type PaymentsResponse as k, type EventCallback as l, type AuthRefreshResponse as m };
+export { Auth as A, type ConnectionState as C, Database as D, Emails as E, Functions as F, HttpClient as H, InsForgeClient as I, Logger as L, Payments as P, Realtime as R, Storage as S, TokenManager as T, StorageBucket as a, type StorageResponse as b, AI as c, type FunctionInvokeOptions as d, type PaymentsResponse as e, type EventCallback as f };

package/dist/index.d.mts

@@ -1,5 +1,7 @@
-import { I as InsForgeClient, a as InsForgeConfig, b as InsForgeAdminConfig } from './client-CqfpCc8Z.mjs';
-export { i as AI, c as ApiError, f as Auth, A as AuthSession, C as ConnectionState, D as Database, E as Emails, l as EventCallback, j as FunctionInvokeOptions, F as Functions, H as HttpClient, e as InsForgeError, d as InsForgeErrorCode, L as Logger, P as Payments, k as PaymentsResponse, R as Realtime, S as Storage, g as StorageBucket, h as StorageResponse, T as TokenManager } from './client-CqfpCc8Z.mjs';
+import { I as InsForgeClient } from './client-C-qBRoea.mjs';
+export { c as AI, A as Auth, C as ConnectionState, D as Database, E as Emails, f as EventCallback, d as FunctionInvokeOptions, F as Functions, H as HttpClient, L as Logger, P as Payments, e as PaymentsResponse, R as Realtime, S as Storage, a as StorageBucket, b as StorageResponse, T as TokenManager } from './client-C-qBRoea.mjs';
+import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-Dk-44JJf.mjs';
+export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-Dk-44JJf.mjs';
 export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SendRawEmailRequest as SendEmailOptions, SendEmailResponse, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
 import '@supabase/postgrest-js';