@buildbase/sdk 0.0.70 → 0.0.73

package/docs/SERVER-CONTENT.md

@@ -0,0 +1,297 @@
+# Content from your server
+
+Blogs, docs, FAQs, testimonials, rich content and collection data are read
+with an **org API token**. That token is your organization's key, so these
+reads happen on your server or at build time, never in a browser.
+
+`@buildbase/sdk/server` does the reading, caches it, and keeps the cache
+honest when content changes. It works on any JavaScript server runtime, and
+the HTTP rules underneath work from any language.
+
+- [Pick a pattern](#pick-a-pattern)
+- [Server client](#server-client)
+- [Caching](#caching)
+- [Content webhooks](#content-webhooks)
+- [Build-time pull](#build-time-pull)
+- [Next.js](#nextjs)
+- [Other languages](#other-languages)
+- [Reference](#reference)
+
+## Pick a pattern
+
+| Your app                                                              | Use                                                                                  |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Has a server (Express, Fastify, NestJS, Hono, Remix, Astro SSR, Next) | [Server client](#server-client) with the [webhook](#content-webhooks)                |
+| Static site, single-page app, or no backend                           | [Build-time pull](#build-time-pull), rebuilt by a deploy hook when content changes   |
+| Not JavaScript (Python, Go, PHP, Ruby, Java)                          | [The HTTP API directly](#other-languages), with `If-None-Match` and the same webhook |
+
+Whichever you pick, a page render should not call BuildBase. Fetch once, cache,
+and let a webhook tell you when to fetch again. Reads that ignore caching
+count against your plan's content-read allowance.
+
+## Server client
+
+```ts
+import { createServerClient } from '@buildbase/sdk/server';
+
+export const content = createServerClient({
+  serverUrl: 'https://api.console.buildbase.app',
+  apiToken: process.env.BUILDBASE_API_TOKEN!, // <orgId>:<secret>
+});
+
+const posts = await content.blogs.list({ limit: 20, sort: { publishedAt: -1 } });
+const post = await content.blogs.byPath('guides/getting-started');
+const refund = await content.richContent.get('refund-policy');
+const questions = await content.faqs.questions('help-center');
+const quotes = await content.testimonials.list();
+const releases = await content.collections.data<{ title: string; version: string }>(
+  'release-notes'
+);
+```
+
+Create the token in the console under **Settings, API tokens**. Give it the
+read-only **content-reader** role: a token that can render a blog should not
+be able to change your billing.
+
+The client refuses to run in a browser. Bundlers building for the browser
+resolve `@buildbase/sdk/server` to a module that throws at load, so a stray
+import fails the build loudly instead of shipping your token.
+
+Runtimes: Node 18+, Bun, Deno, Cloudflare Workers, Vercel and Netlify edge.
+It uses only the standard `fetch`, `Request` and `Response`.
+
+### Express, Fastify, NestJS
+
+```ts
+import express from 'express';
+import { createContentWebhookHandler, toNodeHandler } from '@buildbase/sdk/server';
+import { content } from './content';
+
+const app = express();
+
+app.get('/blog/:slug', async (req, res) => {
+  const post = await content.blogs.byPath(req.params.slug);
+  if (!post) return res.status(404).send('Not found');
+  res.render('post', { post });
+});
+
+// A raw body: the signature covers the exact bytes BuildBase sent.
+app.post(
+  '/webhooks/buildbase',
+  express.raw({ type: 'application/json' }),
+  toNodeHandler(
+    createContentWebhookHandler({
+      secret: process.env.BUILDBASE_WEBHOOK_SECRET!,
+      cache: content.cache,
+    })
+  )
+);
+```
+
+Fastify and NestJS take the same `toNodeHandler(...)`; give the route a raw
+body (a content-type parser that keeps the payload as a string or Buffer).
+
+### Hono, Cloudflare Workers, Deno, Bun
+
+```ts
+import { Hono } from 'hono';
+import { createServerClient, handleContentWebhook, kvCache } from '@buildbase/sdk/server';
+
+type Env = { BUILDBASE_API_TOKEN: string; BUILDBASE_WEBHOOK_SECRET: string; CONTENT: KVNamespace };
+
+const app = new Hono<{ Bindings: Env }>();
+const client = (env: Env) =>
+  createServerClient({
+    serverUrl: 'https://api.console.buildbase.app',
+    apiToken: env.BUILDBASE_API_TOKEN,
+    cache: kvCache(env.CONTENT), // shared across isolates
+  });
+
+app.get('/faq', async c => c.json(await client(c.env).faqs.questions('help-center')));
+
+app.post('/webhooks/buildbase', c =>
+  handleContentWebhook(c.req.raw, {
+    secret: c.env.BUILDBASE_WEBHOOK_SECRET,
+    cache: client(c.env).cache,
+  })
+);
+
+export default app;
+```
+
+## Caching
+
+Every read is cached. While an entry is fresh, a read costs nothing. Once it
+is stale, the client asks BuildBase with `If-None-Match`; if nothing changed
+the answer is an empty `304`, served from BuildBase's own cache without
+touching its database.
+
+| Option              | Default         | Meaning                                                                                   |
+| ------------------- | --------------- | ----------------------------------------------------------------------------------------- |
+| `cache`             | `memoryCache()` | Where entries live. `false` turns caching off.                                            |
+| `defaultTtlSeconds` | `60`            | Freshness when the response carries no `Cache-Control: max-age`.                          |
+| `retainSeconds`     | `86400`         | How long a stale entry is kept, for revalidation and the error fallback.                  |
+| `staleOnError`      | `true`          | Serve the last good copy if BuildBase errors or is unreachable. 401 and 403 always throw. |
+| `timeoutMs`         | `10000`         | Per request.                                                                              |
+
+Stores:
+
+- `memoryCache({ maxEntries })`: per process. Fine for one server.
+- `redisCache(client, { prefix })`: shared. ioredis and node-redis v4+ both work.
+- `kvCache(binding, { prefix })`: Cloudflare Workers KV, or Upstash Redis REST.
+- Your own: implement `CacheStore` (`get`, `set`, `delete`, `deleteByTag`).
+
+Identical reads that arrive at the same time share one request.
+
+BuildBase answers content reads with
+`Cache-Control: private, max-age=60, stale-while-revalidate=300`. The client
+honours both numbers: an entry is fresh for 60 seconds, and for the five
+minutes after that a read gets the cached copy at once while one background
+request revalidates it. Only past both does a read wait for BuildBase.
+`private` does not stop the client caching; it tells shared proxies and CDNs
+not to store a response that was fetched with your token, and this cache lives
+on your own server.
+
+### Tags
+
+Each cached read carries tags, and `content.revalidate(tag)` drops everything
+under one. The same strings appear in content webhooks:
+
+| Tag                           | Covers                                    |
+| ----------------------------- | ----------------------------------------- |
+| `buildbase:blog`              | every blog list                           |
+| `buildbase:blog:<slug>`       | one post, by slug (same for every module) |
+| `buildbase:blog:id:<id>`      | one post, by id                           |
+| `buildbase:collection:<slug>` | every record of one collection            |
+| `buildbase:all`               | everything this client cached             |
+
+Modules: `blog`, `doc`, `faq`, `faq_collection`, `testimonial`,
+`rich_content`, `collection`. `contentTags.*` builds them, and
+`getContentTags(result)` tells you which tags a result was stored under.
+
+## Content webhooks
+
+In the console, under **Settings, Webhooks**, add an endpoint pointing at your
+route and subscribe it to the content events (or to everything; the handler
+ignores what it does not need):
+
+`blog.published`, `blog.updated`, `blog.unpublished`, `blog.deleted`, the same
+four for `doc`, `faq.updated`, `faq_collection.updated`,
+`testimonial.updated`, `testimonial.deleted`, `rich_content.updated`,
+`rich_content.deleted`, `collection.version_published`,
+`collection.record_created`, `collection.record_updated`,
+`collection.record_deleted`.
+
+`handleContentWebhook(request, { secret, cache })` verifies the signature
+(HMAC-SHA256 over `<timestamp>.<body>`, five-minute window), drops the tags the
+event names, and answers `200`. A bad signature gets `401`. Pass `revalidate`
+instead of, or as well as, `cache` to invalidate a framework's own cache, and
+`onEvent` to trigger anything else, such as a static site rebuild.
+
+## Build-time pull
+
+For sites with no server of their own: pull the content once, in CI, and ship
+it as a JSON file. The token stays in CI.
+
+```bash
+BUILDBASE_SERVER_URL=https://api.console.buildbase.app \
+BUILDBASE_API_TOKEN=$BUILDBASE_API_TOKEN \
+npx buildbase content pull --out src/content/buildbase.json
+```
+
+| Flag                    | Default                                                |
+| ----------------------- | ------------------------------------------------------ |
+| `--out <file>`          | required                                               |
+| `--modules <list>`      | `blogs,docs,faqs,testimonials,richContent,collections` |
+| `--collections <slugs>` | every live collection                                  |
+| `--page-size <n>`       | `100`                                                  |
+| `--server-url <url>`    | `BUILDBASE_SERVER_URL`                                 |
+
+The file is `{ generatedAt, blogs, docs, faqs, testimonials, richContent, collections }`,
+with published content only. `pullContent(client, options)` does the same from
+your own build script.
+
+To rebuild when content changes, point a content webhook at a small function
+that calls your host's deploy hook, or use the console's deploy hooks
+(**Settings, Deployments**).
+
+## Next.js
+
+Next.js has its own data cache, keyed by tags. `@buildbase/sdk/server/next`
+hands caching to it:
+
+```ts
+// lib/content.ts
+import { createServerClient } from '@buildbase/sdk/server';
+import { withNextCache } from '@buildbase/sdk/server/next';
+
+export const content = createServerClient({
+  serverUrl: process.env.BUILDBASE_SERVER_URL!,
+  apiToken: process.env.BUILDBASE_API_TOKEN!,
+  ...withNextCache({ revalidate: 300 }),
+});
+```
+
+```ts
+// app/api/webhooks/buildbase/route.ts
+import { createNextWebhookHandler } from '@buildbase/sdk/server/next';
+
+export const POST = createNextWebhookHandler({ secret: process.env.BUILDBASE_WEBHOOK_SECRET! });
+```
+
+Every read goes out with `{ next: { tags, revalidate } }`, and the webhook calls
+`revalidateTag` for what changed. `next` is an optional peer dependency; apps
+on other frameworks never load it.
+
+## Other languages
+
+The client is a convenience; the rules are HTTP.
+
+- Send the token as `Authorization: Bearer <orgId>:<secret>` from your server.
+- Reads answer with `ETag` and `Cache-Control`. Store the body and the ETag;
+  send `If-None-Match: <etag>` next time and a `304` means your copy is current.
+- `filter` and `sort` are bracket-encoded: `?filter[published]=true&sort[publishedAt]=-1&$limit=20`.
+- Verify webhooks: `hex(HMAC-SHA256(secret, timestamp + "." + rawBody))` must
+  equal the part after `sha256=` in `x-buildbase-signature`, and
+  `x-buildbase-timestamp` must be within five minutes. Then drop `data.tags`.
+
+```bash
+curl -s -D - -H "Authorization: Bearer $BUILDBASE_API_TOKEN" \
+  "https://api.console.buildbase.app/api/rich-content/slug/refund-policy"
+```
+
+```python
+import hmac, hashlib, time
+
+def verify(secret: str, body: bytes, signature: str, timestamp: str) -> bool:
+    if abs(time.time() - int(timestamp)) > 300:
+        return False
+    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest("sha256=" + expected, signature)
+```
+
+## Reference
+
+| Call                                                       | Endpoint                                                      | Returns                                          |
+| ---------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------ |
+| `blogs.list({ page, limit, filter, sort, includeDrafts })` | `GET /api/blogs`                                              | `Paginated<BlogPost>`, published only by default |
+| `blogs.get(id)`                                            | `GET /api/blogs/:id`                                          | `BlogPost \| null`                               |
+| `blogs.byPath(path, { draftPreview })`                     | `GET /api/blogs/path?path=`                                   | `BlogPost \| null`                               |
+| `blogs.tree({ folder })`                                   | `GET /api/blogs/folders/tree`                                 | folder tree                                      |
+| `blogs.tags()`, `blogs.authors()`                          | `GET /api/blogs/tags`, `/authors`                             | `Paginated<...>`                                 |
+| `docs.*`                                                   | the same under `/api/docs`                                    | `DocPage`                                        |
+| `faqs.collections()`                                       | `GET /api/faqs/collections`                                   | `Paginated<FaqCollection>`                       |
+| `faqs.collection(slugOrId)`                                | `GET /api/faqs/collections/slug/:slug` or `/:id`              | `FaqCollection \| null`                          |
+| `faqs.questions(slugOrId)`                                 | `GET /api/faqs/collections/slug/:slug/faqs` or `/:id/faqs`    | `Faq[]`, `[]` when the collection does not exist |
+| `testimonials.list({ includeUnpublished })`                | `GET /api/testimonials`                                       | published only by default                        |
+| `testimonials.get(id)`                                     | `GET /api/testimonials/:id`                                   | `Testimonial \| null`                            |
+| `richContent.get(slug)`, `.list()`                         | `GET /api/rich-content/slug/:slug`                            | `RichContent \| null`                            |
+| `collections.data(slug, { version })`, `.list()`           | `GET /api/collections/data/:slug?latest=true`, or `?version=` | `CollectionRecord[]`                             |
+| `revalidate(tag)`, `revalidateAll()`                       |                                                               | drops cached reads                               |
+
+The slug routes for FAQ collections, `GET /api/testimonials/:id` and
+collection data without a `version` need the BuildBase server release that
+ships content delivery; an older server answers those with 404 or 400. The
+rest of the table works on any server.
+
+Errors are `BuildBaseContentError` with `status`, `url` and the response `body`.

package/docs/UI-CONFIG.md

@@ -59,6 +59,7 @@ Fine-grained switches inside each settings screen. All default to `true`.
 | `settings.users.roleChange`           | Per-member role selector                                                 |
 | `settings.users.remove`               | Remove-member button                                                     |
 | `settings.users.seatPricing`          | Seat usage card + extra-seat cost warnings                               |
+| `settings.users.invitations`          | Pending-invitations list (with Resend and Revoke) under the invite form  |
 | `settings.subscription.changePlan`    | Every plan-picker entry point (change plan, view plans, upgrade banners) |
 | `settings.subscription.cancel`        | Cancel-subscription button (Resume stays available)                      |
 | `settings.subscription.managePayment` | Stripe billing-portal button                                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildbase/sdk",
-  "version": "0.0.70",
+  "version": "0.0.73",
   "type": "module",
   "description": "A SDK for Buildbase",
   "main": "dist/index.cjs",
@@ -37,12 +37,57 @@
       "require": "./dist/mcp/index.cjs",
       "default": "./dist/mcp/index.cjs"
     },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "workerd": "./dist/server/index.mjs",
+      "worker": "./dist/server/index.mjs",
+      "edge-light": "./dist/server/index.mjs",
+      "deno": "./dist/server/index.mjs",
+      "bun": "./dist/server/index.mjs",
+      "react-server": {
+        "import": "./dist/server/index.mjs",
+        "require": "./dist/server/index.cjs"
+      },
+      "node": {
+        "import": "./dist/server/index.mjs",
+        "require": "./dist/server/index.cjs"
+      },
+      "browser": {
+        "import": "./dist/server/browser.mjs",
+        "require": "./dist/server/browser.cjs"
+      },
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.cjs",
+      "default": "./dist/server/index.cjs"
+    },
+    "./server/next": {
+      "types": "./dist/server/next/index.d.ts",
+      "edge-light": "./dist/server/next/index.mjs",
+      "react-server": {
+        "import": "./dist/server/next/index.mjs",
+        "require": "./dist/server/next/index.cjs"
+      },
+      "node": {
+        "import": "./dist/server/next/index.mjs",
+        "require": "./dist/server/next/index.cjs"
+      },
+      "browser": {
+        "import": "./dist/server/browser.mjs",
+        "require": "./dist/server/browser.cjs"
+      },
+      "import": "./dist/server/next/index.mjs",
+      "require": "./dist/server/next/index.cjs",
+      "default": "./dist/server/next/index.cjs"
+    },
     "./css": {
       "types": "./dist/css/styles.d.ts",
       "default": "./dist/css/styles.css"
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "buildbase": "dist/cli.mjs"
+  },
   "typesVersions": {
     "*": {
       "react": [
@@ -59,6 +104,12 @@
       ],
       "tracking": [
         "./dist/tracking/index.d.ts"
+      ],
+      "server": [
+        "./dist/server/index.d.ts"
+      ],
+      "server/next": [
+        "./dist/server/next/index.d.ts"
       ]
     }
   },
@@ -71,14 +122,17 @@
     "docs/ERROR_CODES.md",
     "docs/MCP-AND-AGENT-READINESS.md",
     "docs/THEMING.md",
-    "docs/UI-CONFIG.md"
+    "docs/UI-CONFIG.md",
+    "docs/SERVER-CONTENT.md"
   ],
   "sideEffects": [
-    "**/*.css"
+    "**/*.css",
+    "./dist/server/browser.mjs",
+    "./dist/server/browser.cjs"
   ],
   "scripts": {
     "build": "rollup -c && rollup -c rollup.dts.config.js && npm run postbuild",
-    "postbuild": "rimraf dist/types dist/react/types dist/data/types dist/mcp/types dist/tracking/types dist/*.map dist/react/*.map dist/data/*.map dist/mcp/*.map dist/tracking/*.map && mkdir -p dist/css && [ -f dist/react/styles.css ] && mv dist/react/styles.css dist/css/styles.css || true && cp src/css.d.ts dist/css/styles.d.ts",
+    "postbuild": "rimraf dist/types dist/react/types dist/data/types dist/mcp/types dist/tracking/types dist/server/types dist/server/next/types dist/server/browser-types dist/cli-types dist/*.map dist/react/*.map dist/data/*.map dist/mcp/*.map dist/tracking/*.map dist/server/*.map dist/server/next/*.map && mkdir -p dist/css && [ -f dist/react/styles.css ] && mv dist/react/styles.css dist/css/styles.css || true && cp src/css.d.ts dist/css/styles.d.ts",
     "build:analyze": "rollup --config rollup.config.analyze.js",
     "dev": "rollup -c -w",
     "clean": "rimraf dist",
@@ -103,7 +157,13 @@
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "next": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@hookform/resolvers": "^5.0.1",
@@ -126,6 +186,7 @@
     "intl-messageformat": "^11.2.0",
     "lucide-react": ">=0.544.0 <1",
     "react-hook-form": "^7.60.0",
+    "socket.io-client": "^4.8.3",
     "tailwind-merge": "^3.3.1",
     "zod": "^4.3.6"
   },