ZeroStack SDK

Lightweight JavaScript/TypeScript client for the ZeroStack Backend-as-a-Service.

ZeroStack is a Backend-as-a-Service designed to let developers easily store and manage application data without deploying or maintaining a dedicated backend. It provides a simple, ready-to-use infrastructure that client applications — such as web browsers, mobile apps, or lightweight games — can connect to directly. With ZeroStack, developers can quickly implement features like multiplayer game state synchronization, high-score leaderboards, user identifiers, or shared application data through a clean and minimal API. The goal is to remove backend complexity, allowing teams to focus on building user experiences while ZeroStack handles data storage, access, and scalability behind the scenes.

Installation

npm install zerostack-sdk

Or use directly in the browser:

<script src="https://your-zerostack.com/sdk/zerostack.min.js"></script>

Quick Start

import ZeroStack from 'zerostack-sdk';

const zs = new ZeroStack({
  apiUrl: 'https://zerostack.example.com/api',
  wsUrl:  'https://zerostack.example.com',
  apiKey: 'zs_your_api_key',
});

Authentication

// Register
const { user, accessToken, refreshToken } = await zs.auth.register('user@example.com', 'password');

// Login
const { user, accessToken, refreshToken } = await zs.auth.login('user@example.com', 'password');

// Set token for authenticated requests
zs.setToken(accessToken);

// Guest mode (anonymous identity)
zs.setGuestId('guest_' + Math.random().toString(36).slice(2));

Data

CRUD Operations

// List items (with pagination and filtering)
const result = await zs.data.list('messages', {
  limit: 50,
  page: 1,
  filter: { room: 'general' },
});

// Create
const item = await zs.data.create('messages', { text: 'Hello!' });

// Create with options
const privateItem = await zs.data.create('messages',
  { text: 'Secret' },
  { visibility: 'private', allowed: ['user_123', 'guest_abc'] }
);

// Update
const updated = await zs.data.update('messages', item._id, { text: 'Edited' });

// Update access list
const shared = await zs.data.update('messages', item._id,
  { text: 'Shared' },
  { allowed: ['user_123', 'guest_abc', 'guest_xyz'] }
);

// Delete
await zs.data.delete('messages', item._id);

Visibility & Access Control

• Public items (visibility: 'public'): readable by anyone with the API key.
• Private items (visibility: 'private'): only accessible by identities listed in allowed[] and the app owner.
• The creator is automatically added to allowed[] on creation.
• Anyone in allowed[] can update the access list.

Real-time

Requires socket.io-client loaded in the environment.

// Subscribe to changes on a node
zs.realtime.subscribe('messages', (item, event) => {
  console.log(event, item); // event: 'created' | 'updated' | 'deleted'
});

// Connection status
zs.realtime.on('connect', () => console.log('Connected'));
zs.realtime.on('disconnect', () => console.log('Disconnected'));

// Cleanup
zs.realtime.unsubscribe('messages');
zs.realtime.disconnect();

App Configuration

Requires authentication as the app owner (zs.setToken(ownerToken)).

// Set which nodes are publicly accessible
await zs.config.setPublicNodes({
  read:   ['messages', 'rooms'],
  create: ['messages'],
  update: ['messages'],
  delete: [],
});

// Set auto-expiration TTL per node (in seconds)
await zs.config.setNodeTTL({
  sessions: 3600,   // 1 hour
  lobbies:  86400,  // 24 hours
});

Documents in nodes with a TTL are automatically deleted after the specified duration of inactivity (no read or write).

TypeScript

Full type definitions are included. Import types as needed:

import ZeroStack, {
  DataItem,
  ListOptions,
  CreateOptions,
  RealtimeCallback,
  PaginatedResponse,
} from 'zerostack-sdk';

License

MIT