@tandem-language-exchange/content-store 1.1.2 → 1.2.1

package/dist/index-kfqHGgMO.d.ts

@@ -0,0 +1,118 @@
+type CMSProvider = 'contentful' | 'sanity';
+interface S3Config {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+
+declare class ContentStore {
+    private client;
+    private bucket;
+    constructor(cfg: S3Config);
+    upload(key: string, data: unknown): Promise<string>;
+    /** Raw UTF-8 body (e.g. Lingohub file bytes as text). */
+    uploadRaw(key: string, body: string, contentType: string): Promise<string>;
+    download(key: string): Promise<unknown>;
+    /** Raw UTF-8 body from S3 (no JSON.parse). */
+    downloadRaw(key: string): Promise<string>;
+}
+
+/** Retry/backoff for S3 reads (aligned with CMS `RetryConfig` shape). */
+interface S3RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+/**
+ * Default S3 download retry policy from env.
+ * `S3_RETRY_*` overrides `RETRY_*` when set.
+ */
+declare function getDefaultS3RetryConfig(): S3RetryConfig;
+
+interface CmsBundleInfo {
+    [key: string]: string;
+}
+interface TranslationBundleInfo {
+    [key: string]: Record<string, string>;
+}
+interface BundleItem {
+    [key: string]: any;
+}
+interface FetchCmsBundlesOptions {
+    cms: CMSProvider;
+    contentTypes: string[];
+    /** S3 GET retry; defaults via {@link getDefaultS3RetryConfig}. */
+    retry?: S3RetryConfig;
+}
+interface FetchTranslationBundlesOptions {
+    projects: string[];
+    locales?: string[] | undefined;
+    /** S3 GET retry; defaults via {@link getDefaultS3RetryConfig}. */
+    retry?: S3RetryConfig;
+}
+/** One merged JSON file per catalog locale (`en.json`, …). Same options as {@link FetchTranslationBundlesOptions}. */
+type FetchMergedTranslationBundlesOptions = FetchTranslationBundlesOptions;
+interface QueryOptions {
+    /**
+     * Filter items by matching property values (exact equality, or array for IN).
+     * Keys may use dot notation for nested paths, e.g. `{ 'meta._id': 'abc' }` matches
+     * `item.meta._id`.
+     *
+     * Contentful-style operators on the path (before `[`):
+     * - `{ 'field[exists]': true }` — field is present and non-empty (not null, undefined,
+     *   `''`, `[]`, or `{}`).
+     * - `{ 'field[exists]': false }` — field is missing or empty (same emptiness rules).
+     * Nested paths work, e.g. `{ 'blocks.hero[exists]': false }`.
+     */
+    fields?: Record<string, unknown>;
+    /**
+     * Properties to include in each result object. Omit to return all properties.
+     * Keys may use dot notation; nested segments become nested objects in the result,
+     * e.g. `['slug', 'meta._updatedAt']` → `{ slug, meta: { _updatedAt } }`.
+     */
+    select?: string[];
+    /** Maximum number of items to return. */
+    limit?: number;
+    /**
+     * How many levels deep to return.
+     *  - 1 = the item's own scalar properties only; nested objects/refs are nulled.
+     *  - 2 = the item including its direct references; refs inside those are nulled.
+     *  - 3 = three levels deep, and so on.
+     *  - Omit to return the full depth.
+     */
+    include?: number;
+}
+/**
+ * Downloads the latest CMS bundles from S3 and writes them as JSON files to `outputDir`.
+ *
+ * @returns A map of contentType to absolute file path.
+ */
+declare function fetchCmsBundles(store: ContentStore, outputDir: string, options: FetchCmsBundlesOptions): Promise<Record<string, string>>;
+/**
+ * Downloads the latest translation bundles from S3 and writes them as JSON files to `outputDir`.
+ *
+ * @returns For each project, a map of S3 object key to absolute file path on disk.
+ */
+declare function fetchTranslationBundles(store: ContentStore, outputDir: string, options: FetchTranslationBundlesOptions): Promise<TranslationBundleInfo>;
+/**
+ * Downloads translation bundles from S3, parses each raw Lingohub file, and merges all
+ * key/value pairs per **catalog** locale into a single JSON file (e.g. `en.json`).
+ * Duplicate keys across resources or projects: **last write wins** (iteration order:
+ * projects → resources → locales).
+ *
+ * @returns Map of locale code to absolute path of the merged `{locale}.json` file.
+ */
+declare function fetchMergedTranslationBundles(store: ContentStore, outputDir: string, options: FetchMergedTranslationBundlesOptions): Promise<Record<string, string>>;
+/**
+ * Queries a previously fetched bundle from the local filesystem.
+ */
+declare function queryCmsBundle(outputDir: string, cms: CMSProvider, contentType: string, options?: QueryOptions): Promise<unknown[]>;
+
+interface SDKConfig {
+    s3: S3Config;
+    /** Directory where bundle JSON files are saved on the local filesystem. */
+    outputDir: string;
+}
+
+export { type BundleItem as B, type CMSProvider as C, type FetchCmsBundlesOptions as F, type QueryOptions as Q, type SDKConfig as S, type TranslationBundleInfo as T, type FetchTranslationBundlesOptions as a, type FetchMergedTranslationBundlesOptions as b, type CmsBundleInfo as c, ContentStore as d, type S3Config as e, type S3RetryConfig as f, fetchCmsBundles as g, fetchMergedTranslationBundles as h, fetchTranslationBundles as i, getDefaultS3RetryConfig as j, queryCmsBundle as q };

package/dist/index.d.ts

@@ -1 +1 @@
-export { B as BundleInfo, a as BundleItem, C as CMSProvider, F as FetchBundlesOptions, Q as QueryOptions, c as S3Config, S as SDKConfig } from './index-DJXkO17k.js';
+export { B as BundleItem, C as CMSProvider, c as CmsBundleInfo, F as FetchCmsBundlesOptions, b as FetchMergedTranslationBundlesOptions, a as FetchTranslationBundlesOptions, Q as QueryOptions, e as S3Config, f as S3RetryConfig, S as SDKConfig, T as TranslationBundleInfo } from './index-kfqHGgMO.js';

package/dist/node.browser.js

@@ -36,10 +36,16 @@ var ContentStoreSDK = class {
   constructor(_config) {
     serverOnly();
   }
-  fetchBundles() {
+  fetchCmsBundles() {
     return Promise.reject(new Error(SERVER_ONLY));
   }
-  queryBundle() {
+  queryCmsBundle() {
+    return Promise.reject(new Error(SERVER_ONLY));
+  }
+  fetchTranslationBundles() {
+    return Promise.reject(new Error(SERVER_ONLY));
+  }
+  fetchMergedTranslationBundles() {
     return Promise.reject(new Error(SERVER_ONLY));
   }
 };
@@ -48,17 +54,25 @@ var ContentStore = class {
     serverOnly();
   }
 };
-async function fetchBundles() {
+async function fetchCmsBundles() {
+  serverOnly();
+}
+async function queryCmsBundle() {
+  serverOnly();
+}
+async function fetchTranslationBundles() {
   serverOnly();
 }
-async function queryBundle() {
+async function fetchMergedTranslationBundles() {
   serverOnly();
 }
 export {
   ContentStore,
   ContentStoreSDK,
-  fetchBundles,
-  queryBundle,
+  fetchCmsBundles,
+  fetchMergedTranslationBundles,
+  fetchTranslationBundles,
+  queryCmsBundle,
   trimDepth
 };
 //# sourceMappingURL=node.browser.js.map

package/dist/node.browser.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared/trimDepth.ts","../src/node.browser.ts"],"sourcesContent":["/**\n * Trims nested object depth.\n *\n * `remaining` represents how many levels the current object is allowed.\n *  - Scalar properties are always kept.\n *  - Nested objects / arrays-of-objects consume one level. When `remaining`\n *    drops to 1 they are replaced with `null` (no budget left for refs).\n */\nexport function trimDepth(value: unknown, remaining: number): unknown {\n  if (value === null || value === undefined || typeof value !== 'object') {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => trimDepth(item, remaining));\n  }\n\n  const obj = value as Record<string, unknown>;\n  const result: Record<string, unknown> = {};\n\n  for (const [k, v] of Object.entries(obj)) {\n    if (v === null || v === undefined || typeof v !== 'object') {\n      result[k] = v;\n    } else if (remaining <= 1) {\n      result[k] = null;\n    } else if (Array.isArray(v)) {\n      result[k] = v.map((item) => {\n        if (item !== null && typeof item === 'object' && !Array.isArray(item)) {\n          return trimDepth(item, remaining - 1);\n        }\n        return item;\n      });\n    } else {\n      result[k] = trimDepth(v, remaining - 1);\n    }\n  }\n\n  return result;\n}\n","/**\n * Browser / client-bundler entry for `@tandem-language-exchange/content-store/node`.\n * Next.js and Turbopack resolve this when the `browser` condition applies, so `fs`\n * is never pulled into client chunks.\n *\n * Server-only APIs throw if called; `trimDepth` is real and safe everywhere.\n */\nexport type {\n  SDKConfig,\n  FetchBundlesOptions,\n  QueryOptions,\n  BundleInfo,\n  BundleItem,\n} from './sdk/client-types';\nexport type { CMSProvider, S3Config } from './shared/types';\n\nexport { trimDepth } from './shared/trimDepth';\n\nconst SERVER_ONLY =\n  '@tandem-language-exchange/content-store/node uses the filesystem and S3 and only runs on the server. ' +\n  'Import it from getServerSideProps, Route Handlers, or \"use server\" modules — not from _app, layouts, or client components. ' +\n  'You can use `import type { ... } from \"@tandem-language-exchange/content-store\"` in shared code.';\n\nfunction serverOnly(): never {\n  throw new Error(SERVER_ONLY);\n}\n\nexport class ContentStoreSDK {\n  constructor(_config: unknown) {\n    serverOnly();\n  }\n\n  fetchBundles(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n\n  queryBundle(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n}\n\nexport class ContentStore {\n  constructor(_cfg: unknown) {\n    serverOnly();\n  }\n}\n\nexport async function fetchBundles(): Promise<never> {\n  serverOnly();\n}\n\nexport async function queryBundle(): Promise<never> {\n  serverOnly();\n}\n"],"mappings":";AAQO,SAAS,UAAU,OAAgB,WAA4B;AACpE,MAAI,UAAU,QAAQ,UAAU,UAAa,OAAO,UAAU,UAAU;AACtE,WAAO;AAAA,EACT;AAEA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,IAAI,CAAC,SAAS,UAAU,MAAM,SAAS,CAAC;AAAA,EACvD;AAEA,QAAM,MAAM;AACZ,QAAM,SAAkC,CAAC;AAEzC,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,GAAG;AACxC,QAAI,MAAM,QAAQ,MAAM,UAAa,OAAO,MAAM,UAAU;AAC1D,aAAO,CAAC,IAAI;AAAA,IACd,WAAW,aAAa,GAAG;AACzB,aAAO,CAAC,IAAI;AAAA,IACd,WAAW,MAAM,QAAQ,CAAC,GAAG;AAC3B,aAAO,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS;AAC1B,YAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,GAAG;AACrE,iBAAO,UAAU,MAAM,YAAY,CAAC;AAAA,QACtC;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,OAAO;AACL,aAAO,CAAC,IAAI,UAAU,GAAG,YAAY,CAAC;AAAA,IACxC;AAAA,EACF;AAEA,SAAO;AACT;;;ACpBA,IAAM,cACJ;AAIF,SAAS,aAAoB;AAC3B,QAAM,IAAI,MAAM,WAAW;AAC7B;AAEO,IAAM,kBAAN,MAAsB;AAAA,EAC3B,YAAY,SAAkB;AAC5B,eAAW;AAAA,EACb;AAAA,EAEA,eAA+B;AAC7B,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AAAA,EAEA,cAA8B;AAC5B,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AACF;AAEO,IAAM,eAAN,MAAmB;AAAA,EACxB,YAAY,MAAe;AACzB,eAAW;AAAA,EACb;AACF;AAEA,eAAsB,eAA+B;AACnD,aAAW;AACb;AAEA,eAAsB,cAA8B;AAClD,aAAW;AACb;","names":[]}
+{"version":3,"sources":["../src/shared/trimDepth.ts","../src/node.browser.ts"],"sourcesContent":["/**\n * Trims nested object depth.\n *\n * `remaining` represents how many levels the current object is allowed.\n *  - Scalar properties are always kept.\n *  - Nested objects / arrays-of-objects consume one level. When `remaining`\n *    drops to 1 they are replaced with `null` (no budget left for refs).\n */\nexport function trimDepth(value: unknown, remaining: number): unknown {\n  if (value === null || value === undefined || typeof value !== 'object') {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => trimDepth(item, remaining));\n  }\n\n  const obj = value as Record<string, unknown>;\n  const result: Record<string, unknown> = {};\n\n  for (const [k, v] of Object.entries(obj)) {\n    if (v === null || v === undefined || typeof v !== 'object') {\n      result[k] = v;\n    } else if (remaining <= 1) {\n      result[k] = null;\n    } else if (Array.isArray(v)) {\n      result[k] = v.map((item) => {\n        if (item !== null && typeof item === 'object' && !Array.isArray(item)) {\n          return trimDepth(item, remaining - 1);\n        }\n        return item;\n      });\n    } else {\n      result[k] = trimDepth(v, remaining - 1);\n    }\n  }\n\n  return result;\n}\n","/**\n * Browser / client-bundler entry for `@tandem-language-exchange/content-store/node`.\n * Next.js and Turbopack resolve this when the `browser` condition applies, so `fs`\n * is never pulled into client chunks.\n *\n * Server-only APIs throw if called; `trimDepth` is real and safe everywhere.\n */\nexport type {\n  SDKConfig,\n  FetchCmsBundlesOptions,\n  FetchTranslationBundlesOptions,\n  FetchMergedTranslationBundlesOptions,\n  QueryOptions,\n  CmsBundleInfo,\n  TranslationBundleInfo,\n  BundleItem,\n} from './sdk/client-types';\nexport type { CMSProvider, S3Config } from './shared/types';\n\nexport { trimDepth } from './shared/trimDepth';\n\nconst SERVER_ONLY =\n  '@tandem-language-exchange/content-store/node uses the filesystem and S3 and only runs on the server. ' +\n  'Import it from getServerSideProps, Route Handlers, or \"use server\" modules — not from _app, layouts, or client components. ' +\n  'You can use `import type { ... } from \"@tandem-language-exchange/content-store\"` in shared code.';\n\nfunction serverOnly(): never {\n  throw new Error(SERVER_ONLY);\n}\n\nexport class ContentStoreSDK {\n  constructor(_config: unknown) {\n    serverOnly();\n  }\n\n  fetchCmsBundles(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n\n  queryCmsBundle(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n\n  fetchTranslationBundles(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n\n  fetchMergedTranslationBundles(): Promise<never> {\n    return Promise.reject(new Error(SERVER_ONLY));\n  }\n}\n\nexport class ContentStore {\n  constructor(_cfg: unknown) {\n    serverOnly();\n  }\n}\n\nexport async function fetchCmsBundles(): Promise<never> {\n  serverOnly();\n}\n\nexport async function queryCmsBundle(): Promise<never> {\n  serverOnly();\n}\n\nexport async function fetchTranslationBundles(): Promise<never> {\n  serverOnly();\n}\n\nexport async function fetchMergedTranslationBundles(): Promise<never> {\n  serverOnly();\n}\n"],"mappings":";AAQO,SAAS,UAAU,OAAgB,WAA4B;AACpE,MAAI,UAAU,QAAQ,UAAU,UAAa,OAAO,UAAU,UAAU;AACtE,WAAO;AAAA,EACT;AAEA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,IAAI,CAAC,SAAS,UAAU,MAAM,SAAS,CAAC;AAAA,EACvD;AAEA,QAAM,MAAM;AACZ,QAAM,SAAkC,CAAC;AAEzC,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,GAAG,GAAG;AACxC,QAAI,MAAM,QAAQ,MAAM,UAAa,OAAO,MAAM,UAAU;AAC1D,aAAO,CAAC,IAAI;AAAA,IACd,WAAW,aAAa,GAAG;AACzB,aAAO,CAAC,IAAI;AAAA,IACd,WAAW,MAAM,QAAQ,CAAC,GAAG;AAC3B,aAAO,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS;AAC1B,YAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,GAAG;AACrE,iBAAO,UAAU,MAAM,YAAY,CAAC;AAAA,QACtC;AACA,eAAO;AAAA,MACT,CAAC;AAAA,IACH,OAAO;AACL,aAAO,CAAC,IAAI,UAAU,GAAG,YAAY,CAAC;AAAA,IACxC;AAAA,EACF;AAEA,SAAO;AACT;;;ACjBA,IAAM,cACJ;AAIF,SAAS,aAAoB;AAC3B,QAAM,IAAI,MAAM,WAAW;AAC7B;AAEO,IAAM,kBAAN,MAAsB;AAAA,EAC3B,YAAY,SAAkB;AAC5B,eAAW;AAAA,EACb;AAAA,EAEA,kBAAkC;AAChC,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AAAA,EAEA,iBAAiC;AAC/B,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AAAA,EAEA,0BAA0C;AACxC,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AAAA,EAEA,gCAAgD;AAC9C,WAAO,QAAQ,OAAO,IAAI,MAAM,WAAW,CAAC;AAAA,EAC9C;AACF;AAEO,IAAM,eAAN,MAAmB;AAAA,EACxB,YAAY,MAAe;AACzB,eAAW;AAAA,EACb;AACF;AAEA,eAAsB,kBAAkC;AACtD,aAAW;AACb;AAEA,eAAsB,iBAAiC;AACrD,aAAW;AACb;AAEA,eAAsB,0BAA0C;AAC9D,aAAW;AACb;AAEA,eAAsB,gCAAgD;AACpE,aAAW;AACb;","names":[]}

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { S as SDKConfig, F as FetchBundlesOptions, C as CMSProvider, Q as QueryOptions } from './index-DJXkO17k.js';
-export { B as BundleInfo, a as BundleItem, b as ContentStore, c as S3Config, f as fetchBundles, q as queryBundle } from './index-DJXkO17k.js';
+import { S as SDKConfig, F as FetchCmsBundlesOptions, a as FetchTranslationBundlesOptions, T as TranslationBundleInfo, b as FetchMergedTranslationBundlesOptions, C as CMSProvider, Q as QueryOptions } from './index-kfqHGgMO.js';
+export { B as BundleItem, c as CmsBundleInfo, d as ContentStore, e as S3Config, f as S3RetryConfig, g as fetchCmsBundles, h as fetchMergedTranslationBundles, i as fetchTranslationBundles, j as getDefaultS3RetryConfig, q as queryCmsBundle } from './index-kfqHGgMO.js';
 
 /**
  * Trims nested object depth.
@@ -21,11 +21,24 @@ declare class ContentStoreSDK {
      *
      * @returns A map of contentType to absolute file path.
      */
-    fetchBundles(options: FetchBundlesOptions): Promise<Record<string, string>>;
+    fetchCmsBundles(options: FetchCmsBundlesOptions): Promise<Record<string, string>>;
+    /**
+     * Downloads translation bundles from S3 and writes them as JSON files
+     * to `outputDir`.
+     *
+     * @returns Per project, a map of S3 object key to absolute file path.
+     */
+    fetchTranslationBundles(options: FetchTranslationBundlesOptions): Promise<TranslationBundleInfo>;
+    /**
+     * Downloads all translation resources for the given projects/locales, parses them,
+     * and writes one merged `{locale}.json` per locale (string key/value map; duplicate keys:
+     * last wins).
+     */
+    fetchMergedTranslationBundles(options: FetchMergedTranslationBundlesOptions): Promise<Record<string, string>>;
     /**
      * Queries a previously fetched bundle from the local filesystem.
      */
-    queryBundle(cms: CMSProvider, contentType: string, options?: QueryOptions): Promise<unknown[]>;
+    queryCmsBundle(cms: CMSProvider, contentType: string, options?: QueryOptions): Promise<unknown[]>;
 }
 
-export { CMSProvider, ContentStoreSDK, FetchBundlesOptions, QueryOptions, SDKConfig, trimDepth };
+export { CMSProvider, ContentStoreSDK, FetchCmsBundlesOptions, FetchMergedTranslationBundlesOptions, FetchTranslationBundlesOptions, QueryOptions, SDKConfig, TranslationBundleInfo, trimDepth };