@better-i18n/sdk 0.3.0 → 1.0.0

package/README.md

@@ -23,8 +23,7 @@ npm install @better-i18n/sdk
 import { createClient } from "@better-i18n/sdk";
 
 const client = createClient({
-  org: "acme",
-  project: "web-app",
+  project: "acme/web-app",
   apiKey: process.env.BETTER_I18N_API_KEY!,
 });
 
@@ -114,10 +113,9 @@ post.customFields.category;   // string | null (typed!)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `org` | Yes | Organization slug |
-| `project` | Yes | Project slug |
+| `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://api.better-i18n.com`) |
+| `apiBase` | No | API base URL (default: `https://dash.better-i18n.com`) |
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/sdk",
-  "version": "0.3.0",
+  "version": "1.0.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://content.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

@@ -15,29 +15,49 @@ import type {
  * 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}`
+ * - Models: `{apiBase}/v1/content/{org}/{project}/models`
+ * - Entries: `{apiBase}/v1/content/{org}/{project}/models/{model}/entries`
+ * - Entry: `{apiBase}/v1/content/{org}/{project}/models/{model}/entries/{slug}`
  */
 export function createContentAPIClient(
   apiBase: string,
   org: string,
   project: string,
   apiKey: string,
+  debug = false,
 ): ContentClient {
-  const base = `${apiBase}/api/v1/content/${org}/${project}`;
+  const base = `${apiBase}/v1/content/${org}/${project}`;
   const headers: Record<string, string> = {
     "x-api-key": apiKey,
     "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(
@@ -53,16 +73,10 @@ export function createContentAPIClient(
       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 = await res.json() as { items: ContentEntryListItem[]; total: number; hasMore: boolean };
       return {
         items: data.items,
         total: data.total,
@@ -79,16 +93,11 @@ export function createContentAPIClient(
       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/types.ts

@@ -2,14 +2,14 @@
 
 /** 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 ───────────────────────────────────────────────────
@@ -41,7 +41,8 @@ export interface ContentEntry<CF extends Record<string, string | null> = Record<
   // 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;