insforge-sdk-js

Official TypeScript/JavaScript SDK for InsForge - A powerful, open-source Backend-as-a-Service (BaaS) platform.

Features

• Authentication - Email/password, OAuth (Google, GitHub), session management
• Database - Full PostgreSQL database access with PostgREST
• Storage - File upload and management with S3-compatible storage
• Edge Functions - Serverless function invocation
• AI Integration - Built-in AI capabilities
• Payments - Stripe Checkout and Billing Portal session helpers
• TypeScript - Full TypeScript support with type definitions
• Automatic OAuth Handling - Seamless OAuth callback detection

Installation

npm install @insforge/sdk

Or with yarn:

yarn add @insforge/sdk

Quick Start

Initialize the Client

import { createClient } from "@insforge/sdk";

const insforge = createClient({
  baseUrl: "http://localhost:7130", // Your InsForge backend URL
  anonKey: "your-anon-key", // Optional public anon key
});

Server Admin Client

Use createAdminClient() only in trusted server code that needs project-admin privileges:

import { createAdminClient } from "@insforge/sdk";

const admin = createAdminClient({
  baseUrl: "http://localhost:7130",
  apiKey: process.env.INSFORGE_API_KEY!,
});

apiKey belongs in createAdminClient(). Public and user-scoped clients use anonKey.

Authentication

// Sign up a new user
const { data, error } = await insforge.auth.signUp({
  email: "user@example.com",
  password: "securePassword123",
  name: "John Doe", // optional
  redirectTo: "http://localhost:3000/sign-in", // optional, recommended for link-based verification
});

// Sign in with email/password
const { data, error } = await insforge.auth.signInWithPassword({
  email: "user@example.com",
  password: "securePassword123",
});

// OAuth authentication (built-in or custom provider key)
await insforge.auth.signInWithOAuth("google", {
  redirectTo: "http://localhost:3000/dashboard",
  additionalParams: { prompt: "select_account" },
});
// additionalParams is for provider-specific hints only.
// Do not pass client_id, scope, redirect_uri, code_challenge, state, or response_type;
// InsForge sets server-owned OAuth fields and ignores colliding client-provided keys.

// Get current user (call this during browser app startup)
const { data: currentUser } = await insforge.auth.getCurrentUser();

// Get any user's profile by ID (public endpoint)
const { data: profile, error } = await insforge.auth.getProfile("user-id-here");

// Update current user's profile (requires authentication)
const { data: updatedProfile, error } = await insforge.auth.setProfile({
  displayName: "John Doe",
  bio: "Software developer",
  avatarUrl: "https://example.com/avatar.jpg",
});

// Sign out
await insforge.auth.signOut();

Email Verification And Password Reset

// Resend a verification email
await insforge.auth.resendVerificationEmail({
  email: "user@example.com",
  redirectTo: "http://localhost:3000/sign-in", // optional, recommended for link-based verification
});

// Verify email with a 6-digit code
await insforge.auth.verifyEmail({
  email: "user@example.com",
  otp: "123456",
});

// Send password reset email
await insforge.auth.sendResetPasswordEmail({
  email: "user@example.com",
  redirectTo: "http://localhost:3000/reset-password", // optional, recommended for link-based reset
});

// Code-based reset flow: exchange the code, then reset the password
const { data: resetToken } = await insforge.auth.exchangeResetPasswordToken({
  email: "user@example.com",
  code: "123456",
});

if (resetToken) {
  await insforge.auth.resetPassword({
    newPassword: "newSecurePassword123",
    otp: resetToken.token,
  });
}

For link-based verification and password reset, users click the emailed browser links:

• GET /api/auth/email/verify-link
• GET /api/auth/email/reset-password-link

Those backend endpoints validate the token first, then redirect the browser to your redirectTo URL.

• Verification links redirect with insforge_status=success|error, insforge_type=verify_email, and optional insforge_error
• Recommended: use your sign-in page as the verification redirectTo, then show a confirmation message and ask the user to sign in with email and password
• Reset links redirect with token when ready, plus insforge_status=ready|error, insforge_type=reset_password, and optional insforge_error

Database Operations

// Insert data
const { data, error } = await insforge.database
  .from("posts")
  .insert([{ title: "My First Post", content: "Hello World!" }]);

// Query data
const { data, error } = await insforge.database
  .from("posts")
  .select("*")
  .eq("author_id", userId);

// Update data
const { data, error } = await insforge.database
  .from("posts")
  .update({ title: "Updated Title" })
  .eq("id", postId);

// Delete data
const { data, error } = await insforge.database
  .from("posts")
  .delete()
  .eq("id", postId);

File Storage

// Upload a file
const file = document.querySelector('input[type="file"]').files[0];
const { data, error } = await insforge.storage.from("avatars").upload(file);

// Download a file
const { data, error } = await insforge.storage
  .from("avatars")
  .download("user-avatar.png");

// Delete a file
const { data, error } = await insforge.storage
  .from("avatars")
  .remove(["user-avatar.png"]);

// List files
const { data, error } = await insforge.storage.from("avatars").list();

Edge Functions

// Invoke an edge function
const { data, error } = await insforge.functions.invoke("my-function", {
  body: { key: "value" },
});

Payments

// Create and redirect to a Stripe Checkout Session
const { data, error } = await insforge.payments.createCheckoutSession("test", {
  mode: "payment",
  lineItems: [{ stripePriceId: "price_123", quantity: 1 }],
  successUrl: `${window.location.origin}/success`,
  cancelUrl: `${window.location.origin}/pricing`,
  idempotencyKey: "cart_123",
});

if (!error && data?.checkoutSession.url) {
  window.location.assign(data.checkoutSession.url);
}

// Create a subscription checkout for an app billing subject
const { data: subscriptionCheckout } =
  await insforge.payments.createCheckoutSession("test", {
    mode: "subscription",
    subject: { type: "team", id: "team_123" },
    lineItems: [{ stripePriceId: "price_monthly_123", quantity: 1 }],
    successUrl: `${window.location.origin}/billing/success`,
    cancelUrl: `${window.location.origin}/billing`,
  });

if (subscriptionCheckout?.checkoutSession.url) {
  window.location.assign(subscriptionCheckout.checkoutSession.url);
}

// Let an authenticated customer manage their subscription in Stripe Billing Portal
const { data: portal } = await insforge.payments.createCustomerPortalSession(
  "test",
  {
    subject: { type: "team", id: "team_123" },
    returnUrl: `${window.location.origin}/billing`,
  },
);

if (portal?.customerPortalSession.url) {
  window.location.assign(portal.customerPortalSession.url);
}

AI Integration

AI methods return an OpenAI-like response object directly (not the { data, error } envelope used by the other modules) and throw on failure.

// Chat completion
const completion = await insforge.ai.chat.completions.create({
  model: "anthropic/claude-3.5-haiku",
  messages: [{ role: "user", content: "Write a hello world program" }],
});
console.log(completion.choices[0].message.content);

// Streaming chat — returns an async iterable of chunks
const stream = await insforge.ai.chat.completions.create({
  model: "anthropic/claude-3.5-haiku",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

// Generate an image — returns base64-encoded image data
const image = await insforge.ai.images.generate({
  model: "google/gemini-3-pro-image-preview",
  prompt: "A sunset over mountains",
});
const base64Png = image.data[0].b64_json;

// Create embeddings
const embeddings = await insforge.ai.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: "Hello world",
});
console.log(embeddings.data[0].embedding); // number[]

Documentation

For complete API reference and advanced usage, see:

• SDK Reference - Complete API documentation
• InsForge Main Repository - Backend platform and setup guides

Configuration

The SDK supports the following configuration options:

const insforge = createClient({
  baseUrl: "http://localhost:7130", // Your InsForge backend URL
  anonKey: "your-anon-key", // Optional
});

For project-admin keys, use createAdminClient({ apiKey }) in server-only code.

SSR / Next.js

Use @insforge/sdk/ssr for apps that need the same auth session in Server Components, Client Components, Storage, and Realtime. The helper uses explicit baseUrl / anonKey when provided. Otherwise it reads NEXT_PUBLIC_INSFORGE_URL / NEXT_PUBLIC_INSFORGE_ANON_KEY. Missing config throws a clear error.

By default, the SSR helpers use:

• insforge_access_token: browser-readable access token cookie, expires at the JWT exp
• insforge_refresh_token: httpOnly refresh token cookie, expires at the JWT exp

// app/lib/insforge/client.ts
import { createBrowserClient } from "@insforge/sdk/ssr";

export const insforge = createBrowserClient();

// app/lib/insforge/server.ts
import { cookies } from "next/headers";
import { createServerClient } from "@insforge/sdk/ssr";

export async function createInsForgeServerClient() {
  return createServerClient({ cookies: await cookies() });
}

// app/api/auth/refresh/route.ts
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:

import { NextResponse } from "next/server";
import { setAuthCookies } from "@insforge/sdk/ssr";

const response = NextResponse.json({ user: data.user });
setAuthCookies(response.cookies, {
  accessToken: data.accessToken,
  refreshToken: data.refreshToken,
});
return response;

If your refresh route needs custom side effects:

import { refreshAuth } from "@insforge/sdk/ssr";

export async function POST(request: Request) {
  const result = await refreshAuth({ request });
  // run app-specific side effects here
  return result.response;
}

For Next.js Proxy/Middleware, refresh before Server Components render:

// 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";

export async function proxy(request: NextRequest) {
  const response = NextResponse.next({ request });

  await updateSession({
    requestCookies: request.cookies,
    responseCookies: response.cookies,
  });

  return response;
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { createClient, InsForgeClient } from "@insforge/sdk";

const insforge: InsForgeClient = createClient({
  baseUrl: "http://localhost:7130",
});

// Type-safe API calls
const response = await insforge.auth.getCurrentUser();

Error Handling

All SDK methods return a consistent response format:

const { data, error } = await insforge.auth.signUp({...});

if (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.statusCode);
} else {
  console.log('Success:', data);
}

Browser Support

The SDK works in all modern browsers that support:

• ES6+ features
• Fetch API
• Cookies (for refresh token flow)

For Node.js environments, ensure you're using Node.js 18 or higher.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/InsForge/insforge-sdk-js.git
cd insforge-sdk-js

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Run integration tests
npm run test:integration

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Community & Support

• GitHub Issues: Report bugs or request features
• Documentation: https://docs.insforge.com
• Main Repository: InsForge Backend Platform

Related Projects

• InsForge - The main InsForge backend platform
• InsForge MCP - Model Context Protocol server for InsForge

---

Built with ❤️ by the InsForge team