@insforge/sdk 1.4.1 → 1.4.2

package/README.md

@@ -366,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";
@@ -383,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:

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-DoWwzWnh.d.ts → client-BR9o-WUm.d.ts}

@@ -1,4 +1,4 @@
-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-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';
 
@@ -204,6 +204,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;

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

@@ -1,4 +1,4 @@
-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-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';
 
@@ -204,6 +204,7 @@ declare class HttpClient {
 
 interface AuthOptions {
     isServerMode?: boolean;
+    detectOAuthCallback?: boolean;
 }
 type OAuthSignInOptions = {
     redirectTo: string;

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-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';
 

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-BR9o-WUm.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-BR9o-WUm.js';
+import { I as InsForgeConfig, a as InsForgeAdminConfig } from './types-Dk-44JJf.js';
+export { b as ApiError, A as AuthSession, d as InsForgeError, c as InsForgeErrorCode } from './types-Dk-44JJf.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;
@@ -1090,7 +1103,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 = {
@@ -2812,7 +2825,8 @@ 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.storage = new Storage(this.http);