@buildspacestudio/sdk

The official JavaScript/TypeScript SDK for Buildspace — auth, events, storage, and notifications for your app.

Installation

npm install @buildspacestudio/sdk
# or
bun add @buildspacestudio/sdk

Quick start

The SDK has two entrypoints depending on where your code runs:

| Entrypoint | Key type | Use in | |---|---|---| | @buildspacestudio/sdk | Secret key (bs_sec_*) | Server / Node.js / Edge functions | | @buildspacestudio/sdk/client | Publishable key (bs_pub_*) | Browser / React / client components |

Server SDK

import Buildspace from "@buildspacestudio/sdk";

const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);

Client SDK

import { createClient } from "@buildspacestudio/sdk/client";

const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);

Auth

Server — handle OAuth callback

// In your callback route handler:
const tokens = await buildspace.auth.handleCallback(request);
// tokens.access_token, tokens.user

// Verify a session
const session = await buildspace.auth.getSession(sessionToken);
if (!session) {
  // invalid or expired
}

// Sign out
await buildspace.auth.signOut(sessionToken);

Client — generate sign-in / sign-up URLs

const signInUrl = buildspace.auth.getSignInUrl({
  redirectUri: "https://yourapp.com/auth/callback",
  appSlug: "my-app", // optional
});

const signUpUrl = buildspace.auth.getSignUpUrl({
  redirectUri: "https://yourapp.com/auth/callback",
});

Events

Track user and system events for analytics.

Server

// Single event
await buildspace.events.track("user.signed_up", { plan: "pro" }, userId);

// Batch
await buildspace.events.batchTrack([
  { event: "page.viewed", properties: { path: "/dashboard" }, actor_id: userId },
  { event: "feature.used", properties: { feature: "export" }, actor_id: userId },
]);

Client (batched, auto-flushed)

// Fire and forget — events are queued and flushed in batches
buildspace.events.track("button.clicked", { label: "upgrade" });

// Flush immediately (e.g. before page unload)
await buildspace.events.flush();

// Graceful shutdown
await buildspace.events.shutdown();

Configure batching behavior:

const buildspace = createClient(key, {
  events: {
    flushInterval: 3000, // ms, default 5000
    maxBatchSize: 50,    // default 20
  },
});

Storage

Upload and manage files.

Server — get a pre-signed upload URL

const { upload_url, key } = await buildspace.storage.getUploadUrl({
  key: "avatars/user-123.png",
  contentType: "image/png",
  size: file.size,
});

// Upload directly to the signed URL
await fetch(upload_url, { method: "PUT", body: file });

// Get a signed download URL
const { url } = await buildspace.storage.getSignedUrl(key, { expiresIn: 3600 });

// List objects
const { objects } = await buildspace.storage.list("avatars/");

// Delete
await buildspace.storage.delete(key);

// Check usage
const { storageBytes, objectCount } = await buildspace.storage.getUsage();

Client — upload a File/Blob directly

const { key, url } = await buildspace.storage.upload(file, {
  path: "avatars/user-123.png",
  contentType: "image/png", // optional, inferred from File if omitted
});

Notifications

Send transactional emails. Server only.

// Send a custom email
await buildspace.notifications.send({
  to: "[email protected]",
  subject: "Welcome to Buildspace",
  html: "<h1>You're in!</h1>",
  text: "You're in!", // optional plain-text fallback
  replyTo: "[email protected]",
});

// Send from a saved template
await buildspace.notifications.sendTemplate("welcome-email", {
  to: "[email protected]",
  variables: { firstName: "Alex", plan: "Pro" },
});

Sessions

Attach a session token to scope requests to a specific user:

buildspace.setSession(sessionToken);

// All subsequent requests carry the session
const session = await buildspace.auth.getSession(sessionToken);

// Sign out and clear the SDK's stored session
await buildspace.auth.signOut();

Error handling

All errors throw a BuildspaceError:

import { BuildspaceError } from "@buildspacestudio/sdk";

try {
  await buildspace.auth.getSession(token);
} catch (err) {
  if (err instanceof BuildspaceError) {
    console.error(err.service, err.code, err.status, err.message);
  }
}

Configuration

Both new Buildspace() and createClient() accept an optional config object:

const buildspace = new Buildspace(secretKey, {
  baseUrl: "https://api.buildspace.studio", // default
  loginUrl: "https://login.buildspace.studio", // default
  version: "2025-06-01", // API version
  fetch: customFetch, // inject a custom fetch implementation
});

TypeScript

The SDK is written in TypeScript and ships full type definitions. No @types package needed.

License

MIT