@blinkk/root-cms 1.0.1-alpha.0 → 1.0.1

package/dist/client.d.ts

@@ -0,0 +1,273 @@
+import { RootConfig } from '@blinkk/root';
+import { Timestamp, Query, WriteBatch } from 'firebase-admin/firestore';
+import { CMSPlugin } from './plugin.js';
+import 'firebase-admin/app';
+
+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;
+        locales?: string[];
+    };
+    fields: Fields;
+}
+type DocMode = 'draft' | 'published';
+type HttpMethod = 'GET' | 'POST';
+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;
+    };
+    createdAt: Timestamp;
+    createdBy: string;
+    syncedAt?: Timestamp;
+    syncedBy?: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+}
+interface DataSourceData<T = any> {
+    dataSource: DataSource;
+    data: T;
+}
+type DataSourceMode = 'draft' | 'published';
+interface GetDocOptions {
+    /** Mode, either "draft" or "published". */
+    mode: DocMode;
+}
+interface SetDocOptions {
+    /** Mode, either "draft" or "published". */
+    mode: DocMode;
+    /**
+     * Email of user modifying the doc. If blank, defaults to `root-cms-client`.
+     */
+    modifiedBy?: string;
+}
+interface ListDocsOptions {
+    mode: DocMode;
+    offset?: number;
+    limit?: number;
+    orderBy?: string;
+    orderByDirection?: 'asc' | 'desc';
+    query?: (query: Query) => Query;
+}
+interface GetCountOptions {
+    mode: DocMode;
+    query?: (query: Query) => Query;
+}
+interface Translation {
+    [locale: string]: string;
+    source: string;
+}
+interface TranslationsMap {
+    [hash: string]: Translation;
+}
+interface LocaleTranslations {
+    [source: string]: string;
+}
+interface LoadTranslationsOptions {
+    tags?: string[];
+}
+interface Release {
+    id: string;
+    description?: string;
+    docIds?: string[];
+    createdAt?: Timestamp;
+    createdBy?: string;
+    scheduledAt?: Timestamp;
+    scheduledBy?: string;
+    publishedAt?: Timestamp;
+    publishedBy?: string;
+}
+declare class RootCMSClient {
+    private readonly rootConfig;
+    private readonly cmsPlugin;
+    private readonly projectId;
+    private readonly app;
+    private readonly db;
+    constructor(rootConfig: RootConfig);
+    /**
+     * 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>;
+    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;
+    }): Promise<any[]>;
+    /**
+     * Publishes scheduled docs.
+     */
+    publishScheduledDocs(): Promise<any[]>;
+    /**
+     * Publishes docs in scheduled releases.
+     */
+    publishScheduledReleases(): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Returns a data source configuration object.
+     */
+    getDataSource(dataSourceId: string): Promise<DataSource | null>;
+    /**
+     * Syncs a data source to draft state.
+     */
+    syncDataSource(dataSourceId: string, options?: {
+        syncedBy?: string;
+    }): Promise<void>;
+    publishDataSource(dataSourceId: string, options?: {
+        publishedBy?: string;
+    }): Promise<void>;
+    private fetchData;
+    private fetchHttpData;
+    /**
+     * Fetches data from a data source.
+     */
+    getFromDataSource<T = any>(dataSourceId: string, options?: {
+        mode?: 'draft' | 'published';
+    }): Promise<DataSourceData<T> | null>;
+    /**
+     * Verifies user exists in the ACL list.
+     */
+    userExistsInAcl(email: string): Promise<boolean>;
+}
+declare function getCmsPlugin(rootConfig: RootConfig): CMSPlugin;
+/**
+ * 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'}]}}
+ */
+declare function unmarshalData(data: any): any;
+/** @deprecated Use `unmarshalData()` instead. */
+declare function normalizeData(data: any): any;
+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.
+ */
+declare function marshalArray(arr: any[]): ArrayObject;
+/**
+ * Converts an `ArrayObject` to a normal array.
+ */
+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",
+ * }
+ * ```
+ */
+declare function translationsForLocale(translationsMap: TranslationsMap, locale: string): LocaleTranslations;
+
+export { type ArrayObject, type DataSource, type DataSourceData, type DataSourceMode, type Doc, type DocMode, type GetCountOptions, type GetDocOptions, type HttpMethod, type ListDocsOptions, type LoadTranslationsOptions, type LocaleTranslations, type Release, RootCMSClient, type SetDocOptions, type Translation, type TranslationsMap, getCmsPlugin, marshalArray, normalizeData, translationsForLocale, unmarshalArray, unmarshalData };