Skip to main content

qail_workflow/
lib.rs

1//! # QAIL Flow Engine
2//!
3//! Declarative state machine engine for multi-vertical workflows.
4//!
5//! Provides domain-agnostic primitives for orchestrating sequences of
6//! database queries, notifications, and external events. Designed for
7//! booking recovery, inventory sync, and operator coordination across
8//! ferry, car rental, yacht charter, and fishing boat verticals.
9//!
10//! ## Architecture
11//!
12//! ```text
13//! your app (domain states + executor impl)
14//!       ↓
15//! qail-workflow (Flow Engine)
16//!       ↓
17//! qail-core (AST queries composed into steps)
18//!       ↓
19//! optional qail-workflow-postgres (Flow Ledger)
20//! ```
21//!
22//! ## Quick Start
23//!
24//! ```rust,ignore
25//! use qail_workflow::*;
26//! use qail_core::Qail;
27//!
28//! // Define a workflow
29//! let wf = WorkflowDefinition::new("booking_recovery")
30//!     .initial_state("operator_declined")
31//!     .transition("operator_declined", "recovery_mode", vec![
32//!         WorkflowStep::query(
33//!             Qail::get("odysseys").limit(5),
34//!             Some("alternatives"),
35//!         ),
36//!         WorkflowStep::for_each("alternatives", vec![
37//!             WorkflowStep::notify(ChannelKind::WhatsApp, "opportunity_alert", "item.phone"),
38//!         ]),
39//!         WorkflowStep::wait("operator_accept", Duration::from_secs(7200)),
40//!     ]);
41//!
42//! // Run it with your executor
43//! let result = run_workflow(&my_executor, &wf, &mut ctx).await?;
44//! ```
45
46#![deny(warnings)]
47#![deny(clippy::all)]
48#![deny(unused_imports)]
49#![deny(dead_code)]
50
51pub mod channel;
52pub mod context;
53pub mod engine;
54pub mod payment;
55pub mod registry;
56pub mod runtime;
57pub mod state;
58pub mod step;
59
60// Re-exports for convenience
61pub use channel::{ChannelError, ChannelKind, NotifyChannel};
62pub use context::{
63    WorkflowBranchCursorSelection, WorkflowContext, WorkflowCursor, WorkflowCursorFrame,
64    WorkflowPendingWait,
65};
66pub use engine::{
67    LegacyQueryPayloadIssue, WorkflowError, WorkflowExecutor, collect_legacy_query_payload_issues,
68    resume_workflow, resume_workflow_with_event, resume_workflow_with_event_and_options,
69    resume_workflow_with_options, run_workflow, run_workflow_with_options, timeout_due_workflows,
70    timeout_workflow, timeout_workflow_with_options,
71};
72pub use payment::{
73    ChargeRequest, ChargeResponse, ChargeStatus, Currency, OrderOrigin, PaymentDisplay,
74    PaymentError, PaymentEvent, PaymentKind, PaymentProvider,
75};
76pub use registry::{StateTransition, WorkflowDefinition};
77pub use runtime::{
78    WorkflowLease, WorkflowLeaseOptions, WorkflowOperation, WorkflowOperationKind,
79    WorkflowOperationStatus, WorkflowRunOptions, WorkflowSideEffect, WorkflowSideEffectKind,
80    WorkflowSideEffectStatus, WorkflowTimeoutOutcome,
81};
82pub use state::State;
83pub use step::{WorkflowBranchCondition, WorkflowStep};