Overview

The official TypeScript SDK — framework-agnostic, zero dependencies, full type safety.

@raisfast/sdk is a zero-dependency TypeScript client for the RaisFast API. Works with React, Vue, Svelte, Next.js, Nuxt, React Native, and vanilla JS.

Install

pnpm add @raisfast/sdk
# or
npm install @raisfast/sdk
# or
bun add @raisfast/sdk

Initialize

import { RaisFast } from "@raisfast/sdk";

const client = new RaisFast("http://localhost:9898/api/v1");

On first use, call init() to auto-detect the API style (RESTful vs Simple):

await client.init();

Constructor Options

const client = new RaisFast("http://localhost:9898/api/v1", {
  authStore: store,  // custom auth store (default: LocalAuthStore)
});

Auth Store

The SDK stores auth tokens via an IAuthStore interface. Default: localStorage.

import { RaisFast, LocalAuthStore } from "@raisfast/sdk";

// Custom storage key
const store = new LocalAuthStore("my_app_auth");

const client = new RaisFast("http://localhost:9898/api/v1", {
  authStore: store,
});

Custom Store (SSR / React Native)

Implement BaseAuthStore for non-browser environments:

import { BaseAuthStore } from "@raisfast/sdk";

class CookieAuthStore extends BaseAuthStore {
  save(auth) {
    super.save(auth);
    document.cookie = `auth=${super.exportToStorage()}; path=/`;
  }
  clear() {
    super.clear();
    document.cookie = "auth=; path=/; max-age=0";
  }
}

Auth State Changes

client.authStore.onChange((token, user) => {
  console.log("authenticated:", !!token);
  console.log("user:", user?.email);
});

The RaisFast Class

const client = new RaisFast(baseUrl);

// Dynamic content type access
client.collection<Portfolio>("portfolios");    // public API
client.adminCollection<Portfolio>("portfolios"); // admin API

// Built-in modules
client.auth          // Auth & OAuth & SMS
client.users         // User profiles
client.posts         // Blog posts
client.pages         // Static pages
client.comments      // Comments
client.categories    // Categories
client.tags          // Tags
client.media         // File uploads
client.products      // Products
client.cart          // Shopping cart
client.orders        // Orders
client.payment       // Payment
client.wallets       // Wallets
client.events        // SSE real-time
client.health        // Health check

// Admin modules
client.admin         // 23 admin sub-modules

// Single-record content type
const settings = await client.single<SiteSettings>("site_settings");

// RSS feed URL
client.getRssFeedURL();

Request Hooks

Before Send

Add custom headers, logging, or modify requests:

client.beforeSend = (url, options) => {
  options.headers = {
    ...options.headers,
    "X-Custom-Header": "value",
  };
  return { url, options };
};

After Send

Transform responses or add global error handling:

client.afterSend = (response, data) => {
  console.log(`${response.status} ${response.url}`);
  return data;
};

Request Cancellation

// Cancel a specific request by key
client.cancelRequest("search_query");

// Cancel all pending requests
client.cancelAllRequests();

Requests accept a requestKey option. Sending a new request with the same key auto-cancels the previous one:

const result = await portfolios.getList(1, 20, {
  requestKey: "portfolio_list",
});

Error Handling

import { SDKError } from "@raisfast/sdk";

try {
  await portfolios.getOne("invalid-id");
} catch (e) {
  if (e instanceof SDKError) {
    console.log(e.status);    // 404
    console.log(e.code);      // backend error code
    console.log(e.message);   // "not found"
    console.log(e.url);       // request URL
    console.log(e.isAbort);   // was it cancelled?
  }
}

Multi-Tenant

client.setTenantId("tenant-123");  // adds X-Tenant-ID header
client.setTenantId(null);          // reset

Raw Requests

For endpoints not covered by the SDK:

const data = await client.send("/custom/endpoint", {
  method: "POST",
  body: { key: "value" },
});

Content Types API

CRUD operations, filtering, sorting, pagination, file upload, and revisions.

Auth & Users

Built-in Modules

Posts, pages, media, products, cart, orders, payment, wallets, SSE events.

Admin API

23 admin sub-modules for building admin dashboards.

Overview

Content Types API

Auth & Users

Built-in Modules

Admin API

On this page