Taruvi SDK

TypeScript SDK for the Taruvi platform. It gives developers a consistent, typed way to query the Taruvi backend — shared configuration, session authentication, fluent query builders, and structured errors across data, storage, auth, users, functions, analytics, policy, secrets, and app services.

Package: @taruvi/sdk · Version: 1.5.0-beta.1 · License: MIT

Branches: main is for stable releases; beta is for experimental releases. Bumping version in package.json and pushing to either branch triggers CI/CD (npm test, then publish to npm with the matching tag). See Releases and branches.

Installation

# Stable (from main)
npm install @taruvi/sdk

# Experimental (from beta)
npm install @taruvi/sdk@beta

Peer dependencies: axios (>=1), typescript (>=5.7), optional @types/node for server use.

Quick start

import { Client, Database } from '@taruvi/sdk'

const client = new Client({
  apiKey: 'your-site-api-key',
  appSlug: 'your-app-slug',
  apiUrl: 'https://taruvi-site.taruvi.cloud',
})

const db = new Database(client)

const response = await db
  .from('accounts')
  .filters('status', 'eq', 'active')
  .sort('created_at', 'desc')
  .page(1)
  .pageSize(20)
  .execute()

Documentation

Full guides live in docs/:

| Guide | Topic | |-------|--------| | Introduction | Purpose, setup, DI, backend-handled login flow | | Builder pattern | Immutable queries and execution | | Architecture | lib vs lib-internal, request flow | | Clients | What each service does | | API reference | All public methods | | Examples | Chaining patterns and workflows | | Advanced & troubleshooting | Typing, filters, CORS, packaging | | Releases & branches | Stable vs beta, CI/CD publish workflow |

Services at a glance

| Client | Use for | |--------|---------| | Database | Table CRUD, filters, pagination, graph/edges | | Storage | Bucket files: list, upload, download, delete | | Auth | Browser login/signup/logout, session token | | User | User admin, roles, preferences | | Functions | Invoke serverless functions | | Analytics | Run predefined analytics queries | | Settings | Site metadata, user attribute schema | | Secrets | Read secret values | | Policy | Permission checks | | App | App roles and settings |

What's included

• Immutable builder pattern for Database, Storage, App, and Secrets.get() — each chain step returns a new instance so parallel queries never overwrite each other's URLs or filters.
• Session authentication via X-Session-Token; automatic token extraction from URL hash after OAuth redirect in the browser.
• Typed errors — AuthError, NotFoundError, ValidationError, and others exported from the package.

Development

npm run build    # TypeScript compile
npm test         # Vitest unit tests

Additional resources

• SDK design context — backend API contract notes (SDK ↔ API mapping)

Author

Curran C Doddabele · EOX Vantage