Workflow Reference

import { defineCollection, publishingWorkflow } from '@dyrected/core'

export const Articles = defineCollection({
  slug: 'articles',
  workflow: publishingWorkflow(),
  fields: [
    { name: 'title', type: 'text', label: 'Title', required: true },
    { name: 'body', type: 'richText', label: 'Body', required: true },
  ],
})

export function availableWorkflowTransitions(
  workflow: WorkflowConfig,
  state: string,
  user?: AuthenticatedUser,
): WorkflowTransition[]

export function canViewWorkflowDraft(workflow: WorkflowConfig, user?: AuthenticatedUser): boolean

export function createLifecycleEvent(args: {
  name: LifecycleEventName;
  collection: string;
  documentId: string;
  actorId?: string;
  payload: Record<string, unknown>;
}): LifecycleEvent

export async function createWorkflowDocument(args: {
  config: DyrectedConfig;
  collection: CollectionConfig;
  data: Record<string, unknown>;
  user?: AuthenticatedUser;
}): Promise<{ doc: BaseDocument; event: LifecycleEvent }>

export async function dispatchLifecycleEvent(config: DyrectedConfig, event: LifecycleEvent): Promise<void>

export async function dispatchPendingLifecycleEvents(config: DyrectedConfig, limit = 50): Promise<number>

export function initializeWorkflowDocument(data: Record<string, unknown>, workflow: WorkflowConfig)

export const LIFECYCLE_EVENTS_COLLECTION = "__lifecycle_events";

export interface LifecycleEvent<TPayload = Record<string, unknown>> {
  id: string;
  name: LifecycleEventName;
  collection: string;
  documentId: string;
  occurredAt: string;
  actorId?: string;
  payload: TPayload;
  attempts: number;
  status: "pending" | "processing" | "delivered" | "failed";
  nextAttemptAt?: string;
  deliveredAt?: string;
  lastError?: string;
}

export type LifecycleEventHandler = (
  event: LifecycleEvent,
) => void | Promise<void>;

export type LifecycleEventName = (typeof LIFECYCLE_EVENT_NAMES)[number];

export function materializeWorkflowDocument(
  doc: BaseDocument,
  workflow: WorkflowConfig,
  user?: AuthenticatedUser,
): BaseDocument | null

export function publishingWorkflow(): WorkflowConfig

export async function saveWorkflowDraft(args: {
  config: DyrectedConfig;
  collection: CollectionConfig;
  id: string;
  originalDoc: BaseDocument;
  data: Record<string, unknown>;
  user?: AuthenticatedUser;
}): Promise<{ doc: BaseDocument; event: LifecycleEvent }>

export async function transitionWorkflow(args: {
  config: DyrectedConfig;
  collection: CollectionConfig;
  id: string;
  transitionName: string;
  expectedRevision?: number;
  comment?: string;
  user?: AuthenticatedUser;
  req: HookRequestContext;
}): Promise<BaseDocument>

export const WORKFLOW_HISTORY_COLLECTION = "__workflow_history";

export function workflowCapabilities(workflow: WorkflowConfig, user?: AuthenticatedUser): Set<string>

export interface WorkflowConfig<TDoc extends object = Record<string, unknown>> {
  initialState: string;
  /** State used for a new working revision created from published content. */
  draftState?: string;
  states: WorkflowState[];
  transitions: WorkflowTransition[];
  /** Maps values in `user.roles` to workflow capabilities. */
  roles?: WorkflowRole[];
  hooks?: {
    beforeTransition?: CollectionBeforeTransitionHook<TDoc>[];
    afterTransition?: CollectionAfterTransitionHook<TDoc>[];
  };
}

export interface WorkflowMetadata {
  state: string;
  revision: number;
  publishedRevision?: number;
  publishedAt?: string;
  publishedBy?: string;
  /** Transitions currently allowed for the requesting user. Response-only. */
  availableTransitions?: string[];
}

export interface WorkflowRole {
  /** Existing user role value, for example `editor` or `publisher`. */
  role: string;
  capabilities: string[];
}

export interface WorkflowState {
  /** Stable machine-readable state key. */
  name: string;
  /** Label rendered in the Admin UI. */
  label: string;
  /** Marks the state whose revision is visible to public readers. */
  published?: boolean;
  /** Optional visual tone used by the Admin UI. */
  color?: "neutral" | "warning" | "success" | "danger" | "info";
}

export interface WorkflowTransition {
  /** Stable transition key used by the REST and SDK APIs. */
  name: string;
  label: string;
  from: string | string[];
  to: string;
  /** Every listed capability is required. */
  requiredCapabilities?: string[];
  /** Require a non-empty comment when performing the transition. */
  requireComment?: boolean;
  /** Remove the public snapshot after this transition commits. */
  unpublish?: boolean;
}

export interface WorkflowTransitionContext<
  TDoc extends object = Record<string, unknown>,
> {
  transition: WorkflowTransition;
  from: string;
  to: string;
  doc: TDoc;
  user?: AuthenticatedUser;
  comment?: string;
  req: HookRequestContext;
  db: DatabaseAdapter;
}