@nckdv/translation-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,104 @@
+'use strict';
+
+var translationCore = require('@nckdv/translation-core');
+
+// src/client.ts
+
+// src/types.ts
+var TranslationApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "TranslationApiError";
+  }
+  status;
+};
+
+// src/client.ts
+var DEFAULT_CACHE_MS = 5 * 60 * 1e3;
+function createClient(options) {
+  const {
+    apiUrl,
+    apiKey,
+    cacheMs = DEFAULT_CACHE_MS,
+    fetch: fetchImpl = globalThis.fetch
+  } = options;
+  if (!apiUrl) throw new Error("createClient: apiUrl is required.");
+  if (!apiKey) throw new Error("createClient: apiKey is required.");
+  if (typeof fetchImpl !== "function") {
+    throw new Error("createClient: no fetch available; pass one in options.");
+  }
+  const base = apiUrl.replace(/\/+$/, "");
+  const cache = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  async function request(path) {
+    const init = {
+      headers: { "x-api-key": apiKey },
+      cache: "no-store"
+    };
+    const response = await fetchImpl(`${base}${path}`, init);
+    if (!response.ok) {
+      throw new TranslationApiError(
+        response.status === 401 ? "Invalid or revoked API key." : `Translation API returned ${response.status}.`,
+        response.status
+      );
+    }
+    return await response.json();
+  }
+  function fresh(language) {
+    const entry = cache.get(language);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      cache.delete(language);
+      return void 0;
+    }
+    return entry.catalog;
+  }
+  function store(language, catalog) {
+    if (cacheMs > 0) {
+      cache.set(language, { catalog, expiresAt: Date.now() + cacheMs });
+    }
+  }
+  async function getCatalog(language) {
+    const cached = fresh(language);
+    if (cached) return cached;
+    const existing = inFlight.get(language);
+    if (existing) return existing;
+    const pending = request(
+      `/api/catalog/${encodeURIComponent(language)}`
+    ).then((catalog) => {
+      store(language, catalog);
+      return catalog;
+    }).finally(() => inFlight.delete(language));
+    inFlight.set(language, pending);
+    return pending;
+  }
+  async function getCatalogs() {
+    const catalogs = await request("/api/catalog");
+    for (const [language, catalog] of Object.entries(catalogs)) {
+      store(language, catalog);
+    }
+    return catalogs;
+  }
+  async function getTranslator(language) {
+    const messages = await getCatalog(language);
+    return translationCore.createTranslator({ language, messages });
+  }
+  async function prefetch(languages) {
+    if (!languages) {
+      await getCatalogs();
+      return;
+    }
+    await Promise.all(languages.map((language) => getCatalog(language)));
+  }
+  function invalidate(language) {
+    if (language) cache.delete(language);
+    else cache.clear();
+  }
+  return { getCatalog, getCatalogs, getTranslator, prefetch, invalidate };
+}
+
+exports.TranslationApiError = TranslationApiError;
+exports.createClient = createClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":["createTranslator"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { InterpolationValues } from \"@nckdv/translation-core\";\n\n/** A flat catalog for one language, exactly as the API serves it. */\nexport type Catalog = Record<string, string>;\n\nexport type ClientOptions = {\n  /** Where the platform is served from, e.g. `https://translate.example.com`. */\n  apiUrl: string;\n  /**\n   * A project API key. It names its own project, so nothing else identifies\n   * the project — that is the whole point of the credential.\n   *\n   * **Server-side only.** A key is a bearer credential for every catalog in\n   * the project; shipping one to a browser publishes all of them.\n   */\n  apiKey: string;\n  /**\n   * How long a fetched catalog is reused, in milliseconds. Default 5 minutes.\n   *\n   * `0` disables caching, which is what a long-lived editor preview wants and\n   * what a request-scoped server render does not.\n   */\n  cacheMs?: number;\n  /** Swappable for tests and for runtimes with their own fetch. */\n  fetch?: typeof globalThis.fetch;\n};\n\nexport type Translate = (key: string, values?: InterpolationValues) => string;\n\nexport type Client = {\n  /** One language's catalog, from cache when it is still fresh. */\n  getCatalog(language: string): Promise<Catalog>;\n  /** Every language the project has, in one request. */\n  getCatalogs(): Promise<Record<string, Catalog>>;\n  /** A translate function bound to one language. */\n  getTranslator(language: string): Promise<Translate>;\n  /** Warms the cache — call at start-up so the first render does not wait. */\n  prefetch(languages?: string[]): Promise<void>;\n  /** Drops cached catalogs, so the next read goes to the server. */\n  invalidate(language?: string): void;\n};\n\n/** Thrown for any answer that is not a catalog. */\nexport class TranslationApiError extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n  ) {\n    super(message);\n    this.name = \"TranslationApiError\";\n  }\n}\n","import { createTranslator } from \"@nckdv/translation-core\";\nimport {\n  TranslationApiError,\n  type Catalog,\n  type Client,\n  type ClientOptions,\n  type Translate,\n} from \"./types.js\";\n\n/** Five minutes: long enough to matter, short enough that a fix lands soon. */\nconst DEFAULT_CACHE_MS = 5 * 60 * 1000;\n\ntype Entry = {\n  catalog: Catalog;\n  /** When this entry stops being reusable. */\n  expiresAt: number;\n};\n\n/**\n * A client for one project's translations.\n *\n * The key identifies the project, so nothing here takes a project id — a\n * deployment holds one credential rather than a credential and a uuid it\n * cannot verify by eye.\n */\nexport function createClient(options: ClientOptions): Client {\n  const {\n    apiUrl,\n    apiKey,\n    cacheMs = DEFAULT_CACHE_MS,\n    fetch: fetchImpl = globalThis.fetch,\n  } = options;\n\n  if (!apiUrl) throw new Error(\"createClient: apiUrl is required.\");\n  if (!apiKey) throw new Error(\"createClient: apiKey is required.\");\n  if (typeof fetchImpl !== \"function\") {\n    throw new Error(\"createClient: no fetch available; pass one in options.\");\n  }\n\n  const base = apiUrl.replace(/\\/+$/, \"\");\n  const cache = new Map<string, Entry>();\n\n  /**\n   * In-flight requests, keyed the same way as the cache.\n   *\n   * Without this, a cold start that renders ten pages at once makes ten\n   * identical requests for the same catalog. They are shared instead, and the\n   * entry is removed as soon as it settles so a failure is retried rather than\n   * remembered.\n   */\n  const inFlight = new Map<string, Promise<Catalog>>();\n\n  async function request<T>(path: string): Promise<T> {\n    // `cache` is not in Node's own `RequestInit`, but Next.js patches global\n    // fetch and caches by default — and a framework quietly holding on to a\n    // credentialled response is a correctness bug, not an optimisation. So the\n    // field is set through a widened type rather than dropped: this client's\n    // own cache is the one with the policy.\n    const init: RequestInit & { cache?: string } = {\n      headers: { \"x-api-key\": apiKey },\n      cache: \"no-store\",\n    };\n\n    const response = await fetchImpl(`${base}${path}`, init);\n\n    if (!response.ok) {\n      throw new TranslationApiError(\n        response.status === 401\n          ? \"Invalid or revoked API key.\"\n          : `Translation API returned ${response.status}.`,\n        response.status,\n      );\n    }\n    return (await response.json()) as T;\n  }\n\n  function fresh(language: string): Catalog | undefined {\n    const entry = cache.get(language);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= Date.now()) {\n      cache.delete(language);\n      return undefined;\n    }\n    return entry.catalog;\n  }\n\n  function store(language: string, catalog: Catalog) {\n    // A zero TTL means \"do not cache\" rather than \"expire immediately\", so the\n    // entry is simply never written.\n    if (cacheMs > 0) {\n      cache.set(language, { catalog, expiresAt: Date.now() + cacheMs });\n    }\n  }\n\n  async function getCatalog(language: string): Promise<Catalog> {\n    const cached = fresh(language);\n    if (cached) return cached;\n\n    const existing = inFlight.get(language);\n    if (existing) return existing;\n\n    const pending = request<Catalog>(\n      `/api/catalog/${encodeURIComponent(language)}`,\n    )\n      .then((catalog) => {\n        store(language, catalog);\n        return catalog;\n      })\n      .finally(() => inFlight.delete(language));\n\n    inFlight.set(language, pending);\n    return pending;\n  }\n\n  async function getCatalogs(): Promise<Record<string, Catalog>> {\n    const catalogs = await request<Record<string, Catalog>>(\"/api/catalog\");\n    for (const [language, catalog] of Object.entries(catalogs)) {\n      store(language, catalog);\n    }\n    return catalogs;\n  }\n\n  async function getTranslator(language: string): Promise<Translate> {\n    const messages = await getCatalog(language);\n    return createTranslator({ language, messages });\n  }\n\n  async function prefetch(languages?: string[]): Promise<void> {\n    if (!languages) {\n      await getCatalogs();\n      return;\n    }\n    await Promise.all(languages.map((language) => getCatalog(language)));\n  }\n\n  function invalidate(language?: string): void {\n    if (language) cache.delete(language);\n    else cache.clear();\n  }\n\n  return { getCatalog, getCatalogs, getTranslator, prefetch, invalidate };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,54 @@
+import { InterpolationValues } from '@nckdv/translation-core';
+
+/** A flat catalog for one language, exactly as the API serves it. */
+type Catalog = Record<string, string>;
+type ClientOptions = {
+    /** Where the platform is served from, e.g. `https://translate.example.com`. */
+    apiUrl: string;
+    /**
+     * A project API key. It names its own project, so nothing else identifies
+     * the project — that is the whole point of the credential.
+     *
+     * **Server-side only.** A key is a bearer credential for every catalog in
+     * the project; shipping one to a browser publishes all of them.
+     */
+    apiKey: string;
+    /**
+     * How long a fetched catalog is reused, in milliseconds. Default 5 minutes.
+     *
+     * `0` disables caching, which is what a long-lived editor preview wants and
+     * what a request-scoped server render does not.
+     */
+    cacheMs?: number;
+    /** Swappable for tests and for runtimes with their own fetch. */
+    fetch?: typeof globalThis.fetch;
+};
+type Translate = (key: string, values?: InterpolationValues) => string;
+type Client = {
+    /** One language's catalog, from cache when it is still fresh. */
+    getCatalog(language: string): Promise<Catalog>;
+    /** Every language the project has, in one request. */
+    getCatalogs(): Promise<Record<string, Catalog>>;
+    /** A translate function bound to one language. */
+    getTranslator(language: string): Promise<Translate>;
+    /** Warms the cache — call at start-up so the first render does not wait. */
+    prefetch(languages?: string[]): Promise<void>;
+    /** Drops cached catalogs, so the next read goes to the server. */
+    invalidate(language?: string): void;
+};
+/** Thrown for any answer that is not a catalog. */
+declare class TranslationApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+
+/**
+ * A client for one project's translations.
+ *
+ * The key identifies the project, so nothing here takes a project id — a
+ * deployment holds one credential rather than a credential and a uuid it
+ * cannot verify by eye.
+ */
+declare function createClient(options: ClientOptions): Client;
+
+export { type Catalog, type Client, type ClientOptions, type Translate, TranslationApiError, createClient };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { InterpolationValues } from '@nckdv/translation-core';
+
+/** A flat catalog for one language, exactly as the API serves it. */
+type Catalog = Record<string, string>;
+type ClientOptions = {
+    /** Where the platform is served from, e.g. `https://translate.example.com`. */
+    apiUrl: string;
+    /**
+     * A project API key. It names its own project, so nothing else identifies
+     * the project — that is the whole point of the credential.
+     *
+     * **Server-side only.** A key is a bearer credential for every catalog in
+     * the project; shipping one to a browser publishes all of them.
+     */
+    apiKey: string;
+    /**
+     * How long a fetched catalog is reused, in milliseconds. Default 5 minutes.
+     *
+     * `0` disables caching, which is what a long-lived editor preview wants and
+     * what a request-scoped server render does not.
+     */
+    cacheMs?: number;
+    /** Swappable for tests and for runtimes with their own fetch. */
+    fetch?: typeof globalThis.fetch;
+};
+type Translate = (key: string, values?: InterpolationValues) => string;
+type Client = {
+    /** One language's catalog, from cache when it is still fresh. */
+    getCatalog(language: string): Promise<Catalog>;
+    /** Every language the project has, in one request. */
+    getCatalogs(): Promise<Record<string, Catalog>>;
+    /** A translate function bound to one language. */
+    getTranslator(language: string): Promise<Translate>;
+    /** Warms the cache — call at start-up so the first render does not wait. */
+    prefetch(languages?: string[]): Promise<void>;
+    /** Drops cached catalogs, so the next read goes to the server. */
+    invalidate(language?: string): void;
+};
+/** Thrown for any answer that is not a catalog. */
+declare class TranslationApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+
+/**
+ * A client for one project's translations.
+ *
+ * The key identifies the project, so nothing here takes a project id — a
+ * deployment holds one credential rather than a credential and a uuid it
+ * cannot verify by eye.
+ */
+declare function createClient(options: ClientOptions): Client;
+
+export { type Catalog, type Client, type ClientOptions, type Translate, TranslationApiError, createClient };

package/dist/index.js

@@ -0,0 +1,101 @@
+import { createTranslator } from '@nckdv/translation-core';
+
+// src/client.ts
+
+// src/types.ts
+var TranslationApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "TranslationApiError";
+  }
+  status;
+};
+
+// src/client.ts
+var DEFAULT_CACHE_MS = 5 * 60 * 1e3;
+function createClient(options) {
+  const {
+    apiUrl,
+    apiKey,
+    cacheMs = DEFAULT_CACHE_MS,
+    fetch: fetchImpl = globalThis.fetch
+  } = options;
+  if (!apiUrl) throw new Error("createClient: apiUrl is required.");
+  if (!apiKey) throw new Error("createClient: apiKey is required.");
+  if (typeof fetchImpl !== "function") {
+    throw new Error("createClient: no fetch available; pass one in options.");
+  }
+  const base = apiUrl.replace(/\/+$/, "");
+  const cache = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  async function request(path) {
+    const init = {
+      headers: { "x-api-key": apiKey },
+      cache: "no-store"
+    };
+    const response = await fetchImpl(`${base}${path}`, init);
+    if (!response.ok) {
+      throw new TranslationApiError(
+        response.status === 401 ? "Invalid or revoked API key." : `Translation API returned ${response.status}.`,
+        response.status
+      );
+    }
+    return await response.json();
+  }
+  function fresh(language) {
+    const entry = cache.get(language);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      cache.delete(language);
+      return void 0;
+    }
+    return entry.catalog;
+  }
+  function store(language, catalog) {
+    if (cacheMs > 0) {
+      cache.set(language, { catalog, expiresAt: Date.now() + cacheMs });
+    }
+  }
+  async function getCatalog(language) {
+    const cached = fresh(language);
+    if (cached) return cached;
+    const existing = inFlight.get(language);
+    if (existing) return existing;
+    const pending = request(
+      `/api/catalog/${encodeURIComponent(language)}`
+    ).then((catalog) => {
+      store(language, catalog);
+      return catalog;
+    }).finally(() => inFlight.delete(language));
+    inFlight.set(language, pending);
+    return pending;
+  }
+  async function getCatalogs() {
+    const catalogs = await request("/api/catalog");
+    for (const [language, catalog] of Object.entries(catalogs)) {
+      store(language, catalog);
+    }
+    return catalogs;
+  }
+  async function getTranslator(language) {
+    const messages = await getCatalog(language);
+    return createTranslator({ language, messages });
+  }
+  async function prefetch(languages) {
+    if (!languages) {
+      await getCatalogs();
+      return;
+    }
+    await Promise.all(languages.map((language) => getCatalog(language)));
+  }
+  function invalidate(language) {
+    if (language) cache.delete(language);
+    else cache.clear();
+  }
+  return { getCatalog, getCatalogs, getTranslator, prefetch, invalidate };
+}
+
+export { TranslationApiError, createClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { InterpolationValues } from \"@nckdv/translation-core\";\n\n/** A flat catalog for one language, exactly as the API serves it. */\nexport type Catalog = Record<string, string>;\n\nexport type ClientOptions = {\n  /** Where the platform is served from, e.g. `https://translate.example.com`. */\n  apiUrl: string;\n  /**\n   * A project API key. It names its own project, so nothing else identifies\n   * the project — that is the whole point of the credential.\n   *\n   * **Server-side only.** A key is a bearer credential for every catalog in\n   * the project; shipping one to a browser publishes all of them.\n   */\n  apiKey: string;\n  /**\n   * How long a fetched catalog is reused, in milliseconds. Default 5 minutes.\n   *\n   * `0` disables caching, which is what a long-lived editor preview wants and\n   * what a request-scoped server render does not.\n   */\n  cacheMs?: number;\n  /** Swappable for tests and for runtimes with their own fetch. */\n  fetch?: typeof globalThis.fetch;\n};\n\nexport type Translate = (key: string, values?: InterpolationValues) => string;\n\nexport type Client = {\n  /** One language's catalog, from cache when it is still fresh. */\n  getCatalog(language: string): Promise<Catalog>;\n  /** Every language the project has, in one request. */\n  getCatalogs(): Promise<Record<string, Catalog>>;\n  /** A translate function bound to one language. */\n  getTranslator(language: string): Promise<Translate>;\n  /** Warms the cache — call at start-up so the first render does not wait. */\n  prefetch(languages?: string[]): Promise<void>;\n  /** Drops cached catalogs, so the next read goes to the server. */\n  invalidate(language?: string): void;\n};\n\n/** Thrown for any answer that is not a catalog. */\nexport class TranslationApiError extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n  ) {\n    super(message);\n    this.name = \"TranslationApiError\";\n  }\n}\n","import { createTranslator } from \"@nckdv/translation-core\";\nimport {\n  TranslationApiError,\n  type Catalog,\n  type Client,\n  type ClientOptions,\n  type Translate,\n} from \"./types.js\";\n\n/** Five minutes: long enough to matter, short enough that a fix lands soon. */\nconst DEFAULT_CACHE_MS = 5 * 60 * 1000;\n\ntype Entry = {\n  catalog: Catalog;\n  /** When this entry stops being reusable. */\n  expiresAt: number;\n};\n\n/**\n * A client for one project's translations.\n *\n * The key identifies the project, so nothing here takes a project id — a\n * deployment holds one credential rather than a credential and a uuid it\n * cannot verify by eye.\n */\nexport function createClient(options: ClientOptions): Client {\n  const {\n    apiUrl,\n    apiKey,\n    cacheMs = DEFAULT_CACHE_MS,\n    fetch: fetchImpl = globalThis.fetch,\n  } = options;\n\n  if (!apiUrl) throw new Error(\"createClient: apiUrl is required.\");\n  if (!apiKey) throw new Error(\"createClient: apiKey is required.\");\n  if (typeof fetchImpl !== \"function\") {\n    throw new Error(\"createClient: no fetch available; pass one in options.\");\n  }\n\n  const base = apiUrl.replace(/\\/+$/, \"\");\n  const cache = new Map<string, Entry>();\n\n  /**\n   * In-flight requests, keyed the same way as the cache.\n   *\n   * Without this, a cold start that renders ten pages at once makes ten\n   * identical requests for the same catalog. They are shared instead, and the\n   * entry is removed as soon as it settles so a failure is retried rather than\n   * remembered.\n   */\n  const inFlight = new Map<string, Promise<Catalog>>();\n\n  async function request<T>(path: string): Promise<T> {\n    // `cache` is not in Node's own `RequestInit`, but Next.js patches global\n    // fetch and caches by default — and a framework quietly holding on to a\n    // credentialled response is a correctness bug, not an optimisation. So the\n    // field is set through a widened type rather than dropped: this client's\n    // own cache is the one with the policy.\n    const init: RequestInit & { cache?: string } = {\n      headers: { \"x-api-key\": apiKey },\n      cache: \"no-store\",\n    };\n\n    const response = await fetchImpl(`${base}${path}`, init);\n\n    if (!response.ok) {\n      throw new TranslationApiError(\n        response.status === 401\n          ? \"Invalid or revoked API key.\"\n          : `Translation API returned ${response.status}.`,\n        response.status,\n      );\n    }\n    return (await response.json()) as T;\n  }\n\n  function fresh(language: string): Catalog | undefined {\n    const entry = cache.get(language);\n    if (!entry) return undefined;\n    if (entry.expiresAt <= Date.now()) {\n      cache.delete(language);\n      return undefined;\n    }\n    return entry.catalog;\n  }\n\n  function store(language: string, catalog: Catalog) {\n    // A zero TTL means \"do not cache\" rather than \"expire immediately\", so the\n    // entry is simply never written.\n    if (cacheMs > 0) {\n      cache.set(language, { catalog, expiresAt: Date.now() + cacheMs });\n    }\n  }\n\n  async function getCatalog(language: string): Promise<Catalog> {\n    const cached = fresh(language);\n    if (cached) return cached;\n\n    const existing = inFlight.get(language);\n    if (existing) return existing;\n\n    const pending = request<Catalog>(\n      `/api/catalog/${encodeURIComponent(language)}`,\n    )\n      .then((catalog) => {\n        store(language, catalog);\n        return catalog;\n      })\n      .finally(() => inFlight.delete(language));\n\n    inFlight.set(language, pending);\n    return pending;\n  }\n\n  async function getCatalogs(): Promise<Record<string, Catalog>> {\n    const catalogs = await request<Record<string, Catalog>>(\"/api/catalog\");\n    for (const [language, catalog] of Object.entries(catalogs)) {\n      store(language, catalog);\n    }\n    return catalogs;\n  }\n\n  async function getTranslator(language: string): Promise<Translate> {\n    const messages = await getCatalog(language);\n    return createTranslator({ language, messages });\n  }\n\n  async function prefetch(languages?: string[]): Promise<void> {\n    if (!languages) {\n      await getCatalogs();\n      return;\n    }\n    await Promise.all(languages.map((language) => getCatalog(language)));\n  }\n\n  function invalidate(language?: string): void {\n    if (language) cache.delete(language);\n    else cache.clear();\n  }\n\n  return { getCatalog, getCatalogs, getTranslator, prefetch, invalidate };\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@nckdv/translation-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nckdv/translation-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "description": "Client SDK for the nck-translation API: catalog fetching, caching and single-flight.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NiklasErath/nck-translation.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/NiklasErath/nck-translation#readme",
+  "keywords": [
+    "i18n",
+    "translation",
+    "sdk",
+    "internationalization",
+    "localization"
+  ]
+}