ZeroStack SDK

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

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('[email protected]', 'password');

// Login
const { user, accessToken, refreshToken } = await zs.auth.login('[email protected]', '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