@blinkk/root-cms 1.4.4 → 1.4.5

package/dist/core.js

@@ -6,10 +6,361 @@ var __export = (target, all) => {
 
 // core/client.ts
 import crypto from "node:crypto";
+import {
+  FieldValue as FieldValue2,
+  Timestamp as Timestamp2
+} from "firebase-admin/firestore";
+
+// core/translations-manager.ts
 import {
   FieldValue,
   Timestamp
 } from "firebase-admin/firestore";
+
+// shared/strings.ts
+import fnv from "fnv-plus";
+function normalizeStr(str) {
+  const lines = str.trim().split("\n").map((line) => removeTrailingWhitespace(line));
+  return lines.join("\n");
+}
+function removeTrailingWhitespace(str) {
+  return str.trimEnd().replace(/ $/, "");
+}
+function hashStr(str) {
+  if (!str || typeof str !== "string") {
+    throw new Error("input string is invalid");
+  }
+  return fnv.fast1a52hex(normalizeStr(str));
+}
+
+// core/translations-manager.ts
+var TRANSLATIONS_DB_PATH_FORMAT = "/Projects/{project}/TranslationsManager/{mode}/Translations";
+var TRANSLATIONS_LOCALE_DOC_DB_PATH_FORMAT = `${TRANSLATIONS_DB_PATH_FORMAT}/{id}:{locale}`;
+var TranslationsManager = class {
+  constructor(cmsClient) {
+    this.cmsClient = cmsClient;
+  }
+  /**
+   * Saves draft translations for a translations doc id.
+   *
+   * Example:
+   * ```
+   * const strings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'},
+   * };
+   * await tm.saveTranslations('Pages/index', strings);
+   * ```
+   */
+  async saveTranslations(id, strings, options) {
+    const mode = "draft";
+    const localesSet = /* @__PURE__ */ new Set();
+    Object.values(strings).forEach((entry) => {
+      Object.keys(entry).forEach((locale) => {
+        if (locale !== "source") {
+          localesSet.add(locale);
+        }
+      });
+    });
+    const batch = this.cmsClient.db.batch();
+    const locales = Array.from(localesSet);
+    locales.forEach((locale) => {
+      const updates = {
+        id,
+        locale,
+        sys: {
+          modifiedAt: Timestamp.now(),
+          modifiedBy: (options == null ? void 0 : options.modifiedBy) || "root-cms-client"
+        },
+        strings: {}
+      };
+      if ((options == null ? void 0 : options.tags) && options.tags.length > 0) {
+        updates.tags = FieldValue.arrayUnion(...options.tags);
+      }
+      let numUpdates = 0;
+      const hashMap = this.toLocaleDocHashMap(strings, locale);
+      Object.entries(hashMap).forEach(([hash, translations]) => {
+        Object.entries(translations).forEach(([locale2, translation]) => {
+          if (translation) {
+            updates.strings[hash] ??= {};
+            updates.strings[hash][locale2] = translation;
+            numUpdates += 1;
+          }
+        });
+      });
+      if (numUpdates > 0) {
+        const localeDocPath = buildTranslationsLocaleDocDbPath({
+          project: this.cmsClient.projectId,
+          mode,
+          id,
+          locale
+        });
+        const localeDocRef = this.cmsClient.db.doc(localeDocPath);
+        batch.set(localeDocRef, updates, { merge: true });
+      }
+    });
+    await batch.commit();
+  }
+  /**
+   * Publishes a translations doc.
+   */
+  async publishTranslations(id, options) {
+    const db = this.cmsClient.db;
+    const project = this.cmsClient.projectId;
+    const draftPath = buildTranslationsDbPath({ project, mode: "draft" });
+    const query = db.collection(draftPath).where("id", "==", id);
+    const res = await query.get();
+    if (res.size === 0) {
+      console.warn(`no translations to publish for ${id}`);
+      return;
+    }
+    const batch = (options == null ? void 0 : options.batch) || db.batch();
+    res.docs.forEach((doc) => {
+      const translationsLocaleDoc = doc.data();
+      const sys = {
+        ...translationsLocaleDoc.sys,
+        publishedAt: Timestamp.now(),
+        publishedBy: (options == null ? void 0 : options.publishedBy) || "root-cms-client"
+      };
+      batch.update(doc.ref, { sys });
+      const publishedDocPath = buildTranslationsLocaleDocDbPath({
+        project,
+        mode: "published",
+        id: translationsLocaleDoc.id,
+        locale: translationsLocaleDoc.locale
+      });
+      const publishedDocRef = db.doc(publishedDocPath);
+      batch.set(publishedDocRef, { ...translationsLocaleDoc, sys });
+    });
+    const shouldCommitBatch = !(options == null ? void 0 : options.batch);
+    if (shouldCommitBatch) {
+      await batch.commit();
+    }
+  }
+  /**
+   * Fetches translations from one or more translations docs in the translations
+   * manager.
+   *
+   * Example:
+   * ```
+   * await tm.loadTranslations();
+   * // =>
+   * // {
+   * //   "one": {"es": "uno", "fr": "un"},
+   * //   "two": {"es": "dos", "fr": "deux"}
+   * // }
+   * ```
+   *
+   * To load a specific set of translations docs by id:
+   * ```
+   * const translationsToLoad = ['Global/strings', 'Global/header', 'Global/footer', 'Pages/index'];
+   * await tm.loadTranslations({ids: translationsToLoad});
+   * // =>
+   * // {
+   * //   "one": {"es": "uno", "fr": "un"},
+   * //   "two": {"es": "dos", "fr": "deux"}
+   * // }
+   * ```
+   *
+   * To load a subset of locales (more performant):
+   * ```
+   * await tm.loadTranslations({locales: ['es']});
+   * // =>
+   * // {
+   * //   "one": {"es": "uno"},
+   * //   "two": {"es": "dos"}
+   * // }
+   * ```
+   */
+  async loadTranslations(options) {
+    const mode = (options == null ? void 0 : options.mode) || "published";
+    const dbPath = buildTranslationsDbPath({
+      project: this.cmsClient.projectId,
+      mode
+    });
+    let query = this.cmsClient.db.collection(dbPath);
+    if ((options == null ? void 0 : options.ids) && options.ids.length > 0) {
+      query = query.where("id", "in", options.ids);
+    }
+    if ((options == null ? void 0 : options.tags) && options.tags.length > 0) {
+      query = query.where("tags", "array-contains", options.tags);
+    }
+    if ((options == null ? void 0 : options.locales) && options.locales.length > 0) {
+      query = query.where("locale", "in", options.locales);
+    }
+    const results = await query.get();
+    const strings = {};
+    results.forEach((result) => {
+      const localeDoc = result.data();
+      Object.values(localeDoc.strings || {}).forEach((item) => {
+        strings[item.source] ??= { source: item.source };
+        strings[item.source][localeDoc.locale] = item.translation;
+      });
+    });
+    return strings;
+  }
+  /**
+   * Fetches translations for a given locale, with optional fallbacks.
+   * The return value is a map of source string to translated string.
+   *
+   * Example:
+   * ```
+   * await translationsDoc.loadTranslationsForLocale('es');
+   * // =>
+   * // {
+   * //   "one": "uno",
+   * //   "two": "dos",
+   * // }
+   * ```
+   */
+  async loadTranslationsForLocale(locale, options) {
+    const localeSet = /* @__PURE__ */ new Set([
+      locale,
+      ...(options == null ? void 0 : options.fallbackLocales) || []
+    ]);
+    const fallbackLocales = Array.from(localeSet);
+    const multiLocaleStrings = await this.loadTranslations({
+      mode: options == null ? void 0 : options.mode,
+      locales: fallbackLocales
+    });
+    return this.toSingleLocaleMap(multiLocaleStrings, fallbackLocales);
+  }
+  /**
+   * Converts a multi-locale translations map to a flat single-locale map,
+   * with optional support for fallback locales.
+   *
+   * ```
+   * const multiLocaleStrings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'}
+   * };
+   * translationsDoc.toSingleLocaleMap(multiLocaleStrings, ['es']);
+   * // =>
+   * // {
+   * //   "one": "uno",
+   * //   "two": "dos",
+   * // }
+   * ```
+   */
+  toSingleLocaleMap(multiLocaleStrings, fallbackLocales) {
+    const singleLocaleStrings = {};
+    Object.entries(multiLocaleStrings).forEach(([source, translations]) => {
+      let translation = source;
+      for (const locale of fallbackLocales) {
+        if (translations[locale]) {
+          translation = translations[locale];
+          break;
+        }
+      }
+      singleLocaleStrings[source] = translation;
+    });
+    return singleLocaleStrings;
+  }
+  /**
+   * Converts a multi-locale translations map to a single-locale hashed version,
+   * used for storage in in the DB.
+   *
+   * ```
+   * const multiLocaleStrings = {
+   *   'one': {es: 'uno', fr: 'un'},
+   *   'two': {es: 'dos', fr: 'deux'}
+   * };
+   * translationsDoc.toLocaleDocHashMap(multiLocaleStrings, 'es');
+   * // =>
+   * // {
+   * //   "<hash1>": {"source": "one", "translation": "uno"},
+   * //   "<hash2>": {"source": "two", "translation": "dos"},
+   * // }
+   * ```
+   *
+   * One reason for using hashes is because the DB has limits on the number of
+   * chars that can be used as the "key" in a object map.
+   */
+  toLocaleDocHashMap(multiLocaleStrings, locale) {
+    const hashMap = {};
+    Object.entries(multiLocaleStrings).forEach(([source, translations]) => {
+      const translation = translations[locale];
+      if (translation) {
+        const hash = hashStr(source);
+        hashMap[hash] = { source, translation };
+      }
+    });
+    return hashMap;
+  }
+  /**
+   * Import translations from the v1 system to the TranslationsManager.
+   */
+  async importTranslationsFromV1() {
+    var _a;
+    const projectId = this.cmsClient.projectId;
+    const db = this.cmsClient.db;
+    const dbPath = `Projects/${projectId}/Translations`;
+    const query = db.collection(dbPath);
+    const querySnapshot = await query.get();
+    if (querySnapshot.size === 0) {
+      return;
+    }
+    console.log(
+      "[root cms] importing v1 Translations to v2 TranslationsManager"
+    );
+    const translationsDocs = {};
+    querySnapshot.forEach((doc) => {
+      const translation = doc.data();
+      const source = this.cmsClient.normalizeString(translation.source);
+      delete translation.source;
+      const tags = translation.tags || [];
+      delete translation.tags;
+      for (const tag of tags) {
+        if (tag.includes("/")) {
+          const translationsId = tag;
+          translationsDocs[translationsId] ??= {
+            id: translationsId,
+            tags,
+            strings: {}
+          };
+          translationsDocs[translationsId].strings[source] = translation;
+        }
+      }
+    });
+    if (Object.keys(translationsDocs).length === 0) {
+      console.log("[root cms] no v1 translations to save");
+      return;
+    }
+    for (const docId in translationsDocs) {
+      const [collection2, slug] = docId.split("/");
+      if (collection2 && slug) {
+        const doc = await this.cmsClient.getDoc(collection2, slug, {
+          mode: "draft"
+        });
+        const linkedSheet = (_a = doc == null ? void 0 : doc.sys) == null ? void 0 : _a.l10nSheet;
+        if (linkedSheet) {
+          translationsDocs[docId].sys.linkedSheet = linkedSheet;
+        }
+      }
+    }
+    Object.entries(translationsDocs).forEach(([translationsId, data]) => {
+      const len = Object.keys(data.strings).length;
+      console.log(`[root cms] saving ${len} string(s) to ${translationsId}...`);
+      this.saveTranslations(translationsId, data.strings, {
+        tags: data.tags || [translationsId]
+      });
+    });
+  }
+};
+function buildTranslationsDbPath(options) {
+  return TRANSLATIONS_DB_PATH_FORMAT.replace(
+    "{project}",
+    options.project
+  ).replace("{mode}", options.mode);
+}
+function buildTranslationsLocaleDocDbPath(options) {
+  return TRANSLATIONS_LOCALE_DOC_DB_PATH_FORMAT.replace(
+    "{project}",
+    options.project
+  ).replace("{mode}", options.mode).replace("{id}", options.id.replaceAll("/", "--")).replace("{locale}", options.locale);
+}
+
+// core/client.ts
 var RootCMSClient = class {
   constructor(rootConfig) {
     this.rootConfig = rootConfig;
@@ -63,9 +414,9 @@ var RootCMSClient = class {
       slug,
       sys: {
         ...draftSys,
-        createdAt: draftSys.createdAt ?? Timestamp.now(),
+        createdAt: draftSys.createdAt ?? Timestamp2.now(),
         createdBy: draftSys.createdBy ?? modifiedBy,
-        modifiedAt: Timestamp.now(),
+        modifiedAt: Timestamp2.now(),
         modifiedBy,
         locales: (options == null ? void 0 : options.locales) ?? draftSys.locales ?? ["en"]
       },
@@ -173,7 +524,7 @@ var RootCMSClient = class {
       const publishedRef = this.db.doc(
         `${projectCollectionsPath}/${collection2}/Published/${slug}`
       );
-      const firstPublishedAt = sys.firstPublishedAt ?? FieldValue.serverTimestamp();
+      const firstPublishedAt = sys.firstPublishedAt ?? FieldValue2.serverTimestamp();
       const firstPublishedBy = sys.firstPublishedBy ?? publishedBy;
       batch.set(publishedRef, {
         id,
@@ -184,7 +535,7 @@ var RootCMSClient = class {
           ...sys,
           firstPublishedAt,
           firstPublishedBy,
-          publishedAt: FieldValue.serverTimestamp(),
+          publishedAt: FieldValue2.serverTimestamp(),
           publishedBy
         }
       });
@@ -192,11 +543,11 @@ var RootCMSClient = class {
       batch.delete(scheduledRef);
       batchCount += 1;
       batch.update(draftRef, {
-        "sys.scheduledAt": FieldValue.delete(),
-        "sys.scheduledBy": FieldValue.delete(),
+        "sys.scheduledAt": FieldValue2.delete(),
+        "sys.scheduledBy": FieldValue2.delete(),
         "sys.firstPublishedAt": firstPublishedAt,
         "sys.firstPublishedBy": firstPublishedBy,
-        "sys.publishedAt": FieldValue.serverTimestamp(),
+        "sys.publishedAt": FieldValue2.serverTimestamp(),
         "sys.publishedBy": publishedBy
       });
       batchCount += 1;
@@ -270,7 +621,7 @@ var RootCMSClient = class {
           ...sys,
           firstPublishedAt,
           firstPublishedBy,
-          publishedAt: FieldValue.serverTimestamp(),
+          publishedAt: FieldValue2.serverTimestamp(),
           publishedBy: scheduledBy || ""
         }
       });
@@ -278,11 +629,11 @@ var RootCMSClient = class {
       batch.delete(scheduledRef);
       batchCount += 1;
       batch.update(draftRef, {
-        "sys.scheduledAt": FieldValue.delete(),
-        "sys.scheduledBy": FieldValue.delete(),
+        "sys.scheduledAt": FieldValue2.delete(),
+        "sys.scheduledBy": FieldValue2.delete(),
         "sys.firstPublishedAt": firstPublishedAt,
         "sys.firstPublishedBy": firstPublishedBy,
-        "sys.publishedAt": FieldValue.serverTimestamp(),
+        "sys.publishedAt": FieldValue2.serverTimestamp(),
         "sys.publishedBy": scheduledBy || "root-cms-client"
       });
       batchCount += 1;
@@ -305,17 +656,17 @@ var RootCMSClient = class {
   async publishScheduledReleases() {
     const releasesPath = `Projects/${this.projectId}/Releases`;
     const now = Math.ceil((/* @__PURE__ */ new Date()).getTime());
-    const query = this.db.collection(releasesPath).where("scheduledAt", "<=", Timestamp.fromMillis(now));
+    const query = this.db.collection(releasesPath).where("scheduledAt", "<=", Timestamp2.fromMillis(now));
     const querySnapshot = await query.get();
     for (const snapshot of querySnapshot.docs) {
       const release = snapshot.data();
       const batch = this.db.batch();
       const publishedBy = release.scheduledBy || "root-cms-client";
       batch.update(snapshot.ref, {
-        publishedAt: Timestamp.now(),
+        publishedAt: Timestamp2.now(),
         publishedBy,
-        scheduledAt: FieldValue.delete(),
-        scheduledBy: FieldValue.delete()
+        scheduledAt: FieldValue2.delete(),
+        scheduledBy: FieldValue2.delete()
       });
       await this.publishDocs(release.docIds || [], { publishedBy, batch });
     }
@@ -327,7 +678,7 @@ var RootCMSClient = class {
     var _a;
     if ((_a = doc.sys) == null ? void 0 : _a.publishingLocked) {
       if (doc.sys.publishingLocked.until) {
-        const now = Timestamp.now().toMillis();
+        const now = Timestamp2.now().toMillis();
         const until = doc.sys.publishingLocked.until.toMillis();
         return now < until;
       }
@@ -335,6 +686,30 @@ var RootCMSClient = class {
     }
     return false;
   }
+  /**
+   * Returns a `TranslationsManager` object for managing translations.
+   *
+   * To get translations:
+   * ```
+   * await tm.loadTranslations({
+   *   ids: ['Global/strings', 'Pages/index'],
+   *   locales: ['es'],
+   * });
+   * ```
+   *
+   * NOTE: The `TranslationsManager` is a v2 feature that will eventually
+   * replace the v1 translations system.
+   */
+  getTranslationsManager() {
+    var _a;
+    const cmsPluginOptions = this.cmsPlugin.getConfig();
+    if ((_a = cmsPluginOptions.experiments) == null ? void 0 : _a.v2TranslationsManager) {
+      throw new Error(
+        "`v2TranslationsManager` is not enabled. update root.config.ts and add: `{experiments: {v2TranslationsManager: true}}`"
+      );
+    }
+    return new TranslationsManager(this);
+  }
   /**
    * Loads translations saved in the translations collection, optionally
    * filtered by tag.
@@ -380,7 +755,7 @@ var RootCMSClient = class {
         source: this.normalizeString(source)
       };
       if (tags) {
-        data.tags = FieldValue.arrayUnion(...tags);
+        data.tags = FieldValue2.arrayUnion(...tags);
       }
       batch.set(translationRef, data, { merge: true });
       batchCount += 1;
@@ -451,7 +826,7 @@ var RootCMSClient = class {
     const syncedBy = (options == null ? void 0 : options.syncedBy) || "root-cms-client";
     const updatedDataSource = {
       ...dataSource,
-      syncedAt: Timestamp.now(),
+      syncedAt: Timestamp2.now(),
       syncedBy
     };
     const batch = this.db.batch();
@@ -460,7 +835,7 @@ var RootCMSClient = class {
       data
     });
     batch.update(dataSourceDocRef, {
-      syncedAt: Timestamp.now(),
+      syncedAt: Timestamp2.now(),
       syncedBy
     });
     await batch.commit();
@@ -485,7 +860,7 @@ var RootCMSClient = class {
     const publishedBy = (options == null ? void 0 : options.publishedBy) || "root-cms-client";
     const updatedDataSource = {
       ...dataSource,
-      publishedAt: Timestamp.now(),
+      publishedAt: Timestamp2.now(),
       publishedBy
     };
     const batch = this.db.batch();
@@ -497,7 +872,7 @@ var RootCMSClient = class {
       dataSource: updatedDataSource
     });
     batch.update(dataSourceDocRef, {
-      publishedAt: Timestamp.now(),
+      publishedAt: Timestamp2.now(),
       publishedBy
     });
     await batch.commit();
@@ -604,7 +979,7 @@ var RootCMSClient = class {
     }
     const data = {
       action,
-      timestamp: Timestamp.now(),
+      timestamp: Timestamp2.now(),
       by: (options == null ? void 0 : options.by) || "system",
       metadata: (options == null ? void 0 : options.metadata) || {}
     };
@@ -768,7 +1143,7 @@ function parseDocId(docId) {
 }
 
 // core/runtime.ts
-import { FieldValue as FieldValue2 } from "firebase-admin/firestore";
+import { FieldValue as FieldValue3 } from "firebase-admin/firestore";
 async function getDoc(rootConfig, collectionId, slug, options) {
   const cmsPlugin = getCmsPlugin(rootConfig);
   const cmsPluginOptions = cmsPlugin.getConfig();
@@ -890,7 +1265,7 @@ async function publishScheduledDocs(rootConfig) {
         ...sys,
         firstPublishedAt,
         firstPublishedBy,
-        publishedAt: FieldValue2.serverTimestamp(),
+        publishedAt: FieldValue3.serverTimestamp(),
         publishedBy: scheduledBy || ""
       }
     });
@@ -898,11 +1273,11 @@ async function publishScheduledDocs(rootConfig) {
     batch.delete(scheduledRef);
     batchCount += 1;
     batch.update(draftRef, {
-      "sys.scheduledAt": FieldValue2.delete(),
-      "sys.scheduledBy": FieldValue2.delete(),
+      "sys.scheduledAt": FieldValue3.delete(),
+      "sys.scheduledBy": FieldValue3.delete(),
       "sys.firstPublishedAt": firstPublishedAt,
       "sys.firstPublishedBy": firstPublishedBy,
-      "sys.publishedAt": FieldValue2.serverTimestamp(),
+      "sys.publishedAt": FieldValue3.serverTimestamp(),
       "sys.publishedBy": scheduledBy || ""
     });
     batchCount += 1;
@@ -1012,6 +1387,9 @@ function defineCollection(collection2) {
 var collection = defineCollection;
 export {
   RootCMSClient,
+  TranslationsManager,
+  buildTranslationsDbPath,
+  buildTranslationsLocaleDocDbPath,
   getCmsPlugin,
   getDoc,
   isRichTextData,