@tallpond/sdk

Client SDK for tallpond — the browser half of an app that runs against an tallpond gateway. It handles the OAuth/PKCE sign-in dance and makes credentialed calls for metered AI, scoped data, files, and resources. Session tokens live in httpOnly cookies set by the gateway, so app code (and therefore XSS) can never read them.

npm install @tallpond/sdk

Usage

On the hosted platform the gateway injects the app's identity into the served HTML, so createClient() needs no arguments:

import { createClient } from '@tallpond/sdk'

const tallpond = createClient()

await tallpond.auth.signIn() // redirects through the platform IdP
const { authenticated, userId } = await tallpond.auth.getSession()

// Metered AI — billed to the signed-in user, no dev-held keys
const res = await tallpond.ai.chat({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'hi' }],
})
const reply = res.choices?.[0]?.message?.content

// Scoped, per-user data (schema deployed via the tallpond CLI) — a Supabase-
// style query builder you await
await tallpond.table('messages').insert({ body: 'hello', kind: 'user' })
const rows = await tallpond.table('messages').select().orderBy('createdAt', 'desc')

// Files (per bucket), public profiles, wallet
const meta = await tallpond.files('notes').upload('note.txt', blob)
const alice = await tallpond.users.byHandle('alice') // platform-central handles
const me = await tallpond.wallet.get()

Shared, membership-gated data lives on resources:

const room = await tallpond.resource.create('room', { name: 'lobby' })
await tallpond.resource(room.id).members.join()
await tallpond.resource(room.id).table('messages').insert({ body: 'hi', kind: 'user' })

Server functions

Invoke a deployed function (see the functions docs):

const result = await tallpond.functions.invoke('submitMove', {
  resourceId: room.id,
  args: { move: { to: 'e4' } },
})

When writing functions (functions/*.ts, deployed by the CLI), annotate the handler with the type-only FunctionContext export so the compiler checks your code against the real ctx contract — userId, resourceId, fn, invocationId, db.query/db.batch, and gateway() (POST by default, { method: 'GET' } for read routes) are all there is:

import type { FunctionContext } from '@tallpond/sdk'
export default async (ctx: FunctionContext, args: { body: string }) => { /* ... */ }

The OAuth callback path

signIn() redirects back to redirectUri, which defaults to your app's bare origin (/) — so by default, whatever renders at / must call tallpond.auth.handleRedirectCallback() to finish the code exchange. If your router handles the callback on a dedicated page instead, pass the path explicitly (it must match on both the sign-in and callback ends):

const tallpond = createClient({
  redirectUri: `${window.location.origin}/auth/callback`,
})

Hosted apps have exactly two pre-registered redirect URIs: the bare origin and <origin>/auth/callback. Any other path is rejected by the identity provider with invalid_request ("does not match any pre-registered redirect urls").

Scripted clients (e2e tests, agents)

Outside a browser there are no cookies; pass a bearer token instead — e.g. a test-session token minted with tallpond test-session (see the authentication docs):

const tallpond = createClient({
  gatewayUrl: 'https://api.tallpond.com',
  accessToken: process.env.TEST_SESSION_TOKEN,
})
await tallpond.table('messages').insert({ body: 'from a test', kind: 'user' })

In this mode clientId is optional (the token carries the app identity) and the browser auth surface (signIn, callbacks, refresh) does not apply.

Off-platform (local dev, or self-hosting against your own gateway) pass config explicitly:

const tallpond = createClient({
  gatewayUrl: 'http://localhost:3000',
  clientId: 'your-oauth-client-id',
})

Types

App tables are typed by augmenting the SDK from your generated schema types (tallpond typegen writes a declare module '@tallpond/sdk' block), so tallpond.table('messages') is fully typed against your deployed schema.

License

MIT