@insforge/sdk 1.4.1 → 1.4.3

package/README.md

@@ -185,6 +185,31 @@ const { data, error } = await insforge.database
   .eq("id", postId);
 ```
 
+#### Selecting a schema
+
+Queries hit the `public` schema by default. Target a custom schema by chaining `.schema()` — the table name stays bare (it maps to PostgREST's `Accept-Profile`/`Content-Profile` header):
+
+```javascript
+const { data } = await insforge.database
+  .schema("analytics")
+  .from("events")
+  .select("*");
+
+await insforge.database.schema("analytics").rpc("rollup", { day: "2026-01-01" });
+```
+
+Or set a default schema for every query when creating the client:
+
+```javascript
+const insforge = createClient({
+  baseUrl: "...",
+  anonKey: "...",
+  db: { schema: "analytics" },
+});
+```
+
+The schema must be exposed by the backend, and access is still gated by grants + RLS like `public`. Older backends that don't expose the schema return PostgREST `PGRST106` rather than silently falling back.
+
 ### File Storage
 
 ```javascript
@@ -366,6 +391,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";
@@ -383,18 +413,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:

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

package/dist/{client-hYdj36T6.d.mts → client-B6eZHolm.d.mts}

@@ -1,6 +1,7 @@
-import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-NjykhyRq.mjs';
+import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-MKmYAYeg.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';
+import { PostgrestClient } from '@supabase/postgrest-js';
 
 type LogFunction = (message: string, ...args: any[]) => void;
 /**
@@ -204,6 +205,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;
@@ -361,7 +363,22 @@ declare class Auth {
  */
 declare class Database {
     private postgrest;
-    constructor(httpClient: HttpClient);
+    constructor(httpClient: HttpClient, defaultSchema?: string);
+    /**
+     * Select a non-default Postgres schema for the chained query. Maps to
+     * PostgREST's `Accept-Profile` (reads) / `Content-Profile` (writes) header.
+     * The schema must be exposed by the backend.
+     *
+     * @example
+     * const { data } = await client.database
+     *   .schema('analytics')
+     *   .from('events')
+     *   .select('*');
+     *
+     * @example
+     * await client.database.schema('analytics').rpc('rollup', { day: '2026-01-01' });
+     */
+    schema(schemaName: string): PostgrestClient<any, any, string, any>;
     /**
      * Create a query builder for a table
      *

package/dist/{client-DoWwzWnh.d.ts → client-DUmOm_3W.d.ts}

@@ -1,6 +1,7 @@
-import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-NjykhyRq.js';
+import { A as AuthSession, I as InsForgeConfig, e as AuthRefreshResponse, d as InsForgeError } from './types-MKmYAYeg.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';
+import { PostgrestClient } from '@supabase/postgrest-js';
 
 type LogFunction = (message: string, ...args: any[]) => void;
 /**
@@ -204,6 +205,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;
@@ -361,7 +363,22 @@ declare class Auth {
  */
 declare class Database {
     private postgrest;
-    constructor(httpClient: HttpClient);
+    constructor(httpClient: HttpClient, defaultSchema?: string);
+    /**
+     * Select a non-default Postgres schema for the chained query. Maps to
+     * PostgREST's `Accept-Profile` (reads) / `Content-Profile` (writes) header.
+     * The schema must be exposed by the backend.
+     *
+     * @example
+     * const { data } = await client.database
+     *   .schema('analytics')
+     *   .from('events')
+     *   .select('*');
+     *
+     * @example
+     * await client.database.schema('analytics').rpc('rollup', { day: '2026-01-01' });
+     */
+    schema(schemaName: string): PostgrestClient<any, any, string, any>;
     /**
      * Create a query builder for a table
      *

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { I as InsForgeClient } from './client-hYdj36T6.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-hYdj36T6.mjs';
-import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-NjykhyRq.mjs';
-export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-NjykhyRq.mjs';
+import { I as InsForgeClient } from './client-B6eZHolm.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-B6eZHolm.mjs';
+import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-MKmYAYeg.mjs';
+export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-MKmYAYeg.mjs';
 export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SendRawEmailRequest as SendEmailOptions, SendEmailResponse, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
 import '@supabase/postgrest-js';
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { I as InsForgeClient } from './client-DoWwzWnh.js';
-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-DoWwzWnh.js';
-import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-NjykhyRq.js';
-export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-NjykhyRq.js';
+import { I as InsForgeClient } from './client-DUmOm_3W.js';
+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-DUmOm_3W.js';
+import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-MKmYAYeg.js';
+export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-MKmYAYeg.js';
 export { AuthErrorResponse, CreateSessionRequest, CreateUserRequest, RealtimeErrorPayload, SendRawEmailRequest as SendEmailOptions, SendEmailResponse, SocketMessage, SubscribeResponse, UserSchema } from '@insforge/shared-schemas';
 import '@supabase/postgrest-js';
 

package/dist/index.js

@@ -885,19 +885,32 @@ var HttpClient = class {
 
 // src/modules/auth/helpers.ts
 var PKCE_VERIFIER_KEY = "insforge_pkce_verifier";
+async function getWebCrypto() {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.getRandomValues === "function" && webCrypto.subtle) {
+    return webCrypto;
+  }
+  if (typeof process !== "undefined" && process.versions?.node) {
+    const { webcrypto } = await import("crypto");
+    return webcrypto;
+  }
+  throw new Error("Web Crypto API is not available in this environment");
+}
 function base64UrlEncode(buffer) {
   const base64 = btoa(String.fromCharCode(...buffer));
   return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function generateCodeVerifier() {
+async function generateCodeVerifier() {
+  const webCrypto = await getWebCrypto();
   const array = new Uint8Array(32);
-  crypto.getRandomValues(array);
+  webCrypto.getRandomValues(array);
   return base64UrlEncode(array);
 }
 async function generateCodeChallenge(verifier) {
+  const webCrypto = await getWebCrypto();
   const encoder = new TextEncoder();
   const data = encoder.encode(verifier);
-  const hash = await crypto.subtle.digest("SHA-256", data);
+  const hash = await webCrypto.subtle.digest("SHA-256", data);
   return base64UrlEncode(new Uint8Array(hash));
 }
 function storePkceVerifier(verifier) {
@@ -944,7 +957,7 @@ var Auth = class {
     this.http = http;
     this.tokenManager = tokenManager;
     this.options = options;
-    this.authCallbackHandled = this.detectAuthCallback();
+    this.authCallbackHandled = options.detectOAuthCallback === false ? Promise.resolve() : this.detectAuthCallback();
   }
   isServerMode() {
     return !!this.options.isServerMode;
@@ -1041,10 +1054,16 @@ var Auth = class {
   async signOut() {
     try {
       try {
+        const serverMode = this.isServerMode();
+        const csrfToken = !serverMode ? getCsrfToken() : null;
         await this.http.post(
-          this.isServerMode() ? "/api/auth/logout?client_type=mobile" : "/api/auth/logout",
+          serverMode ? "/api/auth/logout?client_type=mobile" : "/api/auth/logout",
           void 0,
-          { credentials: "include", skipAuthRefresh: true }
+          {
+            credentials: "include",
+            skipAuthRefresh: true,
+            ...csrfToken ? { headers: { "X-CSRF-Token": csrfToken } } : {}
+          }
         );
       } catch {
       }
@@ -1090,7 +1109,7 @@ var Auth = class {
       }
       const { provider } = signInOptions;
       const providerKey = encodeURIComponent(provider.toLowerCase());
-      const codeVerifier = generateCodeVerifier();
+      const codeVerifier = await generateCodeVerifier();
       const codeChallenge = await generateCodeChallenge(codeVerifier);
       storePkceVerifier(codeVerifier);
       const params = {
@@ -1450,12 +1469,30 @@ function createInsForgePostgrestFetch(httpClient) {
   };
 }
 var Database = class {
-  constructor(httpClient) {
+  constructor(httpClient, defaultSchema) {
     this.postgrest = new import_postgrest_js.PostgrestClient("http://dummy", {
       fetch: createInsForgePostgrestFetch(httpClient),
-      headers: {}
+      headers: {},
+      ...defaultSchema ? { schema: defaultSchema } : {}
     });
   }
+  /**
+   * Select a non-default Postgres schema for the chained query. Maps to
+   * PostgREST's `Accept-Profile` (reads) / `Content-Profile` (writes) header.
+   * The schema must be exposed by the backend.
+   *
+   * @example
+   * const { data } = await client.database
+   *   .schema('analytics')
+   *   .from('events')
+   *   .select('*');
+   *
+   * @example
+   * await client.database.schema('analytics').rpc('rollup', { day: '2026-01-01' });
+   */
+  schema(schemaName) {
+    return this.postgrest.schema(schemaName);
+  }
   /**
    * Create a query builder for a table
    *
@@ -2812,9 +2849,10 @@ var InsForgeClient = class {
       this.tokenManager.setAccessToken(accessToken);
     }
     this.auth = new Auth(this.http, this.tokenManager, {
-      isServerMode: config.isServerMode ?? !!accessToken
+      isServerMode: config.isServerMode ?? !!accessToken,
+      detectOAuthCallback: config.auth?.detectOAuthCallback
     });
-    this.database = new Database(this.http);
+    this.database = new Database(this.http, config.db?.schema);
     this.storage = new Storage(this.http);
     this.ai = new AI(this.http);
     this.functions = new Functions(this.http, config.functionsUrl);