@better-i18n/sdk 0.2.0 → 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,6 +1,6 @@
 {
   "name": "@better-i18n/sdk",
-  "version": "0.2.0",
+  "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",

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

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

package/src/types.ts

@@ -14,18 +14,30 @@ export interface ClientConfig {
 
 // ─── 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;
@@ -36,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;
@@ -47,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,13 +80,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 +109,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>>;
 }