@dyrected/core 2.5.29 → 2.5.30

package/dist/index.cjs

@@ -20,21 +20,43 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  LIFECYCLE_EVENTS_COLLECTION: () => LIFECYCLE_EVENTS_COLLECTION,
+  LIFECYCLE_EVENT_NAMES: () => LIFECYCLE_EVENT_NAMES,
+  WORKFLOW_HISTORY_COLLECTION: () => WORKFLOW_HISTORY_COLLECTION,
+  availableWorkflowTransitions: () => availableWorkflowTransitions,
+  createLifecycleEvent: () => createLifecycleEvent,
+  createWorkflowDocument: () => createWorkflowDocument,
   defineCollection: () => defineCollection,
   defineConfig: () => defineConfig,
   defineGlobal: () => defineGlobal,
+  dispatchLifecycleEvent: () => dispatchLifecycleEvent,
+  dispatchPendingLifecycleEvents: () => dispatchPendingLifecycleEvents,
   executeFieldAfterRead: () => executeFieldAfterRead,
   executeFieldBeforeChange: () => executeFieldBeforeChange,
   generateAIPrompt: () => generateAIPrompt,
   generateFreshSetupPrompt: () => generateFreshSetupPrompt,
+  initializeWorkflowDocument: () => initializeWorkflowDocument,
+  materializeWorkflowDocument: () => materializeWorkflowDocument,
   normalizeConfig: () => normalizeConfig,
   parseMongoWhere: () => parseMongoWhere,
   parseSort: () => parseSort,
   parseSqlWhere: () => parseSqlWhere,
-  runCollectionHooks: () => runCollectionHooks
+  publishingWorkflow: () => publishingWorkflow,
+  runCollectionHooks: () => runCollectionHooks,
+  saveWorkflowDraft: () => saveWorkflowDraft,
+  transitionWorkflow: () => transitionWorkflow,
+  workflowCapabilities: () => workflowCapabilities
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types/index.ts
+var LIFECYCLE_EVENT_NAMES = [
+  "revision.created",
+  "workflow.transitioned",
+  "entry.published",
+  "entry.unpublished"
+];
+
 // src/utils/setup-prompt.ts
 function buildEnvironmentSection(frameworkLabel, isSelfHosted, config) {
   const credentialLines = isSelfHosted ? "" : `- Site ID  : ${config.siteId}
@@ -183,6 +205,7 @@ COLLECTION OPTIONS:
 - upload: true       \u2014 media library with file upload support
 - auth: true         \u2014 adds login/me endpoints; password field is auto-managed
 - audit: true        \u2014 enables activity logging
+- admin.icon         \u2014 valid Lucide component name for sidebar navigation (e.g. 'Newspaper')
 - admin.useAsTitle   \u2014 field used as display title in admin list view
 - admin.group        \u2014 groups collection under a sidebar heading
 - admin.hidden       \u2014 hides collection from the sidebar (internal/system use)
@@ -227,7 +250,7 @@ const media = defineCollection({
 
 const pages = defineCollection({
   slug: 'pages',
-  admin: { useAsTitle: 'title', group: 'Content' },
+  admin: { icon: 'FileText', useAsTitle: 'title', group: 'Content' },
   fields: [
     { name: 'title', label: 'Title', type: 'text', required: true },
     { name: 'slug',  label: 'URL Slug', type: 'text', required: true, unique: true },
@@ -855,6 +878,250 @@ function generateAIPrompt(activeTab, config) {
   return sections.join("\n");
 }
 
+// src/workflows.ts
+var WORKFLOW_HISTORY_COLLECTION = "__workflow_history";
+var LIFECYCLE_EVENTS_COLLECTION = "__lifecycle_events";
+function publishingWorkflow() {
+  return {
+    initialState: "draft",
+    draftState: "draft",
+    states: [
+      { name: "draft", label: "Draft", color: "neutral" },
+      { name: "in_review", label: "In review", color: "warning" },
+      { name: "published", label: "Published", color: "success", published: true }
+    ],
+    transitions: [
+      { name: "submit", label: "Submit for review", from: "draft", to: "in_review", requiredCapabilities: ["entry.submit"] },
+      { name: "publish", label: "Publish", from: "in_review", to: "published", requiredCapabilities: ["entry.publish"] },
+      { name: "reject", label: "Request changes", from: "in_review", to: "draft", requiredCapabilities: ["entry.publish"], requireComment: true },
+      { name: "unpublish", label: "Unpublish", from: "published", to: "draft", requiredCapabilities: ["entry.unpublish"], unpublish: true }
+    ],
+    roles: [
+      { role: "editor", capabilities: ["entry.edit", "entry.submit"] },
+      { role: "publisher", capabilities: ["entry.edit", "entry.submit", "entry.publish", "entry.unpublish"] },
+      { role: "admin", capabilities: ["entry.edit", "entry.submit", "entry.publish", "entry.unpublish"] }
+    ]
+  };
+}
+function publicMetadata(meta) {
+  const { availableTransitions: _availableTransitions, ...safe } = meta;
+  return safe;
+}
+function workflowCapabilities(workflow, user) {
+  const capabilities = new Set(Array.isArray(user?.capabilities) ? user.capabilities : []);
+  const roles = Array.isArray(user?.roles) ? user.roles : [];
+  for (const mapping of workflow.roles ?? []) {
+    if (roles.includes(mapping.role)) mapping.capabilities.forEach((capability) => capabilities.add(capability));
+  }
+  return capabilities;
+}
+function availableWorkflowTransitions(workflow, state, user) {
+  const capabilities = workflowCapabilities(workflow, user);
+  return workflow.transitions.filter((transition) => {
+    const from = Array.isArray(transition.from) ? transition.from : [transition.from];
+    return from.includes(state) && (transition.requiredCapabilities ?? []).every((item) => capabilities.has(item));
+  });
+}
+function initializeWorkflowDocument(data, workflow) {
+  return {
+    ...data,
+    __workflow: { state: workflow.initialState, revision: 1 }
+  };
+}
+function materializeWorkflowDocument(doc, workflow, user) {
+  const meta = doc.__workflow;
+  if (!meta) return doc;
+  const { __published, __workflow, ...working } = doc;
+  if (!user) {
+    if (!__published || typeof __published !== "object") return null;
+    return { id: doc.id, ...__published, _workflow: publicMetadata(meta) };
+  }
+  return {
+    ...working,
+    _workflow: {
+      ...meta,
+      availableTransitions: availableWorkflowTransitions(workflow, meta.state, user).map((item) => item.name)
+    }
+  };
+}
+function eventId() {
+  return globalThis.crypto?.randomUUID?.() ?? `evt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function createLifecycleEvent(args) {
+  return {
+    id: eventId(),
+    name: args.name,
+    collection: args.collection,
+    documentId: args.documentId,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    actorId: args.actorId,
+    payload: args.payload,
+    attempts: 0,
+    status: "pending"
+  };
+}
+async function persistEvent(db, event) {
+  await db.create({ collection: LIFECYCLE_EVENTS_COLLECTION, data: event });
+}
+async function dispatchLifecycleEvent(config, event) {
+  const db = config.db;
+  if (!db || !config.events?.handlers.length) return;
+  const maxAttempts = config.events.maxAttempts ?? 8;
+  const retryDelayMs = config.events.retryDelayMs ?? 1e3;
+  const attempts = event.attempts + 1;
+  try {
+    await db.update({ collection: LIFECYCLE_EVENTS_COLLECTION, id: event.id, data: { status: "processing", attempts } });
+    for (const handler of config.events.handlers) await handler({ ...event, status: "processing", attempts });
+    await db.update({
+      collection: LIFECYCLE_EVENTS_COLLECTION,
+      id: event.id,
+      data: { status: "delivered", attempts, deliveredAt: (/* @__PURE__ */ new Date()).toISOString(), lastError: null }
+    });
+  } catch (error) {
+    const exhausted = attempts >= maxAttempts;
+    await db.update({
+      collection: LIFECYCLE_EVENTS_COLLECTION,
+      id: event.id,
+      data: {
+        status: "failed",
+        attempts,
+        lastError: error instanceof Error ? error.message : String(error),
+        nextAttemptAt: exhausted ? null : new Date(Date.now() + retryDelayMs * 2 ** (attempts - 1)).toISOString()
+      }
+    });
+  }
+}
+async function dispatchPendingLifecycleEvents(config, limit = 50) {
+  if (!config.db || !config.events?.handlers.length) return 0;
+  const result = await config.db.find({
+    collection: LIFECYCLE_EVENTS_COLLECTION,
+    where: { status: { in: ["pending", "failed"] } },
+    sort: "occurredAt",
+    limit
+  });
+  const now = Date.now();
+  const due = result.docs.filter((doc) => !doc.nextAttemptAt || new Date(doc.nextAttemptAt).getTime() <= now);
+  for (const event of due) await dispatchLifecycleEvent(config, event);
+  return due.length;
+}
+async function saveWorkflowDraft(args) {
+  const { config, collection, id, originalDoc, data, user } = args;
+  const db = config.db;
+  const workflow = collection.workflow;
+  if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
+  const previous = originalDoc.__workflow;
+  const event = createLifecycleEvent({
+    name: "revision.created",
+    collection: collection.slug,
+    documentId: id,
+    actorId: user?.sub,
+    payload: { revision: previous.revision + 1, previousRevision: previous.revision }
+  });
+  const doc = await db.transaction(async (tx) => {
+    const nextMeta = {
+      ...previous,
+      state: originalDoc.__published ? workflow.draftState ?? workflow.initialState : previous.state,
+      revision: previous.revision + 1
+    };
+    const updated = await tx.update({ collection: collection.slug, id, data: { ...data, __workflow: nextMeta } });
+    await persistEvent(tx, event);
+    return updated;
+  });
+  void dispatchLifecycleEvent(config, event);
+  return { doc, event };
+}
+async function createWorkflowDocument(args) {
+  const { config, collection, data, user } = args;
+  const db = config.db;
+  if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
+  let event;
+  const doc = await db.transaction(async (tx) => {
+    const created = await tx.create({ collection: collection.slug, data });
+    event = createLifecycleEvent({
+      name: "revision.created",
+      collection: collection.slug,
+      documentId: created.id,
+      actorId: user?.sub,
+      payload: { revision: 1, previousRevision: null }
+    });
+    await persistEvent(tx, event);
+    return created;
+  });
+  void dispatchLifecycleEvent(config, event);
+  return { doc, event };
+}
+async function transitionWorkflow(args) {
+  const { config, collection, id, transitionName, expectedRevision, comment, user, req } = args;
+  const db = config.db;
+  const workflow = collection.workflow;
+  if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
+  const original = await db.findOne({ collection: collection.slug, id });
+  if (!original) throw Object.assign(new Error("Not Found"), { statusCode: 404 });
+  const meta = original.__workflow;
+  if (!meta) throw Object.assign(new Error("Entry has no workflow metadata"), { statusCode: 409 });
+  if (expectedRevision !== void 0 && expectedRevision !== meta.revision) {
+    throw Object.assign(new Error("This entry changed since it was loaded. Refresh before transitioning it."), { statusCode: 409 });
+  }
+  const transition = workflow.transitions.find((item) => item.name === transitionName);
+  const fromStates = transition ? Array.isArray(transition.from) ? transition.from : [transition.from] : [];
+  if (!transition || !fromStates.includes(meta.state)) {
+    throw Object.assign(new Error(`Transition "${transitionName}" is not valid from "${meta.state}".`), { statusCode: 409 });
+  }
+  if (!availableWorkflowTransitions(workflow, meta.state, user).some((item) => item.name === transition.name)) {
+    throw Object.assign(new Error(`You do not have permission to perform "${transition.label}".`), { statusCode: 403 });
+  }
+  if (transition.requireComment && !comment?.trim()) {
+    throw Object.assign(new Error(`A comment is required for "${transition.label}".`), { statusCode: 400 });
+  }
+  const hookContext = { transition, from: meta.state, to: transition.to, doc: original, user, comment, req, db };
+  for (const hook of workflow.hooks?.beforeTransition ?? []) await hook(hookContext);
+  const events = [createLifecycleEvent({
+    name: "workflow.transitioned",
+    collection: collection.slug,
+    documentId: id,
+    actorId: user?.sub,
+    payload: { transition: transition.name, from: meta.state, to: transition.to, revision: meta.revision, comment }
+  })];
+  const targetState = workflow.states.find((state) => state.name === transition.to);
+  if (targetState.published) {
+    events.push(createLifecycleEvent({ name: "entry.published", collection: collection.slug, documentId: id, actorId: user?.sub, payload: { revision: meta.revision } }));
+  } else if (transition.unpublish) {
+    events.push(createLifecycleEvent({ name: "entry.unpublished", collection: collection.slug, documentId: id, actorId: user?.sub, payload: { revision: meta.publishedRevision } }));
+  }
+  const updated = await db.transaction(async (tx) => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const { __published: _published, __workflow: _workflow, id: _id, ...working } = original;
+    const nextMeta = {
+      ...meta,
+      state: transition.to,
+      ...targetState.published ? { publishedRevision: meta.revision, publishedAt: now, publishedBy: user?.sub } : {},
+      ...transition.unpublish ? { publishedRevision: void 0, publishedAt: void 0, publishedBy: void 0 } : {}
+    };
+    const data = { __workflow: nextMeta };
+    if (targetState.published) data.__published = working;
+    if (transition.unpublish) data.__published = null;
+    const next = await tx.update({ collection: collection.slug, id, data });
+    await tx.create({
+      collection: WORKFLOW_HISTORY_COLLECTION,
+      data: { collection: collection.slug, documentId: id, transition: transition.name, from: meta.state, to: transition.to, revision: meta.revision, comment: comment ?? null, actorId: user?.sub ?? null, createdAt: now }
+    });
+    for (const event of events) await persistEvent(tx, event);
+    if (collection.audit) {
+      await tx.create({ collection: "__audit", data: { collection: collection.slug, documentId: id, operation: "workflow.transition", user: user?.sub ?? null, timestamp: now, changes: JSON.stringify({ transition: transition.name, from: meta.state, to: transition.to, revision: meta.revision }) } });
+    }
+    return next;
+  });
+  for (const event of events) void dispatchLifecycleEvent(config, event);
+  for (const hook of workflow.hooks?.afterTransition ?? []) {
+    try {
+      await hook({ ...hookContext, doc: updated, event: events[0] });
+    } catch (error) {
+      console.error("[dyrected/workflow] afterTransition hook failed:", error);
+    }
+  }
+  return updated;
+}
+
 // src/utils/config.ts
 var AUDIT_COLLECTION_SLUG = "__audit";
 var SYSTEM_FIELDS = [
@@ -896,10 +1163,47 @@ var AUDIT_COLLECTION = {
   ],
   admin: { hidden: true }
 };
+var WORKFLOW_HISTORY_COLLECTION_CONFIG = {
+  slug: WORKFLOW_HISTORY_COLLECTION,
+  labels: { singular: "Workflow transition", plural: "Workflow transitions" },
+  fields: [
+    { name: "collection", type: "text", required: true },
+    { name: "documentId", type: "text", required: true },
+    { name: "transition", type: "text", required: true },
+    { name: "from", type: "text", required: true },
+    { name: "to", type: "text", required: true },
+    { name: "revision", type: "number", required: true },
+    { name: "comment", type: "textarea" },
+    { name: "actorId", type: "text" },
+    { name: "createdAt", type: "date", required: true }
+  ],
+  access: { read: ({ user }) => !!user, create: () => false, update: () => false, delete: () => false },
+  admin: { hidden: true }
+};
+var LIFECYCLE_EVENTS_COLLECTION_CONFIG = {
+  slug: LIFECYCLE_EVENTS_COLLECTION,
+  labels: { singular: "Lifecycle event", plural: "Lifecycle events" },
+  fields: [
+    { name: "name", type: "text", required: true },
+    { name: "collection", type: "text", required: true },
+    { name: "documentId", type: "text", required: true },
+    { name: "occurredAt", type: "date", required: true },
+    { name: "actorId", type: "text" },
+    { name: "payload", type: "json", required: true },
+    { name: "attempts", type: "number", required: true },
+    { name: "status", type: "select", options: ["pending", "processing", "delivered", "failed"], required: true },
+    { name: "nextAttemptAt", type: "date" },
+    { name: "deliveredAt", type: "date" },
+    { name: "lastError", type: "textarea" }
+  ],
+  access: { read: ({ user }) => !!user?.roles?.includes("admin"), create: () => false, update: () => false, delete: () => false },
+  admin: { hidden: true }
+};
 function normalizeConfig(config) {
   const collections = config?.collections || [];
   const globals = config?.globals || [];
   const needsAudit = collections.some((col) => col.audit);
+  const needsWorkflow = collections.some((col) => col.workflow);
   const normalizedCollections = collections.map((col) => {
     let fields = col.fields || [];
     const existingFieldNames = new Set(fields.map((f) => f.name));
@@ -994,9 +1298,17 @@ function normalizeConfig(config) {
     };
   });
   const hasAuditCollection = normalizedCollections.some((col) => col.slug === AUDIT_COLLECTION_SLUG);
+  const systemCollections = [];
+  if (needsAudit && !hasAuditCollection) systemCollections.push(AUDIT_COLLECTION);
+  if (needsWorkflow && !normalizedCollections.some((col) => col.slug === WORKFLOW_HISTORY_COLLECTION)) {
+    systemCollections.push(WORKFLOW_HISTORY_COLLECTION_CONFIG);
+  }
+  if (needsWorkflow && !normalizedCollections.some((col) => col.slug === LIFECYCLE_EVENTS_COLLECTION)) {
+    systemCollections.push(LIFECYCLE_EVENTS_COLLECTION_CONFIG);
+  }
   return {
     ...config,
-    collections: [...normalizedCollections, ...needsAudit && !hasAuditCollection ? [AUDIT_COLLECTION] : []],
+    collections: [...normalizedCollections, ...systemCollections],
     globals
   };
 }
@@ -1347,16 +1659,30 @@ function defineConfig(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  LIFECYCLE_EVENTS_COLLECTION,
+  LIFECYCLE_EVENT_NAMES,
+  WORKFLOW_HISTORY_COLLECTION,
+  availableWorkflowTransitions,
+  createLifecycleEvent,
+  createWorkflowDocument,
   defineCollection,
   defineConfig,
   defineGlobal,
+  dispatchLifecycleEvent,
+  dispatchPendingLifecycleEvents,
   executeFieldAfterRead,
   executeFieldBeforeChange,
   generateAIPrompt,
   generateFreshSetupPrompt,
+  initializeWorkflowDocument,
+  materializeWorkflowDocument,
   normalizeConfig,
   parseMongoWhere,
   parseSort,
   parseSqlWhere,
-  runCollectionHooks
+  publishingWorkflow,
+  runCollectionHooks,
+  saveWorkflowDraft,
+  transitionWorkflow,
+  workflowCapabilities
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { D as DyrectedConfig, F as Field, C as CollectionConfig, P as Prettify, I as InferDocShape, S as SystemDocFields, A as AuthDocFields, U as UploadDocFields, G as GlobalConfig } from './index-Bp7PDOYG.cjs';
-export { a as AccessFunction, b as AdminConfig, c as AuthenticatedUser, B as BaseDocument, d as Block, e as CollectionAfterChangeHook, f as CollectionAfterDeleteHook, g as CollectionAfterReadHook, h as CollectionBeforeChangeHook, i as CollectionBeforeDeleteHook, j as CollectionBeforeReadHook, k as DatabaseAdapter, l as DynamicOptionItem, m as DynamicOptionsConfig, n as DynamicOptionsResolver, o as DynamicOptionsResolverArgs, p as FieldAfterReadHook, q as FieldBeforeChangeHook, r as FieldHook, s as FieldType, t as FileData, u as GlobalAfterChangeHook, v as GlobalAfterReadHook, w as GlobalBeforeChangeHook, x as GlobalBeforeReadHook, H as HookFunction, y as HookRequestContext, z as ImageService, E as PaginatedResult, R as ReadonlyDatabaseAdapter, J as StorageAdapter, K as UploadConfig } from './index-Bp7PDOYG.cjs';
+import { D as DyrectedConfig, F as Field, W as WorkflowConfig, A as AuthenticatedUser, a as WorkflowTransition, L as LifecycleEventName, b as LifecycleEvent, C as CollectionConfig, B as BaseDocument, H as HookRequestContext, P as Prettify, I as InferDocShape, S as SystemDocFields, c as AuthDocFields, U as UploadDocFields, G as GlobalConfig } from './index-DTrpTru7.cjs';
+export { d as AccessFunction, e as AdminConfig, f as AdminDashboardComponentSlots, g as AdminIconName, h as Block, i as CollectionAfterChangeHook, j as CollectionAfterDeleteHook, k as CollectionAfterReadHook, l as CollectionAfterTransitionHook, m as CollectionBeforeChangeHook, n as CollectionBeforeDeleteHook, o as CollectionBeforeReadHook, p as CollectionBeforeTransitionHook, q as CollectionListComponentSlots, r as DatabaseAdapter, s as DynamicOptionItem, t as DynamicOptionsConfig, u as DynamicOptionsResolver, v as DynamicOptionsResolverArgs, w as FieldAfterReadHook, x as FieldBeforeChangeHook, y as FieldHook, z as FieldType, E as FileData, J as GlobalAfterChangeHook, K as GlobalAfterReadHook, M as GlobalBeforeChangeHook, N as GlobalBeforeReadHook, O as HookFunction, Q as ImageService, R as LIFECYCLE_EVENT_NAMES, T as LifecycleEventHandler, V as PaginatedResult, X as ReadonlyDatabaseAdapter, Y as StorageAdapter, Z as UploadConfig, _ as WorkflowMetadata, $ as WorkflowRole, a0 as WorkflowState, a1 as WorkflowTransitionContext } from './index-DTrpTru7.cjs';
+import 'lucide-react';
 
 interface SetupPromptConfig {
     siteName?: string;
@@ -128,6 +129,58 @@ declare function executeFieldBeforeChange(fields: Field[], data: Record<string,
  */
 declare function executeFieldAfterRead(fields: Field[], doc: Record<string, unknown>, user: unknown, db?: unknown): Promise<Record<string, unknown>>;
 
+declare const WORKFLOW_HISTORY_COLLECTION = "__workflow_history";
+declare const LIFECYCLE_EVENTS_COLLECTION = "__lifecycle_events";
+declare function publishingWorkflow(): WorkflowConfig;
+declare function workflowCapabilities(workflow: WorkflowConfig, user?: AuthenticatedUser): Set<string>;
+declare function availableWorkflowTransitions(workflow: WorkflowConfig, state: string, user?: AuthenticatedUser): WorkflowTransition[];
+declare function initializeWorkflowDocument(data: Record<string, unknown>, workflow: WorkflowConfig): {
+    __workflow: {
+        state: string;
+        revision: number;
+    };
+};
+declare function materializeWorkflowDocument(doc: BaseDocument, workflow: WorkflowConfig, user?: AuthenticatedUser): BaseDocument | null;
+declare function createLifecycleEvent(args: {
+    name: LifecycleEventName;
+    collection: string;
+    documentId: string;
+    actorId?: string;
+    payload: Record<string, unknown>;
+}): LifecycleEvent;
+declare function dispatchLifecycleEvent(config: DyrectedConfig, event: LifecycleEvent): Promise<void>;
+declare function dispatchPendingLifecycleEvents(config: DyrectedConfig, limit?: number): Promise<number>;
+declare function saveWorkflowDraft(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    id: string;
+    originalDoc: BaseDocument;
+    data: Record<string, unknown>;
+    user?: AuthenticatedUser;
+}): Promise<{
+    doc: BaseDocument;
+    event: LifecycleEvent;
+}>;
+declare function createWorkflowDocument(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    data: Record<string, unknown>;
+    user?: AuthenticatedUser;
+}): Promise<{
+    doc: BaseDocument;
+    event: LifecycleEvent;
+}>;
+declare function transitionWorkflow(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    id: string;
+    transitionName: string;
+    expectedRevision?: number;
+    comment?: string;
+    user?: AuthenticatedUser;
+    req: HookRequestContext;
+}): Promise<BaseDocument>;
+
 /**
  * Define a collection. When called without an explicit type argument, TypeScript
  * automatically infers the document shape from the `fields` array you provide —
@@ -219,4 +272,4 @@ declare function defineGlobal<TDoc extends object>(config: GlobalConfig<TDoc>):
  */
 declare function defineConfig(config: DyrectedConfig): DyrectedConfig;
 
-export { AuthDocFields, CollectionConfig, DyrectedConfig, Field, GlobalConfig, InferDocShape, Prettify, type SetupPromptConfig, type SortClause, type SortDirection, type SqlWhereResult, SystemDocFields, UploadDocFields, type WhereClause, type WhereOperator, type WhereOperatorName, defineCollection, defineConfig, defineGlobal, executeFieldAfterRead, executeFieldBeforeChange, generateAIPrompt, generateFreshSetupPrompt, normalizeConfig, parseMongoWhere, parseSort, parseSqlWhere, runCollectionHooks };
+export { AuthDocFields, AuthenticatedUser, BaseDocument, CollectionConfig, DyrectedConfig, Field, GlobalConfig, HookRequestContext, InferDocShape, LIFECYCLE_EVENTS_COLLECTION, LifecycleEvent, LifecycleEventName, Prettify, type SetupPromptConfig, type SortClause, type SortDirection, type SqlWhereResult, SystemDocFields, UploadDocFields, WORKFLOW_HISTORY_COLLECTION, type WhereClause, type WhereOperator, type WhereOperatorName, WorkflowConfig, WorkflowTransition, availableWorkflowTransitions, createLifecycleEvent, createWorkflowDocument, defineCollection, defineConfig, defineGlobal, dispatchLifecycleEvent, dispatchPendingLifecycleEvents, executeFieldAfterRead, executeFieldBeforeChange, generateAIPrompt, generateFreshSetupPrompt, initializeWorkflowDocument, materializeWorkflowDocument, normalizeConfig, parseMongoWhere, parseSort, parseSqlWhere, publishingWorkflow, runCollectionHooks, saveWorkflowDraft, transitionWorkflow, workflowCapabilities };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { D as DyrectedConfig, F as Field, C as CollectionConfig, P as Prettify, I as InferDocShape, S as SystemDocFields, A as AuthDocFields, U as UploadDocFields, G as GlobalConfig } from './index-Bp7PDOYG.js';
-export { a as AccessFunction, b as AdminConfig, c as AuthenticatedUser, B as BaseDocument, d as Block, e as CollectionAfterChangeHook, f as CollectionAfterDeleteHook, g as CollectionAfterReadHook, h as CollectionBeforeChangeHook, i as CollectionBeforeDeleteHook, j as CollectionBeforeReadHook, k as DatabaseAdapter, l as DynamicOptionItem, m as DynamicOptionsConfig, n as DynamicOptionsResolver, o as DynamicOptionsResolverArgs, p as FieldAfterReadHook, q as FieldBeforeChangeHook, r as FieldHook, s as FieldType, t as FileData, u as GlobalAfterChangeHook, v as GlobalAfterReadHook, w as GlobalBeforeChangeHook, x as GlobalBeforeReadHook, H as HookFunction, y as HookRequestContext, z as ImageService, E as PaginatedResult, R as ReadonlyDatabaseAdapter, J as StorageAdapter, K as UploadConfig } from './index-Bp7PDOYG.js';
+import { D as DyrectedConfig, F as Field, W as WorkflowConfig, A as AuthenticatedUser, a as WorkflowTransition, L as LifecycleEventName, b as LifecycleEvent, C as CollectionConfig, B as BaseDocument, H as HookRequestContext, P as Prettify, I as InferDocShape, S as SystemDocFields, c as AuthDocFields, U as UploadDocFields, G as GlobalConfig } from './index-DTrpTru7.js';
+export { d as AccessFunction, e as AdminConfig, f as AdminDashboardComponentSlots, g as AdminIconName, h as Block, i as CollectionAfterChangeHook, j as CollectionAfterDeleteHook, k as CollectionAfterReadHook, l as CollectionAfterTransitionHook, m as CollectionBeforeChangeHook, n as CollectionBeforeDeleteHook, o as CollectionBeforeReadHook, p as CollectionBeforeTransitionHook, q as CollectionListComponentSlots, r as DatabaseAdapter, s as DynamicOptionItem, t as DynamicOptionsConfig, u as DynamicOptionsResolver, v as DynamicOptionsResolverArgs, w as FieldAfterReadHook, x as FieldBeforeChangeHook, y as FieldHook, z as FieldType, E as FileData, J as GlobalAfterChangeHook, K as GlobalAfterReadHook, M as GlobalBeforeChangeHook, N as GlobalBeforeReadHook, O as HookFunction, Q as ImageService, R as LIFECYCLE_EVENT_NAMES, T as LifecycleEventHandler, V as PaginatedResult, X as ReadonlyDatabaseAdapter, Y as StorageAdapter, Z as UploadConfig, _ as WorkflowMetadata, $ as WorkflowRole, a0 as WorkflowState, a1 as WorkflowTransitionContext } from './index-DTrpTru7.js';
+import 'lucide-react';
 
 interface SetupPromptConfig {
     siteName?: string;
@@ -128,6 +129,58 @@ declare function executeFieldBeforeChange(fields: Field[], data: Record<string,
  */
 declare function executeFieldAfterRead(fields: Field[], doc: Record<string, unknown>, user: unknown, db?: unknown): Promise<Record<string, unknown>>;
 
+declare const WORKFLOW_HISTORY_COLLECTION = "__workflow_history";
+declare const LIFECYCLE_EVENTS_COLLECTION = "__lifecycle_events";
+declare function publishingWorkflow(): WorkflowConfig;
+declare function workflowCapabilities(workflow: WorkflowConfig, user?: AuthenticatedUser): Set<string>;
+declare function availableWorkflowTransitions(workflow: WorkflowConfig, state: string, user?: AuthenticatedUser): WorkflowTransition[];
+declare function initializeWorkflowDocument(data: Record<string, unknown>, workflow: WorkflowConfig): {
+    __workflow: {
+        state: string;
+        revision: number;
+    };
+};
+declare function materializeWorkflowDocument(doc: BaseDocument, workflow: WorkflowConfig, user?: AuthenticatedUser): BaseDocument | null;
+declare function createLifecycleEvent(args: {
+    name: LifecycleEventName;
+    collection: string;
+    documentId: string;
+    actorId?: string;
+    payload: Record<string, unknown>;
+}): LifecycleEvent;
+declare function dispatchLifecycleEvent(config: DyrectedConfig, event: LifecycleEvent): Promise<void>;
+declare function dispatchPendingLifecycleEvents(config: DyrectedConfig, limit?: number): Promise<number>;
+declare function saveWorkflowDraft(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    id: string;
+    originalDoc: BaseDocument;
+    data: Record<string, unknown>;
+    user?: AuthenticatedUser;
+}): Promise<{
+    doc: BaseDocument;
+    event: LifecycleEvent;
+}>;
+declare function createWorkflowDocument(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    data: Record<string, unknown>;
+    user?: AuthenticatedUser;
+}): Promise<{
+    doc: BaseDocument;
+    event: LifecycleEvent;
+}>;
+declare function transitionWorkflow(args: {
+    config: DyrectedConfig;
+    collection: CollectionConfig;
+    id: string;
+    transitionName: string;
+    expectedRevision?: number;
+    comment?: string;
+    user?: AuthenticatedUser;
+    req: HookRequestContext;
+}): Promise<BaseDocument>;
+
 /**
  * Define a collection. When called without an explicit type argument, TypeScript
  * automatically infers the document shape from the `fields` array you provide —
@@ -219,4 +272,4 @@ declare function defineGlobal<TDoc extends object>(config: GlobalConfig<TDoc>):
  */
 declare function defineConfig(config: DyrectedConfig): DyrectedConfig;
 
-export { AuthDocFields, CollectionConfig, DyrectedConfig, Field, GlobalConfig, InferDocShape, Prettify, type SetupPromptConfig, type SortClause, type SortDirection, type SqlWhereResult, SystemDocFields, UploadDocFields, type WhereClause, type WhereOperator, type WhereOperatorName, defineCollection, defineConfig, defineGlobal, executeFieldAfterRead, executeFieldBeforeChange, generateAIPrompt, generateFreshSetupPrompt, normalizeConfig, parseMongoWhere, parseSort, parseSqlWhere, runCollectionHooks };
+export { AuthDocFields, AuthenticatedUser, BaseDocument, CollectionConfig, DyrectedConfig, Field, GlobalConfig, HookRequestContext, InferDocShape, LIFECYCLE_EVENTS_COLLECTION, LifecycleEvent, LifecycleEventName, Prettify, type SetupPromptConfig, type SortClause, type SortDirection, type SqlWhereResult, SystemDocFields, UploadDocFields, WORKFLOW_HISTORY_COLLECTION, type WhereClause, type WhereOperator, type WhereOperatorName, WorkflowConfig, WorkflowTransition, availableWorkflowTransitions, createLifecycleEvent, createWorkflowDocument, defineCollection, defineConfig, defineGlobal, dispatchLifecycleEvent, dispatchPendingLifecycleEvents, executeFieldAfterRead, executeFieldBeforeChange, generateAIPrompt, generateFreshSetupPrompt, initializeWorkflowDocument, materializeWorkflowDocument, normalizeConfig, parseMongoWhere, parseSort, parseSqlWhere, publishingWorkflow, runCollectionHooks, saveWorkflowDraft, transitionWorkflow, workflowCapabilities };

package/dist/index.js

@@ -1,9 +1,30 @@
 import {
+  LIFECYCLE_EVENTS_COLLECTION,
+  WORKFLOW_HISTORY_COLLECTION,
+  availableWorkflowTransitions,
+  createLifecycleEvent,
+  createWorkflowDocument,
+  dispatchLifecycleEvent,
+  dispatchPendingLifecycleEvents,
   executeFieldAfterRead,
   executeFieldBeforeChange,
+  initializeWorkflowDocument,
+  materializeWorkflowDocument,
   normalizeConfig,
-  runCollectionHooks
-} from "./chunk-SUGK7UYL.js";
+  publishingWorkflow,
+  runCollectionHooks,
+  saveWorkflowDraft,
+  transitionWorkflow,
+  workflowCapabilities
+} from "./chunk-CQDVPMEU.js";
+
+// src/types/index.ts
+var LIFECYCLE_EVENT_NAMES = [
+  "revision.created",
+  "workflow.transitioned",
+  "entry.published",
+  "entry.unpublished"
+];
 
 // src/utils/setup-prompt.ts
 function buildEnvironmentSection(frameworkLabel, isSelfHosted, config) {
@@ -153,6 +174,7 @@ COLLECTION OPTIONS:
 - upload: true       \u2014 media library with file upload support
 - auth: true         \u2014 adds login/me endpoints; password field is auto-managed
 - audit: true        \u2014 enables activity logging
+- admin.icon         \u2014 valid Lucide component name for sidebar navigation (e.g. 'Newspaper')
 - admin.useAsTitle   \u2014 field used as display title in admin list view
 - admin.group        \u2014 groups collection under a sidebar heading
 - admin.hidden       \u2014 hides collection from the sidebar (internal/system use)
@@ -197,7 +219,7 @@ const media = defineCollection({
 
 const pages = defineCollection({
   slug: 'pages',
-  admin: { useAsTitle: 'title', group: 'Content' },
+  admin: { icon: 'FileText', useAsTitle: 'title', group: 'Content' },
   fields: [
     { name: 'title', label: 'Title', type: 'text', required: true },
     { name: 'slug',  label: 'URL Slug', type: 'text', required: true, unique: true },
@@ -1011,16 +1033,30 @@ function defineConfig(config) {
   return config;
 }
 export {
+  LIFECYCLE_EVENTS_COLLECTION,
+  LIFECYCLE_EVENT_NAMES,
+  WORKFLOW_HISTORY_COLLECTION,
+  availableWorkflowTransitions,
+  createLifecycleEvent,
+  createWorkflowDocument,
   defineCollection,
   defineConfig,
   defineGlobal,
+  dispatchLifecycleEvent,
+  dispatchPendingLifecycleEvents,
   executeFieldAfterRead,
   executeFieldBeforeChange,
   generateAIPrompt,
   generateFreshSetupPrompt,
+  initializeWorkflowDocument,
+  materializeWorkflowDocument,
   normalizeConfig,
   parseMongoWhere,
   parseSort,
   parseSqlWhere,
-  runCollectionHooks
+  publishingWorkflow,
+  runCollectionHooks,
+  saveWorkflowDraft,
+  transitionWorkflow,
+  workflowCapabilities
 };