@buildspacestudio/sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,237 @@
+# @buildspacestudio/sdk
+
+The official JavaScript/TypeScript SDK for [Buildspace](https://buildspace.studio) — auth, events, storage, and notifications for your app.
+
+## Installation
+
+```bash
+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
+
+```ts
+import Buildspace from "@buildspacestudio/sdk";
+
+const buildspace = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);
+```
+
+### Client SDK
+
+```ts
+import { createClient } from "@buildspacestudio/sdk/client";
+
+const buildspace = createClient(process.env.NEXT_PUBLIC_BUILDSPACE_KEY!);
+```
+
+---
+
+## Auth
+
+### Server — handle OAuth callback
+
+```ts
+// 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
+}
+
+// Revoke a session (sign out)
+await buildspace.auth.revokeSession(sessionToken);
+```
+
+### Client — generate sign-in / sign-up URLs
+
+```ts
+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
+
+```ts
+// 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)
+
+```ts
+// 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:
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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.**
+
+```ts
+// Send a custom email
+await buildspace.notifications.send({
+  to: "user@example.com",
+  subject: "Welcome to Buildspace",
+  html: "<h1>You're in!</h1>",
+  text: "You're in!", // optional plain-text fallback
+  replyTo: "support@yourapp.com",
+});
+
+// Send from a saved template
+await buildspace.notifications.sendTemplate("welcome-email", {
+  to: "user@example.com",
+  variables: { firstName: "Alex", plan: "Pro" },
+});
+```
+
+---
+
+## Sessions
+
+Attach a session token to scope requests to a specific user:
+
+```ts
+buildspace.setSession(sessionToken);
+
+// All subsequent requests carry the session
+const session = await buildspace.auth.getSession(sessionToken);
+
+// Clear when done
+buildspace.clearSession();
+```
+
+---
+
+## Error handling
+
+All errors throw a `BuildspaceError`:
+
+```ts
+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:
+
+```ts
+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

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@buildspacestudio/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
@@ -42,6 +43,6 @@
   },
   "devDependencies": {
     "typescript": "^5",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }