@better-i18n/sdk 0.1.1

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@better-i18n/sdk",
+  "version": "0.1.1",
+  "description": "SDK for fetching content and translations from Better i18n",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./content": "./src/content.ts",
+    "./translations": "./src/translations.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "i18n",
+    "translations",
+    "content",
+    "sdk",
+    "headless-cms"
+  ],
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/client.ts

@@ -0,0 +1,49 @@
+import type { ClientConfig, BetterI18nClient } 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.
+ *
+ * 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).
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   org: "acme",
+ *   project: "web-app",
+ *   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" });
+ * ```
+ */
+export function createClient(config: ClientConfig): BetterI18nClient {
+  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" +
+        "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),
+  };
+}

package/src/content-api.ts

@@ -0,0 +1,87 @@
+import type {
+  ContentClient,
+  ContentEntry,
+  ContentEntryListItem,
+  ContentModel,
+  ListEntriesOptions,
+  GetEntryOptions,
+} from "./types";
+
+/**
+ * Creates a content client that fetches from the REST API.
+ *
+ * This mode supports filtering, pagination, and real-time data (no caching lag).
+ * Requires an API key for authentication via the `x-api-key` header.
+ *
+ * URL patterns:
+ * - Models: `{apiBase}/api/v1/content/{org}/{project}/models`
+ * - Entries: `{apiBase}/api/v1/content/{org}/{project}/models/{model}/entries`
+ * - Entry: `{apiBase}/api/v1/content/{org}/{project}/models/{model}/entries/{slug}`
+ */
+export function createContentAPIClient(
+  apiBase: string,
+  org: string,
+  project: string,
+  apiKey: string,
+): ContentClient {
+  const base = `${apiBase}/api/v1/content/${org}/${project}`;
+  const headers: Record<string, string> = {
+    "x-api-key": apiKey,
+    "content-type": "application/json",
+  };
+
+  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();
+    },
+
+    async getEntries(
+      modelSlug: string,
+      options?: ListEntriesOptions,
+    ): Promise<ContentEntryListItem[]> {
+      const params = new URLSearchParams();
+      if (options?.language) params.set("language", options.language);
+      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(
+        `${base}/models/${modelSlug}/entries${qs}`,
+        { headers },
+      );
+      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 ?? []);
+    },
+
+    async getEntry(
+      modelSlug: string,
+      entrySlug: string,
+      options?: GetEntryOptions,
+    ): Promise<ContentEntry> {
+      const params = new URLSearchParams();
+      if (options?.language) params.set("language", options.language);
+      const qs = params.toString() ? `?${params}` : "";
+
+      const res = await fetch(
+        `${base}/models/${modelSlug}/entries/${entrySlug}${qs}`,
+        { headers },
+      );
+      if (!res.ok) {
+        throw new Error(
+          `API error fetching entry ${modelSlug}/${entrySlug}: ${res.status}`,
+        );
+      }
+      return res.json();
+    },
+  };
+}

package/src/content.ts

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

package/src/index.ts

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

package/src/translations-cdn.ts

@@ -0,0 +1,51 @@
+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

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

package/src/types.ts

@@ -0,0 +1,135 @@
+// ─── Client Configuration ────────────────────────────────────────────
+
+/** Configuration for creating a Better i18n client. */
+export interface ClientConfig {
+  /** Organization slug (e.g., "acme-corp"). */
+  org: string;
+  /** Project slug (e.g., "web-app"). */
+  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`. */
+  apiBase?: string;
+}
+
+// ─── Content Types ───────────────────────────────────────────────────
+
+/** A full content entry with all localized fields. */
+export interface ContentEntry {
+  id: string;
+  slug: string;
+  status: string;
+  publishedAt: string | null;
+  sourceLanguage: string;
+  availableLanguages: string[];
+  featuredImage: string | null;
+  tags: string[];
+  author: { name: string; image: string | null } | null;
+  customFields: Record<string, string | null>;
+  // Localized content
+  title: string;
+  excerpt: string | null;
+  body: unknown;
+  bodyHtml: string | null;
+  bodyMarkdown: string | null;
+  metaTitle: string | null;
+  metaDescription: string | null;
+}
+
+/** A summary item for content entry lists. */
+export interface ContentEntryListItem {
+  slug: string;
+  title: string;
+  excerpt: string | null;
+  publishedAt: string | null;
+  featuredImage: string | null;
+  tags: string[];
+  author: { name: string; image: string | null } | null;
+}
+
+/** A content model definition. */
+export interface ContentModel {
+  slug: string;
+  displayName: string;
+  description: string | null;
+  kind: string;
+  entryCount: number;
+}
+
+// ─── Translation Types ───────────────────────────────────────────────
+
+/** 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 ──────────────────────────────────────────────
+
+/** Options for listing content entries. */
+export interface ListEntriesOptions {
+  /** Language code for localized content. Defaults to `"en"`. */
+  language?: string;
+  /** Page number (1-based). */
+  page?: number;
+  /** Max entries per page. */
+  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?: string;
+}
+
+/** Client for fetching content entries and models. */
+export interface ContentClient {
+  /** List all content models in the project. */
+  getModels(): Promise<ContentModel[]>;
+  /** List entries for a content model. */
+  getEntries(
+    modelSlug: string,
+    options?: ListEntriesOptions,
+  ): Promise<ContentEntryListItem[]>;
+  /** Fetch a single content entry by slug. */
+  getEntry(
+    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;
+}