qefro-backend-sdk

Qefro backend framework for Business Tool handlers and customer authorization (Rust).

Organizations expose one signed webhook (typically POST /qefro). Qefro Runtime calls ping, capabilities.list, tool.invoke, and tool.resume. Authentication stays in your handlers — Qefro only relays challenges.

Companion TypeScript package: @qefro-ai/backend (feature-parity target).

Install

[dependencies]
qefro-backend-sdk = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "signal"] }

cargo add qefro-backend-sdk

Quick start

use qefro_backend_sdk::{ListenOptions, Qefro, QefroConfig, ToolAuthMode, ToolLookup, ToolMetadata};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = Qefro::new(QefroConfig::new(std::env::var("QEFRO_SIGNING_SECRET")?));

    app.tool(
        ToolMetadata {
            name: "order_status_check".into(),
            description: Some("Look up order status by ID".into()),
            auth: ToolAuthMode::None,
            lookup: Some(ToolLookup {
                by: Some("email".into()),
                required: vec![],
            }),
            input_schema: Some(json!({
                "type": "object",
                "properties": { "order_id": { "type": "string" } },
                "required": ["order_id"]
            })),
            ..Default::default()
        },
        |ctx| async move {
            Ok(json!({
                "order_id": ctx.parameters.get("order_id"),
                "status": "shipped"
            }))
        },
    );

    let handle = app.listen(ListenOptions { port: 8088, host: None, path: None }).await?;
    println!("listening on {}", handle.url);
    tokio::signal::ctrl_c().await?;
    handle.close().await;
    Ok(())
}

Set the same signing secret in Admin Console → Business Tools → SDK Connections, then Sync Tools.

Business Flows

Flows describe how your Business Tools are orchestrated. They are metadata only — the SDK advertises them through capabilities.list and the Qefro Runtime discovers, validates, versions, and (later) executes them. Nothing runs inside the SDK. A flow with a duplicate/empty id (flow or step) is excluded from capabilities.list and surfaced through FlowError instead of panicking.

use qefro_backend_sdk::BusinessFlowMetadata;

app.flow(BusinessFlowMetadata {
    id: "order_lookup".into(),        // immutable identity — renaming `name` never creates a new flow
    name: Some("Order Lookup".into()),
    description: Some("Lookup customer orders".into()),
    category: Some("crm".into()),
    tags: vec!["customer".into(), "orders".into()],
    intent: vec!["track order".into(), "where is my order".into()],
    inputs: vec!["email".into()],
    outputs: vec!["customer".into(), "orders".into()],
    ..Default::default()
})?
.ask("email", "email", "Please enter your email.")
.tool("lookup", "lookup_customer")
.tool("orders", "get_orders")
.complete("done", Some("Here are your recent orders.".into()))?;

Every step needs a unique id; tool steps reference an existing Business Tool by tool_ref. Step builders: .ask() .tool() .challenge() .upload() .condition() .delay() .approval() .complete(). See examples/basic.

Docs

• Register SDK Business Tools
• Define Business Flows
• docs.rs/qefro-backend-sdk

Protocol

Requests are HMAC-SHA256 signed (X-Qefro-Signature / X-Qefro-Timestamp). Responses include X-Qefro-Protocol, X-Qefro-SDK, and X-Qefro-Version.

Build

cargo build
cargo test
cargo run --example basic

Publishing (maintainers)

CI publishes to crates.io via .github/workflows/publish-crates.yml.

1. Create a crates.io API token at https://crates.io/settings/tokens (scopes: publish-new / publish-update).
2. In GitHub → Settings → Secrets and variables → Actions, add secret CARGO_REGISTRY_TOKEN with that token value.
3. Publish either:
   • Actions → Publish crates → Run workflow, or
   • Create a GitHub Release (triggers publish automatically).

Bump version in Cargo.toml before publishing a new release.

License

MIT