@better-i18n/sdk 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,126 @@
+# @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({
+  project: "acme/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 |
+| --- | --- | --- |
+| `project` | Yes | Project identifier in `org/project` format (e.g., `"acme/web-app"`) |
+| `apiKey` | Yes | API key from [dashboard](https://dash.better-i18n.com) |
+| `apiBase` | No | API base URL (default: `https://dash.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,6 +1,6 @@
 {
   "name": "@better-i18n/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Content SDK for Better i18n - headless CMS client for fetching content models and entries",
   "type": "module",
   "main": "src/index.ts",

package/src/client.ts

@@ -1,7 +1,7 @@
 import type { ClientConfig, ContentClient } from "./types";
 import { createContentAPIClient } from "./content-api";
 
-const DEFAULT_API_BASE = "https://api.better-i18n.com";
+const DEFAULT_API_BASE = "https://dash.better-i18n.com";
 
 /**
  * Creates a Better i18n content client.
@@ -12,8 +12,7 @@ const DEFAULT_API_BASE = "https://api.better-i18n.com";
  * @example
  * ```typescript
  * const client = createClient({
- *   org: "acme",
- *   project: "web-app",
+ *   project: "acme/web-app",
  *   apiKey: "bi18n_...",
  * });
  *
@@ -23,16 +22,23 @@ const DEFAULT_API_BASE = "https://api.better-i18n.com";
  * ```
  */
 export function createClient(config: ClientConfig): ContentClient {
-  const { org, project } = config;
   const apiBase = (config.apiBase || DEFAULT_API_BASE).replace(/\/$/, "");
 
+  const parts = config.project.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(
+      `Invalid project format "${config.project}". Expected "org/project" (e.g., "acme/web-app").`,
+    );
+  }
+  const [org, project] = parts;
+
   if (!config.apiKey) {
     throw new Error(
       "API key is required for content API access.\n" +
         "Set apiKey in your client config:\n\n" +
-        '  createClient({ org: "...", project: "...", apiKey: "bi18n_..." })',
+        '  createClient({ project: "acme/web-app", apiKey: "bi18n_..." })',
     );
   }
 
-  return createContentAPIClient(apiBase, org, project, config.apiKey);
+  return createContentAPIClient(apiBase, org, project, config.apiKey, config.debug);
 }

package/src/content-api.ts

@@ -5,6 +5,7 @@ import type {
   ContentModel,
   ListEntriesOptions,
   GetEntryOptions,
+  PaginatedResponse,
 } from "./types";
 
 /**
@@ -23,6 +24,7 @@ export function createContentAPIClient(
   org: string,
   project: string,
   apiKey: string,
+  debug = false,
 ): ContentClient {
   const base = `${apiBase}/api/v1/content/${org}/${project}`;
   const headers: Record<string, string> = {
@@ -30,58 +32,72 @@ export function createContentAPIClient(
     "content-type": "application/json",
   };
 
+  const log = debug
+    ? (...args: unknown[]) => console.log("[better-i18n]", ...args)
+    : () => {};
+
+  if (debug) {
+    log("Client initialized", { apiBase, org, project, base });
+  }
+
+  async function request<T>(url: string, label: string): Promise<{ res: Response; data: T }> {
+    log(`→ ${label}`, url);
+    const res = await fetch(url, { headers });
+    log(`← ${res.status} ${res.statusText}`);
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      log("  Error body:", body);
+      throw new Error(`API error ${label}: ${res.status} ${body}`);
+    }
+    const data = await res.json() as T;
+    log("  Response:", JSON.stringify(data).slice(0, 500));
+    return { res, data };
+  }
+
   return {
     async getModels(): Promise<ContentModel[]> {
-      const res = await fetch(`${base}/models`, { headers });
-      if (!res.ok) {
-        throw new Error(`API error fetching models: ${res.status}`);
-      }
-      return res.json();
+      const { data } = await request<ContentModel[]>(`${base}/models`, "getModels");
+      return data;
     },
 
     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}` : "";
 
-      const res = await fetch(
+      const { data } = await request<{ items: ContentEntryListItem[]; total: number; hasMore: boolean }>(
         `${base}/models/${modelSlug}/entries${qs}`,
-        { headers },
+        `getEntries(${modelSlug})`,
       );
-      if (!res.ok) {
-        throw new Error(
-          `API error fetching entries for ${modelSlug}: ${res.status}`,
-        );
-      }
-      const data: { items?: ContentEntryListItem[] } | ContentEntryListItem[] =
-        await res.json();
-      return Array.isArray(data) ? data : (data.items ?? []);
+      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}` : "";
 
-      const res = await fetch(
+      const { data } = await request<ContentEntry<CF>>(
         `${base}/models/${modelSlug}/entries/${entrySlug}${qs}`,
-        { headers },
+        `getEntry(${modelSlug}/${entrySlug})`,
       );
-      if (!res.ok) {
-        throw new Error(
-          `API error fetching entry ${modelSlug}/${entrySlug}: ${res.status}`,
-        );
-      }
-      return res.json();
+      return data;
     },
   };
 }

package/src/index.ts

@@ -5,7 +5,10 @@ export type {
   ContentClient,
   ContentEntry,
   ContentEntryListItem,
+  ContentEntryStatus,
+  ContentEntrySortField,
   ContentModel,
   ListEntriesOptions,
   GetEntryOptions,
+  PaginatedResponse,
 } from "./types";

package/src/types.ts

@@ -2,40 +2,56 @@
 
 /** Configuration for creating a Better i18n content client. */
 export interface ClientConfig {
-  /** Organization slug (e.g., "acme-corp"). */
-  org: string;
-  /** Project slug (e.g., "web-app"). */
+  /** Project identifier in `org/project` format (e.g., "acme-corp/web-app"). Same as the dashboard URL path. */
   project: string;
   /** API key for authenticating content requests. Required. */
   apiKey: string;
-  /** REST API base URL. Defaults to `https://api.better-i18n.com`. */
+  /** REST API base URL. Defaults to `https://dash.better-i18n.com`. */
   apiBase?: string;
+  /** Enable debug logging to see request URLs, headers, and responses. */
+  debug?: boolean;
 }
 
 // ─── 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;
-  body: unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  body: Record<string, any> | null;
   bodyHtml: string | null;
   bodyMarkdown: string | null;
   metaTitle: string | null;
   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;
@@ -47,6 +63,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,13 +81,22 @@ export interface ContentModel {
 
 // ─── Client Interface ───────────────────────────────────────────────
 
+/** 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 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;
 }
 
@@ -78,15 +110,15 @@ export interface GetEntryOptions {
 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>;
+  ): Promise<ContentEntry<CF>>;
 }