Configure the client

Client and its compatibility subclass PBVexClient are constructed with a URL and an optional ClientOptions object.

Constructor signature

import { Client, type ClientOptions } from '@pbvex/client';

const client = new Client('http://localhost:8090', options);

The first argument may be a string or URL. baseUrl in options resolves a relative URL against the first argument.

Options

interface ClientOptions {
  fetch?: typeof globalThis.fetch;
  baseUrl?: string;
  timeoutMs?: number;
  auth?: string | AuthProvider;
  authStore?: AuthStore;
  realtimeTransport?: RealtimeTransport;
  realtimePath?: string;
  limits?: ClientLimits;
}

Option	Default	Description
fetch	globalThis.fetch	Fetch implementation. Required in environments without native fetch.
baseUrl	url argument	Resolved base URL for /api/pbvex/call and /api/pbvex/realtime.
timeoutMs	30000	Request timeout for calls and realtime establishment. Must be a positive finite number <= 600000.
auth	undefined	Static Bearer token or AuthProvider callback.
authStore	LocalAuthStore	PocketBase-compatible application auth state. Use AuthStore for explicit memory-only state.
realtimeTransport	FetchRealtimeTransport	Custom RealtimeTransport implementation.
realtimePath	/api/pbvex/realtime	SSE endpoint path.
limits	protocol defaults	Per-client size limits (see below).

When both are supplied, auth is the request token source and takes precedence over authStore. Native PocketBase auth methods still update authStore, but PBVex calls continue to use the explicit auth source. Omit auth when native auth-store sessions should authorize calls; use setAuth and clearAuth only when deliberately managing an external token source.

Auth providers

A static token:

const client = new Client('http://localhost:8090', {
  auth: 'my-token',
});

A provider callback is evaluated before each request:

const client = new Client('http://localhost:8090', {
  auth: async () => {
    const session = await getSession();
    return session?.token;
  },
});

setAuth and clearAuth update the client-level auth and refresh live realtime subscriptions:

client.setAuth('new-token');
client.clearAuth();

Per-call auth overrides the client-level provider:

await client.query(api.messages.list, { channel: 'general' }, {
  auth: 'record-token-for-this-call',
});

Limits

interface ClientLimits {
  maxFunctionArgsBytes?: number;
  maxReturnValueBytes?: number;
  maxUploadBytes?: number;
}

• maxFunctionArgsBytes caps the encoded call args body (default 1048576).
• maxReturnValueBytes caps the response body read before truncation (default 1048576).
• maxUploadBytes is accepted for forward compatibility but is not enforced by @pbvex/client; storage uploads use a URL generated by a server-side mutation or action (see Storage).

Limits are validated: non-negative integers only.

const client = new Client('http://localhost:8090', {
  limits: {
    maxFunctionArgsBytes: 64 * 1024,
    maxReturnValueBytes: 256 * 1024,
  },
});

Custom fetch

Use custom fetch for Node <18, testing, or adding headers:

const client = new Client('http://localhost:8090', {
  fetch: (input, init) => {
    return fetch(input, {
      ...init,
      headers: {
        ...init?.headers,
        'X-Request-Id': generateRequestId(),
      },
    });
  },
});

Close

Close all realtime subscriptions when the client is no longer needed:

client.close();

close is idempotent on the default FetchRealtimeTransport. It does not cancel in-flight HTTP calls.