Your first SDK call

Overview

The Oblax JavaScript/TypeScript SDK provides browser and mobile integration with auto-refreshing JWTs, typed error handling, and module-based architecture. The SDK supports multiple authentication scenarios: session module (auto-managed tokens), anonymous sessions, manual token management, and custom refresh skew.

Installation requires npm packages: @oblax/core, @oblax/platform-browser, @oblax/forms, @oblax/bookmarks, and @oblax/auth.

Installation

Install the Oblax JavaScript SDK and its required dependencies.

npm install @oblax/core @oblax/platform-browser @oblax/forms @oblax/bookmarks @oblax/auth

Packages Explained

Package	Purpose
`@oblax/core`	Core Oblax functionality — Oblax class, error types, config options
`@oblax/platform-browser`	Browser platform — `localStorage` + `fetch` integration
`@oblax/forms`	Forms module — create, list, get, update, delete forms
`@oblax/bookmarks`	Bookmarks module — save and reference user bookmarks
`@oblax/auth`	Auth module — session management, JWT storage and refresh

Configuration

Quick Start — Basic Setup

The minimal SDK initialization for a browser-based application.

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { forms } from "@oblax/forms";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [forms()],
});

clientAppId — Your application’s unique identifier on Oblax (obtain from the Oblax dashboard). platform — The browser platform instance (provides localStorage and fetch). modules — The feature modules you want to use (forms, bookmarks, auth, etc.).

Authentication Scenarios

The SDK supports multiple authentication methods. Choose the one that fits your use case.

Scenario 1: Session Module (Auto-Managed Tokens)

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { session } from "@oblax/auth";
import { forms } from "@oblax/forms";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [session(), forms()],
});

await oblax.session.create("webapp", {
  email: "user@example.com",
  password: "secret123",
});

const mine = await oblax.forms.listMine("form");

Auto-refresh: The JWT refreshes transparently before expiry. No manual intervention needed.

Scenario 2: Anonymous Session (No Credentials)

await oblax.session.anonymous("webapp");

const mine = await oblax.forms.listMine("form");

Useful for public endpoints or guest-only access.

Scenario 3: Manual Token Management (Disable Auto-Refresh)

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [session({ autoRefresh: false }), forms()],
});

oblax.setToken("<jwt>");

Scenario 4: Custom Refresh Skew

Trigger refresh 10 seconds before token expiry (default is 5 seconds):

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [session({ refreshSkewMs: 10_000 }), forms()],
});

Scenario 5: Manual Refresh

const res = await oblax.session.create("webapp", { email, password });

await oblax.session.refresh("webapp", res.refreshToken);

Config Options

Configure the Oblax SDK instance with these options:

const oblax = new Oblax({
  clientAppId: "<app-id>",
  platform: browserPlatform(),
  token: "<jwt>",
  endpoint: "https://api.oblax.io",
  environment: "staging",
  apiVersion: "v1",
  timeoutMs: 15_000,
  maxRetries: 5,
  logger: consoleLogger,
  headers: { "x-custom": "value" },
  transport: myCustomHttpProvider,
  storage: myCustomStorage,
  modules: [forms()],
});

Commonly used options:

Option	Purpose
`timeoutMs`	Set request timeout (milliseconds)
`maxRetries`	Number of automatic retries on failure
`headers`	Add default headers to every request
`environment`	Use `'staging'` or `'production'` shortcut
`storage`	Override `localStorage` with custom storage (e.g., `AsyncStorage` for React Native)

Platform Overrides

Browser (localStorage + fetch) — Default

import { platform as browserPlatform } from "@oblax/platform-browser";

new Oblax({
  clientAppId: "<app-id>",
  platform: browserPlatform(),
  modules: [session()],
});

Custom HTTP Provider

const myHttpProvider = {
  fetch: async (input, init) => {
    const res = await fetch(input, init);
    return {
      status: res.status,
      headers: { get: (name) => res.headers.get(name) },
      text: () => res.text(),
      json: () => res.json(),
    };
  },
};

new Oblax({
  clientAppId: "<app-id>",
  platform: browserPlatform(),
  transport: myHttpProvider,
});

Custom Storage Provider

import { memoryStorageProvider } from "@oblax/core";

new Oblax({
  clientAppId: "<app-id>",
  platform: browserPlatform(),
  storage: memoryStorageProvider(),
  modules: [session()],
});

React Native (AsyncStorage)

import { platform as mobilePlatform } from "@oblax/platform-mobile";
import AsyncStorage from "@react-native-async-storage/async-storage";

new Oblax({
  clientAppId: "<app-id>",
  platform: mobilePlatform(AsyncStorage),
  modules: [session()],
});

Node.js (Custom Platform)

import { Oblax } from "@oblax/core";
import { session } from "@oblax/auth";

const platform = {
  name: "node",
  getHttpProvider: () => ({
    fetch: async (input, init) => {
      const res = await fetch(input, init);
      return {
        status: res.status,
        headers: { get: (name) => res.headers.get(name) },
        text: () => res.text(),
        json: () => res.json(),
      };
    },
    getStorageProvider: () => ({
      async getItem(k) {},
      async setItem(k, v) {},
      async removeItem(k) {},
    }),
  }),
};

new Oblax({
  clientAppId: "<app-id>",
  platform,
  modules: [session()],
});

Usage

Your First SDK Calls

List Forms (Authenticated)

const forms = await oblax.forms.listMine("form");
console.log("My forms:", forms);

Create a Form

const created = await oblax.forms.create("form", {
  name: "contact_form",
  fields: [{ name: "email", type: "string", required: true }],
});

console.log("Created form:", created);

Get a Single Form

const form = await oblax.forms.get("form", "f2837hfd17q3phc3");
console.log("Form details:", form);

Update a Form

const updated = await oblax.forms.update("form", "f2837hfd17q3phc3", {
  name: "contact_form_v2",
  fields: [
    { name: "email", type: "string", required: true },
    { name: "phone", type: "string", required: false },
  ],
});

console.log("Updated form:", updated);

Delete a Form

await oblax.forms.delete("form", "f2837hfd17q3phc3");
console.log("Form deleted");

Error Handling

Oblax SDK errors are typed and inspectable. Import the relevant error classes.

import {
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
  PermissionError,
  NetworkError,
} from "@oblax/core";

try {
  const forms = await oblax.forms.listMine("form");
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Authentication failed: token expired or invalid");
  } else if (err instanceof ValidationError) {
    console.error("Validation errors:", err.fields);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof NotFoundError) {
    console.error("The requested form or record was not found");
  } else if (err instanceof PermissionError) {
    console.error("Permission denied: insufficient access role");
  } else if (err instanceof NetworkError) {
    console.error("Network error: check your connection and try again");
  } else {
    console.error("Unexpected error:", err);
  }
}

Full Real-World Example

import { Oblax, AuthenticationError, ValidationError } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { session } from "@oblax/auth";
import { forms, bookmarks } from "@oblax/*";

async function main() {
  const oblax = new Oblax({
    clientAppId: "my-app",
    platform: browserPlatform(),
    modules: [session(), forms()],
  });

  try {
    await oblax.session.create("webapp", {
      email: "alice@example.com",
      password: "hunter2",
    });

    let forms = await oblax.forms.listMine("form");
    console.log("My forms:", forms);

    const created = await oblax.forms.create("form", {
      recordId: "rec_42",
      title: "My Article",
    });
    console.log("Created:", created);

    await oblax.forms.delete("form", created.id);

    await oblax.session.destroy("webapp");
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error("Login failed:", err.message);
    } else if (err instanceof ValidationError) {
      console.error("Validation errors:", err.fields);
    } else {
      console.error("Unexpected error:", err);
    }
  }
}

main();

SDK Checklist

Item	Description
SDK installed	`npm install @oblax/core @oblax/platform-browser @oblax/forms`
Client app ID	Obtained from Oblax dashboard
Platform selected	`browserPlatform()` for web, `mobilePlatform(AsyncStorage)` for RN
Modules registered	`[forms()]`, `[session(), forms()]`, etc.
Authentication set up	Session create, anonymous, or manual token
First API call made	`oblax.forms.listMine('form')` or similar
Error handling implemented	Try/catch with error type inspection

Next Steps

You’ve made your first SDK call. Now decide your deployment path:

Run and Deploy — Local development, production deployment, and observability
[Explore advanced SDK patterns] — Custom storage, HTTP providers, and edge cases