@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/workflows/triggers.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Workflow Trigger Contracts
+ *
+ * Type definitions for workflow triggers - the conditions that start workflows.
+ *
+ * Trigger Types:
+ * - Record triggers: record:created, record:updated, record:deleted
+ * - Cell triggers: cell:changed
+ * - Relation triggers: relation:linked, relation:unlinked
+ * - Schedule triggers: cron-based schedules (cloud-only)
+ * - Webhook triggers: external HTTP requests (cloud-only)
+ * - Manual triggers: user-initiated
+ * - Spawned triggers: started by another workflow
+ *
+ * @see plans/active/workflow/README.md
+ */
+/**
+ * All supported trigger types.
+ */
+export type TriggerType = 'record:created' | 'record:updated' | 'record:deleted' | 'cell:changed' | 'relation:linked' | 'relation:unlinked' | 'schedule' | 'webhook' | 'manual' | 'workflow:spawned';
+/**
+ * Union of all trigger configurations.
+ */
+export type TriggerConfig = RecordTrigger | CellTrigger | RelationTrigger | ScheduleTrigger | WebhookTrigger | ManualTrigger | SpawnedTrigger;
+/**
+ * Base configuration for record triggers.
+ */
+export interface RecordTriggerBase {
+    /** Table name to watch */
+    table: string;
+    /** Optional filter condition (only trigger if record matches) */
+    filter?: RecordFilterCondition;
+}
+/**
+ * Trigger when a record is created.
+ */
+export interface RecordCreatedTrigger extends RecordTriggerBase {
+    type: 'record:created';
+}
+/**
+ * Trigger when a record is updated.
+ */
+export interface RecordUpdatedTrigger extends RecordTriggerBase {
+    type: 'record:updated';
+    /** Specific field to watch (any field if not specified) */
+    field?: string;
+    /** Specific value to match (any value if not specified) */
+    value?: unknown;
+    /** Only trigger if field changed FROM this value */
+    oldValue?: unknown;
+}
+/**
+ * Trigger when a record is deleted.
+ */
+export interface RecordDeletedTrigger extends RecordTriggerBase {
+    type: 'record:deleted';
+}
+/**
+ * Union of all record triggers.
+ */
+export type RecordTrigger = RecordCreatedTrigger | RecordUpdatedTrigger | RecordDeletedTrigger;
+/**
+ * Filter condition for record triggers.
+ */
+export interface RecordFilterCondition {
+    field: string;
+    operator: FilterOperator;
+    value: unknown;
+}
+/**
+ * Filter operators for record triggers.
+ */
+export type FilterOperator = 'equals' | 'not_equals' | 'contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'greater_than_or_equals' | 'less_than' | 'less_than_or_equals' | 'in' | 'not_in' | 'is_null' | 'is_not_null';
+/**
+ * Trigger when a cell value changes.
+ */
+export interface CellTrigger {
+    type: 'cell:changed';
+    /** Sheet name to watch */
+    sheet: string;
+    /** Range to watch (e.g., "B2:B100", "A1", "Column:B") */
+    range: string;
+    /** Optional filter on value */
+    filter?: CellFilterCondition;
+}
+/**
+ * Filter condition for cell triggers.
+ */
+export interface CellFilterCondition {
+    /** Only trigger if new value matches */
+    newValue?: unknown;
+    /** Only trigger if old value matches */
+    oldValue?: unknown;
+    /** Only trigger if value changed (true = must change, false = any update) */
+    changed?: boolean;
+}
+/**
+ * Trigger when a relation is linked.
+ */
+export interface RelationLinkedTrigger {
+    type: 'relation:linked';
+    /** Table containing the relation column */
+    table: string;
+    /** Relation column name */
+    column: string;
+    /** Optional: target table (only trigger if linked to specific table) */
+    targetTable?: string;
+}
+/**
+ * Trigger when a relation is unlinked.
+ */
+export interface RelationUnlinkedTrigger {
+    type: 'relation:unlinked';
+    /** Table containing the relation column */
+    table: string;
+    /** Relation column name */
+    column: string;
+    /** Optional: target table */
+    targetTable?: string;
+}
+/**
+ * Union of relation triggers.
+ */
+export type RelationTrigger = RelationLinkedTrigger | RelationUnlinkedTrigger;
+/**
+ * Trigger on a schedule (cron expression).
+ * Always runs on cloud runtime.
+ */
+export interface ScheduleTrigger {
+    type: 'schedule';
+    /** Cron expression (e.g., "0 9 * * 1" for Monday 9am) */
+    cron: string;
+    /** Timezone (e.g., "America/New_York", "UTC") */
+    timezone: string;
+    /**
+     * Whether to catch up on missed schedules.
+     * If true, runs immediately for any missed scheduled times.
+     * Default: false
+     */
+    catchUp?: boolean;
+    /**
+     * Maximum concurrent instances from this schedule.
+     * If an instance is still running when the next schedule fires,
+     * new instance is skipped if maxConcurrent is reached.
+     * Default: 1
+     */
+    maxConcurrent?: number;
+}
+/**
+ * Trigger from an external HTTP request.
+ * Always runs on cloud runtime.
+ */
+export interface WebhookTrigger {
+    type: 'webhook';
+    /** URL path (e.g., "/stripe-payment") */
+    path: string;
+    /** HTTP method (default: POST) */
+    method: WebhookMethod;
+    /** Optional authentication configuration */
+    auth?: WebhookAuth;
+    /** Validation schema for request body (JSON Schema) */
+    bodySchema?: Record<string, unknown>;
+    /** Transform function name to apply to request body */
+    transform?: string;
+}
+/**
+ * Supported HTTP methods for webhooks.
+ */
+export type WebhookMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Webhook authentication configuration.
+ */
+export type WebhookAuth = WebhookAuthNone | WebhookAuthBearer | WebhookAuthApiKey | WebhookAuthHmac;
+export interface WebhookAuthNone {
+    type: 'none';
+}
+export interface WebhookAuthBearer {
+    type: 'bearer';
+    /** Secret name containing the expected token */
+    secretName: string;
+}
+export interface WebhookAuthApiKey {
+    type: 'api_key';
+    /** Header name to check */
+    headerName: string;
+    /** Secret name containing the expected key */
+    secretName: string;
+}
+export interface WebhookAuthHmac {
+    type: 'hmac';
+    /** Header name containing the signature */
+    signatureHeader: string;
+    /** Secret name containing the signing key */
+    secretName: string;
+    /** HMAC algorithm (default: sha256) */
+    algorithm?: 'sha256' | 'sha512';
+}
+/**
+ * Trigger manually by user or API call.
+ */
+export interface ManualTrigger {
+    type: 'manual';
+    /**
+     * Input schema (JSON Schema) for manual trigger.
+     * Used for UI form generation and validation.
+     */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Required permissions to trigger this workflow.
+     */
+    requiredPermissions?: string[];
+}
+/**
+ * Trigger when spawned by another workflow.
+ */
+export interface SpawnedTrigger {
+    type: 'workflow:spawned';
+    /**
+     * Input schema (JSON Schema) expected from parent.
+     */
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * Event data passed to workflow when triggered.
+ */
+export interface TriggerEvent {
+    /** Trigger type */
+    type: TriggerType;
+    /** Unique event ID */
+    eventId: string;
+    /** Timestamp when trigger fired (ISO 8601) */
+    timestamp: string;
+    /** Trigger-specific payload */
+    payload: TriggerPayload;
+}
+/**
+ * Union of all trigger payloads.
+ */
+export type TriggerPayload = RecordTriggerPayload | CellTriggerPayload | RelationTriggerPayload | ScheduleTriggerPayload | WebhookTriggerPayload | ManualTriggerPayload | SpawnedTriggerPayload;
+/**
+ * Payload for record triggers.
+ */
+export interface RecordTriggerPayload {
+    table: string;
+    recordId: string;
+    record?: Record<string, unknown>;
+    field?: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+/**
+ * Payload for cell triggers.
+ */
+export interface CellTriggerPayload {
+    sheet: string;
+    cell: string;
+    range: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+/**
+ * Payload for relation triggers.
+ */
+export interface RelationTriggerPayload {
+    table: string;
+    column: string;
+    sourceRecordId: string;
+    targetRecordId: string;
+    targetTable: string;
+}
+/**
+ * Payload for schedule triggers.
+ */
+export interface ScheduleTriggerPayload {
+    scheduledTime: string;
+    cron: string;
+    timezone: string;
+}
+/**
+ * Payload for webhook triggers.
+ */
+export interface WebhookTriggerPayload {
+    path: string;
+    method: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body: unknown;
+    remoteAddress?: string;
+}
+/**
+ * Payload for manual triggers.
+ */
+export interface ManualTriggerPayload {
+    input: Record<string, unknown>;
+    triggeredBy?: string;
+}
+/**
+ * Payload for spawned triggers.
+ */
+export interface SpawnedTriggerPayload {
+    parentWorkflowId: string;
+    parentInstanceId: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Registered trigger with metadata.
+ */
+export interface RegisteredTrigger {
+    /** Trigger ID */
+    id: string;
+    /** Workflow ID this trigger starts */
+    workflowId: string;
+    /** Workflow version */
+    workflowVersion: string;
+    /** Trigger configuration */
+    config: TriggerConfig;
+    /** Whether trigger is active */
+    active: boolean;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last updated timestamp */
+    updatedAt: string;
+}
+/**
+ * Trigger match result.
+ */
+export interface TriggerMatch {
+    /** Matched trigger */
+    trigger: RegisteredTrigger;
+    /** Event that matched */
+    event: TriggerEvent;
+    /** Score (for prioritization when multiple triggers match) */
+    score: number;
+}
+//# sourceMappingURL=triggers.d.ts.map

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

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

package/dist/workflows/versioning.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Workflow Versioning Contracts
+ *
+ * Type definitions for workflow versioning and migration.
+ * Versioning is critical for durable workflows because instances
+ * may run for days/weeks while the workflow code is updated.
+ *
+ * Strategies:
+ * - replace: New instances use new code, running instances use old code
+ * - parallel: Both versions run independently
+ * - migrate: Running instances are migrated to new version
+ *
+ * @see plans/active/workflow/README.md
+ */
+import type { WorkflowState } from './instance';
+/**
+ * Strategy for handling workflow version upgrades.
+ */
+export type VersioningStrategy = 'replace' | 'parallel' | 'migrate';
+/**
+ * Detailed versioning strategy configuration.
+ */
+export interface VersioningConfig {
+    /** Strategy type */
+    strategy: VersioningStrategy;
+    /**
+     * For 'replace' strategy: how long to keep old version active
+     * for running instances (default: until all instances complete)
+     */
+    gracePeriod?: string;
+    /**
+     * For 'parallel' strategy: which version is default for new triggers
+     */
+    defaultVersion?: 'latest' | 'previous' | string;
+    /**
+     * For 'migrate' strategy: migration function reference
+     */
+    migration?: MigrationConfig;
+}
+/**
+ * Reference to a migration function.
+ */
+export type MigrationFunction = string;
+/**
+ * Migration configuration for 'migrate' strategy.
+ */
+export interface MigrationConfig {
+    /** Migration function name (class method) */
+    functionName: string;
+    /**
+     * Whether to migrate immediately or lazily.
+     * - 'immediate': Migrate all running instances when new version deploys
+     * - 'lazy': Migrate each instance when it next needs to execute
+     * Default: 'lazy'
+     */
+    timing: 'immediate' | 'lazy';
+    /**
+     * Whether migration is reversible.
+     * If true, must also provide rollback function.
+     */
+    reversible: boolean;
+    /** Rollback function name (required if reversible: true) */
+    rollbackFunctionName?: string;
+    /**
+     * Maximum instances to migrate in parallel.
+     * Only relevant for 'immediate' timing.
+     * Default: 10
+     */
+    batchSize?: number;
+    /**
+     * Timeout for individual migration (ISO 8601 duration).
+     * Default: '5m'
+     */
+    timeout?: string;
+}
+/**
+ * Migration operation (runtime).
+ */
+export interface MigrationOperation {
+    /** Migration ID */
+    id: string;
+    /** Source version */
+    fromVersion: string;
+    /** Target version */
+    toVersion: string;
+    /** Migration status */
+    status: MigrationStatus;
+    /** Instances to migrate */
+    totalInstances: number;
+    /** Instances migrated successfully */
+    migratedInstances: number;
+    /** Instances that failed migration */
+    failedInstances: number;
+    /** Start time (ISO 8601) */
+    startedAt: string;
+    /** Completion time (ISO 8601) */
+    completedAt?: string;
+    /** Failed instance details */
+    failures?: MigrationFailure[];
+}
+/**
+ * Migration status.
+ */
+export type MigrationStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'rolled_back';
+/**
+ * Migration failure details.
+ */
+export interface MigrationFailure {
+    /** Instance ID */
+    instanceId: string;
+    /** Error message */
+    error: string;
+    /** Old state (before migration attempt) */
+    oldState?: WorkflowState;
+    /** Whether rollback was applied */
+    rolledBack: boolean;
+    /** Timestamp */
+    timestamp: string;
+}
+/**
+ * Workflow version information.
+ */
+export interface WorkflowVersion {
+    /** Version string (semantic versioning) */
+    version: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Whether this version is active (accepting new triggers) */
+    active: boolean;
+    /** Whether this version is deprecated */
+    deprecated: boolean;
+    /** Deprecation message if deprecated */
+    deprecationMessage?: string;
+    /** Number of running instances on this version */
+    runningInstances: number;
+    /** Deployment timestamp (ISO 8601) */
+    deployedAt: string;
+    /** Deployment user/system */
+    deployedBy?: string;
+    /** Version metadata */
+    metadata?: VersionMetadata;
+}
+/**
+ * Version metadata.
+ */
+export interface VersionMetadata {
+    /** Git commit hash */
+    commitHash?: string;
+    /** Git branch */
+    branch?: string;
+    /** Change description */
+    description?: string;
+    /** Breaking changes from previous version */
+    breakingChanges?: string[];
+    /** Migration notes */
+    migrationNotes?: string;
+}
+/**
+ * Semantic version components.
+ */
+export interface SemanticVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    build?: string;
+}
+/**
+ * Interface for workflow version registry.
+ */
+export interface IVersionRegistry {
+    /**
+     * Register a new workflow version.
+     */
+    register(workflowId: string, version: string, metadata?: VersionMetadata): Promise<void>;
+    /**
+     * Get all versions for a workflow.
+     */
+    getVersions(workflowId: string): Promise<WorkflowVersion[]>;
+    /**
+     * Get the latest active version.
+     */
+    getLatestVersion(workflowId: string): Promise<WorkflowVersion | null>;
+    /**
+     * Get a specific version.
+     */
+    getVersion(workflowId: string, version: string): Promise<WorkflowVersion | null>;
+    /**
+     * Activate a version (make it accept new triggers).
+     */
+    activateVersion(workflowId: string, version: string): Promise<void>;
+    /**
+     * Deactivate a version (stop accepting new triggers).
+     */
+    deactivateVersion(workflowId: string, version: string): Promise<void>;
+    /**
+     * Deprecate a version with a message.
+     */
+    deprecateVersion(workflowId: string, version: string, message: string): Promise<void>;
+    /**
+     * Get running instances count for a version.
+     */
+    getRunningInstanceCount(workflowId: string, version: string): Promise<number>;
+}
+/**
+ * State migration result.
+ */
+export interface StateMigrationResult {
+    /** Whether migration succeeded */
+    success: boolean;
+    /** New state after migration */
+    newState?: WorkflowState;
+    /** Error if migration failed */
+    error?: string;
+    /** Warnings during migration */
+    warnings?: string[];
+    /** Fields that were added */
+    addedFields?: string[];
+    /** Fields that were removed */
+    removedFields?: string[];
+    /** Fields that were transformed */
+    transformedFields?: string[];
+}
+/**
+ * State migration context provided to migration functions.
+ */
+export interface MigrationContext {
+    /** Source version */
+    fromVersion: string;
+    /** Target version */
+    toVersion: string;
+    /** Old state (read-only) */
+    oldState: Readonly<WorkflowState>;
+    /** Instance ID */
+    instanceId: string;
+    /** Current step at time of migration */
+    currentStep: string;
+    /** Helper: Deep clone a value */
+    clone<T>(value: T): T;
+    /** Helper: Log a warning */
+    warn(message: string): void;
+    /** Helper: Get current time */
+    now(): Date;
+}
+//# sourceMappingURL=versioning.d.ts.map

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

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