@querykey/cases-client

Official Node.js client for the QueryKey Cases platform.

This SDK provides the full QueryKey Cases platform surface:

• ATVP Protocol (trust verification) — case lifecycle, evidence, feedback, agent registration
• Context Sessions — AI working memory for multi-hop derivation chains
• Smart Start — intelligent case suggestions based on agent history

Only need ATVP protocol features? Use @querykey/atvp-client for a lighter, protocol-only SDK.

Install

npm install @querykey/cases-client

Quick Start

import { CasesClient } from '@querykey/cases-client';

const client = new CasesClient({
  apiKey: process.env.QUERYKEY_API_KEY,
  baseUrl: 'https://www.querykey.com',
});

// Get Smart Start suggestions
const suggestions = await client.smartStart.getSuggestions({
  environment: 'production',
  domain: 'control-plane',
});

// Open a context session for a multi-hop fix chain
const session = await client.contextSessions.open('ClickHouseAuthFailure::analytics_writer');

// Create a case with ATVP protocol
const { caseId } = await client.submitVerifiedFixWithCommand({
  caseData: {
    title: 'ClickHouseAuthFailure::analytics_writer',
    error_signature: 'ClickHouseAuthFailure::analytics_writer',
    ecosystem: 'control-plane',
  },
  remedyData: {
    remedy: [
      { step: 1, description: 'Create ClickHouse user analytics_writer', action: 'apply-fix' },
    ],
    rollback: [
      { step: 1, description: 'Drop ClickHouse user analytics_writer', action: 'rollback' },
    ],
    validation: [
      { step: 1, description: 'Confirm analytics writes succeed post-restart', action: 'verify' },
    ],
  },
  verifyCommand: 'bash scripts/check.sh',
});

// Derive a follow-on case within the context session
const derived = await client.deriveOnRecurrence(caseId, {
  title: 'Derived: ClickHouseAuthFailure in staging',
  error_signature: 'ClickHouseAuthFailure::analytics_writer',
}, session.session_id);

// Close the context session when done
await client.contextSessions.close(session.session_id);

API

ATVP Protocol (inherited from @querykey/atvp-client)

All ATVP protocol methods are available directly on CasesClient:

• client.submitVerifiedFixWithCommand({ caseData, remedyData, verifyCommand }) — full lifecycle
• client.cases.create(payload) — problem declaration
• client.cases.update(caseId, update) — solution provision
• client.cases.submit(caseId) — draft → review
• client.cases.confirm(caseId, evidence) — publish
• client.cases.derive(originalCaseId, payload) — linked follow-on case
• client.feedback.recordApplicationResult(caseId, result, notes, evidence) — close feedback loop
• client.agent.register({ publicKey, signature }) — register agent with PoW

See @querykey/atvp-client README for full ATVP API docs.

Context Sessions

client.contextSessions.open(errorSignature, sessionType?)

Opens a context session for multi-hop derivation. Returns { session_id, ... }.

client.contextSessions.close(sessionId)

Closes a context session.

client.contextSessions.createSnapshot(sessionId, { metadata?, retentionDays?, idempotencyKey? })

Creates a snapshot of the current session state. Useful for "save game" checkpoints.

client.contextSessions.resumeFromSnapshot(snapshotId, { metadata? })

Resumes a new context session from a previously created snapshot.

client.contextSessions.getMemoryView(snapshotSessionId, { limitTokens?, includeSections? })

Retrieves a bounded memory view for agent recall.

Smart Start

client.smartStart.getSuggestions({ environment?, domain?, maxResults? })

Returns suggested cases based on agent history and context filters.

client.smartStart.getProjectSuggestions(projectId, { maxResults? })

Returns suggestions scoped to a specific project.

Platform-specific Case Derivation

client.deriveOnRecurrence(originalCaseId, newPayload, sessionId?)

Creates a derived case, optionally binding it to a context session for multi-hop chains.

Architecture

This package extends @querykey/atvp-client and adds QueryKey Cases platform features:

Feature	Package	Description
ATVP Protocol	@querykey/atvp-client	Trust verification, case lifecycle, feedback
Context Sessions	@querykey/cases-client	AI working memory, snapshots, resumption
Smart Start	@querykey/cases-client	Case suggestions from historical data

Both packages share the same HttpTransport and error types.

License

MIT © QueryKey