@blinkk/root-cms 3.0.1 → 3.0.3

package/dist/core/client.d.ts

@@ -0,0 +1,715 @@
+import { type RootConfig } from '@blinkk/root';
+import { App } from 'firebase-admin/app';
+import { Firestore, Query, Timestamp, WriteBatch } from 'firebase-admin/firestore';
+import { CMSPlugin } from './plugin.js';
+import { Collection } from './schema.js';
+import { TranslationsManager } from './translations-manager.js';
+export interface Doc<Fields = any> {
+    /** The id of the doc, e.g. "Pages/foo-bar". */
+    id: string;
+    /** The collection id of the doc, e.g. "Pages". */
+    collection: string;
+    /** The slug of the doc, e.g. "foo-bar". */
+    slug: string;
+    sys: {
+        createdAt: number;
+        createdBy: string;
+        modifiedAt: number;
+        modifiedBy: string;
+        firstPublishedAt?: number;
+        firstPublishedBy?: string;
+        publishedAt?: number;
+        publishedBy?: string;
+        publishingLocked: {
+            lockedAt: string;
+            lockedBy: string;
+            reason: string;
+            until?: Timestamp;
+        };
+        locales?: string[];
+    };
+    fields: Fields;
+}
+export type DocMode = 'draft' | 'published';
+export type UserRole = 'ADMIN' | 'EDITOR' | 'CONTRIBUTOR' | 'VIEWER';
+export type HttpMethod = 'GET' | 'POST';
+export type CronUnit = 'minutes' | 'hours' | 'days';
+export interface DataSourceCron {
+    enabled: boolean;
+    interval: number;
+    unit: CronUnit;
+    autoPublish?: boolean;
+}
+export interface DataSource {
+    id: string;
+    description?: string;
+    type: 'http' | 'gsheet';
+    url: string;
+    /**
+     * Currently only used by gsheet. `array` returns the sheet as an array of
+     * arrays, `map` returns the sheet as an array of objects.
+     */
+    dataFormat?: 'array' | 'map';
+    /**
+     * Options for HTTP requests.
+     */
+    httpOptions?: {
+        method: HttpMethod;
+        headers?: Record<string, string>;
+        body?: string;
+    };
+    cron?: DataSourceCron;
+    createdAt: Timestamp;
+    createdBy: string;
+    syncedAt?: Timestamp;
+    syncedBy?: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+    archivedAt?: Timestamp;
+    archivedBy?: string;
+}
+export interface DataSourceData<T = any> {
+    dataSource: DataSource;
+    data: T;
+    /** Optional list of column headers (for gsheet sources). */
+    headers?: string[];
+}
+export type DataSourceMode = 'draft' | 'published';
+export interface GetDocOptions {
+    /** Mode, either "draft" or "published". */
+    mode: DocMode;
+}
+export interface SetDocOptions {
+    /** Mode, either "draft" or "published". */
+    mode: DocMode;
+}
+export interface SaveDraftOptions {
+    /**
+     * Locales to enable.
+     */
+    locales?: string[];
+    /**
+     * Email of user modifying the doc. If blank, defaults to `root-cms-client`.
+     */
+    modifiedBy?: string;
+    /**
+     * Whether to validate fieldsData against the collection schema before saving.
+     * If validation fails, an error will be thrown with details about the validation errors.
+     */
+    validate?: boolean;
+}
+export interface UpdateDraftOptions {
+    /**
+     * Whether to validate the updated field against the collection schema.
+     * If validation fails, an error will be thrown with details about the validation errors.
+     */
+    validate?: boolean;
+}
+export interface ListDocsOptions {
+    mode: DocMode;
+    offset?: number;
+    limit?: number;
+    orderBy?: string;
+    orderByDirection?: 'asc' | 'desc';
+    query?: (query: Query) => Query;
+    /**
+     * Whether to fetch the "raw" version of the doc (for use in conjunction with
+     * `setRawDoc()`).
+     */
+    raw?: boolean;
+}
+export interface GetCountOptions {
+    mode: DocMode;
+    query?: (query: Query) => Query;
+}
+export interface Translation {
+    [locale: string]: string;
+    source: string;
+}
+export interface TranslationsMap {
+    [hash: string]: Translation;
+}
+export interface LocaleTranslations {
+    [source: string]: string;
+}
+export interface LoadTranslationsOptions {
+    tags?: string[];
+}
+export interface Release {
+    id: string;
+    description?: string;
+    docIds?: string[];
+    dataSourceIds?: string[];
+    createdAt?: Timestamp;
+    createdBy?: string;
+    scheduledAt?: Timestamp;
+    scheduledBy?: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+}
+export interface Action<T = any> {
+    /**
+     * The name of the action.
+     */
+    action: string;
+    /**
+     * The user's email that performed the action (or "system").
+     */
+    by?: string;
+    /**
+     * Timestamp when the action occurred.
+     */
+    timestamp: Timestamp;
+    /**
+     * Metadata for the action.
+     */
+    metadata?: T;
+    /**
+     * Optional list of quick links to display in the UI.
+     */
+    links?: {
+        label: string;
+        url: string;
+        target?: string;
+    }[];
+}
+export interface ListActionsOptions {
+    /**
+     * Filter by a specific action. Defaults to all actions.
+     */
+    action?: string;
+    /**
+     * Filter by a specific user. Defaults to all users.
+     */
+    by?: string;
+    /**
+     * Max number of actions to return. Defaults to 100.
+     */
+    limit?: number;
+}
+export declare class RootCMSClient {
+    readonly rootConfig: RootConfig;
+    readonly cmsPlugin: CMSPlugin;
+    readonly projectId: string;
+    readonly app: App;
+    readonly db: Firestore;
+    constructor(rootConfig: RootConfig);
+    /**
+     * Converts a doc mode to the Firestore collection name.
+     */
+    private getModeCollection;
+    /**
+     * Retrieves doc data from Root.js CMS.
+     */
+    getDoc<Fields = any>(collectionId: string, slug: string, options: GetDocOptions): Promise<Doc<Fields> | null>;
+    /**
+     * Retrieves raw doc data as stored in the database. Only use this if you know
+     * 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, FirebaseFirestore.DocumentData>;
+    /**
+     * Returns a collection's schema definition as defined in
+     * `/collections/<id>.schema.ts`.
+     */
+    getCollection(collectionId: string): Promise<Collection | null>;
+    /**
+     * Saves draft data to a doc.
+     *
+     * Note: this saves data to the "fields" attr of the draft doc. If you need to
+     * modify the sys-level attributes of the doc, use `setRawDoc()`.
+     */
+    saveDraftData(docId: string, fieldsData: any, options?: SaveDraftOptions): Promise<void>;
+    /**
+     * Updates a specific field path in a draft doc.
+     *
+     * This allows partial updates to nested fields without replacing the entire document.
+     * For example: `updateDraftData('Pages/home', 'hero.title', 'New Title')`
+     *
+     * @param docId - The document ID (e.g., 'Pages/home')
+     * @param path - JSON path to the field (e.g., 'hero.title' or 'content.0.text')
+     * @param fieldValue - The value to set at the specified path
+     * @param options - Update options including validation
+     */
+    updateDraftData(docId: string, path: string, fieldValue: any, options?: UpdateDraftOptions): Promise<void>;
+    /**
+     * Sets the raw document data directly in Firestore.
+     *
+     * CAUTION Prefer using `saveDraftData('Pages/foo', data)` in most cases.
+     * Only use this method if you need to manipulate system-level (sys) fields
+     * directly or if you're implementing low-level data operations.
+     *
+     * ## Validation & Normalization
+     *
+     * This method automatically validates and normalizes `sys` fields to prevent
+     * data integrity issues that can cause runtime errors like
+     * "e.toMillis is not a function".
+     *
+     * ### Timestamp Fields (auto-converted)
+     * The following fields accept multiple formats and are automatically converted
+     * to Firestore Timestamp objects:
+     * - `sys.createdAt`
+     * - `sys.modifiedAt`
+     * - `sys.publishedAt`
+     * - `sys.firstPublishedAt`
+     *
+     * Accepted formats:
+     * - Firestore `Timestamp` object (unchanged)
+     * - `number` - Interpreted as milliseconds since epoch, converted to Timestamp
+     * - `Date` object - Converted to Timestamp
+     *
+     * ### Required Fields (auto-populated with defaults if missing)
+     * - `sys.createdAt` - Defaults to current time if not provided
+     * - `sys.modifiedAt` - Defaults to current time if not provided
+     * - `sys.createdBy` - Defaults to 'root-cms-client' if not provided
+     * - `sys.modifiedBy` - Defaults to 'root-cms-client' if not provided
+     * - `sys.locales` - Defaults to ['en'] if not provided
+     *
+     * ### Optional Fields (validated if present)
+     * - `sys.publishedBy` - String identifier
+     * - `sys.firstPublishedBy` - String identifier
+     * - `sys.publishingLocked` - Object with optional `until` Timestamp
+     *
+     * ### Document Identity
+     * The `id`, `collection`, and `slug` fields are always set to match the
+     * provided parameters, overwriting any existing values to prevent data
+     * inconsistencies.
+     *
+     * @param collectionId - The collection ID (e.g., 'Pages')
+     * @param slug - The document slug (e.g., 'home')
+     * @param data - The complete document data including sys and fields
+     * @param options - Options specifying mode ('draft' or 'published')
+     *
+     * @throws {Error} If sys fields are invalid or missing required fields
+     * @throws {Error} If timestamp fields have invalid types
+     *
+     * @example
+     * ```typescript
+     * // Minimal example - sys fields use defaults
+     * await client.setRawDoc('Pages', 'home', {
+     *   sys: {},  // All sys fields will be auto-populated with defaults
+     *   fields: {
+     *     title: 'Home Page'
+     *   }
+     * }, { mode: 'draft' });
+     *
+     * // Full example - with number timestamps (auto-converted)
+     * await client.setRawDoc('Pages', 'home', {
+     *   id: 'Pages/home',
+     *   collection: 'Pages',
+     *   slug: 'home',
+     *   sys: {
+     *     createdAt: Date.now(),  // Auto-converted to Timestamp.
+     *     createdBy: 'user@example.com',
+     *     modifiedAt: Date.now(),  // Auto-converted to Timestamp.
+     *     modifiedBy: 'user@example.com',
+     *     locales: ['en', 'es']
+     *   },
+     *   fields: {
+     *     title: 'Home Page'
+     *   }
+     * }, { mode: 'draft' });
+     * ```
+     */
+    setRawDoc(collectionId: string, slug: string, data: any, options: SetDocOptions): Promise<void>;
+    /**
+     * Lists docs from a Root.js CMS collection.
+     */
+    listDocs<T>(collectionId: string, options: ListDocsOptions): Promise<{
+        docs: T[];
+    }>;
+    /**
+     * Returns the number of docs in a Root.js CMS collection.
+     */
+    getDocsCount(collectionId: string, options: GetCountOptions): Promise<number>;
+    /**
+     * Batch publishes a set of docs by id.
+     */
+    publishDocs(docIds: string[], options?: {
+        publishedBy: string;
+        batch?: WriteBatch;
+        releaseId?: string;
+    }): Promise<any[]>;
+    /**
+     * Batch unpublishes a set of docs by id.
+     */
+    unpublishDocs(docIds: string[], options?: {
+        unpublishedBy?: string;
+        batch?: WriteBatch;
+    }): Promise<any[]>;
+    /**
+     * Publishes scheduled docs.
+     */
+    publishScheduledDocs(): Promise<any[]>;
+    /**
+     * Publishes docs in scheduled releases.
+     */
+    publishScheduledReleases(): Promise<void>;
+    /**
+     * Syncs data sources that have cron scheduling enabled and are due for sync.
+     */
+    syncScheduledDataSources(): Promise<void>;
+    /**
+     * Checks if a doc is currently "locked" for publishing.
+     */
+    testPublishingLocked(doc: Doc): boolean;
+    /**
+     * 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(): TranslationsManager;
+    /**
+     * Loads translations saved in the translations collection, optionally
+     * filtered by tag.
+     *
+     * Returns a map like:
+     * ```
+     * {
+     *   "<hash>": {"source": "Hello", "es": "Hola", "fr": "Bonjour"},
+     * }
+     * ```
+     */
+    loadTranslations(options?: LoadTranslationsOptions): Promise<TranslationsMap>;
+    /**
+     * Saves a map of translations, e.g.:
+     * ```
+     * await client.saveTranslations({
+     *   "Hello": {"es": "Hola", "fr": "Bonjour"},
+     * });
+     * ```
+     */
+    saveTranslations(translations: {
+        [source: string]: {
+            [locale: string]: string;
+        };
+    }, tags?: string[]): Promise<void>;
+    /**
+     * Returns the "key" used for a translation as stored in the db. Translations
+     * are stored under `Projects/<project id>/Translations/<sha1 hash>`.
+     */
+    getTranslationKey(source: string): string;
+    /**
+     * Cleans a string that's used for translations. Performs the following:
+     * - Removes any leading/trailing whitespace
+     * - Removes spaces at the end of any line
+     */
+    normalizeString(str: string): string;
+    /**
+     * Loads translations for a particular locale.
+     *
+     * Returns a map like:
+     * ```
+     * {
+     *   "Hello": "Bonjour",
+     * }
+     * ```
+     */
+    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, FirebaseFirestore.DocumentData>;
+    /**
+     * Returns a data source configuration object.
+     */
+    getDataSource(dataSourceId: string): Promise<DataSource | null>;
+    /**
+     * Archives a data source. Archived data sources cannot be synced or published.
+     */
+    archiveDataSource(dataSourceId: string, options?: {
+        archivedBy?: string;
+    }): Promise<void>;
+    /**
+     * Unarchives a data source.
+     */
+    unarchiveDataSource(dataSourceId: string): Promise<void>;
+    /**
+     * Syncs a data source to draft state.
+     */
+    syncDataSource(dataSourceId: string, options?: {
+        syncedBy?: string;
+    }): Promise<void>;
+    publishDataSource(dataSourceId: string, options?: {
+        publishedBy?: string;
+    }): Promise<void>;
+    /**
+     * Unpublishes a data source. Removes the `publishedAt`/`publishedBy`
+     * metadata from the DataSource doc and deletes the `Data/published` doc.
+     */
+    unpublishDataSource(dataSourceId: string): Promise<void>;
+    publishDataSources(dataSourceIds: string[], options?: {
+        publishedBy: string;
+        batch?: WriteBatch;
+        commitBatch?: boolean;
+    }): Promise<void>;
+    private fetchData;
+    private fetchHttpData;
+    /**
+     * Fetches data from a Google Sheet using the Google Sheets API v4.
+     *
+     * ## Setup
+     *
+     * For the server-side service account to access the Google Sheet:
+     *
+     * 1. **Enable the Google Sheets API** in the Google Cloud Console for the
+     *    project associated with the service account.
+     *    https://console.cloud.google.com/apis/library/sheets.googleapis.com
+     *
+     * 2. **Share the Google Sheet** with the service account's email address
+     *    (e.g. `my-service-account@my-project.iam.gserviceaccount.com`).
+     *    Open the sheet in Google Sheets, click "Share", and add the service
+     *    account email as a Viewer.
+     *
+     *    - For **App Engine**: the service account email is typically
+     *      `<project-id>@appspot.gserviceaccount.com`.
+     *    - For **Cloud Run**: check the service account configured for the
+     *      Cloud Run service in the Google Cloud Console.
+     *    - For **local development**: use the service account email from the
+     *      JSON key file specified in `GOOGLE_APPLICATION_CREDENTIALS`.
+     */
+    private fetchGsheetData;
+    /**
+     * Fetches data from a data source.
+     */
+    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, FirebaseFirestore.DocumentData>;
+    /**
+     * Gets the user's role from the project's ACL.
+     */
+    getUserRole(email: string): Promise<UserRole | null>;
+    /**
+     * Verifies user exists in the ACL list.
+     */
+    userExistsInAcl(email: string): Promise<boolean>;
+    /**
+     * Lists action logs from the database.
+     */
+    listActions(options?: ListActionsOptions): Promise<Action[]>;
+    logAction(action: string, options?: {
+        by?: string;
+        metadata?: any;
+        links?: {
+            label: string;
+            url: string;
+            target?: string;
+        }[];
+    }): 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.
+ */
+export declare function isRichTextData(data: any): boolean;
+export declare function getCmsPlugin(rootConfig: RootConfig): CMSPlugin;
+/**
+ * Walks the data tree and converts any array of objects into "array objects"
+ * for storage in firestore.
+ */
+export declare function marshalData(data: any): any;
+/**
+ * Walks the data tree and converts any Timestamp objects to millis and any
+ * _array maps to normal arrays.
+ *
+ * E.g.:
+ *
+ * normalizeData({
+ *   sys: {modifiedAt: Timestamp(123)},
+ *   fields: {
+ *     _array: ['asdf'],
+ *     asdf: {title: 'hello'}
+ *   }
+ * })
+ * // => {sys: {modifiedAt: 123}, fields: {foo: [{title: 'hello'}]}}
+ */
+export declare function unmarshalData(data: any): any;
+/** @deprecated Use `unmarshalData()` instead. */
+export declare function normalizeData(data: any): any;
+export interface ArrayObject {
+    [key: string]: any;
+    _array: string[];
+}
+/**
+ * Serializes an array into an `ArrayObject`, e.g.:
+ *
+ * ```
+ * marshalArray([1, 2, 3])
+ * // => {a: 1, b: 2, c: 3, _array: ['a', 'b', 'c']}
+ * ```
+ *
+ * This database storage method makes it easier to update a single field in a
+ * deeply nested array object.
+ */
+export declare function toArrayObject(arr: any[]): ArrayObject;
+export declare const marshalArray: typeof toArrayObject;
+/**
+ * Converts an `ArrayObject` to a normal array.
+ */
+export declare function unmarshalArray(arrObject: ArrayObject): any[];
+/**
+ * Converts a translations map from `loadTranslations()` to a map of source to
+ * translated string for a particular locale.
+ *
+ * Returns a map like:
+ * ```
+ * {
+ *   "Hello": "Bonjour",
+ * }
+ * ```
+ */
+export declare function translationsForLocale(translationsMap: TranslationsMap, locale: string): LocaleTranslations;
+/**
+ * Parses a docId (e.g. `Pages/foo`) and returns the `collection` and `slug`.
+ */
+export declare function parseDocId(docId: string): {
+    collection: string;
+    slug: string;
+};
+export interface BatchRequestOptions {
+    mode: 'draft' | 'published';
+    /**
+     * Whether to automatically fetch translations for the docs retrieved in the
+     * request.
+     */
+    translate?: boolean;
+}
+export interface BatchRequestQuery {
+    queryId: string;
+    collectionId: string;
+    queryOptions?: BatchRequestQueryOptions;
+}
+export interface BatchRequestQueryOptions {
+    offset?: number;
+    limit?: number;
+    orderBy?: string;
+    orderByDirection?: 'asc' | 'desc';
+    query?: (query: Query) => Query;
+}
+export 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;
+}
+export 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;
+}
+export 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;
+}