@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/workflows/instance.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Workflow Instance Contracts
+ *
+ * Type definitions for workflow instance state, history, and runtime tracking.
+ * Instances are the running/paused/completed executions of workflow definitions.
+ *
+ * @see plans/active/workflow/README.md
+ */
+import type { RuntimeType } from './runtime';
+/**
+ * Workflow instance status.
+ */
+export type InstanceStatus = 'pending' | 'running' | 'waiting' | 'sleeping' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'dead_letter';
+/**
+ * Workflow instance - a running/completed execution of a workflow definition.
+ */
+export interface WorkflowInstance {
+    /** Unique instance identifier */
+    id: string;
+    /** Workflow definition ID */
+    workflowId: string;
+    /** Workflow version at time of creation */
+    workflowVersion: string;
+    /** Current status */
+    status: InstanceStatus;
+    /** Current step name (null if completed/failed) */
+    currentStep: string | null;
+    /** Current runtime environment */
+    runtime: RuntimeType;
+    /** Instance state (JSON-serializable, user workflow instance variables) */
+    state: WorkflowState;
+    /** Trigger event that started this instance */
+    triggerEvent: TriggerEventData;
+    /** Step execution history */
+    history: StepHistory[];
+    /** Pending timers (for sleeping/waiting) */
+    timers: Timer[];
+    /** Events this instance is waiting for */
+    waitingForEvents?: string[];
+    /** Parent instance ID if this is a child workflow */
+    parentInstanceId?: string;
+    /** Child instance IDs spawned by this workflow */
+    childInstanceIds: string[];
+    /** Retry state for current step */
+    retryState?: RetryState;
+    /** Error information if failed */
+    error?: InstanceError;
+    /** Cancellation reason if cancelled */
+    cancellationReason?: string;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last updated timestamp (ISO 8601) */
+    updatedAt: string;
+    /** Completion timestamp (ISO 8601) */
+    completedAt?: string;
+    /** User/system that created this instance */
+    createdBy?: string;
+    /** Idempotency key for deduplication */
+    idempotencyKey?: string;
+    /** Tags for filtering/categorization */
+    tags?: string[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Workflow state - the user's instance variables.
+ * MUST be JSON-serializable (no functions, dates as ISO strings, etc.).
+ */
+export type WorkflowState = Record<string, JsonSerializable>;
+/**
+ * JSON-serializable value types.
+ */
+export type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
+    [key: string]: JsonSerializable;
+};
+/**
+ * Data about the event that triggered a workflow instance.
+ */
+export interface TriggerEventData {
+    /** Event type (e.g., "record:created", "schedule", "webhook") */
+    type: string;
+    /** Timestamp of the trigger (ISO 8601) */
+    timestamp: string;
+    /** Event payload (varies by trigger type) */
+    payload: Record<string, unknown>;
+}
+/**
+ * Record trigger event payload.
+ */
+export interface RecordTriggerPayload {
+    /** Table name */
+    table: string;
+    /** Record ID */
+    recordId: string;
+    /** Changed field (for update triggers) */
+    field?: string;
+    /** Old value (for update triggers) */
+    oldValue?: unknown;
+    /** New value (for update triggers) */
+    newValue?: unknown;
+    /** Full record data */
+    record?: Record<string, unknown>;
+}
+/**
+ * Schedule trigger event payload.
+ */
+export interface ScheduleTriggerPayload {
+    /** Scheduled time (ISO 8601) */
+    scheduledTime: string;
+    /** Cron expression */
+    cron: string;
+    /** Timezone */
+    timezone: string;
+}
+/**
+ * Webhook trigger event payload.
+ */
+export interface WebhookTriggerPayload {
+    /** Request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Request headers (filtered for safety) */
+    headers: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+    /** Request body */
+    body: unknown;
+}
+/**
+ * Cell trigger event payload.
+ */
+export interface CellTriggerPayload {
+    /** Sheet name */
+    sheet: string;
+    /** Cell address (e.g., "A1") */
+    cell: string;
+    /** Old value */
+    oldValue?: unknown;
+    /** New value */
+    newValue?: unknown;
+}
+/**
+ * Manual trigger event payload.
+ */
+export interface ManualTriggerPayload {
+    /** User input data */
+    input: Record<string, unknown>;
+    /** User who triggered */
+    triggeredBy?: string;
+}
+/**
+ * Spawned workflow trigger payload.
+ */
+export interface SpawnedTriggerPayload {
+    /** Parent workflow ID */
+    parentWorkflowId: string;
+    /** Parent instance ID */
+    parentInstanceId: string;
+    /** Input data from parent */
+    input: Record<string, unknown>;
+}
+/**
+ * Execution history entry for a step.
+ */
+export interface StepHistory {
+    /** Step name */
+    stepName: string;
+    /** Step status */
+    status: StepStatus;
+    /** Attempt number (1-indexed) */
+    attempt: number;
+    /** Start timestamp (ISO 8601) */
+    startedAt: string;
+    /** End timestamp (ISO 8601) */
+    completedAt?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Runtime where step executed */
+    runtime: RuntimeType;
+    /** Input data to the step */
+    input?: Record<string, unknown>;
+    /** Output/result from the step */
+    output?: unknown;
+    /** Error if step failed */
+    error?: StepError;
+    /** Next step transitioned to */
+    nextStep?: string;
+    /** Whether this was a retry attempt */
+    isRetry: boolean;
+}
+/**
+ * Step execution status.
+ */
+export type StepStatus = 'running' | 'completed' | 'failed' | 'skipped' | 'compensated';
+/**
+ * Step error information.
+ */
+export interface StepError {
+    /** Error type/class */
+    type: string;
+    /** Error message */
+    message: string;
+    /** Stack trace (sanitized) */
+    stack?: string;
+    /** Whether this error is retryable */
+    retryable: boolean;
+    /** Additional error context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Pending timer for a workflow instance.
+ */
+export interface Timer {
+    /** Timer ID */
+    id: string;
+    /** Timer type */
+    type: TimerType;
+    /** When the timer fires (ISO 8601) */
+    fireAt: string;
+    /** Step to resume when timer fires */
+    targetStep: string;
+    /** Events being waited for (for 'wait_for' timers) */
+    waitingForEvents?: string[];
+    /** Whether timer has fired */
+    fired: boolean;
+    /** Timer metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Timer type.
+ */
+export type TimerType = 'sleep' | 'wait_for' | 'schedule' | 'step_timeout';
+/**
+ * Retry state for current step.
+ */
+export interface RetryState {
+    /** Current attempt number (1-indexed) */
+    currentAttempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Next retry time (ISO 8601) if waiting to retry */
+    nextRetryAt?: string;
+    /** History of retry attempts */
+    attemptHistory: RetryAttempt[];
+}
+/**
+ * Individual retry attempt record.
+ */
+export interface RetryAttempt {
+    /** Attempt number */
+    attempt: number;
+    /** When attempt was made (ISO 8601) */
+    attemptedAt: string;
+    /** Error that caused retry */
+    error: StepError;
+    /** Delay before next retry (ms) */
+    delayMs: number;
+}
+/**
+ * Instance-level error information.
+ */
+export interface InstanceError {
+    /** Error type */
+    type: InstanceErrorType;
+    /** Error message */
+    message: string;
+    /** Step where error occurred */
+    stepName?: string;
+    /** Original error details */
+    originalError?: StepError;
+    /** Timestamp (ISO 8601) */
+    occurredAt: string;
+}
+/**
+ * Instance error types.
+ */
+export type InstanceErrorType = 'step_failed' | 'step_timeout' | 'wait_timeout' | 'invalid_transition' | 'serialization_error' | 'promotion_failed' | 'system_error';
+/**
+ * Options for querying workflow instances.
+ */
+export interface InstanceQueryOptions {
+    /** Filter by workflow ID */
+    workflowId?: string;
+    /** Filter by workflow class name */
+    workflowClass?: string;
+    /** Filter by status(es) */
+    status?: InstanceStatus | InstanceStatus[];
+    /** Filter by runtime */
+    runtime?: RuntimeType;
+    /** Filter by parent instance */
+    parentInstanceId?: string;
+    /** Filter by tag */
+    tags?: string[];
+    /** Custom filter conditions */
+    filter?: Record<string, unknown>;
+    /** Created after (ISO 8601) */
+    createdAfter?: string;
+    /** Created before (ISO 8601) */
+    createdBefore?: string;
+    /** Sort order */
+    sort?: InstanceSortOption;
+    /** Pagination limit */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+}
+/**
+ * Sort options for instance queries.
+ */
+export interface InstanceSortOption {
+    /** Field to sort by */
+    field: 'createdAt' | 'updatedAt' | 'status';
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Result of instance query.
+ */
+export interface InstanceQueryResult {
+    /** Matching instances */
+    instances: WorkflowInstance[];
+    /** Total count (for pagination) */
+    total: number;
+    /** Whether more results exist */
+    hasMore: boolean;
+}
+/**
+ * Lightweight instance summary for lists and monitoring.
+ */
+export interface InstanceSummary {
+    /** Instance ID */
+    id: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Workflow name */
+    workflowName: string;
+    /** Current status */
+    status: InstanceStatus;
+    /** Current step */
+    currentStep: string | null;
+    /** Runtime */
+    runtime: RuntimeType;
+    /** Progress (completed steps / total steps) */
+    progress?: {
+        completed: number;
+        total: number;
+    };
+    /** Created at */
+    createdAt: string;
+    /** Updated at */
+    updatedAt: string;
+    /** Has error */
+    hasError: boolean;
+    /** Brief error message if failed */
+    errorMessage?: string;
+}
+//# sourceMappingURL=instance.d.ts.map

package/dist/workflows/instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/workflows/instance.ts"],"names":[],"mappings":"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"}

package/dist/workflows/runtime.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Workflow Runtime Contracts
+ *
+ * Type definitions for the dual-runtime model:
+ * - Local Runtime: Browser-based (Pyodide/WebAssembly)
+ * - Cloud Runtime: Server-based (Python)
+ *
+ * Workflows can run in either runtime, with automatic promotion
+ * from local to cloud when needed (e.g., wait_for, sleep, schedules).
+ *
+ * @see plans/active/workflow/README.md
+ */
+import type { WorkflowInstance, WorkflowState } from './instance';
+/**
+ * Runtime type for workflow execution.
+ */
+export type RuntimeType = 'local' | 'cloud' | 'auto';
+/**
+ * Runtime preference configuration.
+ */
+export interface RuntimeConfig {
+    /** Default runtime for this workflow */
+    default: RuntimeType;
+    /**
+     * Conditions that trigger auto-promotion to cloud.
+     * Only relevant when default is 'local' or 'auto'.
+     */
+    autoPromotionTriggers: AutoPromotionTrigger[];
+    /**
+     * Maximum time a workflow can run locally before auto-promotion.
+     * Prevents local workflows from blocking browser resources.
+     */
+    maxLocalDurationMs?: number;
+    /**
+     * Whether to preload Pyodide on page load.
+     * If false, loaded on first workflow trigger.
+     * Default: false (lazy load)
+     */
+    preloadPyodide?: boolean;
+}
+/**
+ * Conditions that trigger automatic promotion from local to cloud.
+ */
+export type AutoPromotionTrigger = 'wait_for' | 'sleep' | 'schedule' | 'timeout' | 'explicit';
+/**
+ * State for workflow promotion from local to cloud.
+ */
+export interface PromotionState {
+    /** Whether promotion is in progress */
+    inProgress: boolean;
+    /** Promotion status */
+    status: PromotionStatus;
+    /** Step that triggered promotion */
+    triggerStep?: string;
+    /** Reason for promotion */
+    reason?: AutoPromotionTrigger;
+    /** Promotion start time (ISO 8601) */
+    startedAt?: string;
+    /** Promotion completion time (ISO 8601) */
+    completedAt?: string;
+    /** Error if promotion failed */
+    error?: PromotionError;
+    /** Cloud instance ID after successful promotion */
+    cloudInstanceId?: string;
+}
+/**
+ * Promotion status values.
+ */
+export type PromotionStatus = 'idle' | 'serializing' | 'uploading' | 'confirming' | 'completed' | 'failed';
+/**
+ * Promotion error information.
+ */
+export interface PromotionError {
+    /** Error type */
+    type: PromotionErrorType;
+    /** Error message */
+    message: string;
+    /** Error details */
+    details?: Record<string, unknown>;
+    /** Whether promotion can be retried */
+    retryable: boolean;
+}
+/**
+ * Types of promotion errors.
+ */
+export type PromotionErrorType = 'serialization_failed' | 'network_error' | 'cloud_rejected' | 'state_too_large' | 'version_mismatch' | 'timeout';
+/**
+ * Serialized workflow instance for cross-runtime transfer.
+ * MUST be JSON-serializable (no functions, dates as ISO strings, etc.).
+ */
+export interface SerializedInstance {
+    /** Instance ID */
+    id: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Workflow version */
+    workflowVersion: string;
+    /** Instance state (user's workflow variables) */
+    state: WorkflowState;
+    /** Current step name */
+    currentStep: string;
+    /** Source runtime */
+    sourceRuntime: RuntimeType;
+    /** Serialization timestamp (ISO 8601) */
+    serializedAt: string;
+    /** Step history (for replay) */
+    history: SerializedStepHistory[];
+    /** Pending timers */
+    timers: SerializedTimer[];
+    /** Trigger event data */
+    triggerEvent: Record<string, unknown>;
+    /** Metadata */
+    metadata: SerializedMetadata;
+    /** Checksum for integrity verification */
+    checksum: string;
+}
+/**
+ * Serialized step history entry.
+ */
+export interface SerializedStepHistory {
+    stepName: string;
+    status: string;
+    attempt: number;
+    startedAt: string;
+    completedAt?: string;
+    output?: unknown;
+    error?: Record<string, unknown>;
+}
+/**
+ * Serialized timer.
+ */
+export interface SerializedTimer {
+    id: string;
+    type: string;
+    fireAt: string;
+    targetStep: string;
+    waitingForEvents?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serialized metadata.
+ */
+export interface SerializedMetadata {
+    /** Parent instance ID if spawned */
+    parentInstanceId?: string;
+    /** Idempotency key */
+    idempotencyKey?: string;
+    /** Tags */
+    tags?: string[];
+    /** Custom metadata */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Capabilities available in each runtime.
+ */
+export interface RuntimeCapabilities {
+    /** Runtime type */
+    runtime: RuntimeType;
+    /** Whether HTTP requests are supported */
+    http: boolean;
+    /** Whether notifications are supported */
+    notifications: boolean;
+    /** Whether secrets access is supported */
+    secrets: boolean;
+    /** Whether spawning child workflows is supported */
+    spawnWorkflows: boolean;
+    /** Whether sleeping is supported */
+    sleep: boolean;
+    /** Whether wait_for is supported */
+    waitFor: boolean;
+    /** Maximum execution time (ms) */
+    maxExecutionTime: number | null;
+    /** Maximum state size (bytes) */
+    maxStateSize: number;
+    /** Available Python packages */
+    availablePackages: string[];
+}
+/**
+ * Interface for workflow runtime implementations.
+ */
+export interface IWorkflowRuntime {
+    /** Runtime type */
+    readonly type: RuntimeType;
+    /** Runtime capabilities */
+    readonly capabilities: RuntimeCapabilities;
+    /** Whether runtime is ready */
+    isReady(): boolean;
+    /** Initialize runtime (e.g., load Pyodide) */
+    initialize(): Promise<void>;
+    /** Execute a workflow step */
+    executeStep(instance: WorkflowInstance, stepName: string, input: Record<string, unknown>): Promise<StepExecutionResult>;
+    /** Serialize instance for promotion */
+    serializeInstance(instance: WorkflowInstance): SerializedInstance;
+    /** Deserialize instance from promotion */
+    deserializeInstance(serialized: SerializedInstance): WorkflowInstance;
+    /** Validate state is serializable */
+    validateState(state: WorkflowState): StateValidationResult;
+}
+/**
+ * Result of step execution.
+ */
+export interface StepExecutionResult {
+    /** Whether step completed successfully */
+    success: boolean;
+    /** Next step to transition to (null if completed) */
+    nextStep: string | null;
+    /** Updated instance state */
+    state: WorkflowState;
+    /** Step output/return value */
+    output?: unknown;
+    /** Error if step failed */
+    error?: {
+        type: string;
+        message: string;
+        retryable: boolean;
+    };
+    /** Whether promotion was requested */
+    promotionRequested: boolean;
+    /** Promotion reason if requested */
+    promotionReason?: AutoPromotionTrigger;
+    /** Timer to create (for sleep/wait_for) */
+    timer?: {
+        type: 'sleep' | 'wait_for';
+        fireAt: string;
+        targetStep: string;
+        waitingForEvents?: string[];
+    };
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Result of state validation.
+ */
+export interface StateValidationResult {
+    /** Whether state is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: StateValidationError[];
+    /** State size in bytes */
+    sizeBytes: number;
+}
+/**
+ * State validation error.
+ */
+export interface StateValidationError {
+    /** Path to invalid field (e.g., "deal.connection") */
+    path: string;
+    /** Error message */
+    message: string;
+    /** Invalid value (may be truncated) */
+    value?: string;
+}
+/**
+ * Pyodide loading state.
+ */
+export interface PyodideState {
+    /** Whether Pyodide is loaded */
+    loaded: boolean;
+    /** Whether Pyodide is loading */
+    loading: boolean;
+    /** Load error if any */
+    error?: string;
+    /** Load start time (ISO 8601) */
+    loadStartedAt?: string;
+    /** Load completion time (ISO 8601) */
+    loadCompletedAt?: string;
+    /** Load duration in milliseconds */
+    loadDurationMs?: number;
+    /** Pyodide version */
+    version?: string;
+}
+/**
+ * Pyodide configuration.
+ */
+export interface PyodideConfig {
+    /** CDN URL for Pyodide */
+    cdnUrl: string;
+    /** Index URL for packages */
+    indexUrl?: string;
+    /** Packages to preload */
+    preloadPackages?: string[];
+    /** Whether to load micropip */
+    loadMicropip?: boolean;
+    /** Memory limit in bytes */
+    memoryLimit?: number;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/workflows/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/workflows/runtime.ts"],"names":[],"mappings":"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"}