@better-i18n/sdk 0.1.1 → 0.3.0

package/README.md

@@ -0,0 +1,128 @@
+# @better-i18n/sdk
+
+Content SDK for [Better i18n](https://better-i18n.com). A lightweight, typed client for fetching content models and entries from the headless CMS.
+
+## Features
+
+- 📦 **Zero Dependencies** — Runs anywhere with `fetch()`
+- 🔒 **Type-Safe** — Full TypeScript types with generic custom fields
+- 🌍 **Language-Aware** — Fetch localized content by language code
+- 📄 **Pagination Built-in** — Paginated listing with total count and `hasMore`
+- 🔍 **Filtering & Sorting** — Filter by status, sort by date or title
+- ⚡ **Lightweight** — Thin wrapper over REST API
+
+## Installation
+
+```bash
+npm install @better-i18n/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "@better-i18n/sdk";
+
+const client = createClient({
+  org: "acme",
+  project: "web-app",
+  apiKey: process.env.BETTER_I18N_API_KEY!,
+});
+
+// List content models
+const models = await client.getModels();
+
+// List published blog posts
+const { items, total, hasMore } = await client.getEntries("blog-posts", {
+  status: "published",
+  sort: "publishedAt",
+  order: "desc",
+  language: "en",
+  limit: 10,
+});
+
+// Get a single entry with localized content
+const post = await client.getEntry("blog-posts", "hello-world", {
+  language: "fr",
+});
+console.log(post.title, post.bodyMarkdown);
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `getModels()` | List all content models with entry counts |
+| `getEntries(modelSlug, options?)` | Paginated list of entries for a model |
+| `getEntry(modelSlug, entrySlug, options?)` | Full content entry with all fields |
+
+### `getEntries` Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `language` | `string` | source language | Language code for localized content |
+| `status` | `"draft" \| "published" \| "archived"` | all | Filter by entry status |
+| `sort` | `"publishedAt" \| "createdAt" \| "updatedAt" \| "title"` | `"updatedAt"` | Sort field |
+| `order` | `"asc" \| "desc"` | `"desc"` | Sort direction |
+| `page` | `number` | `1` | Page number (1-based) |
+| `limit` | `number` | `50` | Entries per page (1-100) |
+
+### `getEntry` Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `language` | `string` | source language | Language code for localized content |
+
+### Response Types
+
+**`getEntries` returns `PaginatedResponse<ContentEntryListItem>`:**
+
+```typescript
+{
+  items: ContentEntryListItem[]; // slug, title, excerpt, publishedAt, tags, author
+  total: number;                 // total matching entries
+  hasMore: boolean;              // more pages available
+}
+```
+
+**`getEntry` returns `ContentEntry<CF>`:**
+
+```typescript
+{
+  id, slug, status, publishedAt, sourceLanguage, availableLanguages,
+  featuredImage, tags, author, customFields,
+  title, excerpt, body, bodyHtml, bodyMarkdown,
+  metaTitle, metaDescription
+}
+```
+
+## Typed Custom Fields
+
+Use the generic type parameter for type-safe custom fields:
+
+```typescript
+interface BlogFields {
+  readingTime: string | null;
+  category: string | null;
+}
+
+const post = await client.getEntry<BlogFields>("blog-posts", "hello-world");
+post.customFields.readingTime; // string | null (typed!)
+post.customFields.category;   // string | null (typed!)
+```
+
+## Configuration
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `org` | Yes | Organization slug |
+| `project` | Yes | Project slug |
+| `apiKey` | Yes | API key from [dashboard](https://dash.better-i18n.com) |
+| `apiBase` | No | API base URL (default: `https://api.better-i18n.com`) |
+
+## Documentation
+
+Full documentation at [docs.better-i18n.com/sdk](https://docs.better-i18n.com/sdk)
+
+## License
+
+MIT © [Better i18n](https://better-i18n.com)

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "@better-i18n/sdk",
-  "version": "0.1.1",
-  "description": "SDK for fetching content and translations from Better i18n",
+  "version": "0.3.0",
+  "description": "Content SDK for Better i18n - headless CMS client for fetching content models and entries",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./content": "./src/content.ts",
-    "./translations": "./src/translations.ts"
+    ".": "./src/index.ts"
   },
   "files": [
     "src",
@@ -18,11 +16,11 @@
     "typecheck": "tsc --noEmit"
   },
   "keywords": [
-    "i18n",
-    "translations",
     "content",
     "sdk",
-    "headless-cms"
+    "headless-cms",
+    "better-i18n",
+    "cms"
   ],
   "devDependencies": {
     "typescript": "~5.9.3"

package/src/client.ts

@@ -1,15 +1,13 @@
-import type { ClientConfig, BetterI18nClient } from "./types";
+import type { ClientConfig, ContentClient } from "./types";
 import { createContentAPIClient } from "./content-api";
-import { createTranslationsCDNClient } from "./translations-cdn";
 
-const DEFAULT_CDN_BASE = "https://cdn.better-i18n.com";
 const DEFAULT_API_BASE = "https://api.better-i18n.com";
 
 /**
- * Creates a Better i18n client with content and translation sub-clients.
+ * Creates a Better i18n content client.
  *
- * Content is always fetched from the REST API and requires an API key.
- * Translations are served from the CDN for performance (no API key needed).
+ * Fetches content models and entries from the REST API.
+ * Requires an API key for authentication.
  *
  * @example
  * ```typescript
@@ -19,31 +17,22 @@ const DEFAULT_API_BASE = "https://api.better-i18n.com";
  *   apiKey: "bi18n_...",
  * });
  *
- * // Content (API mode, requires apiKey)
- * const posts = await client.content.getEntries("blog-posts", { language: "fr" });
- * const post = await client.content.getEntry("blog-posts", "hello-world");
- * const models = await client.content.getModels();
- *
- * // Translations (CDN mode, no API key needed)
- * const strings = await client.translations.get("common", { language: "fr" });
+ * const models = await client.getModels();
+ * const posts = await client.getEntries("blog-posts", { language: "fr" });
+ * const post = await client.getEntry("blog-posts", "hello-world");
  * ```
  */
-export function createClient(config: ClientConfig): BetterI18nClient {
+export function createClient(config: ClientConfig): ContentClient {
   const { org, project } = config;
-  const cdnBase = (config.cdnBase || DEFAULT_CDN_BASE).replace(/\/$/, "");
   const apiBase = (config.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
 
   if (!config.apiKey) {
     throw new Error(
-      "API key is required. Content is served via the REST API.\n" +
+      "API key is required for content API access.\n" +
         "Set apiKey in your client config:\n\n" +
         '  createClient({ org: "...", project: "...", apiKey: "bi18n_..." })',
     );
   }
 
-  return {
-    content: createContentAPIClient(apiBase, org, project, config.apiKey),
-    // Translations always served from CDN for performance
-    translations: createTranslationsCDNClient(cdnBase, org, project),
-  };
+  return createContentAPIClient(apiBase, org, project, config.apiKey);
 }

package/src/content-api.ts

@@ -5,6 +5,7 @@ import type {
   ContentModel,
   ListEntriesOptions,
   GetEntryOptions,
+  PaginatedResponse,
 } from "./types";
 
 /**
@@ -42,9 +43,12 @@ export function createContentAPIClient(
     async getEntries(
       modelSlug: string,
       options?: ListEntriesOptions,
-    ): Promise<ContentEntryListItem[]> {
+    ): Promise<PaginatedResponse<ContentEntryListItem>> {
       const params = new URLSearchParams();
       if (options?.language) params.set("language", options.language);
+      if (options?.status) params.set("status", options.status);
+      if (options?.sort) params.set("sort", options.sort);
+      if (options?.order) params.set("order", options.order);
       if (options?.page) params.set("page", String(options.page));
       if (options?.limit) params.set("limit", String(options.limit));
       const qs = params.toString() ? `?${params}` : "";
@@ -58,16 +62,19 @@ export function createContentAPIClient(
           `API error fetching entries for ${modelSlug}: ${res.status}`,
         );
       }
-      const data: { items?: ContentEntryListItem[] } | ContentEntryListItem[] =
-        await res.json();
-      return Array.isArray(data) ? data : (data.items ?? []);
+      const data = await res.json() as { items: ContentEntryListItem[]; total: number; hasMore: boolean };
+      return {
+        items: data.items,
+        total: data.total,
+        hasMore: data.hasMore,
+      };
     },
 
-    async getEntry(
+    async getEntry<CF extends Record<string, string | null> = Record<string, string | null>>(
       modelSlug: string,
       entrySlug: string,
       options?: GetEntryOptions,
-    ): Promise<ContentEntry> {
+    ): Promise<ContentEntry<CF>> {
       const params = new URLSearchParams();
       if (options?.language) params.set("language", options.language);
       const qs = params.toString() ? `?${params}` : "";

package/src/index.ts

@@ -1,14 +1,14 @@
 export { createClient } from "./client";
+export { createContentAPIClient } from "./content-api";
 export type {
   ClientConfig,
-  BetterI18nClient,
   ContentClient,
-  TranslationsClient,
   ContentEntry,
   ContentEntryListItem,
+  ContentEntryStatus,
+  ContentEntrySortField,
   ContentModel,
-  TranslationManifest,
   ListEntriesOptions,
   GetEntryOptions,
-  GetTranslationsOptions,
+  PaginatedResponse,
 } from "./types";

package/src/types.ts

@@ -1,6 +1,6 @@
 // ─── Client Configuration ────────────────────────────────────────────
 
-/** Configuration for creating a Better i18n client. */
+/** Configuration for creating a Better i18n content client. */
 export interface ClientConfig {
   /** Organization slug (e.g., "acme-corp"). */
   org: string;
@@ -8,26 +8,36 @@ export interface ClientConfig {
   project: string;
   /** API key for authenticating content requests. Required. */
   apiKey: string;
-  /** CDN base URL for translations. Defaults to `https://cdn.better-i18n.com`. */
-  cdnBase?: string;
-  /** REST API base URL for content. Defaults to `https://api.better-i18n.com`. */
+  /** REST API base URL. Defaults to `https://api.better-i18n.com`. */
   apiBase?: string;
 }
 
 // ─── Content Types ───────────────────────────────────────────────────
 
-/** A full content entry with all localized fields. */
-export interface ContentEntry {
+/**
+ * A full content entry with all localized fields.
+ *
+ * @typeParam CF - Custom fields shape. Defaults to `Record<string, string | null>`.
+ *
+ * @example
+ * ```typescript
+ * // Typed custom fields
+ * interface BlogFields { readingTime: string | null; category: string | null }
+ * const post = await client.getEntry<BlogFields>("blog", "hello-world");
+ * post.customFields.readingTime; // string | null (typed!)
+ * ```
+ */
+export interface ContentEntry<CF extends Record<string, string | null> = Record<string, string | null>> {
   id: string;
   slug: string;
-  status: string;
+  status: "draft" | "published" | "archived";
   publishedAt: string | null;
   sourceLanguage: string;
   availableLanguages: string[];
   featuredImage: string | null;
   tags: string[];
   author: { name: string; image: string | null } | null;
-  customFields: Record<string, string | null>;
+  customFields: CF;
   // Localized content
   title: string;
   excerpt: string | null;
@@ -38,6 +48,9 @@ export interface ContentEntry {
   metaDescription: string | null;
 }
 
+/** Entry status filter values. */
+export type ContentEntryStatus = "draft" | "published" | "archived";
+
 /** A summary item for content entry lists. */
 export interface ContentEntryListItem {
   slug: string;
@@ -49,6 +62,13 @@ export interface ContentEntryListItem {
   author: { name: string; image: string | null } | null;
 }
 
+/** Paginated response wrapper. */
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  hasMore: boolean;
+}
+
 /** A content model definition. */
 export interface ContentModel {
   slug: string;
@@ -58,43 +78,30 @@ export interface ContentModel {
   entryCount: number;
 }
 
-// ─── Translation Types ───────────────────────────────────────────────
+// ─── Client Interface ───────────────────────────────────────────────
 
-/** Manifest describing project languages and translation coverage. */
-export interface TranslationManifest {
-  projectSlug: string;
-  sourceLanguage: string;
-  languages: Array<{
-    code: string;
-    name: string;
-    nativeName: string;
-    isSource: boolean;
-    keyCount: number;
-  }>;
-  updatedAt: string;
-}
-
-// ─── Client Interfaces ──────────────────────────────────────────────
+/** Sortable fields for content entries. */
+export type ContentEntrySortField = "publishedAt" | "createdAt" | "updatedAt" | "title";
 
 /** Options for listing content entries. */
 export interface ListEntriesOptions {
-  /** Language code for localized content. Defaults to `"en"`. */
+  /** Language code for localized content. Defaults to source language. */
   language?: string;
+  /** Filter by entry status. */
+  status?: ContentEntryStatus;
+  /** Field to sort by. Defaults to `"updatedAt"`. */
+  sort?: ContentEntrySortField;
+  /** Sort direction. Defaults to `"desc"`. */
+  order?: "asc" | "desc";
   /** Page number (1-based). */
   page?: number;
-  /** Max entries per page. */
+  /** Max entries per page (1-100). Defaults to 50. */
   limit?: number;
 }
 
 /** Options for fetching a single content entry. */
 export interface GetEntryOptions {
-  /** Language code for localized content. Defaults to `"en"`. */
-  language?: string;
-}
-
-/** Options for fetching translations. */
-export interface GetTranslationsOptions {
-  /** Language code. Defaults to `"en"`. */
+  /** Language code for localized content. Defaults to source language. */
   language?: string;
 }
 
@@ -102,34 +109,15 @@ export interface GetTranslationsOptions {
 export interface ContentClient {
   /** List all content models in the project. */
   getModels(): Promise<ContentModel[]>;
-  /** List entries for a content model. */
+  /** List entries for a content model with pagination. */
   getEntries(
     modelSlug: string,
     options?: ListEntriesOptions,
-  ): Promise<ContentEntryListItem[]>;
+  ): Promise<PaginatedResponse<ContentEntryListItem>>;
   /** Fetch a single content entry by slug. */
-  getEntry(
+  getEntry<CF extends Record<string, string | null> = Record<string, string | null>>(
     modelSlug: string,
     entrySlug: string,
     options?: GetEntryOptions,
-  ): Promise<ContentEntry>;
-}
-
-/** Client for fetching translation strings. */
-export interface TranslationsClient {
-  /** Fetch translations for a namespace. */
-  get(
-    namespace: string,
-    options?: GetTranslationsOptions,
-  ): Promise<Record<string, string>>;
-  /** Fetch the project translation manifest. */
-  getManifest(): Promise<TranslationManifest>;
-}
-
-/** The unified Better i18n client. */
-export interface BetterI18nClient {
-  /** Content sub-client for headless CMS operations. */
-  content: ContentClient;
-  /** Translations sub-client for i18n string fetching. */
-  translations: TranslationsClient;
+  ): Promise<ContentEntry<CF>>;
 }

package/src/content.ts

@@ -1,9 +0,0 @@
-export { createContentAPIClient } from "./content-api";
-export type {
-  ContentClient,
-  ContentEntry,
-  ContentEntryListItem,
-  ContentModel,
-  ListEntriesOptions,
-  GetEntryOptions,
-} from "./types";

package/src/translations-cdn.ts

@@ -1,51 +0,0 @@
-import type {
-  TranslationsClient,
-  TranslationManifest,
-  GetTranslationsOptions,
-} from "./types";
-
-/**
- * Creates a translations client that fetches from the CDN.
- *
- * Translation files are pre-built JSON served from Cloudflare R2.
- * No authentication required.
- *
- * URL patterns:
- * - Namespace: `{cdnBase}/{org}/{project}/{lang}/{namespace}.json`
- * - Manifest: `{cdnBase}/{org}/{project}/manifest.json`
- */
-export function createTranslationsCDNClient(
-  cdnBase: string,
-  org: string,
-  project: string,
-): TranslationsClient {
-  const base = `${cdnBase}/${org}/${project}`;
-
-  return {
-    async get(
-      namespace: string,
-      options?: GetTranslationsOptions,
-    ): Promise<Record<string, string>> {
-      const lang = options?.language || "en";
-      const ns = namespace || "default";
-      const res = await fetch(`${base}/${lang}/${ns}.json`);
-      if (!res.ok) {
-        if (res.status === 404) return {};
-        throw new Error(
-          `Failed to fetch translations for ${ns} (${lang}): ${res.status}`,
-        );
-      }
-      return res.json();
-    },
-
-    async getManifest(): Promise<TranslationManifest> {
-      const res = await fetch(`${base}/manifest.json`);
-      if (!res.ok) {
-        throw new Error(
-          `Failed to fetch translation manifest: ${res.status}`,
-        );
-      }
-      return res.json();
-    },
-  };
-}

package/src/translations.ts

@@ -1,6 +0,0 @@
-export { createTranslationsCDNClient } from "./translations-cdn";
-export type {
-  TranslationsClient,
-  TranslationManifest,
-  GetTranslationsOptions,
-} from "./types";