Use the TypeScript SDK

The TypeScript SDK works in Node 18 and later, Bun, Deno and edge runtimes. It has no runtime dependencies and needs only fetch.

Install

npm install @pgb/sdk

Create a client

import { createClient } from "@pgb/sdk";

// Browser or mobile app: your PUBLISHABLE key
const pgb = createClient("my-project", { key: "pgb_pub_..." });

// Server: a SECRET key. Never ship it to a browser.
const admin = createClient({ projectId: "my-project", apiKey: process.env.PGBHUB_SECRET_KEY });

createClient("my-project") talks to https://my-project.pgbhub.app. You can also pass endpoint, or set PGBHUB_PROJECT_ID, PGBHUB_ENDPOINT and PGBHUB_API_KEY in the environment.

Your first query

const users = pgb.table("users");

const created = await users.create({ name: "Alex", email: "[email protected]" });
const admins = await users.find({ role: "admin" }, { limit: 10, orderBy: "created_at", order: "DESC" });
const one = await users.findOne({ email: "[email protected]" });
const total = await users.count();

For anything else, run SQL: await pgb.db.query("SELECT now()").

What is in the box

Namespace	Main methods
pgb.table(name)	find, findFirst, findOne, create, update, delete, count
pgb.db	query
pgb.auth	signUp, signIn, signOut, getUser, refreshSession, requestOtp, sendMagicLink, forgotPassword, resetPassword, two-factor and social login calls
pgb.storage	upload, list, delete, createSignedUrl, createBucket, setBucketVisibility
pgb.mail	send
pgb.functions	invoke, list, deploy, delete
pgb.cron	list, create, update, toggle, run, listRuns, delete
pgb.jobs	enqueue, get, list, cancel
pgb.queues	send, receive, ack, nack
pgb.realtime	broadcast, subscribe
pgb.actions	call actions by name, $register, $list, $deliveries

Admin calls such as sending mail, creating buckets or deploying functions need the secret key.

Sign users in

const result = await pgb.auth.signUp({ email, password });
const login = await pgb.auth.signIn({ email, password });
if (login.mfa_required) {
  await pgb.auth.verifyMfa({ challengeToken: login.challenge_token!, code: "123456" });
}
const user = await pgb.auth.getUser();

The SDK keeps the session in memory. Use getSession() and setSession() to store it where your app needs it. See Authentication in your project.

Errors, timeouts and retries

Every failure throws a PGBError with status, code, retryAfter (on rate limits) and a readable message. Requests time out after 30 seconds by default. Reads retry twice after network errors, timeouts, 429, 502, 503 and 504. Writes are never retried automatically.

Generate types

npx pgb pull --db my_database --out src/types/pgbhub.d.ts
npx pgb dev

pgb pull writes TypeScript types from your schema. pgb dev starts a local mock gateway on port 4000 for development. The CLI also has pgb init, pgb login and pgb inspect.

Good to know

• Use a publishable key in the browser and rely on row-level security.
• Keep the secret key in an environment variable on your server.