pub struct Client { /* private fields */ }Expand description
A thin async client for the kindling daemon.
Cheap to clone-by-config; construct once and share a reference. Each call
opens a fresh connection (no pooling), so the client itself holds no live
socket and is Send + Sync.
Implementations§
Source§impl Client
impl Client
Sourcepub fn new() -> Result<Client, ClientError>
pub fn new() -> Result<Client, ClientError>
Build a client from the default ClientConfig: socket at
~/.kindling/kindling.sock, project root from the current directory,
the compiled schema version, a 1s connect budget, and the real binary
spawner.
Sourcepub fn with_config(config: ClientConfig) -> Client
pub fn with_config(config: ClientConfig) -> Client
Build a client from an explicit ClientConfig.
Sourcepub fn config(&self) -> &ClientConfig
pub fn config(&self) -> &ClientConfig
The configuration this client was built with.
Sourcepub async fn health(&self) -> Result<Health, ClientError>
pub async fn health(&self) -> Result<Health, ClientError>
GET /v1/health — version, schema version, and touched project ids.
Verifies the daemon’s schemaVersion matches
ClientConfig::expected_schema_version; returns
ClientError::SchemaMismatch if not (fail loud).
Sourcepub async fn open_capsule(
&self,
kind: CapsuleType,
intent: impl Into<String>,
scope_ids: ScopeIds,
id: Option<String>,
) -> Result<Capsule, ClientError>
pub async fn open_capsule( &self, kind: CapsuleType, intent: impl Into<String>, scope_ids: ScopeIds, id: Option<String>, ) -> Result<Capsule, ClientError>
POST /v1/capsules — open a capsule.
Sourcepub async fn get_open_capsule(
&self,
session_id: &str,
) -> Result<Option<Capsule>, ClientError>
pub async fn get_open_capsule( &self, session_id: &str, ) -> Result<Option<Capsule>, ClientError>
GET /v1/capsules/open?sessionId=… — the open session capsule for
session_id, or None when none is open.
Each Claude Code hook is a fresh process holding only the session id, so the Stop hook resolves the capsule it must close through this endpoint rather than tracking it in-process.
Sourcepub async fn close_capsule(
&self,
capsule_id: &str,
body: CloseCapsuleBody,
) -> Result<Capsule, ClientError>
pub async fn close_capsule( &self, capsule_id: &str, body: CloseCapsuleBody, ) -> Result<Capsule, ClientError>
PATCH /v1/capsules/:id/close — close a capsule.
Sourcepub async fn append_observation(
&self,
input: ObservationInput,
capsule_id: Option<String>,
validate: Option<bool>,
) -> Result<AppendResult, ClientError>
pub async fn append_observation( &self, input: ObservationInput, capsule_id: Option<String>, validate: Option<bool>, ) -> Result<AppendResult, ClientError>
POST /v1/observations — append an observation, optionally attaching it
to capsule_id and toggling service-side validate (default true).
Returns an AppendResult carrying the stored observation and the
daemon’s deduplicated flag. A duplicate id is not an error: the
daemon ignores the write and returns the pre-existing row with
deduplicated: true, so replaying an already-delivered observation is a
no-op.
Sourcepub async fn retrieve(
&self,
options: RetrieveOptions,
) -> Result<RetrieveResult, ClientError>
pub async fn retrieve( &self, options: RetrieveOptions, ) -> Result<RetrieveResult, ClientError>
POST /v1/retrieve — deterministic ranked retrieval.
Sourcepub async fn list_observations(
&self,
request: ListObservationsRequest,
) -> Result<ListObservationsResult, ClientError>
pub async fn list_observations( &self, request: ListObservationsRequest, ) -> Result<ListObservationsResult, ClientError>
POST /v1/observations/list — exhaustive, deterministically-paginated
observation list (FTS-independent; kind / scope / half-open time-range
filters with a keyset cursor). Returns one page; pass back
ListObservationsResult::next_cursor as
ListObservationsRequest::cursor until it is None.
Sourcepub async fn pin(&self, body: CreatePinBody) -> Result<Pin, ClientError>
pub async fn pin(&self, body: CreatePinBody) -> Result<Pin, ClientError>
POST /v1/pins — create a pin.
Sourcepub async fn unpin(&self, pin_id: &str) -> Result<(), ClientError>
pub async fn unpin(&self, pin_id: &str) -> Result<(), ClientError>
DELETE /v1/pins/:id — remove a pin.
Sourcepub async fn forget(&self, observation_id: &str) -> Result<(), ClientError>
pub async fn forget(&self, observation_id: &str) -> Result<(), ClientError>
POST /v1/observations/:id/forget — redact an observation (content
replaced with [redacted], redacted flag set). Succeeds on 204.
A missing id surfaces as ClientError::Api with status 404 (the
daemon maps the store’s ObservationNotFound). The observation_id must
be exact — prefix resolution is a higher-layer concern.
Sourcepub async fn session_start_context(
&self,
max_results: Option<u32>,
) -> Result<Option<String>, ClientError>
pub async fn session_start_context( &self, max_results: Option<u32>, ) -> Result<Option<String>, ClientError>
POST /v1/context/session-start — the assembled + formatted SessionStart
injection markdown, or None when there is nothing to inject.
The daemon owns the formatting (recency-ordered observations, pin
previews, and the toLocaleString-parity dates). max_results caps the
recent-observation count (default 10 when None). The project scope is
derived from this client’s project root, reproducing the Node hook’s
{ repoId: <project root> } filter within the project database.
Sourcepub async fn pre_compact_context(&self) -> Result<Option<String>, ClientError>
pub async fn pre_compact_context(&self) -> Result<Option<String>, ClientError>
POST /v1/context/pre-compact — the assembled + formatted PreCompact
injection markdown (pinned items + latest session summary), or None
when there is nothing to inject.
As with Self::session_start_context, the project scope is derived
from this client’s project root.