kapable-sdk (0.19.0)

Published 2026-09-15 07:51:47 +00:00 by kapable

Setup this registry in the Cargo configuration file (for example ~/.cargo/config.toml):

[registries.forgejo]
index = "sparse+" # Sparse index
# index = "" # Git

[net]
git-fetch-with-cli = true

To install the package using Cargo, run the following command:

cargo add kapable-sdk@0.19.0 --registry forgejo

For more information on the Cargo registry, see the documentation.

Typed Rust SDK for the Kapable v2 platform API

kapable-sdk

Typed Rust SDK for the Kapable v2 platform API. The single, typed, audited mirror of every customer-tier capability on the platform, scoped to the correct security token. The Rust twin of the TypeScript @kapable/sdk, kept at method parity by a shared coverage manifest.

Version 0.2.0 — customer-tier coverage 74.7% (up from 50.6% at the 2026-06-08 audit). 11 modules, 315 methods. See CHANGELOG.md.

Install

Published to the Kapable Forgejo cargo registry (anonymous read). One-time registry setup in .cargo/config.toml (project or ~/.cargo):

[registries.kapable]
index = "sparse+https://git.kapable.dev/api/packages/kapable/cargo/"

Then:

[dependencies]
kapable-sdk = { registry = "kapable", version = "0.2" }

Quick start

use kapable_sdk::KapableClient;

#[tokio::main]
async fn main() -> Result<(), kapable_sdk::KapableError> {
    let client = KapableClient::new("https://api.kapable.ai")
        .api_key("my-api-key")
        .build();

    let stories = client.board().list_stories(Default::default()).await?;
    println!("Found {} stories (total {})", stories.data.len(), stories.total);

    let buckets = client.store().list_buckets().await?;
    for bucket in &buckets {
        println!("Bucket: {}", bucket.name);
    }
    Ok(())
}

Auth

Two authentication methods:

// API key (x-api-key header)
let client = KapableClient::new("https://api.kapable.ai")
    .api_key("sk_live_...")
    .build();

// Bearer token (JWT / session)
let client = KapableClient::new("https://api.kapable.ai")
    .token("eyJ...")
    .build();

Picking the right token

The SDK never enforces authorization — the server does — but it ships a typed description of the platform's RBAC / token model so you can pick the right credential. See kapable_sdk::security (Permission, TokenType, Scope, AuthRequirement, and the tier presets):

use kapable_sdk::security::{tier, Permission};

let billing_req = tier::owner_with(Permission::BillingManage);
assert!(tier::OWNER.token_types.contains(&kapable_sdk::TokenType::Session));

Token tiering & contribution rules: ../kapable-sdk/CONTRIBUTING.md (shared, both languages)
Full RBAC / token-tiering matrix + gap analysis: ../docs/sdk-surface-matrix.md
Operator/admin endpoints (berth, foreman, host, gateway, …) are deliberately excluded — they belong in the planned ops SDK, never this crate.

Workspace scoping

Workspace-scoped data (workspaces module, workspace_scoped data tables) is resolved server-side from the X-Workspace-Id header (membership-validated by kapable-auth; a workspace-bound credential always wins over the header). The SDK sets the header natively — no header plumbing needed:

// Builder scope: every request carries X-Workspace-Id
let client = KapableClient::new("https://api.kapable.ai")
    .token("eyJ...")
    .workspace_id("a4d3…")
    .build();

// Derive re-scoped clients — sub-clients carry the new scope
let other = client.with_workspace_id("other-ws"); // different workspace
let org_wide = client.without_workspace_id();     // org-wide opt-out (no header)

Real-time (SSE)

Several modules expose text/event-stream endpoints (board events, data row changes, comms room/agent/anomaly feeds, AI proxy streaming). They return a Stream of typed events backed by the sse module (parse_sse_buffer / SseEvent), usable directly against any Kapable SSE endpoint.

Modules

11 customer-tier modules. Method counts are Rust / TS (kept at parity by the drift gate). The lists below are generated from ../kapable-sdk/coverage-manifest.json — the source of truth for the wrapped surface.

Module	Methods (Rust / TS)	Service	Description
`ai`	6 / 6	kapable-ai	Provider catalog, per-org config, upstream proxy (SSE)
`auth`	109 / 115	kapable-auth	Login, signup, orgs, members, API keys, apps, deployments, lanes, workspaces
`billing`	3 / 3	kapable-billing	Org subscription summary, Stripe checkout, customer portal
`board`	41 / 42	kapable-board	Stories, sprints, plans, products, comments, closures, Routa coordination
`comms`	43 / 43	kapable-comms	Agents, mailboxes, rooms, messages, email, bridges, SSE feeds
`data`	17 / 18	kapable-data	Tables CRUD, rows CRUD, search, bulk ops, CSV, SSE row changes
`harbor`	11 / 11	harbor	Runtime licensing + release store (public + org-scoped reads)
`knowledge`	37 / 38	kapable-knowledge	Claims, edges, predicates, perspectives, entities, tensions
`secrets`	7 / 7	strongbox	Org-scoped secrets vault: CRUD, rotate, audit
`store`	10 / 10	kapable-store	Buckets, objects, presigned URLs
`wiki`	31 / 31	kv2-wiki	Pages/collections/tags/projects CRUD, prompt-gen, agent-tools

Plus security (Permission / TokenType / Scope / AuthRequirement), sse (event-stream parser + connector), error, and types (ListResponse, ListParams).

Method index

Accessed via client.<module>().<method>(...).

ai — configure_provider, get_provider, list_providers, proxy, proxy_stream, remove_provider_config
auth — login, signup, logout, logout_everywhere, refresh, me, validate, validate_header, session_info, magic_link_request, magic_link_verify, create_api_key, list_api_keys, revoke_api_key, create_service_token, get_org, rename_org, get_org_caps, list_org_members, assign_member_role, deactivate_member, reactivate_member, create_invitation, list_invitations, revoke_invitation, accept_invitation, list_roles, create_role, update_role, delete_role, list_permissions, list_org_apps, get_app_detail, get_app_choice, create_app_choice, fork_app_choice, rename_app, delete_app, pause_app, resume_app, request_deploy, rebuild_app, … (full list in the manifest; admin_create_org/admin_create_org_api_key are admin-tier and now live in kapable-ops-sdk-rs; the 3 internal X-Callback-Token deployment/owner-email callbacks were dropped from both SDKs — they are internal service-to-service, intentionally in no SDK)
billing — get, init, portal
board — list_stories, get_story, create_story, update_story, delete_story, transition_story, search_stories, list_sprints, get_sprint, create_sprint, start_sprint, complete_sprint, attach_story, detach_story, get_closure, upsert_closure, list_plans, get_plan, create_plan, update_plan, list_revisions, create_revision, list_products, get_product, create_product, update_product, list_comments, create_comment, update_comment, delete_comment, get_lanes, set_lanes, post_evidence, get_verdict, list_worktrees, agent_report, list_story_repos, add_story_repo, remove_story_repo, list_repos, stream_events
comms — create_agent, list_agents, delete_agent, mint_agent_key, list_agent_keys, revoke_agent_key, create_mailbox, list_agent_mailboxes, delete_mailbox, list_mailbox_channels, create_channel, get_message, list_messages, send_email, create_room, list_rooms, get_room, room_presence, heartbeat, join_room, invite_agent_to_room, revoke_room_agent, create_invite, list_invites, revoke_invite, post_room_message, list_room_messages, mint_app_token, list_app_tokens, revoke_app_token, post_annotations, upsert_mailbox_quota, get_mailbox_quotas, delete_mailbox_quota, mailbox_rate_limit_hits, list_org_send_audit, link_telegram_bridge, telegram_setup_url, list_bridges, revoke_bridge, stream_room, stream_agent, stream_anomaly_feed
data — list_tables, create_table, drop_table, migrate_table, list_rows, get_row, create_rows, update_row, patch_row, delete_row, search_rows, bulk_update, bulk_delete, import_csv, export_data, stream_changes, stream_org_changes
harbor — activate, validate, verify_release, get_org_public_key, get_release_manifest, get_latest_release_compat, download_release_artifact, download_artifact, get_license, get_license_usage, list_org_keys
knowledge — create_claim, get_claim, list_claims, search_claims, list_claims_by_perspective, retract_claim, create_claim_confidence_evidence, list_claim_confidence_evidence, create_claim_meta, list_claim_meta, create_claim_derivations, list_claim_derivations, create_edge, list_edges, list_predicates, predicate_ontology, create_source, list_sources, delete_source, create_page, list_pages, merge_pages, create_corpus, get_corpus, list_corpora, get_perspective, list_perspectives, list_canonical_entities, resolve_canonical_entity, list_merge_candidates, decide_merge_candidate, unmerge_merge_candidate, list_source_provenance, source_provenance_graph, list_invariants, list_assay_runs, detect_tensions
secrets — create, get, list, update, delete, rotate, audit
store — list_buckets, create_bucket, list_objects, paginate_objects, upload_object, download_object, head_object, delete_object, presign_upload, presign_download
wiki — create_page, list_pages, update_page, delete_page, get_raw_page, create_entity_page, create_prompt_page, update_prompt, regenerate, generate_narrative, page_generation_history, create_collection, list_collections, get_collection, update_collection, delete_collection, add_page_to_collection, remove_page_from_collection, update_page_in_collection, create_tag, list_tags, add_tags_to_page, remove_tag_from_page, delete_tag, create_project, list_projects, search_claims, get_canonical_entity, list_predicates, read_page_tool, list_pages_tool

Coverage & drift gate

Coverage is measured against the customer-tier, SDK-eligible endpoint inventory. The TypeScript package owns the manifest and the gate (cd ../kapable-sdk && bun run check-drift); this crate is kept at method parity by the same manifest. Current: 74.7% customer-tier coverage, 0 phantom methods.

License

MIT

Customer service tokens

Create and rotate still use /v1/auth/service-tokens from your own session with keys.manage. New secrets start with sig_st_ and are revealed once. Metadata reports kind: signet or legacy_hmac; older servers may omit it. Signet rotation keeps the platform token id; legacy st_ rotation returns a successor id. List and revoke support both kinds. No admin key is needed in this SDK or client code.

Signet scopes cannot exceed the member's authority. Workspace bindings are preserved in the exact scope path; send the matching X-Workspace-Id when using the token. Project bindings (including default production projects) and workspace roles currently receive SERVICE_TOKEN_BINDING_UNSUPPORTED instead of a broader credential. An uncertain mutation requires operator reconciliation before retrying. Public create/rotate function signatures are unchanged.

ID	Version
aes-gcm	^0.10
base64	^0.22
bytes	^1
chrono	^0.4
futures-util	^0.3
rand	^0.8
reqwest	^0.12
serde	^1
serde_json	^1
thiserror	^2
tokio	^1
url	^2
uuid	^1
futures-util	^0.3
tokio	^1
wiremock	^0.6

Details

Cargo

2026-09-15 07:51:47 +00:00

Repository website

MIT

252 KiB

Assets (1)

kapable-sdk-0.19.0.crate 252 KiB

Versions (41) View all

0.19.1

2026-09-20

0.19.0

2026-09-15

0.18.2

2026-09-13

0.18.1

2026-09-05

0.18.0

2026-08-22