PulsaClient

PulsaClient is the root class of the Pulsabase SDK. All operations — queries, auth, storage, real-time, and edge functions — flow through it.

Constructor

import 'reflect-metadata';
import { PulsaClient } from 'pulsabase';

const pb = new PulsaClient(options: PulsabaseClientOptions);

PulsabaseClientOptions

Property	Type	Required	Description
engineUrl	string		URL of pulsabase-core (e.g. https://api.myproject.pulsabase.io)
apiKey	string		Project API key (pk_live_...)
auth.clientId	string		OAuth client ID
auth.clientSecret	string	—	OAuth client secret (server-side only, never expose in browser)
auth.redirectUri	string	—	Redirect URI for PKCE / social login flows
auth.postLogoutRedirectUri	string	—	Post-logout redirect URI
broadcasterUrl	string	—	WebSocket URL for real-time subscriptions
storageUrl	string	—	URL of pulsabase-storage
idpUrl	string	—	URL of pulsabase-idp (required for auth)
tenantId	string	—	Project / tenant ID
subTenantId	string	—	Sub-tenant ID (multi-tenant apps)
models	ModelClass[]	—	Array of model classes for hydration
autoRefreshToken	boolean	—	Auto-refresh tokens before expiry (default: true)
tokenRefreshLeewaySeconds	number	—	Seconds before expiry to refresh (default: 60)
dedupe	PulsabaseDedupeOptions	—	Global deduplication config for real-time events

---

pb.from(ModelClass)

Returns a QueryBuilder instance for the given model. All database reads and writes start here.

pb.from(User)           // → QueryBuilder<User>
pb.from(User).find()    // SELECT * FROM users (limit 100)
pb.from(User).insert({ name: 'Jane', email: 'jane@example.com' })

See QueryBuilder reference for all chainable methods.

---

pb.model(ModelClass, id)

Returns a ModelInstance scoped to a specific record by its primary key. Used for relation management.

const room = pb.model(Room, roomId);

await room.members().attach(userId, { role: 'admin' });
await room.members().detach(userId);
await room.members().sync([userId1, userId2]);

See RelationBuilder reference.

---

pb.transaction(operations)

Execute multiple operations atomically in a single database transaction. All operations succeed or all roll back.

const results = await pb.transaction([
  pb.from(Account).where('id', senderId).buildUpdate({ balance: 50 }),
  pb.from(Account).where('id', receiverId).buildUpdate({ balance: 150 }),
  pb.from(AuditLog).buildInsert({ action: 'transfer', amount: 100 }),
]);

Each item in the array must be a QueryBuilder prepared with buildInsert, buildUpdate, buildDelete, buildFind, buildFindOne, or buildUpsert followed by .toPayload() (automatically called by transaction).

---

pb.edge(functionName)

Returns an EdgeFunctionBuilder to invoke an edge function.

// Synchronous
const result = await pb.edge('process-order').invoke({ productId: 'p-1', qty: 2 });

// With dry run (returns __logs of all steps)
const result = await pb.edge('process-order').dryRun().invoke({ ... });

EdgeFunctionBuilder Methods

Method	Returns	Description
.dryRun()	EdgeFunctionBuilder	Enables dry run mode — no real side effects
.invoke(payload?)	Promise<T>	Execute synchronously and wait for result

---

pb.channel(name)

Returns a PulsaChannel for custom pub/sub messaging (not tied to a database table).

const typing = pb.channel('room:123:typing');

typing.on('typing', (payload) => {
  console.log(`${payload.user} is typing...`);
});

await typing.subscribe();

// Send an event
await typing.send('typing', { user: 'Jane', roomId: '123' });

// Clean up
typing.unsubscribeChannel();

---

pb.listen(callback, options?)

Listen to real-time database change events via WebSocket. Returns an unsubscribe function.

const unsub = pb.listen((msg) => {
  console.log(msg.action, msg.table, msg.data);
}, {
  filterTable: 'messages',
  filterAction: ['INSERT'],
});

// Stop listening
unsub();

ListenOptions

Property	Type	Description
filterTable	string | string[]	Filter by table name(s)
filterAction	'INSERT' | 'UPDATE' | 'DELETE' (or array)	Filter by event type(s)
filter	(msg) => boolean	Custom filter function (overrides filterTable/filterAction)
dedupe	ChangeEventBufferOptions	Per-listener deduplication config

---

pb.invoke(name, payload?, options?)

Lower-level edge function invocation (used internally by EdgeFunctionBuilder).

const result = await pb.invoke('my-function', { key: 'value' }, { dry_run: true });

---

pb.auth

Access to the AuthService instance. See AuthService reference.

await pb.auth.signInWithPassword(email, password);
const user = pb.auth.getCachedUser();
pb.auth.hasRole('admin');

---

pb.storage

Access to the PulsaStorage instance. See Storage reference.

const obj = await pb.storage.upload('avatar.jpg', file);
const { presigned_url } = await pb.storage.download(objectId);

---

pb.destroy()

Clean up all resources — closes WebSocket connection, clears refresh timers, removes all listeners. Call this when unmounting your app or terminating a server process.

pb.destroy();