@riverbankcms/sdk 0.128.0 → 0.129.1

package/dist/_dts/sdk/src/cli/errors.d.ts

@@ -1,62 +0,0 @@
-/**
- * CLI Error Handling
- *
- * Provides enhanced error formatting for CLI commands.
- */
-/**
- * SDK CLI error codes
- */
-export declare const ErrorCodes: {
-    readonly MISSING_ENV: "sdk:missing-env";
-    readonly INVALID_CONFIG: "sdk:invalid-config";
-    readonly NETWORK_ERROR: "sdk:network-error";
-    readonly TIMEOUT: "sdk:timeout";
-    readonly UNAUTHORIZED: "sdk:unauthorized";
-    readonly FORBIDDEN: "sdk:forbidden";
-    readonly VALIDATION_ERROR: "sdk:validation-error";
-    readonly MISSING_CONTENT_TYPE: "sdk:missing-content-type";
-    readonly UNKNOWN_BLOCK_KIND: "sdk:unknown-block-kind";
-    readonly FILE_NOT_FOUND: "sdk:file-not-found";
-    readonly FILE_WRITE_ERROR: "sdk:file-write-error";
-    readonly UNKNOWN: "sdk:unknown";
-};
-export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-/**
- * Format error for CLI display
- */
-export interface FormattedError {
-    code: string;
-    message: string;
-    details?: unknown;
-    suggestion?: string;
-}
-export type CliEnvironmentTarget = 'local' | 'remote';
-export interface CliErrorContext {
-    target: CliEnvironmentTarget;
-    dashboardUrl?: string;
-    siteId?: string;
-}
-/**
- * Format an error for CLI display
- */
-export declare function formatError(error: unknown, ctx?: CliErrorContext): FormattedError;
-/**
- * Format validation errors for display
- */
-export declare function formatValidationErrors(errors: Array<{
-    path: string;
-    message: string;
-}>): string;
-/**
- * Format push operation diff for display
- */
-export interface DiffItem {
-    type: 'add' | 'update' | 'delete';
-    identifier: string;
-    contentType?: string;
-}
-export declare function formatDiff(items: DiffItem[]): string;
-/**
- * Get actionable message for SDK error
- */
-export declare function getActionableMessage(code: string): string | undefined;

package/dist/_dts/sdk/src/cli/helpers/ai-runtime.d.ts

@@ -1,2 +0,0 @@
-import type { AiRuntime } from '../../ai/runtime';
-export declare function loadAiRuntime(moduleId?: string): Promise<AiRuntime>;

package/dist/_dts/sdk/src/cli/helpers.d.ts

@@ -1,399 +0,0 @@
-/**
- * Shared CLI Helpers
- *
- * Common utilities and types shared across CLI commands.
- * Reduces duplication and ensures consistent behavior.
- */
-import { Command } from 'commander';
-import type { SiteId } from '../../../core/src/index';
-import type { ManagementClient } from '../client/management/types';
-import { InvocationEnvelope, type OutputContext } from './output';
-import { type CliErrorContext } from './errors';
-/**
- * Run `fn` within a fresh invocation envelope. Returns the envelope so `runCli`
- * can flush it and derive the exit code after the run completes (or fails).
- */
-export declare function runWithInvocation<T>(fn: (envelope: InvocationEnvelope) => Promise<T>): {
-    envelope: InvocationEnvelope;
-    done: Promise<T>;
-};
-/** The current invocation's envelope, if output is running inside `runCli`. */
-export declare function currentInvocationEnvelope(): InvocationEnvelope | undefined;
-/**
- * Build the space-separated command path for the envelope's `command` field,
- * excluding the root program name (e.g. `entry upsert`, `drafts`).
- */
-export declare function resolveCommandPath(command: Command): string;
-/**
- * Create an OutputContext bound to a command. In JSON mode it resolves the
- * current invocation's envelope from the async context, so all output funnels
- * into one document.
- */
-export declare function createOutputForCommand(command: Command): OutputContext;
-/**
- * Environment target for CLI operations.
- */
-export type EnvTarget = 'local' | 'remote';
-/**
- * Result of an operation on a specific environment.
- */
-export interface EnvResult<T> {
-    success: boolean;
-    result?: T;
-    error?: Error;
-}
-/**
- * Global options available on all commands via --json, --quiet, --env flags.
- */
-export interface GlobalOptions {
-    json?: boolean;
-    quiet?: boolean;
-    /** @deprecated Use --env=remote instead */
-    remote?: boolean;
-    /** Target environment: local, remote, or both */
-    env?: string;
-}
-/**
- * Options for commands that accept JSON data via --data or --file.
- */
-export interface DataInputOptions {
-    data?: string;
-    file?: string;
-}
-/**
- * Options for commands that require confirmation.
- */
-export interface ConfirmOptions {
-    yes?: boolean;
-}
-/**
- * Context object provided to command handlers.
- */
-export interface CommandContext {
-    output: OutputContext;
-    client: ManagementClient;
-    isRemote: boolean;
-    isJsonOutput: boolean;
-    targetEnv: EnvTarget;
-    siteId: SiteId;
-    /** Environment targets for this operation */
-    envTargets: EnvTarget[];
-}
-/**
- * Pagination options for list commands.
- */
-export interface PaginationOptions {
-    limit?: string;
-    page?: string;
-}
-/**
- * Parsed pagination values.
- */
-export interface ParsedPagination {
-    limit: number;
-    page: number;
-}
-/**
- * Type for row formatter functions used in table display.
- * Each formatter takes an entity and returns an array of string values.
- *
- * @example
- * const formatEntryRow: RowFormatter<ManagementEntry> = (entry) => [
- *   entry.identifier,
- *   entry.status,
- *   formatDateShort(entry.updatedAt),
- * ];
- */
-export type RowFormatter<T> = (item: T) => string[];
-/**
- * Entry format written to content/entries/*.json.
- * Operational fields such as manual ordering and unpublished state live in
- * metadata so entry files remain authoring-focused.
- */
-export interface EntryContentFileOutput {
-    identifier: string;
-    data: Record<string, unknown>;
-    status: 'draft' | 'published';
-    /** Slug for URL routing - only present for routable content types */
-    slug?: string;
-    blocks?: Record<string, Array<{
-        identifier: string | null;
-        kind: string;
-        content: Record<string, unknown>;
-    }>>;
-}
-/**
- * Map an entry from API response to pull output format.
- * Conditionally includes slug only for routable content (when slug is defined).
- */
-export interface EntryForOutput {
-    identifier: string;
-    data: Record<string, unknown>;
-    status: 'draft' | 'published';
-    hasUnpublishedChanges: boolean;
-    slug?: string;
-    title?: string;
-    manualOrder?: number;
-    blocks?: EntryContentFileOutput['blocks'];
-}
-export declare function mapEntryForOutput<T extends EntryForOutput>(entry: T): EntryContentFileOutput;
-/**
- * Parse pagination options from command flags.
- *
- * @param options - Object containing optional limit and page strings
- * @returns Parsed pagination values with defaults
- *
- * @example
- * const { limit, page } = parsePaginationOptions({ limit: '10', page: '2' });
- */
-export declare function parsePaginationOptions(options: PaginationOptions): ParsedPagination;
-/**
- * Format an ISO date string to a short date (YYYY-MM-DD).
- *
- * @param isoDate - ISO date string (e.g., "2024-01-15T10:30:00Z")
- * @returns Short date string (e.g., "2024-01-15")
- *
- * @example
- * formatDateShort("2024-01-15T10:30:00Z") // "2024-01-15"
- */
-export declare function formatDateShort(isoDate: string): string;
-/**
- * Parse JSON data from --data flag or --file flag.
- *
- * @param options - Object containing optional data string or file path
- * @returns Parsed JSON object
- * @throws Error if neither data nor file is provided
- * @throws SyntaxError if JSON is invalid
- *
- * @example
- * const data = await parseJsonData({ data: '{"title": "Hello"}' });
- * const data = await parseJsonData({ file: './content.json' });
- */
-export declare function parseJsonData(options: DataInputOptions): Promise<Record<string, unknown>>;
-/**
- * Parse JSON array from --data flag or --file flag.
- * Handles both direct array format and { items: [...] } wrapper format.
- *
- * @param options - Object containing optional data string or file path
- * @returns Parsed JSON array
- *
- * @example
- * const items = await parseJsonArray({ file: './items.json' });
- */
-export declare function parseJsonArray<T>(options: DataInputOptions): Promise<T[]>;
-/**
- * Prompt for confirmation unless --yes is provided.
- * Remote operations always require --yes for safety.
- *
- * @param message - Confirmation message to display
- * @param options - Object containing optional yes flag
- * @param isRemote - Whether this is a remote operation
- * @returns True if confirmed, false otherwise
- *
- * @example
- * const confirmed = await confirmAction('Delete entry "post-1"?', { yes: false }, true);
- * if (!confirmed) return;
- */
-export declare function confirmAction(message: string, options: ConfirmOptions, isRemote: boolean): Promise<boolean>;
-/**
- * Parse the --env flag value into an array of environment targets.
- *
- * @param env - The --env flag value (local, remote, or both)
- * @returns Array of environment targets
- * @throws Error if invalid value
- *
- * @example
- * parseEnvTargets('local')  // ['local']
- * parseEnvTargets('remote') // ['remote']
- * parseEnvTargets('both')   // ['local', 'remote']
- */
-export declare function parseEnvTargets(env: string): EnvTarget[];
-/**
- * Run an operation for multiple environment targets in parallel.
- * Continues execution even if one environment fails.
- *
- * @param targets - Environment targets to run the operation for
- * @param operation - Async operation to run for each target
- * @param output - Output context for logging
- * @returns Map of results for each environment
- *
- * @example
- * const results = await runForEnvironments(
- *   ['local', 'remote'],
- *   async (target) => {
- *     const client = createClientForEnv(target);
- *     return client.push(content);
- *   },
- *   output
- * );
- */
-export declare function runForEnvironments<T>(targets: EnvTarget[], operation: (target: EnvTarget) => Promise<T>, output: OutputContext, options?: {
-    /**
-     * Optional predicate to determine logical success for fulfilled operations.
-     * If omitted, any fulfilled operation is treated as success.
-     */
-    isResultSuccess?: (result: T) => boolean;
-    /**
-     * Optional formatter for logical-failure errors in results by environment output.
-     */
-    formatFailure?: (result: T) => string;
-}): Promise<Map<EnvTarget, EnvResult<T>>>;
-/**
- * Check if all environments succeeded.
- */
-export declare function allEnvSucceeded<T>(results: Map<EnvTarget, EnvResult<T>>): boolean;
-/**
- * Create a management client for a specific environment target.
- *
- * @param target - Environment target (local or remote)
- * @returns Management client configured for that environment
- */
-export declare function createClientForEnv(target: EnvTarget): ManagementClient;
-/**
- * Create command context with output, client, and environment info.
- *
- * @param command - Commander command instance
- * @returns Context object with output, client, environment targets, and flags
- *
- * @example
- * const ctx = createCommandContext(command);
- * ctx.output.info('Starting...');
- * await ctx.client.entries.get('post', 'my-post');
- */
-export declare function createCommandContext(command: Command): CommandContext;
-/**
- * Get global options and output context without creating a client.
- * Useful when you need to check conditions before creating the client.
- *
- * @param command - Commander command instance
- * @returns Object with output, environment info, and globalOpts
- */
-export declare function getOutputContext(command: Command): {
-    output: OutputContext;
-    isRemote: boolean;
-    envTargets: EnvTarget[];
-    globalOpts: GlobalOptions;
-};
-/**
- * Handle errors in a consistent way across all commands.
- *
- * @param error - The error that occurred
- * @param output - Output context for displaying errors
- *
- * @example
- * try {
- *   await doSomething();
- * } catch (error) {
- *   handleCommandError(error, output);
- * }
- */
-export declare function handleCommandError(error: unknown, output: OutputContext, ctx?: CliErrorContext): void;
-/**
- * Wrap an async command action with standard error handling.
- *
- * @param action - The async action to wrap
- * @returns Wrapped action that handles errors
- *
- * @example
- * .action(withErrorHandling(async (args, options, command) => {
- *   const ctx = createCommandContext(command);
- *   // ... command logic
- * }))
- */
-export declare function withErrorHandling<TArgs extends unknown[]>(action: (...args: [...TArgs, Command]) => Promise<void>): (...args: [...TArgs, Command]) => Promise<void>;
-/**
- * Wrap a command action so handlers receive a resolved command context instead
- * of the raw Commander instance.
- */
-export declare function withCommandContext<TArgs extends unknown[], TOptions = unknown>(action: (ctx: CommandContext, ...args: [...TArgs, TOptions]) => Promise<void>): (...args: [...TArgs, TOptions, Command]) => Promise<void>;
-/**
- * Wrap a destructive command action with confirmation prompt and error handling.
- *
- * @param getMessage - Function that builds the confirmation message from command args
- * @param action - The async action to perform after confirmation
- * @returns Wrapped action that confirms, then executes with error handling
- *
- * @example
- * .action(withConfirmation(
- *   (type, identifier) => `Delete entry "${type}/${identifier}"?`,
- *   async (ctx, type, identifier) => {
- *     ctx.output.info(`Deleting entry: ${type}/${identifier}`);
- *     await ctx.client.entries.delete(type, identifier);
- *     ctx.output.success(`Entry deleted: ${identifier}`);
- *   }
- * ))
- */
-export declare function withConfirmation<TArgs extends unknown[]>(getMessage: (...args: TArgs) => string, action: (ctx: CommandContext, ...args: TArgs) => Promise<void>): (...args: [...TArgs, ConfirmOptions, Command]) => Promise<void>;
-/**
- * Configuration for get command factory.
- */
-export interface GetCommandConfig<T> {
-    /** Resource name for display (e.g., 'entry', 'page') */
-    resourceName: string;
-    /** Argument names (e.g., ['type', 'identifier'] or ['identifier']) */
-    args: readonly string[];
-    /** Function to fetch the resource */
-    get: (client: ManagementClient, ...args: string[]) => Promise<T | null>;
-    /** Function to format the resource for non-JSON output */
-    formatOutput: (item: T) => Record<string, unknown>;
-}
-/**
- * Create a get command for a resource.
- *
- * @example
- * const getCommand = createGetCommand({
- *   resourceName: 'entry',
- *   args: ['type', 'identifier'],
- *   get: (client, type, id) => client.entries.get(type, id),
- *   formatOutput: (entry) => ({
- *     id: entry.id,
- *     status: entry.status,
- *   }),
- * });
- */
-export declare function createGetCommand<T>(config: GetCommandConfig<T>): Command;
-/**
- * Result type for list operations.
- */
-export interface ListResult<T> {
-    items: T[];
-    pagination?: {
-        page: number;
-        limit: number;
-        total: number;
-    };
-}
-/**
- * Configuration for list command factory.
- */
-export interface ListCommandConfig<T> {
-    /** Resource name for display (e.g., 'entry', 'page') */
-    resourceName: string;
-    /** Plural resource name (e.g., 'entries', 'pages') */
-    resourceNamePlural: string;
-    /** Argument names (e.g., ['type'] for entries, [] for pages) */
-    args: readonly string[];
-    /** Whether this list supports pagination options */
-    hasPagination: boolean;
-    /** Function to fetch the list - receives args as array plus optional pagination */
-    list: (client: ManagementClient, args: string[], pagination?: ParsedPagination) => Promise<ListResult<T>>;
-    /** Table column headers */
-    tableHeaders: string[];
-    /** Row formatter for table display */
-    formatRow: RowFormatter<T>;
-}
-/**
- * Create a list command for a resource.
- *
- * @example
- * const listCommand = createListCommand({
- *   resourceName: 'entry',
- *   resourceNamePlural: 'entries',
- *   args: ['type'],
- *   hasPagination: true,
- *   list: (client, [type], pagination) => client.entries.list(type, pagination),
- *   tableHeaders: ['Identifier', 'Status', 'Updated'],
- *   formatRow: (entry) => [entry.identifier, entry.status, entry.updatedAt],
- * });
- */
-export declare function createListCommand<T>(config: ListCommandConfig<T>): Command;

package/dist/_dts/sdk/src/cli/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Riverbank CMS SDK CLI
- *
- * CLI tools for SDK site developers.
- * Supports bidirectional content management: pull content from CMS and push content back.
- *
- * This module is the bin entry point: it loads env files, then runs the CLI via
- * `runCli`, which owns the process exit code and guarantees exactly one JSON
- * envelope per invocation under `--json`. The command tree lives in `program.ts`.
- */
-export {};

package/dist/_dts/sdk/src/cli/init-docs/constants.d.ts

@@ -1,16 +0,0 @@
-/**
- * Shared constants for init-docs functionality.
- */
-/**
- * Deprecated theme fields to omit from documentation.
- * Empty since legacy fields (customCss, blockCustomCss) have been removed from the schema.
- */
-export declare const DEPRECATED_THEME_FIELDS: string[];
-/**
- * Category mapping for theme schema fields.
- * Maps field names to their documentation category.
- *
- * When adding new top-level fields to themeSchema, add them here
- * to ensure proper categorization in generated docs.
- */
-export declare const THEME_FIELD_CATEGORY_MAP: Record<string, string[]>;

package/dist/_dts/sdk/src/cli/init-docs/index.d.ts

@@ -1,12 +0,0 @@
-type InitDocsOptions = {
-    rootDir: string;
-    configPath?: string;
-    agentsPath: string;
-    output?: {
-        info(message: string, data?: unknown): void;
-        warn(message: string, data?: unknown): void;
-        success(message: string, data?: unknown): void;
-    };
-};
-export declare function initDocs(options: InitDocsOptions): Promise<void>;
-export {};

package/dist/_dts/sdk/src/cli/init-docs/templates.d.ts

@@ -1,18 +0,0 @@
-import type { RiverbankSiteConfig } from '../../config/types';
-type SectionState = {
-    config?: RiverbankSiteConfig;
-    errorMessage?: string;
-};
-export declare function getGeneratedMarkers(): {
-    start: string;
-    end: string;
-};
-export declare function buildSchemaTemplate(state: SectionState): string;
-export declare function buildBlockTypesTemplate(): string;
-export declare function buildSiteBlockTypesTemplate(state: SectionState): string;
-export declare function buildSchemaGeneratedSection(state: SectionState): string;
-export declare function buildBlockTypesGeneratedSection(): string;
-export declare function buildSiteBlockTypesGeneratedSection(state: SectionState): string;
-export declare function buildThemeSchemaTemplate(): string;
-export declare function buildThemeSchemaGeneratedSection(): string;
-export {};

package/dist/_dts/sdk/src/cli/init-docs/zod-to-markdown.d.ts

@@ -1,28 +0,0 @@
-/**
- * Zod Schema Introspection Utility
- *
- * Walks Zod schemas and generates markdown documentation.
- * Uses Zod's internal _def property for introspection.
- */
-import type { ZodTypeAny } from 'zod';
-export type SchemaFieldInfo = {
-    name: string;
-    type: string;
-    optional: boolean;
-    nullable: boolean;
-    description?: string;
-    enumValues?: string[];
-    literalValue?: string;
-    children?: SchemaFieldInfo[];
-    arrayElementType?: string;
-    recordValueType?: string;
-    defaultValue?: unknown;
-};
-/**
- * Extract information from a schema recursively
- */
-export declare function extractSchemaInfo(schema: ZodTypeAny, skipFields?: string[]): SchemaFieldInfo[];
-/**
- * Group fields by category for documentation organization
- */
-export declare function groupFieldsByCategory(fields: SchemaFieldInfo[]): Map<string, SchemaFieldInfo[]>;

package/dist/_dts/sdk/src/cli/load-config.d.ts

@@ -1,14 +0,0 @@
-/**
- * Config file loader for riverbank.config.ts
- *
- * Uses jiti to load TypeScript config files at runtime without
- * requiring a build step.
- */
-/**
- * Load builder config from a TypeScript file.
- *
- * @param configPath - Path to config file, or directory containing riverbank.config.ts
- * @returns The loaded config object
- * @throws Error if config file not found or invalid
- */
-export declare function loadConfigFile(configPath?: string): Promise<unknown>;

package/dist/_dts/sdk/src/cli/media/identifiers.d.ts

@@ -1,18 +0,0 @@
-import type { PulledContent } from '../../client/management/types';
-import type { LocalContent } from '../content/reader';
-export type MediaValue = {
-    type: 'image' | 'video' | 'audio' | 'document' | 'spreadsheet' | 'archive';
-    identifier?: string | null;
-    assetId?: string;
-    storagePath?: string;
-    storageBucket?: string;
-    src?: string;
-    mimeType?: string;
-    width?: number;
-    height?: number;
-    [key: string]: unknown;
-};
-type MediaValueHandler = (value: MediaValue, location: string) => void;
-export declare const walkLocalContentMedia: (content: LocalContent, handler: MediaValueHandler) => void;
-export declare const walkPulledContentMedia: (content: PulledContent, handler: MediaValueHandler) => void;
-export {};

package/dist/_dts/sdk/src/cli/media/local-media.d.ts

@@ -1,14 +0,0 @@
-import type { LocalMediaManifest } from '../content/media-manifest';
-export type LocalMediaFile = {
-    identifier: string;
-    filename: string;
-    filePath: string;
-    mimeType: string;
-    checksum: string;
-    data: Buffer;
-};
-export declare const MEDIA_DIR_NAME = "media";
-export declare function loadLocalMediaFile(contentDir: string, identifier: string, manifest: LocalMediaManifest): Promise<LocalMediaFile | null>;
-export declare function writeLocalMediaFile(contentDir: string, filename: string, data: Buffer): Promise<string>;
-export declare function readLocalMediaChecksum(filePath: string): Promise<string>;
-export declare function localMediaFileExists(filePath: string): Promise<boolean>;