JavaScript SDK

The TaruviBase JavaScript SDK provides typed service clients for application data, authentication, files, functions, secrets, policies, settings, and analytics. Configure one Client, then pass it to the services your application uses.

This guide covers @taruvi/sdk 1.5.3.

Install the SDK

npm install @taruvi/sdk

The package is an ECMAScript module and includes static type declarations.

Configure a browser client

Create one client when the application starts. The following Vite example reads the site URL and app slug from public build-time configuration; use the equivalent public configuration mechanism in another framework:

import {Auth, Client} from '@taruvi/sdk';

export const taruvi = new Client({
  apiUrl: import.meta.env.VITE_TARUVI_SITE_URL,
  appSlug: import.meta.env.VITE_TARUVI_APP_SLUG,
  apiKey: 'session-authenticated-client',
});

export const auth = new Auth(taruvi);

Version 1.5.3 requires an apiKey value but does not send it with requests. Use the placeholder value shown above. Never put a real API key in browser code.

Start browser sign-in from an application action:

export function signIn() {
  auth.login();
}

After sign-in, TaruviBase redirects to the application with #session_token=<value>. Constructing Client on that page stores the token in browser storage, removes it from the URL, and sends it as X-Session-Token on later requests. The browser runtime ignores the constructor's token option, so do not pass a browser session through that field.

Follow the authentication guide for the full redirect and session flow.

Configure a server client

Version 1.5.3 authenticates with a user's session token. In a non-browser runtime, pass that token as token:

import {Client} from '@taruvi/sdk';

export const taruvi = new Client({
  apiUrl: process.env.TARUVI_SITE_URL!,
  appSlug: process.env.TARUVI_APP_SLUG!,
  apiKey: 'session-authenticated-client',
  token: process.env.TARUVI_SESSION_TOKEN!,
});

Keep the session token in the runtime's secret store. The SDK sends it as X-Session-Token.

Call TaruviBase with an API key from a server

The SDK does not send API keys. To call TaruviBase from a server with the API key from Settings → Connect, use the REST API directly and keep this code server-only:

const response = await fetch(
  `${process.env.TARUVI_SITE_URL}/api/apps/${process.env.TARUVI_APP_SLUG}/datatables/tasks/data/?page=1&page_size=20`,
  {headers: {Authorization: `Api-Key ${process.env.TARUVI_API_KEY}`}},
);
if (!response.ok) {
  throw new Error(`TaruviBase request failed with ${response.status}`);
}
const {data, total} = await response.json();

The API request lifecycle describes the response envelope and error codes.

Choose a service client

Services are exported classes. Construct the service you need; version 1.5.3 does not expose them as properties such as client.database.

import {Database} from '@taruvi/sdk';

export const database = new Database(taruvi);

For example, after a tasks table is available:

await database
  .from('tasks')
  .sort('title', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

Client	Use it for
Auth	Browser redirects, session validation, and the current user
Database	Records, filters, sorting, pagination, and aggregations
Storage	Objects in app storage buckets
Functions	Function invocation
User	Users, roles, app membership, and preferences
Policy	Permission checks and allowed actions
Secrets	Reading one or more secrets
Settings	Site metadata and user attributes
App	App roles and settings
Analytics	Saved analytics-query execution

Handle responses and errors

Service methods return the parsed TaruviBase response. Record responses use status, message, and data, with total and pagination when the operation supports them.

The package exports typed errors for validation, authentication, authorization, missing resources, conflicts, rate limits, timeouts, and network failures. Catch the narrow error your application can resolve, then use TaruviError as the final SDK-level fallback.

import {ForbiddenError, TaruviError} from '@taruvi/sdk';

try {
  await database.from('tasks').get('task-id').execute();
} catch (error) {
  if (error instanceof ForbiddenError) {
    // Return the user to a permitted workflow.
  } else if (error instanceof TaruviError) {
    // Show a safe application-level failure state.
  }
}

Package compatibility

@taruvi/sdk 1.5.3 declares peer ranges axios >=1 <2, typescript >=5.7 <6, and @types/node >=18 <25; it does not declare a Node.js runtime range. TaruviBase API and SDK releases are versioned independently, so pin the SDK and test authentication, reads, writes, permission failures, and cleanup before upgrading.

The HTTP client clears its stored session after a 401, 410, or 419 response. It keeps the session after 403 because the credential may still be valid for another action.

Choose a task from the Products overview for focused SDK methods and examples.

Deploy your app

Once you've built your application with the JavaScript SDK, set up automated deployments to production:

Deploy with GitHub Actions →