Browser vs server
@tenantcloud/sdk ships two builds with one type surface:
| Build | Selected by | Talks to | Identity |
|---|---|---|---|
Browser (@tenantcloud/sdk/browser) | The browser export condition (Vite, webpack, any bundler) | Your app's own origin under /_tc/* | The Edge session cookie (same-origin requests) |
Server (@tenantcloud/sdk/server) | The node export condition | Platform services via injected env vars | The X-TC-User header on the incoming request, or the project token in jobs |
You can import a build explicitly with @tenantcloud/sdk/browser or @tenantcloud/sdk/server.
The /_tc/* paths
Every project origin (https://<project>.apps.<your-domain>) serves the platform under /_tc/:
| Path | What |
|---|---|
/_tc/auth/me | The signed-in user (JSON) |
/_tc/auth/login?rd=…, /_tc/auth/logout | Sign-in round trip, single sign-out |
/_tc/db/* | The project's Data API (PostgREST) |
/_tc/storage/v1/* | File storage |
/_tc/int/<integration>/* | The Integration Gateway |
The browser build only ever calls these same-origin paths, so there is nothing to configure and no CORS.
Member availability
| Member | Browser | Server |
|---|---|---|
tc.auth.user() | Yes (calls /_tc/auth/me) | Yes, tc.auth.user(req) verifies X-TC-User |
tc.auth.token() | Returns null | Yes |
tc.auth.login(), tc.auth.logout() | Yes | No |
tc.db.from(), tc.db.rpc() | Yes | Yes, as the current request's user |
tc.db.sql | Throws SERVER_ONLY | Yes (service role) |
tc.db.asUser(req), tc.db.pool() | Throws SERVER_ONLY | Yes |
tc.db.end() | No-op | Closes the pool |
tc.storage | Yes | Yes |
tc.m365, tc.int, tc.teams | Yes | Yes |
tc.int.<name>.connect(), .status(), .disconnect() | Yes | No |
tc.middleware() | Throws SERVER_ONLY | Yes |
tc.withRequest(req, fn) | Runs fn() | Yes |
Server environment
On the server the SDK reads these variables. The platform sets all of them; you never set them yourself (names starting with TC_ are reserved).
| Variable | Used by |
|---|---|
DATABASE_URL | tc.db.sql, tc.db.pool() (service role) |
TC_POSTGREST_URL | tc.db.from(), tc.db.asUser() |
TC_GATEWAY_URL | tc.m365, tc.int, tc.teams |
TC_STORAGE_URL | tc.storage |
TC_JWKS_URL | Verifying X-TC-User |
TC_PROJECT | The expected token audience (tc:app:<project>) |
TC_PROJECT_URL | Absolute signed and public storage URLs |
TC_PROJECT_TOKEN | Cron and worker services only: the app's own identity |
TC_PROJECT_OWNER_EMAIL | Mail sent as the app |
TC_DB_POOL | Optional: database pool size (default 5) |
PORT | Where your app listens (8080) |
If one is missing (for example when you run the server outside the platform), the call throws NOT_CONFIGURED with a fix that tells you to deploy.
createClient(options)
Apps use the default tc export. createClient exists for tests and scripts.
createClient(opts?: { origin?: string; fetch?: typeof fetch; env?: Record<string, string | undefined> }): Tc
| Option | Build | Description |
|---|---|---|
origin | Browser | The app origin to call (default location.origin) |
fetch | Both | A custom fetch (tests) |
env | Server | Environment to read instead of process.env |
test/setup.js
import { createClient } from '@tenantcloud/sdk/server'
const tc = createClient({ env: { TC_JWKS_URL: 'http://localhost:9999/jwks', TC_PROJECT: 'expenses' } })
Helpers
| Export | Description |
|---|---|
userToken(req) | Server build only. Pulls the raw X-TC-User token from an Express/Node request, a Fetch Request, a Hono context or a string |
rowsToObjects(values) | Turns [[header…], [row…]] into objects keyed by the header row. Empty headers become column_<n> |
shareId(url) | The Microsoft Graph "shares" key for a SharePoint/OneDrive URL |
Was this page helpful?