@bettercms-ai/sdk 1.6.0

package/README.md

@@ -0,0 +1,126 @@
+# @bettercms-ai/sdk
+
+Typed JavaScript/TypeScript client for the BetterCMS Delivery API.
+
+## Installation
+
+```bash
+npm install @bettercms-ai/sdk
+# or
+pnpm add @bettercms-ai/sdk
+# or
+yarn add @bettercms-ai/sdk
+```
+
+## Quick start
+
+```ts
+import { BetterCMS } from "@bettercms-ai/sdk";
+
+const client = BetterCMS.site({ workspace: "my-workspace" });
+
+// Fetch a single page
+const page = await client.getContent("home");
+console.log(page.entry.title);
+
+// List pages (paginated)
+const result = await client.listContent({ page: 1, perPage: 20 });
+console.log(result.items);
+console.log(`Next page? ${result.hasNextPage}`);
+
+// Iterate all pages automatically
+for await (const item of client.listContentAll()) {
+  console.log(item.entry.title);
+}
+
+// Collect with a limit
+const top = await client.listContentAll().all({ limit: 500 });
+```
+
+## With an API key
+
+```ts
+const client = BetterCMS.site({
+  workspace: "my-workspace",
+  apiKey: process.env.BETTERCMS_API_KEY,
+});
+```
+
+## TypeScript
+
+This package is written in TypeScript and ships its own type declarations. No separate `@types/` package needed. All types from `@bettercms-ai/types` are re-exported.
+
+## Error handling
+
+The SDK throws `BetterCMSError` on failures. Each error has a semantic `code`:
+
+```ts
+import { BetterCMSError, ErrorCodes } from "@bettercms-ai/sdk";
+
+try {
+  const page = await client.getContent("does-not-exist");
+} catch (err) {
+  if (err instanceof BetterCMSError) {
+    switch (err.code) {
+      case ErrorCodes.CONTENT_NOT_FOUND:
+        // 404
+        break;
+      case ErrorCodes.UNAUTHORIZED:
+        // 401
+        break;
+      case ErrorCodes.FORBIDDEN:
+        // 403
+        break;
+      case ErrorCodes.RATE_LIMITED:
+        // 429
+        break;
+      case ErrorCodes.INTERNAL_ERROR:
+        // 5xx
+        break;
+      case ErrorCodes.NETWORK_ERROR:
+        // Network failure
+        break;
+    }
+  }
+}
+```
+
+## API
+
+### `BetterCMS.site(options)`
+
+| Option    | Type   | Required | Default                    |
+| --------- | ------ | -------- | -------------------------- |
+| `workspace` | `string` | Yes      | —                          |
+| `apiKey`  | `string` | No       | —                          |
+| `baseUrl` | `string` | No       | `https://api.bettercms.ai/v1` |
+
+Returns a `BetterCMSDeliveryClient` instance.
+
+### `client.getContent(slug)`
+
+Fetches a single published page by slug.
+
+```ts
+const content = await client.getContent("about-us");
+```
+
+### `client.listContent(options?)`
+
+Returns a paginated result object.
+
+```ts
+const result = await client.listContent({ page: 1, perPage: 20 });
+// result.items, result.hasNextPage, result.totalPages, ...
+```
+
+### `client.listContentAll(options?)`
+
+Returns an async iterator that transparently follows pagination.
+
+```ts
+for await (const item of client.listContentAll()) { ... }
+
+// With a limit:
+const items = await client.listContentAll().all({ limit: 100 });
+```