The TypeScript SDK

Install and connect

The SDK runs in Node 18 and later, Bun, Deno and edge runtimes, and needs only fetch.

npm install @pgb/sdk

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

const pgb = createClient("my-project", { key: "pgb_pub_..." });            // apps
const admin = createClient({ projectId: "my-project", apiKey: process.env.PGBHUB_SECRET_KEY }); // servers

createClient("my-project") talks to https://my-project.pgbhub.app. Options include endpoint, timeoutMs (default 30000) and maxRetries (default 2, for reads only).

First query

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

const result = await pgb.db.query("SELECT now()");

Sign people in

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();
await pgb.auth.signOut();

The SDK keeps the session in memory. getSession() and setSession() let you store it wherever your app needs. Also available: one-time codes (requestOtp, verifyOtp), magic links, password reset, profile updates, sessions, two-factor setup and social login (oauthStart, oauthCallback).

Other services

await pgb.functions.invoke("note_summary", { name: "Ana" });
await admin.mail.send({ to: "[email protected]", subject: "Hi", text: "Hello" });
await admin.storage.createBucket("receipts", { visibility: "private" });
const { url } = await admin.storage.createSignedUrl("receipts", "inv-1.pdf", { expiresIn: 900 });
await admin.jobs.enqueue(/* job type, target, config, payload */);
await admin.queues.send("orders", { order_id: 1 });
await admin.realtime.broadcast("orders", { id: 1 }, { event: "created" });
const stop = pgb.realtime.subscribe("orders", (evt) => console.log(evt));

Mail, bucket changes, signed links, function deployment and cron management need the secret key.

Actions

const res = await pgb.actions.saveUser({ name: "Alex", email: "[email protected]" });
const preview = await pgb.actions.saveUser({ name: "Alex" }, { dryRun: true });

Errors

Failures throw PGBError with status, code, retryAfter and a readable message:

import { PGBError } from "@pgb/sdk";
try {
  await pgb.auth.signIn({ email, password });
} catch (err) {
  if (err instanceof PGBError && err.status === 429) { /* wait err.retryAfter seconds */ }
}

Writes are never retried automatically.

Types and local development

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

pgb pull generates types from your schema. pgb dev runs a local mock gateway on port 4000.

Try it

1. Install the SDK in a small script.
2. Create a client with your publishable key and find rows from a table that allows it.
3. Create a second client with a secret key and send yourself an email.
4. Catch a deliberately wrong sign-in and print err.status.

Recap

• createClient with a publishable key in apps, a secret key on servers.
• Tables, SQL, auth, functions, mail, storage, jobs, queues, realtime and actions live in one client.
• Failures are PGBError, and only reads retry by themselves.