@blinkk/root-cms

action: string;

The name of the action.

by?: string;

The user's email that performed the action (or "system").

timestamp: Timestamp;

Timestamp when the action occurred.

metadata?: T;

Metadata for the action.

links?: {
    label: string;
    url: string;
    target?: string;
}[];

Optional list of quick links to display in the UI.

dryRun?: boolean;

Resolve and validate everything, but write nothing.

verifyBefore?: boolean;

Also check each op's recorded before against the value currently in the database and fail on drift. Off by default: before is documentation for the human reviewing the proposal, not a precondition.

modifiedBy?: string;

Attributed as the author of the writes.

skipValidation?: boolean;

Skip schema validation of the resulting doc fields.

addDoc(docId: string): void;

Adds a doc to the batch request.

addDataSource(dataSourceId: string): void;

Adds a data source to the batch request.

addQuery(queryId: string, collectionId: string, queryOptions?: BatchRequestQueryOptions): void;

Adds a collection-based query to the batch request.

addTranslations(translationsId: string): void;

Adds a translations doc to the request.

fetch(): Promise<BatchResponse>;

Fetches data from the DB.

translate?: boolean;

Whether to automatically fetch translations for the docs retrieved in the request (including docs returned by queries).

locales?: string[];

Locales to fetch translations for. Each locale is expanded through its fallback chain (per the i18n.fallbacks config). Defaults to the locales configured in i18n.locales.

translations: Record<string, Record<string, TranslationsLocaleDoc>>;

Translations locale docs retrieved in the request, keyed by translations id then by locale. The ids are in precedence order: generic translations (e.g. "common") first, doc-specific translations last.

getTranslations(locale: string | string[]): LocaleTranslations;

Returns a map of translations for a given locale or locale fallbacks.

The input is either a single locale (e.g. "de"), which is expanded through the fallback chain configured in i18n.fallbacks, or an array of locales representing an explicit fallback chain, e.g. ["en-CA", "en-GB", "en"].

The returned value is a flat map of source string to translated string, e.g.: {"<source>": "<translation>"}

collection: string;

Collection mapped to the route.

slugParam?: string;

Route param name used for the slug. Used for dynamic routes, e.g. [...slug].tsx. Defaults to "slug".

slugFormat?: string;

Format pattern for slugs that use multiple param values to form the slug, e.g. for experiments you might have something like:

Route: routes/ex/[experimentId]/[...page].tsx Doc ID: ExperimentPages/1234--about--foo URL path: /ex/1234/about/foo/

To grab the correct doc, use {slugFormat: '[experimentId]/[page]'}.

slug?: string;

Slug to use for the route. Used for non-dynamic, single-document routes.

fetchData?: (context: RouteContext) => Record<string, Promise<any>>;

Callback function that returns a map of Promises that contain fetched data. Once the promise is resolved, the values are injected into page's props for rendering.

notFoundHook?: (req: Request, res: Response) => void | Promise<void>;

Hook that's called when the doc is not found. If not provided, the default 404 handler will be called.

preRenderHook?: (props: any, context: RouteContext) => any | Promise<any>;

Hook for amending any props values before being passed to the page component.

setResponseHeaders?: (req: Request, res: Response) => void;

Hook for setting any response headers.

translations?: (context: RouteContext) => {
    tags?: string[];
};

Translations configuration.

disableCacheControl?: boolean;

Sets Cache-Control header to private.

ssg?: boolean;

Enables SSG mode for sites that serve on SCS or other static servers.

ssgMode?: DocMode;

Overrides the "mode" (draft vs published) for SSG builds. Primarily intended for testing prior to launches.

previewOnly?: boolean;

Whether the route should only be available with ?preview=true.

defaultLocale?: string;

Overrides the default locale for the route.

dataFormat?: GsheetDataFormat;

Currently only used by gsheet. map returns the sheet as an array of objects keyed by the header row, grid returns the sheet as an array of arrays of strings (including the header row).

httpOptions?: {
    method: HttpMethod;
    headers?: Record<string, string>;
    body?: string;
};

Options for HTTP requests.

schedule?: CronScheduleType;

Scheduling mode. Defaults to interval when unset (for backwards compatibility with data sources created before specific schedules were supported).

interval?: number;

Interval value, used when schedule is interval.

unit?: CronUnit;

Interval unit, used when schedule is interval.

expression?: string;

Standard 5-field cron expression, used when schedule is daily, weekly, or custom, e.g. 0 19 * * * for "every day at 7pm".

timezone?: string;

IANA timezone used to evaluate expression, e.g. America/New_York. Defaults to UTC when unset.

headers?: string[];

Optional list of column headers (for gsheet sources).

readonly lastRun: number | null;

Millis timestamp of the last graph update, or null if never built.

readonly edges: Record<string, string[]>;

Map of doc id to the sorted list of doc ids it references.

getDependencies(docIds: string | string[], options?: GetDependenciesOptions): string[];

Returns the doc ids referenced by the given doc(s), i.e. the additional docs that need to be fetched when fetching the given docs. Resolves transitively by default (references of referenced docs are included, recursively; cycles are handled). The input doc ids themselves are excluded from the result.

getDependents(docIds: string | string[], options?: GetDependenciesOptions): string[];

Returns the doc ids that reference the given doc(s). Useful for finding which docs are affected when a doc changes (e.g. for cache invalidation). Resolves transitively by default.

docsWithRefs: number;

Number of docs with at least one outgoing reference.

refs: number;

Total number of outgoing reference edges.

forced: boolean;

True if a full (force) rebuild was performed.

skipped: boolean;

True if the rebuild short-circuited (no doc changes were found).

isEnabled(): boolean;

Returns true if the dependency graph feature is enabled.

isCollectionTracked(collectionId: string): boolean;

Returns true if the given collection passes the include/exclude filter.

listCollectionIds(): Promise<string[]>;

Lists collection ids by globbing <rootDir>/collections/*.schema.ts, filtered by the include/exclude config.

hasChangesSince(meta: {
    lastRun: Timestamp;
    docCounts: Record<string, number>;
}): Promise<boolean>;

Returns true when any doc changed (created, updated, published, or deleted) since lastRun. Uses limit(1) probes for modifications and count() aggregations (compared against the doc counts captured at lastRun) for deletions, so the no-change case stays cheap.

runCronUpdate(options?: {
    minIntervalMs?: number;
}): Promise<DependencyGraphRebuildResult | null>;

Cron entrypoint: incrementally updates the graph when the feature is enabled, the min interval has elapsed, and any doc changed since the last run. Returns null when the update was skipped.

buildPublishBatchOps(docs: Array<{
    collection: string;
    slug: string;
    fields?: any;
}>): Promise<DependencyGraphBatchOp[]>;

Builds the writes that sync the published-mode edges for docs being published, so new references are queryable immediately (without waiting for the next cron tick). Callers weave the returned ops into the same batch as the publish writes. Returns an empty list when the feature is disabled, no tracked docs are affected, or the graph has never been built.

buildUnpublishBatchOps(docs: Array<{
    collection: string;
    slug: string;
}>): Promise<DependencyGraphBatchOp[]>;

Builds the writes that remove the published-mode edges for docs being unpublished. See buildPublishBatchOps().

syncPublishedDocs(docIds: string[]): Promise<{
    synced: number;
}>;

Re-reads the given docs from the Published collection and syncs their published-mode edges: existing docs get their refs re-extracted, missing docs (unpublished or deleted) get their edges removed. Used by the /cms/api/dependency_graph.sync_published endpoint, which the CMS UI calls after client-side publishes. Idempotent — the graph is synced to whatever is currently in the database.

rebuildGraph(opts?: {
    force?: boolean;
}): Promise<DependencyGraphRebuildResult>;

Orchestrates a graph rebuild (incremental by default; full when force: true).

getGraph(mode: DocMode): Promise<DependencyGraph>;

Returns the dependency graph for the given mode, loading it from Firestore if necessary. Loaded graphs are cached in-process and re-validated against _meta.lastRun on every call, so repeated calls only cost a single meta doc read until the graph changes.

getStatus(): Promise<DependencyGraphStatus>;

Lightweight metadata read for status endpoints.

enabled: boolean;

Whether the feature is enabled via the cmsPlugin config.

lastRun: number | null;

Millis timestamp of the last graph update, or null if never built.

id: string;

The id of the doc, e.g. "Pages/foo-bar".

collection: string;

The collection id of the doc, e.g. "Pages".

slug: string;

The slug of the doc, e.g. "foo-bar".

note?: string;

Free-form rationale shown to the reviewer.

transitive?: boolean;

Whether to resolve dependencies transitively (i.e. also include the references of referenced docs, recursively). Defaults to true.

mode: DocMode;

Mode, either "draft" or "published".

iterations?: number;

The number of PBKDF2 iterations. Defaults to DEFAULT_ITERATIONS. Higher values are slower to compute and slower to brute force.

ids: string[];

Translations doc ids that were created or updated.

action?: string;

Filter by a specific action. Defaults to all actions.

by?: string;

Filter by a specific user. Defaults to all users.

limit?: number;

Max number of actions to return. Defaults to 100.

orderBy?: string;

DB field path to order results by, e.g. sys.createdAt. Defaults to slug. The default is skipped when a query fn is provided, since the query fn may supply its own ordering.

raw?: boolean;

Whether to fetch the "raw" version of the doc (for use in conjunction with setRawDoc()).

trigger?: 'build' | 'dev';

What triggered the migration (used for logging/state).

skipped: boolean;

True if the migration was skipped, either because it already completed or because another process holds the running lock.

algorithm: PasswordHashAlgorithm;

The key derivation algorithm used, e.g. pbkdf2-sha256.

iterations: number;

The number of PBKDF2 iterations used to derive the hash.

salt: string;

The random salt used to derive the hash, base64-encoded.

hash: string;

The derived hash, base64-encoded.

id: string;

Stable id for the proposal, e.g. "2026-08-20-hero-refresh".

project?: string;

CMS project id the proposal targets. Advisory only.

generated?: string;

ISO-8601 timestamp of when the proposal was generated.

changeIndex: number;

Zero-based index of the change in proposal.changes.

target: string;

The target of the change, e.g. a doc id or release id.

path?: string;

Dotted field path, when the failure is tied to one.

path: string;

Dotted path within the target object (no leading "fields." prefix).

index?: number;

Zero-based array index. Required for "remove_item", optional for "insert_item".

after?: any;

The value to write ("set") or insert ("insert_item").

before?: any;

The value as it stood when the proposal was written. Review-only: the applier ignores it unless verifyBefore is explicitly enabled.

applyToDoc(doc: Doc): Doc;

Applies any edit ops for doc.id to an unmarshaled doc.

hasNewDocsInCollection(collectionId: string): boolean;

True if the proposal creates any doc in collectionId.

countNewDocsInCollection(collectionId: string): number;

Number of docs the proposal creates in collectionId.

newDocsInCollection(collectionId: string, existingIds: Set<string>): Doc[];

Builds Doc objects for the docs the proposal creates in collectionId, skipping any that already exist in the db.

buildNewDoc(docId: string): Doc | null;

Synthesizes a Doc for a doc id the proposal creates, or null if the proposal does not create it. Duplicated docs are not resolved here (the source doc is not available synchronously), so they come back with empty fields.

newDocIds(): string[];

Every doc id the proposal creates, in proposal order.

allTranslations(): Record<string, Record<string, string>> | null;

All proposed translations, flattened to {source: {locale: string}}.

localeDocStrings(translationsId: string, locale: string): Record<string, {
    source: string;
    translation: string;
}> | null;

Returns proposed strings for one translations id and locale, shaped like the strings hash map stored on a translations locale doc, or null when the proposal has nothing for it.

line?: number;

1-based line number in the source YAML, when known.

path: string;

Dotted path to the offending value, e.g. "changes.0.ops.1.path".

match?: string | string[] | ((req: Request) => boolean);

Restricts the guard to matching request paths. Accepts a path prefix (e.g. /admin), a list of prefixes, or a predicate (req) => boolean. When omitted, login is enforced for every request the middleware sees.

This is useful when adding the middleware to root.config.ts's server.middlewares, which are mounted app-wide with no path scope.

loginUrl?: string;

The login page to redirect unauthenticated users to. Defaults to /cms/login. The original URL is added as a continue query param so the user is returned to the requested page after signing in.

summary: string;

Short human-readable description of what will be written.

paths?: string[];

Field paths the change touches, for doc and release changes.

readonly proposal?: ProposalOverlay;

An unapplied change proposal overlaid on top of everything this client reads. Lets a developer preview proposed content against a running site before accepting it. Reads only — writes never fold the proposal in.

overlayDoc<T = any>(doc: T): T;

Applies the proposal overlay (if any) to an unmarshaled doc.

Called from every non-raw read path. getRawDoc() and listDocs({raw: true}) deliberately skip this: those exist to feed setRawDoc(), and folding proposed content into them would leak it into a write.

proposedDocsInCollection(collectionId: string, existingIds: Set<string>): Doc<any>[];

Returns docs the proposal creates in a collection that do not exist in the database yet, so list and count reads can include them.

getDoc<Fields = any>(collectionId: string, slug: string, options: GetDocOptions): Promise<Doc<Fields> | null>;

Retrieves doc data from Root.js CMS.

getRawDoc(collectionId: string, slug: string, options: GetDocOptions): Promise<any | null>;

Retrieves raw doc data as stored in the database. Only use this if you know what you are doing.

dbCollectionDocsPath(collectionId: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a collection.

dbDocPath(collectionId: string, slug: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a content doc.

dbDocRef(collectionId: string, slug: string, options: {
    mode: 'draft' | 'published';
}): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;

Firestore doc ref for a content doc.

getCollection(collectionId: string): Promise<Collection | null>;

Returns a collection's schema definition as defined in /collections/<id>.schema.ts.

saveDraftData(docId: string, fieldsData: any, options?: SaveDraftOptions): Promise<void>;

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().

updateDraftData(docId: string, path: string, fieldValue: any, options?: UpdateDraftOptions): 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')

setRawDoc(collectionId: string, slug: string, data: any, options: SetDocOptions): 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.

// 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' });

listDocs<T>(collectionId: string, options: ListDocsOptions): Promise<{
    docs: T[];
}>;

Lists docs from a Root.js CMS collection.

getDocsCount(collectionId: string, options: GetCountOptions): Promise<number>;

Returns the number of docs in a Root.js CMS collection.

publishDocs(docIds: string[], options?: {
    publishedBy: string;
    batch?: WriteBatch;
    releaseId?: string;
}): Promise<any[]>;

Batch publishes a set of docs by id.

unpublishDocs(docIds: string[], options?: {
    unpublishedBy?: string;
    batch?: WriteBatch;
}): Promise<any[]>;

Batch unpublishes a set of docs by id.

publishScheduledDocs(): Promise<any[]>;

Publishes scheduled docs.

dbReleasePath(releaseId: string): string;

Returns the Firestore path for a release doc.

getRelease(releaseId: string): Promise<Release | null>;

Retrieves a release by id, or null if it does not exist.

listReleases(): Promise<Release[]>;

Lists all releases, most recently created first.

setRelease(releaseId: string, release: Partial<Release>, options?: {
    modifiedBy?: string;
}): Promise<void>;

Creates or updates a release.

Only the fields describing the release's contents are written (description, docIds, dataSourceIds); scheduling and publishing state is left untouched, so this can never publish or schedule a release as a side effect.

publishScheduledReleases(): Promise<void>;

Publishes docs in scheduled releases.

syncScheduledDataSources(): Promise<void>;

Syncs data sources that have cron scheduling enabled and are due for sync.

testPublishingLocked(doc: Doc): boolean;

Checks if a doc is currently "locked" for publishing.

getTranslationsManager(): TranslationsManager;

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.

isV2TranslationsEnabled(): boolean;

Returns true if the v2 TranslationsManager is enabled via the experiments.v2TranslationsManager plugin config flag.

loadTranslations(options?: LoadTranslationsOptions): Promise<TranslationsMap>;

Loads translations saved in the translations collection, optionally filtered by tag.

Returns a map like:

{
  "<hash>": {"source": "Hello", "es": "Hola", "fr": "Bonjour"},
}

saveTranslations(translations: {
    [source: string]: {
        [locale: string]: string;
    };
}, tags?: string[]): Promise<void>;

Saves a map of translations, e.g.:

await client.saveTranslations({
  "Hello": {"es": "Hola", "fr": "Bonjour"},
});

verifyPassword(stored: PasswordHash | null | undefined, password: string): Promise<boolean>;

Verifies a candidate password against the hashed value stored by a password field. Returns false when the field is empty or malformed.

const doc = await cmsClient.getDoc('Members', 'alice', {mode: 'published'});
const ok = await cmsClient.verifyPassword(doc?.fields.password, input);

getTranslationKey(source: string): string;

Returns the "key" used for a translation as stored in the db. Translations are stored under Projects/<project id>/Translations/<sha1 hash>.

normalizeString(str: 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

loadTranslationsForLocale(locale: string, options?: LoadTranslationsOptions): Promise<LocaleTranslations>;

Loads translations for a particular locale.

The locale is expanded through the fallback chain configured in i18n.fallbacks (ending with i18n.defaultLocale), so a string missing a translation for the locale falls through to its fallbacks before the source string is used.

Returns a map like:

{
  "Hello": "Bonjour",
}

getDataSource(dataSourceId: string): Promise<DataSource | null>;

Returns a data source configuration object.

archiveDataSource(dataSourceId: string, options?: {
    archivedBy?: string;
}): Promise<void>;

Archives a data source. Archived data sources cannot be synced or published.

unarchiveDataSource(dataSourceId: string): Promise<void>;

Unarchives a data source.

syncDataSource(dataSourceId: string, options?: {
    syncedBy?: string;
}): Promise<void>;

Syncs a data source to draft state.

unpublishDataSource(dataSourceId: string): Promise<void>;

Unpublishes a data source. Removes the publishedAt/publishedBy metadata from the DataSource doc and deletes the Data/published doc.

getFromDataSource<T = any>(dataSourceId: string, options?: {
    mode?: 'draft' | 'published';
}): Promise<DataSourceData<T> | null>;

Fetches data from a data source.

dbDataSourceDataPath(dataSourceId: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a datasource data.

dbDataSourceDataRef(dataSourceId: string, options: {
    mode: 'draft' | 'published';
}): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;

Firestore doc ref for a datasource data.

getUserAcl(email: string): Promise<{
    exists: boolean;
    role: UserRole | null;
}>;

Looks up the user's entry in the project's ACL with a single Firestore read. exists is true if the user (or their domain's wildcard entry, e.g. *@example.com) is in the ACL; role may be null for entries without an assigned role.

getUserRole(email: string): Promise<UserRole | null>;

Gets the user's role from the project's ACL.

userExistsInAcl(email: string): Promise<boolean>;

Verifies user exists in the ACL list.

listActions(options?: ListActionsOptions): Promise<Action[]>;

Lists action logs from the database.

sendEmail(options: SendEmailOptions): Promise<string>;

Queues an email in the Projects/${projectId}/Emails collection in firestore, which is processed by the Root.js email service (apps/root-services). Returns the id of the queued email doc.

Delivery is asynchronous: the email service sends pending emails when its /_/send_emails endpoint is called (typically via a cron). Pass the emailService option to notify the service right away.

getDependencyGraph(options: {
    mode: DocMode;
}): Promise<DependencyGraph>;

Returns the dependency graph for a given mode, which tracks reference field usages between docs. Requires the dependencyGraph option to be enabled on the cmsPlugin config (the graph is kept up to date by the CMS cron job).

Example:

const graph = await cmsClient.getDependencyGraph({mode: 'published'});
const depIds = graph.getDependencies(['Pages/index']);
// => ['Authors/alice', 'BlogPosts/hello-world', ...]

getDocDependencies(docIds: string | string[], options: {
    mode: DocMode;
    transitive?: boolean;
}): Promise<string[]>;

Returns the ids of the docs referenced by the given doc(s), i.e. the additional docs that need to be fetched when fetching the given docs. Dependencies are resolved transitively by default (pass transitive: false for direct references only).

Requires the dependencyGraph option to be enabled on the cmsPlugin config.

Example:

const depIds = await cmsClient.getDocDependencies(['Pages/index'], {
  mode: 'published',
});
const req = cmsClient.createBatchRequest({mode: 'published'});
req.addDoc('Pages/index');
depIds.forEach((docId) => req.addDoc(docId));
const res = await req.fetch();

createBatchRequest(options: BatchRequestOptions): BatchRequest;

Creates a batch request that is capable of fetching one or more docs, corresponding translations, and dataSources.

proposal?: Proposal;

An unapplied change proposal to overlay on top of every read. Use this to preview proposed content on a running site before accepting it.

id: string;

The id of the doc, e.g. "Pages/foo-bar".

collection: string;

The collection id of the doc, e.g. "Pages".

slug: string;

The slug of the doc, e.g. "foo-bar".

sys: {
    createdAt: number;
    createdBy: string;
    modifiedAt: number;
    modifiedBy: string;
    firstPublishedAt?: number;
    firstPublishedBy?: string;
    publishedAt?: number;
    publishedBy?: string;
    locales?: string[];
    sortKey?: string;
};

System-level metadata.

fields?: Fields;

User-entered field values from the CMS.

handle: (req: RouteRequest, res: RouteResponse) => Promise<void>;

SSR handler.

getStaticProps?: GetStaticProps;

SSG handler props handler, enabled with {ssg: true}.

getStaticPaths?: GetStaticPaths;

SSG path params provider, enabled with {ssg: true}.

req?: RouteRequest;

HTTP request object. Only available in SSR mode.

slug: string;

The slug of the page being requested.

mode: DocMode;

Doc publishing mode.

cmsClient: RootCMSClient;

Client for interacting with Root CMS data.

params: RouteParams;

URL param map from filesystem routing.

locales?: string[];

Locales to enable.

modifiedBy?: string;

Email of user modifying the doc. If blank, defaults to root-cms-client.

validate?: boolean;

Whether to validate fieldsData against the collection schema before saving. If validation fails, an error will be thrown with details about the validation errors.

type AspectRatio = string | number;

An aspect ratio, expressed either as a string like '16:9', '16/9' or '16x9', or as a number like 1.7778 (width divided by height).

interface CollectionPublishingOptions

Publishing options configured on a collection.

const define: typeof defineSchema;

Defines the schema for a collection or reusable component.

function definePreset<T = Record<string, any>>(preset: SchemaPreset<T>): SchemaPreset<T>;

Defines a preset for use within schema.define({presets: [...]}). The optional generic parameter T constrains the shape of the preset's data field. Pass an auto-generated fields type to enable type-safety:

import type {HeroFields} from './generated/types.d.ts';

schema.definePreset<HeroFields>({
  id: 'big',
  label: 'Big hero',
  data: {title: 'Welcome'},
});

interface DocumentSource

Sources the selectable values for a field from a field within another CMS document.

Use this when a set of allowed values is managed centrally in the CMS (e.g. a list of feature flags defined in a global module) and you want other fields to pick from that list instead of typing free-form strings.

Example: source a flag select's options from the name of each item in the flags array of the GlobalModules/flags document.

schema.select({
  id: 'flag',
  source: {
    doc: 'GlobalModules/flags',
    field: 'flags',
    valueKey: 'name',
    helpKey: 'description',
  },
  creatable: true,
});

type FieldValueSource = DocumentSource;

The source of selectable values for a field. Currently only a CMS document source is supported; other source types may be added in the future.

type FieldWithId = Field;

Similar to Field but with a required id. TODO(stevenle): fix this.

function glob(pattern: string, options?: GlobOptions): SchemaPattern;

Creates a schema pattern that is resolved at project load time.

This is the recommended way to reference multiple schemas in a oneOf field, especially for self-referencing schemas like containers. The pattern is resolved after all schemas are loaded, completely avoiding circular import issues.

// Simple usage - include all templates:
export default schema.define({
  name: 'Container',
  fields: [
    schema.array({
      id: 'children',
      of: schema.oneOf({
        types: schema.glob('/templates/*\/*.schema.ts'),
      }),
    }),
  ],
});

// With exclusions:
schema.oneOf({
  types: schema.glob('/templates/*\/*.schema.ts', {
    exclude: ['DeprecatedTemplate'],
  }),
});

// With field omissions (useful for nested contexts):
schema.oneOf({
  types: schema.glob('/blocks/*\/*.schema.ts', {
    omitFields: ['id'],
  }),
});

interface GlobOptions

Options for schema.glob().

type PasswordField = CommonFieldProps & {
    type: 'password';
    default?: never;
    minLength?: number;
    iterations?: number;
};

A field for securely storing a password.

The password is hashed in the CMS UI before it is saved, so the plain text value is never written to the db. The stored value is a PasswordHash containing the algorithm, salt and hash. Use verifyPassword() from @blinkk/root-cms (or RootCMSClient.verifyPassword()) to check whether a candidate password matches.

schema.password({id: 'password', label: 'Password'});

// Server-side:
const ok = await cmsClient.verifyPassword(doc.fields.password, input);

type PasswordFieldValue = PasswordHash;

The value stored in the db for a PasswordField.

interface PasswordHash

The value stored in the db for a password field. The salt and the derived hash are stored base64-encoded alongside the parameters used to compute them, so the algorithm or its cost can change without invalidating existing hashes.

type PasswordHashAlgorithm = 'pbkdf2-sha256';

The hashing algorithms supported by hashPassword.

const preset: typeof definePreset;

Alias for definePreset.

interface PublishCheckConfig

A check configured to run as part of a collection's publishing flow.

type PublishCheckLevel = 'required' | 'warning';

Severity level for a check configured on a collection.

- required: an error result halts publishing. - warning: publishing continues, and the message is surfaced afterwards.

interface SchemaPattern

A schema pattern that is resolved at project load time. This allows schemas to reference other schemas by glob pattern without causing circular import issues, since resolution is deferred until all schemas are loaded.

to: string | string[];

Recipient email address(es).

from?: string;

Sender email address. The sender must be authorized to send email via the App Engine Mail API, e.g. noreply@<gcp-project-id>.appspotmail.com. Defaults to noreply@<gcp-project-id>.appspotmail.com.

subject: string;

Subject line.

body?: string;

Plain-text body. When omitted, a plain-text body is derived from htmlBody.

htmlBody?: string;

Optional HTML body.

expiresAt?: Date;

Optional expiration date. If the email is still unsent when the email service processes the queue after this date (e.g. the service was down), the email is marked as expired and skipped instead of being delivered late.

emailService?: string | boolean;

Email service used to trigger delivery immediately after the email is queued. Setting this to true uses the default hosted service at https://services.rootjs.dev. Set to a base URL to use a self-hosted deployment of the service (apps/root-services). When unset, the email remains queued until the email service's cron next processes the queue.

mode: DocMode;

Mode, either "draft" or "published".

id: string;

Translations id. In most cases, this is the same as the doc id, e.g. Pages/foo--bar.

saveTranslations(id: string, strings: MultiLocaleTranslationsMap, options?: {
    tags?: string[];
    modifiedBy?: string;
    linkedSheet?: TranslationsLinkedSheet;
}): Promise<void>;

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);

publishTranslations(id: string, options?: {
    batch?: WriteBatch;
    publishedBy?: string;
}): Promise<void>;

Publishes a translations doc.

publishTranslationsBulk(ids: string[], options?: {
    publishedBy?: string;
}): Promise<{
    publishedIds: string[];
}>;

Publishes multiple translations docs by id, e.g.:

await tm.publishTranslationsBulk(['Pages/index', 'common']);

addPublishTranslationsOps(localeDocs: TranslationsLocaleDocWithRef[], batch: WriteBatch, options?: {
    publishedBy?: string;
}): number;

Adds the write ops for publishing a set of draft translations locale docs to a batch. For each locale doc, the draft doc's sys is updated with publishedAt/By and a copy is saved to the published collection. Returns the number of ops added to the batch (2 per locale doc).

getTranslationsLocaleDocs(ids: string[], mode: TranslationsDocMode): Promise<Record<string, TranslationsLocaleDocWithRef[]>>;

Fetches the translations locale docs (with their doc refs) for a set of translations doc ids, grouped by id.

loadTranslations(options?: {
    ids?: string[];
    tags?: string[];
    locales?: Locale[];
    mode?: TranslationsDocMode;
}): Promise<MultiLocaleTranslationsMap>;

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"}
// }

loadTranslationsForLocale(locale: Locale, options?: {
    mode?: TranslationsDocMode;
    fallbackLocales?: Locale[];
}): Promise<SingleLocaleTranslationsMap>;

Fetches translations for a given locale, with optional fallbacks. The return value is a map of source string to translated string.

If no fallbackLocales are provided, the fallback chain is resolved from the project's i18n.fallbacks config.

Example:

await translationsDoc.loadTranslationsForLocale('es');
// =>
// {
//   "one": "uno",
//   "two": "dos",
// }

importTranslationsFromV1(): Promise<ImportTranslationsFromV1Result>;

Imports translations from the v1 system to the TranslationsManager.

Each v1 string is grouped into a v2 translations doc per tag (e.g. a string tagged Pages/index is saved to the Pages/index translations doc). Untagged strings are grouped into a v1-untagged doc so that nothing is dropped. The imported translations are saved as drafts; use publishTranslationsBulk() to publish them.

validate?: boolean;

Whether to validate the updated field against the collection schema. If validation fails, an error will be thrown with details about the validation errors.

get element(): HTMLIFrameElement | null;

The iframe element (iframe mode only).

get window(): Window | null;

The pop-up window (popup mode only).

on<K extends keyof AIEvents>(type: K, cb: (payload: AIEvents[K]) => void): () => void;

Subscribes to an event. Returns an unsubscribe function.

reload(): void;

Reloads the embedded chat (starts a fresh chat).

close(): void;

Closes the embedded chat.

closeAndReload(): void;

Closes the embedded chat and reloads the host page.

readonly docId: string;

The doc being edited, e.g. Pages/about.

get element(): HTMLIFrameElement | null;

The iframe element (iframe mode only).

get window(): Window | null;

The pop-up window (popup mode only).

on<K extends keyof EditorEvents>(type: K, cb: (payload: EditorEvents[K]) => void): () => void;

Subscribes to an editor event. Returns an unsubscribe function.

focusField(deepKey: string): void;

Scrolls the editor to (focuses) a field, e.g. hero.title.

reload(): void;

Reloads the embedded editor.

close(): void;

Closes the embedded editor, discarding any unsaved changes.

closeAndReload(): void;

Closes the embedded editor and reloads the host page.

ready: {
    docId?: string;
};

The embedded page finished loading.

saved: {
    docId?: string;
    saveState?: SaveState;
};

The doc was saved.

published: {
    docId?: string;
    publishedAt?: number;
};

The doc was published.

error: {
    error?: string;
};

An error occurred (e.g. the pop-up was blocked).

close: void;

The embedded window was closed (via close() or by the user).

mode?: 'popup' | 'iframe';

How to open the editor. Defaults to popup.

container?: HTMLElement;

Container the iframe is appended to. Required when mode is iframe.

deeplink?: string;

Deep key of a field to scroll to on load, e.g. hero.title.

width?: number;

Pop-up window width. Defaults to 480.

height?: number;

Pop-up window height. Defaults to 720.

docId?: string;

Doc to provide as context to the AI chat, e.g. Pages/about.

readonly isEmbedded: boolean;

Whether this page is rendered inside the in-CMS preview pane.

focusField(deepKey: string): void;

Requests that the doc editor scroll to (focus) a field, e.g. hero.title. Used to implement "click to edit".

navigateToDoc(docId: string, options?: {
    confirm?: boolean;
}): void;

Tells the doc editor to switch to a document, so the editor follows the preview as the user navigates the site.

Call it with the page's own doc id when the page loads. isEmbedded is false outside the CMS preview pane, so the call is a no-op on the live site. The CMS only acts on it when the plugin's preview.channel enables messages from the preview.

The editor asks the user before switching by default, since a doc changing on its own is disorienting for someone who doesn't know the page can do that. Pass {confirm: false} to switch straight away, for sites that have their own affordance for it (a toggle the user turned on, say).

Usage:

const preview = new PreviewConnection();
if (preview.isEmbedded) {
  preview.navigateToDoc(doc.id);
}

on(type: 'highlight', cb: (event: PreviewHighlightEvent) => void): () => void;

Subscribes to field highlight requests from the doc editor (sent when the user hovers/focuses a field). Returns an unsubscribe function.

disconnect(): void;

Removes the message listener and all subscriptions.

deepKey: string | null;

Deep key of the field to highlight, or null to clear highlights.

scroll: boolean;

Whether to scroll the highlighted node into view.

readonly cmsOrigin: string;

Normalized origin of the Root CMS server.

openEditor(docId: string, options?: OpenEditorOptions): EmbeddedEditor;

Opens the headless doc editor for a doc (e.g. Pages/about) in a pop-up or iframe. In popup mode, call from a user gesture (e.g. a click handler) to avoid pop-up blockers.

The slug portion of the docId is normalized the same way the CMS normalizes slugs, so a URL-like path also works, e.g. Pages/about/foo -> Pages/about--foo.

openRootAI(options?: OpenRootAIOptions): EmbeddedAI;

Opens the headless Root AI chat in a pop-up or iframe, optionally with a doc as context. In popup mode, call from a user gesture (e.g. a click handler) to avoid pop-up blockers.

static connectPreview(): PreviewConnection;

Connects to the doc editor from a site rendered inside the in-CMS preview pane, enabling "click to edit" (PreviewConnection.focusField) and field highlighting (on('highlight', ...)).

static isInPreviewIframe(): boolean;

Returns whether this page is rendered inside the in-CMS preview pane.

The parent's location is the reliable signal: the preview iframe is same-origin, so the CMS path is readable. The referrer only names the CMS for the first page the pane loads -- once the user follows a link inside the preview it names the previous page of the site instead -- so it is kept as a fallback for the cases where the parent can't be read.

cmsOrigin: string;

Origin of the Root CMS server, e.g. https://cms.example.com.

action: string;

The name of the action.

by?: string;

The user's email that performed the action (or "system").

timestamp: Timestamp;

Timestamp when the action occurred.

metadata?: T;

Metadata for the action.

links?: {
    label: string;
    url: string;
    target?: string;
}[];

Optional list of quick links to display in the UI.

addDoc(docId: string): void;

Adds a doc to the batch request.

addDataSource(dataSourceId: string): void;

Adds a data source to the batch request.

addQuery(queryId: string, collectionId: string, queryOptions?: BatchRequestQueryOptions): void;

Adds a collection-based query to the batch request.

addTranslations(translationsId: string): void;

Adds a translations doc to the request.

fetch(): Promise<BatchResponse>;

Fetches data from the DB.

translate?: boolean;

Whether to automatically fetch translations for the docs retrieved in the request (including docs returned by queries).

locales?: string[];

Locales to fetch translations for. Each locale is expanded through its fallback chain (per the i18n.fallbacks config). Defaults to the locales configured in i18n.locales.

translations: Record<string, Record<string, TranslationsLocaleDoc>>;

Translations locale docs retrieved in the request, keyed by translations id then by locale. The ids are in precedence order: generic translations (e.g. "common") first, doc-specific translations last.

getTranslations(locale: string | string[]): LocaleTranslations;

Returns a map of translations for a given locale or locale fallbacks.

The input is either a single locale (e.g. "de"), which is expanded through the fallback chain configured in i18n.fallbacks, or an array of locales representing an explicit fallback chain, e.g. ["en-CA", "en-GB", "en"].

The returned value is a flat map of source string to translated string, e.g.: {"<source>": "<translation>"}

dataFormat?: GsheetDataFormat;

Currently only used by gsheet. map returns the sheet as an array of objects keyed by the header row, grid returns the sheet as an array of arrays of strings (including the header row).

httpOptions?: {
    method: HttpMethod;
    headers?: Record<string, string>;
    body?: string;
};

Options for HTTP requests.

schedule?: CronScheduleType;

Scheduling mode. Defaults to interval when unset (for backwards compatibility with data sources created before specific schedules were supported).

interval?: number;

Interval value, used when schedule is interval.

unit?: CronUnit;

Interval unit, used when schedule is interval.

expression?: string;

Standard 5-field cron expression, used when schedule is daily, weekly, or custom, e.g. 0 19 * * * for "every day at 7pm".

timezone?: string;

IANA timezone used to evaluate expression, e.g. America/New_York. Defaults to UTC when unset.

headers?: string[];

Optional list of column headers (for gsheet sources).

id: string;

The id of the doc, e.g. "Pages/foo-bar".

collection: string;

The collection id of the doc, e.g. "Pages".

slug: string;

The slug of the doc, e.g. "foo-bar".

mode: DocMode;

Mode, either "draft" or "published".

iterations?: number;

The number of PBKDF2 iterations. Defaults to DEFAULT_ITERATIONS. Higher values are slower to compute and slower to brute force.

action?: string;

Filter by a specific action. Defaults to all actions.

by?: string;

Filter by a specific user. Defaults to all users.

limit?: number;

Max number of actions to return. Defaults to 100.

orderBy?: string;

DB field path to order results by, e.g. sys.createdAt. Defaults to slug. The default is skipped when a query fn is provided, since the query fn may supply its own ordering.

raw?: boolean;

Whether to fetch the "raw" version of the doc (for use in conjunction with setRawDoc()).

algorithm: PasswordHashAlgorithm;

The key derivation algorithm used, e.g. pbkdf2-sha256.

iterations: number;

The number of PBKDF2 iterations used to derive the hash.

salt: string;

The random salt used to derive the hash, base64-encoded.

hash: string;

The derived hash, base64-encoded.

applyToDoc(doc: Doc): Doc;

Applies any edit ops for doc.id to an unmarshaled doc.

hasNewDocsInCollection(collectionId: string): boolean;

True if the proposal creates any doc in collectionId.

countNewDocsInCollection(collectionId: string): number;

Number of docs the proposal creates in collectionId.

newDocsInCollection(collectionId: string, existingIds: Set<string>): Doc[];

Builds Doc objects for the docs the proposal creates in collectionId, skipping any that already exist in the db.

buildNewDoc(docId: string): Doc | null;

Synthesizes a Doc for a doc id the proposal creates, or null if the proposal does not create it. Duplicated docs are not resolved here (the source doc is not available synchronously), so they come back with empty fields.

newDocIds(): string[];

Every doc id the proposal creates, in proposal order.

allTranslations(): Record<string, Record<string, string>> | null;

All proposed translations, flattened to {source: {locale: string}}.

localeDocStrings(translationsId: string, locale: string): Record<string, {
    source: string;
    translation: string;
}> | null;

Returns proposed strings for one translations id and locale, shaped like the strings hash map stored on a translations locale doc, or null when the proposal has nothing for it.

readonly proposal?: ProposalOverlay;

An unapplied change proposal overlaid on top of everything this client reads. Lets a developer preview proposed content against a running site before accepting it. Reads only — writes never fold the proposal in.

overlayDoc<T = any>(doc: T): T;

Applies the proposal overlay (if any) to an unmarshaled doc.

Called from every non-raw read path. getRawDoc() and listDocs({raw: true}) deliberately skip this: those exist to feed setRawDoc(), and folding proposed content into them would leak it into a write.

proposedDocsInCollection(collectionId: string, existingIds: Set<string>): Doc<any>[];

Returns docs the proposal creates in a collection that do not exist in the database yet, so list and count reads can include them.

getDoc<Fields = any>(collectionId: string, slug: string, options: GetDocOptions): Promise<Doc<Fields> | null>;

Retrieves doc data from Root.js CMS.

getRawDoc(collectionId: string, slug: string, options: GetDocOptions): Promise<any | null>;

Retrieves raw doc data as stored in the database. Only use this if you know what you are doing.

dbCollectionDocsPath(collectionId: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a collection.

dbDocPath(collectionId: string, slug: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a content doc.

dbDocRef(collectionId: string, slug: string, options: {
    mode: 'draft' | 'published';
}): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;

Firestore doc ref for a content doc.

getCollection(collectionId: string): Promise<Collection | null>;

Returns a collection's schema definition as defined in /collections/<id>.schema.ts.

saveDraftData(docId: string, fieldsData: any, options?: SaveDraftOptions): Promise<void>;

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().

updateDraftData(docId: string, path: string, fieldValue: any, options?: UpdateDraftOptions): 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')

setRawDoc(collectionId: string, slug: string, data: any, options: SetDocOptions): 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.

// 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' });

listDocs<T>(collectionId: string, options: ListDocsOptions): Promise<{
    docs: T[];
}>;

Lists docs from a Root.js CMS collection.

getDocsCount(collectionId: string, options: GetCountOptions): Promise<number>;

Returns the number of docs in a Root.js CMS collection.

publishDocs(docIds: string[], options?: {
    publishedBy: string;
    batch?: WriteBatch;
    releaseId?: string;
}): Promise<any[]>;

Batch publishes a set of docs by id.

unpublishDocs(docIds: string[], options?: {
    unpublishedBy?: string;
    batch?: WriteBatch;
}): Promise<any[]>;

Batch unpublishes a set of docs by id.

publishScheduledDocs(): Promise<any[]>;

Publishes scheduled docs.

dbReleasePath(releaseId: string): string;

Returns the Firestore path for a release doc.

getRelease(releaseId: string): Promise<Release | null>;

Retrieves a release by id, or null if it does not exist.

listReleases(): Promise<Release[]>;

Lists all releases, most recently created first.

setRelease(releaseId: string, release: Partial<Release>, options?: {
    modifiedBy?: string;
}): Promise<void>;

Creates or updates a release.

Only the fields describing the release's contents are written (description, docIds, dataSourceIds); scheduling and publishing state is left untouched, so this can never publish or schedule a release as a side effect.

publishScheduledReleases(): Promise<void>;

Publishes docs in scheduled releases.

syncScheduledDataSources(): Promise<void>;

Syncs data sources that have cron scheduling enabled and are due for sync.

testPublishingLocked(doc: Doc): boolean;

Checks if a doc is currently "locked" for publishing.

getTranslationsManager(): TranslationsManager;

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.

isV2TranslationsEnabled(): boolean;

Returns true if the v2 TranslationsManager is enabled via the experiments.v2TranslationsManager plugin config flag.

loadTranslations(options?: LoadTranslationsOptions): Promise<TranslationsMap>;

Loads translations saved in the translations collection, optionally filtered by tag.

Returns a map like:

{
  "<hash>": {"source": "Hello", "es": "Hola", "fr": "Bonjour"},
}

saveTranslations(translations: {
    [source: string]: {
        [locale: string]: string;
    };
}, tags?: string[]): Promise<void>;

Saves a map of translations, e.g.:

await client.saveTranslations({
  "Hello": {"es": "Hola", "fr": "Bonjour"},
});

verifyPassword(stored: PasswordHash | null | undefined, password: string): Promise<boolean>;

Verifies a candidate password against the hashed value stored by a password field. Returns false when the field is empty or malformed.

const doc = await cmsClient.getDoc('Members', 'alice', {mode: 'published'});
const ok = await cmsClient.verifyPassword(doc?.fields.password, input);

getTranslationKey(source: string): string;

Returns the "key" used for a translation as stored in the db. Translations are stored under Projects/<project id>/Translations/<sha1 hash>.

normalizeString(str: 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

loadTranslationsForLocale(locale: string, options?: LoadTranslationsOptions): Promise<LocaleTranslations>;

Loads translations for a particular locale.

The locale is expanded through the fallback chain configured in i18n.fallbacks (ending with i18n.defaultLocale), so a string missing a translation for the locale falls through to its fallbacks before the source string is used.

Returns a map like:

{
  "Hello": "Bonjour",
}

getDataSource(dataSourceId: string): Promise<DataSource | null>;

Returns a data source configuration object.

archiveDataSource(dataSourceId: string, options?: {
    archivedBy?: string;
}): Promise<void>;

Archives a data source. Archived data sources cannot be synced or published.

unarchiveDataSource(dataSourceId: string): Promise<void>;

Unarchives a data source.

syncDataSource(dataSourceId: string, options?: {
    syncedBy?: string;
}): Promise<void>;

Syncs a data source to draft state.

unpublishDataSource(dataSourceId: string): Promise<void>;

Unpublishes a data source. Removes the publishedAt/publishedBy metadata from the DataSource doc and deletes the Data/published doc.

getFromDataSource<T = any>(dataSourceId: string, options?: {
    mode?: 'draft' | 'published';
}): Promise<DataSourceData<T> | null>;

Fetches data from a data source.

dbDataSourceDataPath(dataSourceId: string, options: {
    mode: 'draft' | 'published';
}): string;

Firestore path for a datasource data.

dbDataSourceDataRef(dataSourceId: string, options: {
    mode: 'draft' | 'published';
}): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;

Firestore doc ref for a datasource data.

getUserAcl(email: string): Promise<{
    exists: boolean;
    role: UserRole | null;
}>;

Looks up the user's entry in the project's ACL with a single Firestore read. exists is true if the user (or their domain's wildcard entry, e.g. *@example.com) is in the ACL; role may be null for entries without an assigned role.

getUserRole(email: string): Promise<UserRole | null>;

Gets the user's role from the project's ACL.

userExistsInAcl(email: string): Promise<boolean>;

Verifies user exists in the ACL list.

listActions(options?: ListActionsOptions): Promise<Action[]>;

Lists action logs from the database.

sendEmail(options: SendEmailOptions): Promise<string>;

Queues an email in the Projects/${projectId}/Emails collection in firestore, which is processed by the Root.js email service (apps/root-services). Returns the id of the queued email doc.

Delivery is asynchronous: the email service sends pending emails when its /_/send_emails endpoint is called (typically via a cron). Pass the emailService option to notify the service right away.

getDependencyGraph(options: {
    mode: DocMode;
}): Promise<DependencyGraph>;

Returns the dependency graph for a given mode, which tracks reference field usages between docs. Requires the dependencyGraph option to be enabled on the cmsPlugin config (the graph is kept up to date by the CMS cron job).

Example:

const graph = await cmsClient.getDependencyGraph({mode: 'published'});
const depIds = graph.getDependencies(['Pages/index']);
// => ['Authors/alice', 'BlogPosts/hello-world', ...]

getDocDependencies(docIds: string | string[], options: {
    mode: DocMode;
    transitive?: boolean;
}): Promise<string[]>;

Returns the ids of the docs referenced by the given doc(s), i.e. the additional docs that need to be fetched when fetching the given docs. Dependencies are resolved transitively by default (pass transitive: false for direct references only).

Requires the dependencyGraph option to be enabled on the cmsPlugin config.

Example:

const depIds = await cmsClient.getDocDependencies(['Pages/index'], {
  mode: 'published',
});
const req = cmsClient.createBatchRequest({mode: 'published'});
req.addDoc('Pages/index');
depIds.forEach((docId) => req.addDoc(docId));
const res = await req.fetch();

createBatchRequest(options: BatchRequestOptions): BatchRequest;

Creates a batch request that is capable of fetching one or more docs, corresponding translations, and dataSources.

proposal?: Proposal;

An unapplied change proposal to overlay on top of every read. Use this to preview proposed content on a running site before accepting it.

locales?: string[];

Locales to enable.

modifiedBy?: string;

Email of user modifying the doc. If blank, defaults to root-cms-client.

validate?: boolean;

Whether to validate fieldsData against the collection schema before saving. If validation fails, an error will be thrown with details about the validation errors.

to: string | string[];

Recipient email address(es).

from?: string;

Sender email address. The sender must be authorized to send email via the App Engine Mail API, e.g. noreply@<gcp-project-id>.appspotmail.com. Defaults to noreply@<gcp-project-id>.appspotmail.com.

subject: string;

Subject line.

body?: string;

Plain-text body. When omitted, a plain-text body is derived from htmlBody.

htmlBody?: string;

Optional HTML body.

expiresAt?: Date;

Optional expiration date. If the email is still unsent when the email service processes the queue after this date (e.g. the service was down), the email is marked as expired and skipped instead of being delivered late.

emailService?: string | boolean;

Email service used to trigger delivery immediately after the email is queued. Setting this to true uses the default hosted service at https://services.rootjs.dev. Set to a base URL to use a self-hosted deployment of the service (apps/root-services). When unset, the email remains queued until the email service's cron next processes the queue.

mode: DocMode;

Mode, either "draft" or "published".

validate?: boolean;

Whether to validate the updated field against the collection schema. If validation fails, an error will be thrown with details about the validation errors.

models: AiModelConfig[];

Models exposed in the model picker. The first entry is the default.

defaultModel?: string;

Id of the default model. Defaults to the first model in models.

imageModels?: AiModelConfig[];

Image generation models. Used by the image generator and any other features that produce images. Supported providers are openai (e.g. gpt-image-*), and google or google-vertex with a Gemini image model (e.g. gemini-3-pro-image-preview). Imagen models are not supported.

defaultImageModel?: string;

Id of the default image model. Defaults to the first entry in imageModels.

systemPrompt?: string;

Optional system prompt prepended to every conversation. If a ROOT.md file exists at the project root, its contents are appended to this prompt automatically.

maxSteps?: number;

Maximum tool-loop steps before stopping. Defaults to 10.

id: string;

Stable id used by the CMS UI and stored alongside chat history.

label?: string;

Optional human-readable label rendered in the model picker.

description?: string;

Optional description shown under the label.

provider: AiProvider;

AI provider/family to route requests to.

modelId?: string;

Provider-specific model id (e.g. gpt-4o, claude-opus-4-5, gemini-2.5-pro). Defaults to id if omitted.

apiKey?: string;

API key for the provider. For google-vertex this is an optional express-mode API key; omit it to authenticate with Google Cloud Application Default Credentials instead.

baseURL?: string;

Override the provider's base URL (required for openai-compatible).

headers?: Record<string, string>;

Custom headers to send with each request.

project?: string;

Google Cloud project id (google-vertex only). Defaults to the CMS's firebaseConfig.projectId, then to the Application Default Credentials project.

location?: string;

Vertex AI location (google-vertex only), e.g. us-central1. Defaults to global.

capabilities?: AiModelCapabilities;

Capabilities advertised to the UI.

rootConfig: RootConfig;

The Root.js config.

cmsClient: RootCMSClient;

The Root CMS client for accessing the database.

docId: string;

The document ID, e.g. Pages/index.

collectionId: string;

The collection ID, e.g. Pages.

slug: string;

The slug, e.g. index.

collectionSchema: schema.Collection | null;

The collection schema.

status: CheckStatus;

Whether the check succeeded, warned, or failed.

message: string;

A message describing the result. Supports markdown.

metadata?: Record<string, any>;

Optional metadata to include with the result.

endpoint?: string;

Custom API endpoint for chat prompts.

model?: string;

Gen AI model to use.

id: string;

Unique ID for the check.

label: string;

Human-readable label displayed in the UI.

description?: string;

Optional description explaining what the check does.

collections?: string[];

Optional list of collection IDs to restrict this check to. When set, the check is only shown and runnable for documents belonging to one of the listed collections. When omitted, the check applies to all collections.

run: (ctx: CheckContext) => Promise<CheckResult>;

Function that runs the check on the server-side and returns a result.

includeCollections?: string[];

Collections to track in the dependency graph. If specified, only docs in these collections are scanned for outgoing references. If unset, all collections are scanned (subject to excludeCollections).

Note that these filters only control which docs are scanned for outgoing references — referenced doc ids are always recorded as-is, even when the referenced doc lives in a collection that is not scanned.

excludeCollections?: string[];

Collections to exclude from the dependency graph. Applied after includeCollections.

onAction?: (ctx: NotificationServiceContext, action: Action) => Promise<void | NotificationResult>;

Async function called when an action occurs in the CMS. Receives the action and may dispatch a notification (e.g. send email, post to Slack) via the service's underlying transport. Can optionally return a NotificationResult describing delivery status.

includeCollections?: string[];

Collections to include in the search index. If specified, only these collections are indexed. If unset, all collections are indexed (subject to excludeCollections).

excludeCollections?: string[];

Collections to exclude from the search index. Applied after includeCollections.

includeDocIds?: string[];

Doc ids to include in the search index. If specified, only these docs are indexed (within collections that pass the collection filter). Format: <collectionId>/<slug>.

excludeDocIds?: string[];

Doc ids to exclude from the search index. Applied after includeDocIds. Format: <collectionId>/<slug>.

id: string;

Unique ID for the service (e.g. 'sendgrid', 'crowdin').

label: string;

Human-readable label displayed in the UI (e.g. "SendGrid").

icon?: string;

Optional icon URL displayed in the UI next to the label. Similar to the sidebar tools icon option, this should be a URL to an image.

rootConfig: RootConfig;

The Root.js config.

cmsClient: RootCMSClient;

The Root CMS client for accessing the database.

user?: {
    email: string;
};

Email of the user that triggered the action, if any. Some service calls are initiated by the system rather than a user, in which case this is undefined.

icon?: string;

Sidebar icon URL. For consistency with other icons used by Root CMS, we recommend picking an icon from https://tabler.io/icons with the stroke weight set to "1.5". Paste the "Data URI" or "Base64 Data URI" from the icon's download modal.

label?: string;

Label.

iframeUrl?: string;

Iframe URL to render for the tool.

cmsUrl?: string;

CMS URL that should be opened when the tool is selected. The url must start with /cms/. Use this to create shortcuts to CMS pages instead of rendering the tool inside an iframe.

externalUrl?: string;

External URL that should open in a new tab when the tool is selected.

id: string;

Identifies the theme in config, in the URL and in a user's preference.

name?: string;

Shown in the theme picker. Defaults to the id.

file?: string;

Path to a CSS file, relative to the project root (root.config.ts).

css?: string;

CSS appended after the file, or the whole theme on its own.

onImport?: (ctx: TranslationServiceContext, data: TranslationRow[]) => Promise<TranslationRow[] | TranslationImportResult>;

Async function to import translations from the service. Should return an array of translation rows that will be merged into the CMS translations database, or a TranslationImportResult object to display a notification without importing any rows.

onExport?: (ctx: TranslationServiceContext, data: TranslationRow[]) => Promise<void | TranslationExportResult>;

Async function to export translations to the service. Receives the current translation rows for the document. Can optionally return an object with a message to display in the success notification.

role?: UserRole | null;

The user's role within the project's ACL, or null if unassigned. This is populated on req.user for every authenticated request.

checks?: Array<string | PublishCheckConfig>;

Checks to run before docs in this collection are published or scheduled. Accepts either a check ID (which defaults to the required level) or a {id, level} config object.

id?: string;

Unique ID for the service. Defaults to 'comment-email'.

label?: string;

Human-readable label displayed in the UI. Defaults to 'Comment emails'.

icon?: string;

Optional icon URL displayed in the UI next to the label.

actions?: FieldCommentAction[];

Comment actions that trigger an email. Defaults to new comments, resolves and reopens (doc.comment.add, doc.comment.resolve, doc.comment.reopen).

notifyMentions?: boolean;

Whether to notify users mentioned in the comment via @mention. Defaults to true.

notifyParticipants?: boolean;

Whether to notify previous participants of the thread (everyone who has commented on the field). Defaults to true.

notifySelf?: boolean;

Whether to include the user that performed the action in the recipients. Defaults to false.

to?: string[] | ((data: CommentEmailTemplateData, ctx: NotificationServiceContext) => string[] | Promise<string[]>);

Additional recipients, either a static list or a function returning the list for a given action (e.g. doc watchers). Merged with the mentioned users and participants.

filter?: (data: CommentEmailTemplateData, ctx: NotificationServiceContext) => boolean | Promise<boolean>;

Optional filter called before sending. Return false to skip the notification, e.g. to ignore comments on certain collections.

from?: string;

Sender email address. Defaults to noreply@<gcp-project-id>.appspotmail.com.

cmsUrl?: string;

Base URL of the site hosting the CMS, used to build links to the commented field (e.g. https://example.com). Defaults to rootConfig.domain.

template?: EmailNotificationTemplate | ((data: CommentEmailTemplateData, ctx: NotificationServiceContext) => EmailNotificationTemplate | Promise<EmailNotificationTemplate>);

Custom email content. Either {placeholder} string templates resolved against CommentEmailTemplateData (e.g. {fieldLabel}, {by}, {content}, {url}) or a function returning the final email. When unset, a default subject and body describing the comment are used.

emailService?: string | boolean;

Email service used to trigger delivery immediately after the email is queued. See emailNotifications() for details.

expireAfterMinutes?: number;

Number of minutes after which an unsent email expires.

action: Action<FieldCommentActionMetadata>;

The action log entry that triggered the notification.

actionName: FieldCommentAction;

Action name, e.g. doc.comment.add.

by: string;

Email of the user that performed the action.

docId: string;

Doc id in the form <collection>/<slug>.

fieldKey: string;

Deep key of the commented field.

fieldLabel: string;

Human-readable label of the field, falling back to the deep key.

content: string;

Plain-text content of the comment (empty for resolve/reopen actions).

mentions: string[];

Lower-cased emails mentioned in the comment.

participants: string[];

Lower-cased emails of everyone who has commented on the thread.

summary: string;

Short human-readable description of what happened.

url: string;

Link to the field in the CMS, built from rootConfig.domain (or the cmsUrl option). Empty when neither is configured.

id?: string;

Unique ID for the service. Defaults to 'email'.

label?: string;

Human-readable label displayed in the UI. Defaults to 'Email'.

icon?: string;

Optional icon URL displayed in the UI next to the label.

to: string[] | ((action: Action, ctx: NotificationServiceContext) => string[] | Promise<string[]>);

Recipients of the email notification. Either a static list of email addresses or a function that returns the recipients for a given action (e.g. to look up watchers of a doc). Returning an empty list skips the notification.

from?: string;

Sender email address. The sender must be authorized to send email via the App Engine Mail API, e.g. noreply@<gcp-project-id>.appspotmail.com. Defaults to noreply@<gcp-project-id>.appspotmail.com.

actions?: string[];

Actions that trigger an email notification, e.g. ['doc.publish', 'release.*']. Patterns support wildcards, where * matches any number of characters and ? matches a single character. Matching is case-insensitive. When unset, all actions trigger an email notification.

filter?: (action: Action, ctx: NotificationServiceContext) => boolean | Promise<boolean>;

Optional filter called after the actions patterns match. Return false to skip the notification (e.g. to ignore actions performed by certain users).

transformData?: (action: Action, ctx: NotificationServiceContext) => T | Promise<T>;

Optional transformation applied to the action log data before the email templates are rendered. The returned value is passed to the templates as the template data. When unset, the action log data object is used as-is.

template?: EmailNotificationTemplate | ((data: T, action: Action, ctx: NotificationServiceContext) => EmailNotificationTemplate | Promise<EmailNotificationTemplate>);

Templates used to render the email. Either an object with {placeholder} string templates or a function that returns the final email content for full control. Function results are used verbatim, i.e. no placeholder rendering or HTML escaping is applied.

A missing subject falls back to the default subject template. The default body and html templates (see DEFAULT_EMAIL_TEMPLATE) apply only when neither body nor html is provided. Providing only body sends a plain-text-only email; providing only html derives the plain-text body from the html.

emailService?: string | boolean;

Email service used to trigger delivery immediately after the email is queued. Setting this to true uses the default hosted service at https://services.rootjs.dev. Set to a base URL to use a self-hosted deployment of the service (apps/root-services). When unset, the email remains queued until the email service's cron next processes the queue.

expireAfterMinutes?: number;

Number of minutes after which an unsent email expires. Expired emails are skipped by the email service instead of being delivered late. When unset, queued emails never expire.

subject?: string;

Subject line.

body?: string;

Plain-text body.

html?: string;

HTML body. Values injected into an HTML string template are HTML-escaped. Omit (while providing body) to send a plain-text-only email.

id: string;

Unique id of the entry within the thread.

type?: FieldCommentType;

Kind of entry. Defaults to comment when missing.

body?: RichTextData | null;

Rich text body of the comment.

content?: string;

Plain-text rendering of the body, used for previews and notifications.

mentions?: string[];

Lower-cased emails of users mentioned via @mention in the body.

deleted?: boolean;

Set when the comment was deleted by its author. The body is cleared.

commentId?: string;

Id of the comment entry, for add, edit and delete actions.

content?: string;

Plain-text content of the comment, truncated for the log.

mentions?: string[];

Lower-cased emails of users mentioned in the comment.

participants?: string[];

Lower-cased emails of everyone who has commented on the thread.

id: string;

Thread id. Open threads use the id derived from the field key; resolved threads carry a timestamp suffix.

docId: string;

Doc id in the form <collection>/<slug>.

fieldKey: string;

Deep key of the field within the doc, e.g. fields.hero.title.

fieldLabel?: string;

Human-readable label of the field at the time of the first comment.

comments: FieldComment[];

Chronological history of comments and status changes.

participants: string[];

Lower-cased emails of everyone who has commented on the thread.

status?: 'success' | 'info' | 'error';

Delivery status. - 'success': the notification was delivered. - 'error': delivery failed; message should describe why. - 'info' (default): the service handled the action but did not deliver a notification (e.g. the action was filtered out).

message?: string;

Optional human-readable message describing the result.

id: string;

ID of a check registered via cmsPlugin({checks: [...]}).

level?: PublishCheckLevel;

Severity level for the check. Defaults to required.

docId: string;

The doc the check ran against, e.g. Pages/index.

checkId: string;

ID of the check that produced this result.

label: string;

Human-readable label for the check.

level: PublishCheckLevel;

The severity level the check was configured with.

status: PublishCheckStatus;

Outcome of the check run.

message: string;

A message describing the result. Supports markdown.

metadata?: Record<string, any>;

Optional metadata returned by the check.

title?: string;

Optional title displayed in the notification after export.

message?: string;

Optional message displayed in the notification after export.

link?: {
    url: string;
    label?: string;
};

Optional link displayed in the notification (e.g. to the translation service).

status?: 'success' | 'info' | 'error';

Notification status controlling the color of the notification. - 'success': green - 'error': red - 'info' (default): neutral

title?: string;

Optional title displayed in the notification after import.

message?: string;

Optional message displayed in the notification after import.

link?: {
    url: string;
    label?: string;
};

Optional link displayed in the notification (e.g. to the translation service).

status?: 'success' | 'info' | 'error';

Notification status controlling the color of the notification. - 'success': green - 'error': red - 'info' (default): neutral

source: string;

The source string.

translations: Record<TranslationLanguage, string>;

Map of translation language to translated string. Translation languages are derived from the project's locales via the i18n.translationLanguages config in root.config.ts; when no mapping is configured, the keys are the locale ids themselves.

description?: string;

Optional translator notes/context for the source string.

collections?: string[];

Optional list of collection IDs to restrict this check to. When set, the check is only shown and runnable for documents in these collections.

docId: string;

The document ID, e.g. Pages/index.

collectionId: string;

The collection ID, e.g. Pages.

slug: string;

The slug, e.g. index.

locales: RootLocale[];

The locales configured for the project.

translationLanguages: TranslationLanguage[];

The translation languages for the project, derived from locales via the i18n.translationLanguages config in root.config.ts (deduped, since multiple locales may share a translation language). Equal to locales when no mapping is configured. The translations keys in TranslationRow data use these languages.

user: {
    email: string;
};

The email of the user performing the action.

components?: RichTextComponentMap;

Rich text components override for both inline and block level components.

t?: (msg: string, params?: Record<string, string | number>) => string;

Translator function override.