@blinkk/root-cms 1.4.6 → 1.4.8

package/dist/app.js

@@ -7,7 +7,7 @@ import { render as renderToString } from "preact-render-to-string";
 // package.json
 var package_default = {
   name: "@blinkk/root-cms",
-  version: "1.4.6",
+  version: "1.4.8",
   author: "s@blinkk.com",
   license: "MIT",
   engines: {
@@ -140,7 +140,7 @@ var package_default = {
     vitest: "0.34.6"
   },
   peerDependencies: {
-    "@blinkk/root": "1.4.6",
+    "@blinkk/root": "1.4.8",
     "firebase-admin": ">=11",
     "firebase-functions": ">=4",
     preact: ">=10",

package/dist/{client-c_QAurxr.d.ts → client-AE0BYn69.d.ts}

@@ -377,6 +377,8 @@ interface DataSource {
 interface DataSourceData<T = any> {
     dataSource: DataSource;
     data: T;
+    /** Optional list of column headers (for gsheet sources). */
+    headers?: string[];
 }
 type DataSourceMode = 'draft' | 'published';
 interface GetDocOptions {
@@ -486,6 +488,24 @@ declare class RootCMSClient {
      * what you are doing.
      */
     getRawDoc(collectionId: string, slug: string, options: GetDocOptions): Promise<any | null>;
+    /**
+     * Firestore path for a collection.
+     */
+    dbCollectionDocsPath(collectionId: string, options: {
+        mode: 'draft' | 'published';
+    }): string;
+    /**
+     * Firestore path for a content doc.
+     */
+    dbDocPath(collectionId: string, slug: string, options: {
+        mode: 'draft' | 'published';
+    }): string;
+    /**
+     * Firestore doc ref for a content doc.
+     */
+    dbDocRef(collectionId: string, slug: string, options: {
+        mode: 'draft' | 'published';
+    }): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData>;
     /**
      * Saves draft data to a doc.
      *
@@ -589,6 +609,18 @@ declare class RootCMSClient {
      * ```
      */
     loadTranslationsForLocale(locale: string, options?: LoadTranslationsOptions): Promise<LocaleTranslations>;
+    /**
+     * Firestore path for a translations file.
+     */
+    dbTranslationsPath(translationsId: string, options: {
+        mode: 'draft' | 'published';
+    }): string;
+    /**
+     * Firestore doc ref for a translations file.
+     */
+    dbTranslationsRef(translationsId: string, options: {
+        mode: 'draft' | 'published';
+    }): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData>;
     /**
      * Returns a data source configuration object.
      */
@@ -610,6 +642,18 @@ declare class RootCMSClient {
     getFromDataSource<T = any>(dataSourceId: string, options?: {
         mode?: 'draft' | 'published';
     }): Promise<DataSourceData<T> | null>;
+    /**
+     * Firestore path for a datasource data.
+     */
+    dbDataSourceDataPath(dataSourceId: string, options: {
+        mode: 'draft' | 'published';
+    }): string;
+    /**
+     * Firestore doc ref for a datasource data.
+     */
+    dbDataSourceDataRef(dataSourceId: string, options: {
+        mode: 'draft' | 'published';
+    }): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData>;
     /**
      * Gets the user's role from the project's ACL.
      */
@@ -622,6 +666,11 @@ declare class RootCMSClient {
         by?: string;
         metadata?: any;
     }): Promise<void>;
+    /**
+     * Creates a batch request that is capable of fetching one or more docs,
+     * corresponding translations, and dataSources.
+     */
+    createBatchRequest(options: BatchRequestOptions): BatchRequest;
 }
 /**
  * Returns true if the `data` is a rich text data object.
@@ -691,5 +740,102 @@ declare function parseDocId(docId: string): {
     collection: string;
     slug: string;
 };
+interface BatchRequestOptions {
+    mode: 'draft' | 'published';
+    /**
+     * Whether to automatically fetch translations for the docs retrieved in the
+     * request.
+     */
+    translate?: boolean;
+}
+interface BatchRequestQuery {
+    queryId: string;
+    collectionId: string;
+    queryOptions?: BatchRequestQueryOptions;
+}
+interface BatchRequestQueryOptions {
+    offset?: number;
+    limit?: number;
+    orderBy?: string;
+    orderByDirection?: 'asc' | 'desc';
+    query?: (query: Query) => Query;
+}
+interface TranslationsDoc {
+    id: string;
+    sys: {
+        modifiedAt: Timestamp;
+        modifiedBy: string;
+        publishedAt?: Timestamp;
+        publishedBy?: string;
+        linkedSheet?: {
+            spreadsheetId: string;
+            gid: number;
+            linkedAt: Timestamp;
+            linkedBy: string;
+        };
+        tags?: string[];
+    };
+    strings: TranslationsMap;
+}
+declare class BatchRequest {
+    cmsClient: RootCMSClient;
+    private options;
+    private db;
+    private docIds;
+    private dataSourceIds;
+    private queries;
+    private translationsIds;
+    constructor(cmsClient: RootCMSClient, options: BatchRequestOptions);
+    /**
+     * Adds a doc to the batch request.
+     */
+    addDoc(docId: string): void;
+    /**
+     * Adds a data source to the batch request.
+     */
+    addDataSource(dataSourceId: string): void;
+    /**
+     * Adds a collection-based query to the batch request.
+     */
+    addQuery(queryId: string, collectionId: string, queryOptions?: BatchRequestQueryOptions): void;
+    /**
+     * Adds a translation file to the request.
+     */
+    addTranslations(translationsId: string): void;
+    /**
+     * Fetches data from the DB.
+     */
+    fetch(): Promise<BatchResponse>;
+    private fetchDocs;
+    private fetchQueries;
+    private fetchDataSources;
+    private fetchTranslations;
+}
+declare class BatchResponse {
+    docs: Record<string, Doc>;
+    queries: Record<string, Doc[]>;
+    dataSources: Record<string, DataSourceData>;
+    translations: Record<string, TranslationsDoc>;
+    /**
+     * Returns a map of translations for a given locale or locale fallbacks.
+     *
+     * The input is either a single locale (e.g. "de") or an array of locales
+     * representing the fallback tree, e.g. ["en-CA", "en-GB", "en"].
+     *
+     * TODO(stevenle): support the locale fallback tree.
+     *
+     * The returned value is a flat map of source string to translated string,
+     * e.g.:
+     * {"<source>": "<translation>"}
+     */
+    getTranslations(locale: string): LocaleTranslations;
+    /**
+     * Merges the strings from all translations files retrieved in the request.
+     * The returned value is a map of string to translations, e.g.:
+     *
+     * {"<hash>": {"source": "<source>", "<locale>": "<translation>"}}
+     */
+    private getTranslationsMap;
+}
 
-export { type Action as A, type TranslationsLocaleDocHashMap as B, type TranslationsLocaleDocEntry as C, type Doc as D, type SingleLocaleTranslationsMap as E, TranslationsManager as F, type GetDocOptions as G, type HttpMethod as H, buildTranslationsDbPath as I, buildTranslationsLocaleDocDbPath as J, type CMSUser as K, type LoadTranslationsOptions as L, type MultiLocaleTranslationsMap as M, type CMSAIConfig as N, type CMSSidebarTool as O, type CMSPluginOptions as P, type CMSPlugin as Q, type Release as R, type SetDocOptions as S, type TranslationsMap as T, type UserRole as U, cmsPlugin as V, type LocaleTranslations as a, type DocMode as b, type DataSource as c, type DataSourceData as d, type DataSourceMode as e, type SaveDraftOptions as f, type ListDocsOptions as g, type GetCountOptions as h, type Translation as i, type ListActionsOptions as j, RootCMSClient as k, isRichTextData as l, getCmsPlugin as m, marshalData as n, normalizeData as o, type ArrayObject as p, marshalArray as q, unmarshalArray as r, translationsForLocale as s, toArrayObject as t, unmarshalData as u, parseDocId as v, type Locale as w, type SourceString as x, type TranslatedString as y, type TranslationsDocMode as z };
+export { cmsPlugin as $, type Action as A, type BatchRequestOptions as B, BatchResponse as C, type Doc as D, type Locale as E, type SourceString as F, type GetDocOptions as G, type HttpMethod as H, type TranslatedString as I, type TranslationsDocMode as J, type TranslationsLocaleDocHashMap as K, type LoadTranslationsOptions as L, type TranslationsLocaleDocEntry as M, type MultiLocaleTranslationsMap as N, type SingleLocaleTranslationsMap as O, TranslationsManager as P, buildTranslationsDbPath as Q, type Release as R, type SetDocOptions as S, type TranslationsMap as T, type UserRole as U, buildTranslationsLocaleDocDbPath as V, type CMSUser as W, type CMSAIConfig as X, type CMSSidebarTool as Y, type CMSPluginOptions as Z, type CMSPlugin as _, type LocaleTranslations as a, type DocMode as b, type DataSource as c, type DataSourceData as d, type DataSourceMode as e, type SaveDraftOptions as f, type ListDocsOptions as g, type GetCountOptions as h, type Translation as i, type ListActionsOptions as j, RootCMSClient as k, isRichTextData as l, getCmsPlugin as m, marshalData as n, normalizeData as o, type ArrayObject as p, marshalArray as q, unmarshalArray as r, translationsForLocale as s, toArrayObject as t, unmarshalData as u, parseDocId as v, type BatchRequestQuery as w, type BatchRequestQueryOptions as x, type TranslationsDoc as y, BatchRequest as z };

package/dist/client.d.ts

@@ -1,4 +1,4 @@
 import '@blinkk/root';
 import 'firebase-admin/app';
 import 'firebase-admin/firestore';
-export { A as Action, p as ArrayObject, c as DataSource, d as DataSourceData, e as DataSourceMode, D as Doc, b as DocMode, h as GetCountOptions, G as GetDocOptions, H as HttpMethod, j as ListActionsOptions, g as ListDocsOptions, L as LoadTranslationsOptions, a as LocaleTranslations, R as Release, k as RootCMSClient, f as SaveDraftOptions, S as SetDocOptions, i as Translation, T as TranslationsMap, U as UserRole, m as getCmsPlugin, l as isRichTextData, q as marshalArray, n as marshalData, o as normalizeData, v as parseDocId, t as toArrayObject, s as translationsForLocale, r as unmarshalArray, u as unmarshalData } from './client-c_QAurxr.js';
+export { A as Action, p as ArrayObject, z as BatchRequest, B as BatchRequestOptions, w as BatchRequestQuery, x as BatchRequestQueryOptions, C as BatchResponse, c as DataSource, d as DataSourceData, e as DataSourceMode, D as Doc, b as DocMode, h as GetCountOptions, G as GetDocOptions, H as HttpMethod, j as ListActionsOptions, g as ListDocsOptions, L as LoadTranslationsOptions, a as LocaleTranslations, R as Release, k as RootCMSClient, f as SaveDraftOptions, S as SetDocOptions, i as Translation, y as TranslationsDoc, T as TranslationsMap, U as UserRole, m as getCmsPlugin, l as isRichTextData, q as marshalArray, n as marshalData, o as normalizeData, v as parseDocId, t as toArrayObject, s as translationsForLocale, r as unmarshalArray, u as unmarshalData } from './client-AE0BYn69.js';

package/dist/client.js

@@ -390,6 +390,35 @@ var RootCMSClient = class {
     }
     return null;
   }
+  /**
+   * Firestore path for a collection.
+   */
+  dbCollectionDocsPath(collectionId, options) {
+    let modeCollection = "";
+    if (options.mode === "draft") {
+      modeCollection = "Drafts";
+    } else if (options.mode === "published") {
+      modeCollection = "Published";
+    } else {
+      throw new Error(`unknown mode: ${options.mode}`);
+    }
+    return `Projects/${this.projectId}/Collections/${collectionId}/${modeCollection}`;
+  }
+  /**
+   * Firestore path for a content doc.
+   */
+  dbDocPath(collectionId, slug, options) {
+    const collectionDocsPath = this.dbCollectionDocsPath(collectionId, options);
+    const normalizedSlug = slug.replaceAll("/", "--");
+    return `${collectionDocsPath}/${normalizedSlug}`;
+  }
+  /**
+   * Firestore doc ref for a content doc.
+   */
+  dbDocRef(collectionId, slug, options) {
+    const docPath = this.dbDocPath(collectionId, slug, options);
+    return this.db.doc(docPath);
+  }
   /**
    * Saves draft data to a doc.
    *
@@ -790,6 +819,25 @@ var RootCMSClient = class {
     const translationsMap = await this.loadTranslations(options);
     return translationsForLocale(translationsMap, locale);
   }
+  /**
+   * Firestore path for a translations file.
+   */
+  dbTranslationsPath(translationsId, options) {
+    const mode = options.mode;
+    if (!(mode === "draft" || mode === "published")) {
+      throw new Error(`invalid mode: ${mode}`);
+    }
+    const slug = translationsId.replaceAll("/", "--");
+    const dbPath = `Projects/${this.projectId}/TranslationsManager/${mode}/Translations/${slug}`;
+    return dbPath;
+  }
+  /**
+   * Firestore doc ref for a translations file.
+   */
+  dbTranslationsRef(translationsId, options) {
+    const dbPath = this.dbTranslationsPath(translationsId, options);
+    return this.db.doc(dbPath);
+  }
   /**
    * Returns a data source configuration object.
    */
@@ -860,7 +908,8 @@ var RootCMSClient = class {
     const batch = this.db.batch();
     batch.set(dataDocRefPublished, {
       dataSource: updatedDataSource,
-      data: (dataRes == null ? void 0 : dataRes.data) || null
+      data: (dataRes == null ? void 0 : dataRes.data) || null,
+      ...(dataRes == null ? void 0 : dataRes.headers) ? { headers: dataRes.headers } : {}
     });
     batch.update(dataDocRefDraft, {
       dataSource: updatedDataSource
@@ -911,14 +960,34 @@ var RootCMSClient = class {
     if (!dataSourceId || dataSourceId.includes("/")) {
       throw new Error(`invalid data source id: ${dataSourceId}`);
     }
-    const dbPath = `Projects/${this.projectId}/DataSources/${dataSourceId}/Data/${mode}`;
-    const docRef = this.db.doc(dbPath);
+    const docRef = this.dbDataSourceDataRef(dataSourceId, { mode });
     const doc = await docRef.get();
     if (doc.exists) {
       return doc.data();
     }
     return null;
   }
+  /**
+   * Firestore path for a datasource data.
+   */
+  dbDataSourceDataPath(dataSourceId, options) {
+    if (!dataSourceId || dataSourceId.includes("/")) {
+      throw new Error(`invalid data source id: ${dataSourceId}`);
+    }
+    const mode = options.mode;
+    if (!(mode === "draft" || mode === "published")) {
+      throw new Error(`invalid mode: ${mode}`);
+    }
+    const dbPath = `Projects/${this.projectId}/DataSources/${dataSourceId}/Data/${mode}`;
+    return dbPath;
+  }
+  /**
+   * Firestore doc ref for a datasource data.
+   */
+  dbDataSourceDataRef(dataSourceId, options) {
+    const dbPath = this.dbDataSourceDataPath(dataSourceId, options);
+    return this.db.doc(dbPath);
+  }
   /**
    * Gets the user's role from the project's ACL.
    */
@@ -990,6 +1059,13 @@ var RootCMSClient = class {
       }
     }
   }
+  /**
+   * Creates a batch request that is capable of fetching one or more docs,
+   * corresponding translations, and dataSources.
+   */
+  createBatchRequest(options) {
+    return new BatchRequest(this, options);
+  }
 };
 function isRichTextData(data) {
   return Boolean(
@@ -1135,7 +1211,213 @@ function parseDocId(docId) {
   }
   return { collection, slug };
 }
+var BatchRequest = class {
+  constructor(cmsClient, options) {
+    this.docIds = [];
+    this.dataSourceIds = [];
+    this.queries = [];
+    this.translationsIds = [];
+    this.cmsClient = cmsClient;
+    this.db = cmsClient.db;
+    this.options = options;
+  }
+  /**
+   * Adds a doc to the batch request.
+   */
+  addDoc(docId) {
+    this.docIds.push(docId);
+  }
+  /**
+   * Adds a data source to the batch request.
+   */
+  addDataSource(dataSourceId) {
+    this.dataSourceIds.push(dataSourceId);
+  }
+  /**
+   * Adds a collection-based query to the batch request.
+   */
+  addQuery(queryId, collectionId, queryOptions) {
+    this.queries.push({
+      queryId,
+      collectionId,
+      queryOptions
+    });
+  }
+  /**
+   * Adds a translation file to the request.
+   */
+  addTranslations(translationsId) {
+    this.translationsIds.push(translationsId);
+  }
+  /**
+   * Fetches data from the DB.
+   */
+  async fetch() {
+    const res = new BatchResponse();
+    const promises = [
+      this.fetchDocs(res),
+      this.fetchQueries(res),
+      this.fetchDataSources(res)
+    ];
+    if (!this.options.translate && this.translationsIds.length > 0) {
+      promises.push(this.fetchTranslations(res));
+    }
+    await Promise.all(promises);
+    if (this.translationsIds.length > 0) {
+      await this.fetchTranslations(res);
+    }
+    return res;
+  }
+  async fetchDocs(res) {
+    if (this.docIds.length === 0) {
+      return;
+    }
+    const docRefs = this.docIds.map((docId) => {
+      const [collectionId, slug] = docId.split("/");
+      return this.cmsClient.dbDocRef(collectionId, slug, {
+        mode: this.options.mode
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.docIds.forEach((docId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        console.warn(`doc "${docId}" does not exist`);
+        return;
+      }
+      const docData = unmarshalData(doc.data());
+      res.docs[docId] = docData;
+      if (this.options.translate) {
+        this.addTranslations(docId);
+      }
+    });
+  }
+  async fetchQueries(res) {
+    if (this.queries.length === 0) {
+      return;
+    }
+    const mode = this.options.mode;
+    const handleQuery = async (queryItem) => {
+      const docsPath = this.cmsClient.dbCollectionDocsPath(
+        queryItem.collectionId,
+        { mode }
+      );
+      const queryOptions = queryItem.queryOptions || {};
+      let query = this.db.collection(docsPath);
+      if (queryOptions.limit) {
+        query = query.limit(queryOptions.limit);
+      }
+      if (queryOptions.offset) {
+        query = query.offset(queryOptions.offset);
+      }
+      if (queryOptions.orderBy) {
+        query = query.orderBy(
+          queryOptions.orderBy,
+          queryOptions.orderByDirection
+        );
+      }
+      if (queryOptions.query) {
+        query = queryOptions.query(query);
+      }
+      const results = await query.get();
+      const docs = [];
+      results.forEach((result) => {
+        const doc = unmarshalData(result.data());
+        docs.push(doc);
+      });
+      res.queries[queryItem.queryId] = docs;
+    };
+    await Promise.all(this.queries.map((queryItem) => handleQuery(queryItem)));
+  }
+  async fetchDataSources(res) {
+    if (this.dataSourceIds.length === 0) {
+      return;
+    }
+    const docRefs = this.dataSourceIds.map((dataSourceId) => {
+      return this.cmsClient.dbDataSourceDataRef(dataSourceId, {
+        mode: this.options.mode
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.dataSourceIds.forEach((dataSourceId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        console.warn(`"data source "${dataSourceId}" does not exist`);
+        return;
+      }
+      res.dataSources[dataSourceId] = doc.data();
+    });
+  }
+  async fetchTranslations(res) {
+    if (this.translationsIds.length === 0) {
+      return;
+    }
+    const docRefs = this.translationsIds.map((translationsId) => {
+      return this.cmsClient.dbTranslationsRef(translationsId, {
+        mode: this.options.mode
+      });
+    });
+    const docs = await this.db.getAll(...docRefs);
+    this.translationsIds.forEach((translationsId, i) => {
+      const doc = docs[i];
+      if (!doc.exists) {
+        return;
+      }
+      res.translations[translationsId] = doc.data();
+    });
+  }
+};
+var BatchResponse = class {
+  constructor() {
+    this.docs = {};
+    this.queries = {};
+    this.dataSources = {};
+    this.translations = {};
+  }
+  /**
+   * Returns a map of translations for a given locale or locale fallbacks.
+   *
+   * The input is either a single locale (e.g. "de") or an array of locales
+   * representing the fallback tree, e.g. ["en-CA", "en-GB", "en"].
+   *
+   * TODO(stevenle): support the locale fallback tree.
+   *
+   * The returned value is a flat map of source string to translated string,
+   * e.g.:
+   * {"<source>": "<translation>"}
+   */
+  getTranslations(locale) {
+    const translationsMap = this.getTranslationsMap();
+    const translations = translationsForLocale(translationsMap, locale);
+    return translations;
+  }
+  /**
+   * Merges the strings from all translations files retrieved in the request.
+   * The returned value is a map of string to translations, e.g.:
+   *
+   * {"<hash>": {"source": "<source>", "<locale>": "<translation>"}}
+   */
+  getTranslationsMap() {
+    const translationsDocs = Object.values(this.translations).reverse();
+    const translationsMap = {};
+    for (const translationsDoc of translationsDocs) {
+      const strings = translationsDoc.strings || {};
+      for (const hash in strings) {
+        const translations = strings[hash];
+        translationsMap[hash] ??= { source: translations.source };
+        for (const locale in translations) {
+          if (locale !== "source" && translations[locale]) {
+            translationsMap[hash][locale] = translations[locale];
+          }
+        }
+      }
+    }
+    return translationsMap;
+  }
+};
 export {
+  BatchRequest,
+  BatchResponse,
   RootCMSClient,
   getCmsPlugin,
   isRichTextData,

package/dist/core.d.ts

@@ -1,8 +1,8 @@
-import { L as LoadTranslationsOptions, T as TranslationsMap, a as LocaleTranslations } from './client-c_QAurxr.js';
-export { A as Action, p as ArrayObject, c as DataSource, d as DataSourceData, e as DataSourceMode, D as Doc, b as DocMode, h as GetCountOptions, G as GetDocOptions, H as HttpMethod, j as ListActionsOptions, g as ListDocsOptions, w as Locale, M as MultiLocaleTranslationsMap, R as Release, k as RootCMSClient, f as SaveDraftOptions, S as SetDocOptions, E as SingleLocaleTranslationsMap, x as SourceString, y as TranslatedString, i as Translation, z as TranslationsDocMode, C as TranslationsLocaleDocEntry, B as TranslationsLocaleDocHashMap, F as TranslationsManager, U as UserRole, I as buildTranslationsDbPath, J as buildTranslationsLocaleDocDbPath, m as getCmsPlugin, l as isRichTextData, q as marshalArray, n as marshalData, o as normalizeData, v as parseDocId, t as toArrayObject, s as translationsForLocale, r as unmarshalArray, u as unmarshalData } from './client-c_QAurxr.js';
+import { L as LoadTranslationsOptions, T as TranslationsMap, a as LocaleTranslations } from './client-AE0BYn69.js';
+export { A as Action, p as ArrayObject, z as BatchRequest, B as BatchRequestOptions, w as BatchRequestQuery, x as BatchRequestQueryOptions, C as BatchResponse, c as DataSource, d as DataSourceData, e as DataSourceMode, D as Doc, b as DocMode, h as GetCountOptions, G as GetDocOptions, H as HttpMethod, j as ListActionsOptions, g as ListDocsOptions, E as Locale, N as MultiLocaleTranslationsMap, R as Release, k as RootCMSClient, f as SaveDraftOptions, S as SetDocOptions, O as SingleLocaleTranslationsMap, F as SourceString, I as TranslatedString, i as Translation, y as TranslationsDoc, J as TranslationsDocMode, M as TranslationsLocaleDocEntry, K as TranslationsLocaleDocHashMap, P as TranslationsManager, U as UserRole, Q as buildTranslationsDbPath, V as buildTranslationsLocaleDocDbPath, m as getCmsPlugin, l as isRichTextData, q as marshalArray, n as marshalData, o as normalizeData, v as parseDocId, t as toArrayObject, s as translationsForLocale, r as unmarshalArray, u as unmarshalData } from './client-AE0BYn69.js';
 import { RootConfig } from '@blinkk/root';
 import { Query } from 'firebase-admin/firestore';
-export { s as schema } from './schema-hlZc-G1f.js';
+export { s as schema } from './schema-NuZy-PDV.js';
 import 'firebase-admin/app';
 import 'preact';