Marble SDK

The official TypeScript SDK for Marble CMS.
Provides a strongly typed client, pagination helpers, retry/backoff, and webhook verification utilities.

---

✨ Features

• 📦 @usemarble/core – base SDK package with:
  • MarbleClient – typed API client for posts, tags, categories, authors
  • Runtime validation with Zod
  • Pagination helpers (iteratePostPages, paginatePosts, etc.)
  • Retry & backoff with exponential jitter
  • Webhook verification with HMAC + timestamp tolerance
• 🧪 Unit tests powered by Vitest
• 📚 API docs via TypeDoc

---

📂 Project Structure

sdk/
├─ packages/
│  ├─ core/          # @usemarble/core SDK
│  │  ├─ src/        # implementation
│  │  ├─ tests/      # vitest unit tests
│  │  ├─ docs/       # docs generated by typedoc
│  │  └─ dist/       # build output
│  ├─ react/         # (planned) React adapter
│  ├─ next/          # (planned) Next.js adapter
│  └─ vite/          # (planned) Vite plugin
├─ typedoc.json      # docs config
├─ vitest.config.ts  # test runner config
└─ package.json      # workspace root

---

🚀 Getting Started

1. Install dependencies

pnpm install

2. Build the core SDK

pnpm --filter @usemarble/core build

3. Run tests

pnpm test

This runs Vitest across all packages.
Tests are located in packages/core/tests.

---

🧪 Example Usage

import { MarbleClient } from "@usemarble/core";

const marble = new MarbleClient({ baseUrl: "https://api.marble.io", apiKey: "sk_123", // optional });

// List posts const { posts, pagination } = await marble.listPosts({ limit: 5 }); console.log(posts.map((p) => p.title));

// Fetch a single post const { post } = await marble.getPost("hello-world"); console.log(post.title);

// Stream posts page-by-page for await (const page of marble.iteratePostPages({})) { console.log("Page", page.pagination.currentPage, "posts:", page.posts.length); }

---

🔔 Webhooks

Verify incoming Marble webhook requests:

import { verifyMarbleSignature, parseWebhookEvent } from "@usemarble/core";

const rawBody = '{"id":"evt_1","type":"post.published","createdAt":"2024-01-01T00:00:00Z","data":{"id":"123"}}';

const headers = { "x-marble-signature": "t=1690000000,v1=abc123...", "x-marble-timestamp": "1690000000", };

verifyMarbleSignature(rawBody, headers, "whsec_123");

const evt = parseWebhookEvent<{ id: string }>(rawBody, (d) => d as { id: string }); console.log(evt.type, evt.data.id);

---

📖 Documentation

To generate API reference docs (HTML): pnpm typedoc

The docs output will be in docs/.

---

🛠️ Development Notes

• Uses pnpm workspaces for monorepo management.
• Tests run with Vitest (vitest.config.ts in root).
• Future adapters: React, Next.js, Vite will be developed under packages/.