Skip to content

SDK and OpenAPI

Terminal window
bfast sdk --app my-counter --out client.ts
bfast openapi --app my-counter --out openapi.json

These commands require a platform key with read scope. The platform verifies the contract hash against the selected deployment. A candidate build cannot replace its selected contract. Older deployments without hashes need an update.

The generated TypeScript client has no package dependencies. Use it from a server client or the app’s registered origin. Managed browser CORS for unrelated frontend origins remains separate work.

import { Client, APIError } from './client';
const client = new Client({
baseUrl: appURL,
accessToken: () => currentAppSessionToken,
});
const counters = await client.listCounters();
console.log(counters[0].value.toString());

The token callback can return a promise. The client treats tokens as opaque, sends a bearer header, omits ambient cookies and refuses redirects. It performs no automatic request retries. Use signal for cancellation and fetch for a custom server transport. See app login.

The first method argument holds path/query parameters. The second holds the JSON body. A body without path/query parameters uses {} as its first argument. A single body parameter uses its value directly, such as a string. Multiple body parameters use an object with the declared names.

Request types preserve optional/defaulted fields. Responses have required fields and explicit nullable values. IDs, times, dates and durations use strings. V1 int maps to bigint. The client preserves exact signed 64-bit integers during JSON encoding/decoding. Use toString() for display.

OpenAPI separates input and output schemas. It includes defaults, enums, opaque bearer security, error envelopes and managed File routes.

Use standard File objects and the methods described in File storage. APIError exposes status, code and message for application HTTP failures. Malformed response JSON uses invalid_response. Transport and cancellation errors come from the chosen fetch implementation.

try {
await client.listCounters();
} catch (error) {
if (error instanceof APIError) console.log(error.status, error.code);
else throw error;
}