SDK Reference

npm install blacklake

import { BlackLake } from 'blacklake';

const bl = new BlackLake(config: BlackLakeConfig);

interface BlackLakeConfig {
  apiKey: string;     // Required. Your organisation's API key.
  baseUrl?: string;   // Optional. Defaults to https://api.blacklake.systems.
                      // Set to 'http://localhost:3100' for local mode.
}

// Local mode
const bl = new BlackLake({
  apiKey: 'local',
  baseUrl: 'http://localhost:3100',
});

// Cloud mode
const bl = new BlackLake({
  apiKey: process.env.BLACKLAKE_API_KEY!,
  // baseUrl defaults to https://api.blacklake.systems
});

bl.govern(request: GovernRequest): Promise<GovernResponse>

interface GovernRequest {
  agent: string;                        // Agent name (as registered)
  tool: string;                         // Tool name (as registered)
  action?: Record<string, unknown>;     // Optional. The action the agent wants to take. Logged with the evaluation.
  context?: Record<string, unknown>;    // Optional. Caller-supplied context. Logged with the evaluation.
  /**
   * Pre-call cost estimate. REQUIRED for cost-aware policies and budget
   * pre-checks to deny before the LLM call leaves the network.
   * Without it, the resolver sees `tool.estimated_cost_usd = 0` and
   * cost-aware gt/gte conditions never match.
   */
  estimate?: GovernEstimate;
  session_id?: string;  // Group of related calls within an agent run.
  task_id?: string;     // User-facing task within a session.
  user_id?: string;     // Caller-supplied user attribution; drives per-user budgets.
}

interface GovernEstimate {
  provider: string;
  model: string;
  input_tokens: number;
  output_ceiling_tokens: number;
  estimated_cost_usd: number;  // Run bl.cost.estimate() first; pass total_usd here.
}

interface GovernResponse {
  decision: 'allow' | 'deny' | 'approval_required' | 'default_deny';
  evaluation_id: string;      // ID of the recorded evaluation.
  policy_id: string | null;   // ID of the matched policy, or null.
  reason: string;             // Human-readable explanation of the decision.
  evaluated_at: string;       // ISO 8601 UTC timestamp.
  approval_id?: string;       // Present only when decision === 'approval_required'.
  decision_token: string;     // Signed receipt token. Verify with bl.decisions.verify().
  estimated_cost_usd?: number;       // Echo of the supplied estimate. Confirms the server saw what you sent.
  budget_headroom_usd?: number | null; // Headroom on the tightest enforcing budget. null when no enforcing budget applies.
}

const result = await bl.govern({
  agent: 'data-pipeline-agent',
  tool: 'write-to-database',
  action: { table: 'orders', operation: 'insert' },
  context: { run_id: 'run_abc123' },
});

if (result.decision === 'allow') {
  await writeToDatabase(payload);
} else {
  throw new Error(`Blocked by governance: ${result.reason} (${result.evaluation_id})`);
}

import { BlackLake, withGovernance } from 'blacklake';

const bl = new BlackLake({ apiKey: process.env.BLACKLAKE_API_KEY });

const result = await withGovernance(
  bl,
  {
    agent: 'support-bot',
    tool: 'stripe.refund',
    action: { amount_cents: 4200 },
    externalSystem: 'temporal',
    context: {
      engine: { engine: 'temporal', workflow_id: 'wf_1', run_id: 'r_2', step_id: 'refund', attempt: 1 },
    },
  },
  async () => stripe.refunds.create({ payment_intent: 'pi_3Nq8X', amount: 4200 }),
);

import { governedTool } from 'blacklake';

const refund = governedTool(
  bl,
  { agent: 'support-bot', tool: 'stripe.refund', externalSystem: 'inngest' },
  async (paymentIntent: string, amount: number) =>
    stripe.refunds.create({ payment_intent: paymentIntent, amount }),
);

await refund(
  { action: { amount: 4200 }, context: { engine: { engine: 'inngest', run_id: 'r' } } },
  'pi_3Nq8X',
  4200,
);

import { detectEngine } from 'blacklake';

const engine = detectEngine();
// { engine: 'github-actions', workflow_id: 'release', run_id: '12345', ... }
// — or {} when no CI env is detected.

await bl.govern({
  agent: 'release-bot',
  tool: 'gcloud.run.deploy',
  context: { engine },
});

bl.agents.create(data: {
  name: string;
  description?: string;
  environment: 'development' | 'staging' | 'production';
  risk_classification: 'low' | 'medium' | 'high' | 'critical';
  approval_mode?: 'auto_approve' | 'require_approval' | 'block';
  /**
   * Free-text identifier (email, team name, ticket reference) for audit
   * attribution. Strongly recommended in production.
   */
  owner?: string;
  /**
   * Capture path that registered this agent. Defaults to 'manual' for SDK
   * callers; set to 'sdk' to attribute the agent to your application code,
   * 'ci' for governed CI pipelines, etc. Used by the Coverage view.
   */
  source?: 'manual' | 'mcp' | 'sdk' | 'ci';
}): Promise<Agent>

const agent = await bl.agents.create({
  name: 'fraud-detection-agent',
  environment: 'production',
  risk_classification: 'high',
  owner: 'platform-team@acme.example',
  source: 'sdk',
});

bl.agents.list(params?: {
  environment?: 'development' | 'staging' | 'production';
  status?: 'active' | 'suspended' | 'disabled';
  limit?: number;
  offset?: number;
  sort?: 'created_at' | 'updated_at' | 'name' | 'environment' | 'risk_classification' | 'status';
  order?: 'asc' | 'desc';
  include_deleted?: boolean;
  only_deleted?: boolean;
}): Promise<{
  data: Agent[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

// All active production agents
const { data: agents, total } = await bl.agents.list({
  environment: 'production',
  status: 'active',
});

bl.agents.get(id: string): Promise<Agent>

const agent = await bl.agents.get('agent_01j...');

bl.agents.update(
  id: string,
  data: Partial<{
    name: string;
    description: string;
    environment: 'development' | 'staging' | 'production';
    risk_classification: 'low' | 'medium' | 'high' | 'critical';
    status: 'active' | 'suspended' | 'disabled';
    approval_mode: 'auto_approve' | 'require_approval' | 'block';
    owner: string;
  }>
): Promise<Agent>

const updated = await bl.agents.update('agent_01j...', {
  risk_classification: 'critical',
});

bl.agents.suspend(id: string): Promise<Agent>

await bl.agents.suspend('agent_01j...');

bl.agents.activate(id: string): Promise<Agent>

await bl.agents.activate('agent_01j...');

bl.agents.delete(id: string): Promise<Agent>

const archived = await bl.agents.delete('agent_01j...');
console.log(archived.deleted_at); // ISO timestamp

bl.agents.restore(id: string): Promise<Agent>

await bl.agents.restore('agent_01j...');

bl.agents.bindTool(
  agentId: string,
  toolId: string
): Promise<{ id: string; agent_id: string; tool_id: string; created_at: string }>

await bl.agents.bindTool('agent_01j...', 'tool_01j...');

bl.agents.listTools(agentId: string): Promise<ToolBinding[]>

interface ToolBinding {
  binding_id: string;
  binding_created_at: string;
  tool: Tool;
}

const bindings = await bl.agents.listTools('agent_01j...');
for (const b of bindings) {
  console.log(b.tool.name, b.binding_created_at);
}

bl.agents.unbindTool(agentId: string, toolId: string): Promise<void>

await bl.agents.unbindTool('agent_01j...', 'tool_01j...');

bl.tools.create(data: {
  name: string;
  description?: string;
  risk_classification: 'low' | 'medium' | 'high' | 'critical';
  /** Free-text owner — same shape as on agents. */
  owner?: string;
  /** Capture path that registered this tool. Used by Coverage. */
  source?: 'manual' | 'mcp' | 'sdk' | 'ci';
}): Promise<Tool>

const tool = await bl.tools.create({
  name: 'delete-record',
  description: 'Permanently deletes a database record',
  risk_classification: 'critical',
  owner: 'platform-team@acme.example',
  source: 'sdk',
});

bl.tools.list(params?: {
  limit?: number;
  offset?: number;
  sort?: 'created_at' | 'name' | 'risk_classification';
  order?: 'asc' | 'desc';
  include_deleted?: boolean;
  only_deleted?: boolean;
}): Promise<{
  data: Tool[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

const { data: tools } = await bl.tools.list();

bl.tools.get(id: string): Promise<Tool>

const tool = await bl.tools.get('tool_01j...');

bl.tools.update(id: string, patch: { name?, description?, risk_classification?, owner? }): Promise<Tool>

const tool = await bl.tools.update('tool_01j...', { owner: 'platform-team@acme.example' });

bl.tools.delete(id: string): Promise<Tool>

await bl.tools.delete('tool_01j...');

bl.tools.restore(id: string): Promise<Tool>

await bl.tools.restore('tool_01j...');

bl.policies.create(data: {
  name: string;
  priority: number;
  agent_selector?: Record<string, unknown>;
  tool_selector?: Record<string, unknown>;
  outcome: 'allow' | 'deny' | 'approval_required';
  enabled?: boolean;
  requires_two_person?: boolean;
  approver_roles?: string[];
  cost_conditions?: Record<string, unknown> | null;
  mode?: 'enforce' | 'monitor';
}): Promise<Policy>

const policy = await bl.policies.create({
  name: 'block-high-risk-tools-in-prod',
  priority: 1,
  agent_selector: { environment: 'production' },
  tool_selector: { risk_classification: 'high' },
  outcome: 'deny',
});

bl.policies.list(params?: {
  limit?: number;
  offset?: number;
  sort?: 'name' | 'priority' | 'created_at' | 'updated_at';
  order?: 'asc' | 'desc';
}): Promise<{
  data: Policy[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

const { data: policies, total } = await bl.policies.list();

bl.policies.get(id: string): Promise<Policy>

const policy = await bl.policies.get('pol_01j...');

bl.policies.update(
  id: string,
  data: Partial<{
    name: string;
    priority: number;
    agent_selector: Record<string, unknown>;
    tool_selector: Record<string, unknown>;
    outcome: 'allow' | 'deny' | 'approval_required';
    enabled: boolean;
    requires_two_person: boolean;
    approver_roles: string[] | null;
    cost_conditions: Record<string, unknown> | null;
    mode: 'enforce' | 'monitor';
  }>
): Promise<Policy>

// Disable a policy without deleting it
const updated = await bl.policies.update('pol_01j...', { enabled: false });

bl.policies.delete(id: string): Promise<void>

bl.policies.simulate(draft: {
  priority: number;
  agent_selector?: Record<string, unknown>;
  tool_selector?: Record<string, unknown>;
  outcome: 'allow' | 'deny' | 'approval_required';
  window_days?: number;  // default 30, max 365
  sample_limit?: number; // default 50, max 500
}): Promise<PolicySimulationResult>

const sim = await bl.policies.simulate({
  priority: 5,
  agent_selector: { environment: 'production' },
  tool_selector: { risk_classification: 'high' },
  outcome: 'approval_required',
  window_days: 30,
});

console.log(sim.before, sim.after, sim.changes.transitions);
// { allow: 1500, ... } { allow: 1450, approval_required: 150, ... }
// { allow_to_approval_required: 50 }

await bl.policies.delete('pol_01j...');

bl.evaluations.list(params?: {
  agent_id?: string;
  tool_id?: string;
  outcome?: 'allow' | 'deny' | 'approval_required' | 'default_deny';
  limit?: number;   // Default: 50
  offset?: number;  // Default: 0
}): Promise<PaginatedResponse<Evaluation>>

// Last 10 denied evaluations for a specific agent
const { data, total } = await bl.evaluations.list({
  agent_id: 'agent_01j...',
  outcome: 'deny',
  limit: 10,
});

console.log(`Showing ${data.length} of ${total} denials`);

bl.evaluations.get(id: string): Promise<Evaluation>

const evaluation = await bl.evaluations.get('eval_01j...');

bl.evaluations.listResults(id: string): Promise<{ data: ActionResult[] }>

const { data: results } = await bl.evaluations.listResults('eval_01j...');

for (const result of results) {
  console.log(result.status, result.external_system, result.external_id);
}

bl.evaluations.recordResult(
  id: string,
  body: CreateActionResultRequest,
): Promise<ActionResult>

const decision = await bl.govern({
  agent: 'release-agent',
  tool: 'deploy-service',
  action: { service: 'api', environment: 'production' },
  context: { run_id: 'run_123' },
});

if (decision.decision === 'allow') {
  const started = Date.now();

  try {
    const run = await deployService();

    await bl.evaluations.recordResult(decision.evaluation_id, {
      status: 'succeeded',
      external_system: 'github-actions',
      external_id: run.id,
      external_url: run.url,
      duration_ms: Date.now() - started,
      exit_code: 0,
      output_digest: run.outputDigest,
      metadata: { workflow: 'deploy' },
    });
  } catch (error) {
    await bl.evaluations.recordResult(decision.evaluation_id, {
      status: 'failed',
      external_system: 'github-actions',
      duration_ms: Date.now() - started,
      error: error instanceof Error ? error.message : String(error),
    });

    throw error;
  }
}

bl.decisions.verify(params: {
  evaluation_id: string;
  decision_token: string;
}): Promise<VerifyDecisionResult>

const receipt = await bl.decisions.verify({
  evaluation_id: decision.evaluation_id,
  decision_token: decision.decision_token,
});

if (receipt.valid) {
  console.log(receipt.decision, receipt.policy_name, receipt.action_results);
} else {
  console.warn(`Receipt verification failed: ${receipt.reason}`);
}

bl.cost.record(body: CostRecordIngest): Promise<CostRecord>

const decision = await bl.govern({ agent: 'claude-prod', tool: 'github__create-issue' });

// ... your direct Bedrock / Vertex / Foundry call happens here ...

await bl.cost.record({
  evaluation_id: decision.evaluation_id,
  provider: 'bedrock',
  model: 'anthropic.claude-sonnet-4-6',
  input_tokens: 1820,
  output_tokens: 412,
  capture_path: 'sdk',
});

bl.cost.estimate(body: CostEstimateRequest): Promise<CostBreakdown>

const breakdown = await bl.cost.estimate({
  provider: 'anthropic',
  model: 'claude-opus-4-7',
  input_tokens: 12_000,
  output_ceiling_tokens: 4_000,
});

console.log(`Projected: $${breakdown.total_usd.toFixed(4)} (pricing v${breakdown.pricing_version})`);

bl.cost.summary(period?: 'day' | '7d' | '30d' | '90d'): Promise<unknown>

bl.cost.byEvaluation(evaluationId: string): Promise<CostByEvaluation>

const { summary, records, decision_token_v2 } = await bl.cost.byEvaluation(evalId);
if (decision_token_v2) {
  // Receipt is now v2 — bind it into your audit trail.
}

bl.cost.timeseries(period?: 'day' | '7d' | '30d' | '90d'): Promise<{
  period: string;
  days: Array<{ day: string; cost_usd: number; calls: number }>;
}>

bl.cost.decomposition(period?: 'day' | '7d' | '30d' | '90d'): Promise<unknown>

bl.cost.export(
  format: 'csv' | 'ndjson',
  period?: '7d' | '30d' | '90d'
): Promise<string>

bl.cost.pricing(version?: string): Promise<{
  version: string;
  current_version: string;
  available_versions: string[];
  rows: Array<{
    provider: CostProvider;
    model: string;
    match_kind: 'exact' | 'prefix';
    rates: {
      input_per_1m: number;
      output_per_1m: number;
      cache_read_per_1m: number;
      cache_write_per_1m: number;
      thinking_per_1m: number;
    };
  }>;
}>

bl.cost.orphans(params?: {
  limit?: number;
  offset?: number;
  since?: string;
}): Promise<{
  data: CostRecord[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

bl.budgets.list(): Promise<Budget[]>

bl.budgets.create(args: BudgetCreate): Promise<Budget>

await bl.budgets.create({
  name: 'Production Opus / month',
  scope_type: 'agent',
  scope_id: 'agent_…',
  period: 'month',
  timezone: 'Europe/London',
  soft_limit_usd: 800,
  hard_limit_usd: 1000,
});

bl.budgets.get(id: string): Promise<Budget>

bl.budgets.status(id: string): Promise<BudgetStatus>

const s = await bl.budgets.status(budgetId);
console.log(`${s.spend_usd} / ${s.hard_limit_usd} (${s.state})`);
// → 742.18 / 1000 (soft_80)

bl.budgets.statusFor(id: string): Promise<BudgetStatus>

bl.budgets.workspaceStatus(): Promise<{
  budgets: Array<{
    id: string;
    name: string;
    scope_type: BudgetScope;
    scope_id: string | null;
    scope_name: string | null;
    period: BudgetPeriod;
    spend_usd: number;
    soft_limit_usd: number | null;
    hard_limit_usd: number;
  }>;
}>

bl.budgets.update(id: string, patch: Partial<BudgetCreate>): Promise<Budget>

bl.budgets.delete(id: string): Promise<void>

bl.organisation.get(): Promise<Organisation>

const org = await bl.organisation.get();
console.log(org.name, org.contact_email);

bl.organisation.delete(confirmation: string, reason?: string): Promise<void>

const org = await bl.organisation.get();
await bl.organisation.delete(org.name, 'switching to a regulated tenant');

bl.organisation.reset(confirmation: string, reason?: string): Promise<{
  reset_at: string;
  organisation_id: string;
  total_rows: number;
  counts: Record<string, number>;
  preserved: string[];
  note: string;
}>

const org = await bl.organisation.get();
const result = await bl.organisation.reset(org.name);
console.log(`Wiped ${result.total_rows} rows across ${Object.keys(result.counts).length} tables`);

bl.approvals.list(params?: {
  status?: 'pending' | 'approved' | 'rejected' | 'expired';
  agent_id?: string;
  tool_id?: string;
  limit?: number;   // Default: 50
  offset?: number;  // Default: 0
}): Promise<PaginatedResponse<Approval>>

// All pending approvals
const { data, total } = await bl.approvals.list({ status: 'pending' });
console.log(`${data.length} of ${total} pending approvals`);

bl.approvals.get(id: string): Promise<Approval>

const approval = await bl.approvals.get('approval_01j...');
console.log(approval.status, approval.expires_at);

bl.approvals.status(id: string): Promise<ApprovalStatusResponse>

const { status, decided_at, expires_at } = await bl.approvals.status('approval_01j...');

bl.approvals.approve(
  id: string,
  data: { decided_by: string; reason?: string }
): Promise<Approval>

const approval = await bl.approvals.approve('approval_01j...', {
  decided_by: 'ops-team',
  reason: 'Verified vendor and amount are correct',
});
console.log(approval.status); // 'approved'

bl.approvals.reject(
  id: string,
  data: { decided_by: string; reason?: string }
): Promise<Approval>

const approval = await bl.approvals.reject('approval_01j...', {
  decided_by: 'ops-team',
  reason: 'Amount exceeds policy limit without CFO sign-off',
});
console.log(approval.status); // 'rejected'

bl.approvals.breakGlass(
  id: string,
  args: { decided_by: string; reason: string }
): Promise<Approval>

const approval = await bl.approvals.breakGlass('approval_01j...', {
  decided_by: 'oncall@acme.example',
  reason:
    'Production incident — bypassing two-person approval to roll back the bad release immediately.',
});

bl.approvals.wait(
  id: string,
  options?: {
    interval?: number;  // Poll interval in ms. Default: 2000.
    timeout?: number;   // Total wait time in ms. Default: 300000 (5 minutes).
  }
): Promise<Approval>

try {
  const approval = await bl.approvals.wait('approval_01j...', {
    interval: 3000,
    timeout: 60_000, // 1 minute
  });

  if (approval.status === 'approved') {
    await executeAction();
  } else {
    console.log(`Not approved: ${approval.decision_reason}`);
  }
} catch (err) {
  if (err instanceof BlackLakeError && err.code === 'APPROVAL_WAIT_TIMEOUT') {
    console.log('Timed out waiting for approval. Use webhooks for long-running workflows.');
  }
  throw err;
}

bl.webhooks.list(): Promise<{ webhooks: Webhook[] }>

const { webhooks } = await bl.webhooks.list();
const active = webhooks.filter(w => w.enabled);

bl.webhooks.create(data: {
  url: string;
  events: Array<'approval.created' | 'approval.approved' | 'approval.rejected'>;
  enabled?: boolean;  // Default: true
}): Promise<CreatedWebhook>

const wh = await bl.webhooks.create({
  url: 'https://myapp.example/webhooks/blacklake',
  events: ['approval.created', 'approval.approved', 'approval.rejected'],
});

console.log(wh.secret); // save this — not shown again

bl.webhooks.get(id: string): Promise<Webhook>

const wh = await bl.webhooks.get('wh_01j...');
console.log(wh.url, wh.enabled);

bl.webhooks.update(
  id: string,
  data: Partial<{
    url: string;
    events: WebhookEvent[];      // see "Webhook event names" below for the full list
    enabled: boolean;
  }>
): Promise<Webhook>

// Disable a webhook temporarily
const wh = await bl.webhooks.update('wh_01j...', { enabled: false });

bl.webhooks.delete(id: string): Promise<void>

await bl.webhooks.delete('wh_01j...');

bl.webhooks.listDeliveries(
  id: string,
  params?: {
    limit?: number;
    offset?: number;
    sort?: 'delivered_at' | 'status_code' | 'duration_ms';
    order?: 'asc' | 'desc';
  }
): Promise<{
  data: WebhookDelivery[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

const { data, total } = await bl.webhooks.listDeliveries('wh_01j...', { limit: 10 });
for (const d of data) {
  console.log(`${d.event}  status=${d.status_code ?? 'error'}  ${d.delivered_at}`);
}

bl.webhooks.test(id: string): Promise<{
  delivery_id: string;
  status_code: number | null;
  response_body: string | null;
  error: string | null;
  duration_ms: number | null;
  delivered_at: string;
}>

bl.webhooks.resendDelivery(id: string, deliveryId: string): Promise<{
  delivery_id: string;
  replay_of: string;
}>

bl.webhooks.resendFailedDeliveries(id: string): Promise<{
  resent: number;
  deliveries: Array<{ original_id: string; new_id: string }>;
}>

bl.webhooks.rotateSecret(id: string): Promise<{
  id: string;
  secret: string;
  secret_suffix: string;
  warning: string;
}>

bl.webhooks.health(id: string): Promise<{
  webhook_id: string;
  window_size: number;        // up to 100
  success_rate: number;       // 0–1
  last_success_at: string | null;
  dead_letter_count: number;
}>

bl.webhooks.deadLetter(
  id: string,
  params?: { limit?: number; offset?: number }
): Promise<{ data: WebhookDelivery[]; total: number; limit: number; offset: number; sort: string; order: 'asc' | 'desc' }>

import { verifyWebhook } from 'blacklake';

// Express / Hono / Next.js — pass the raw body and the request headers map.
// Throws BlackLakeError (code: WEBHOOK_SIGNATURE_INVALID) on mismatch.
await verifyWebhook({
  secret: process.env.WEBHOOK_SECRET!,
  rawBody,                  // the body bytes as a string, BEFORE any JSON.parse
  headers: req.headers,     // includes x-blacklake-signature + x-blacklake-timestamp
});

import { BlackLake } from 'blacklake';

await BlackLake.verifyWebhookSignature({
  secret: process.env.WEBHOOK_SECRET!,
  rawBody,
  signature: req.headers['x-blacklake-signature'] as string,
  timestamp: req.headers['x-blacklake-timestamp'] as string,
});

bl.apiKeys.list(params?: {
  limit?: number;
  offset?: number;
  sort?: 'created_at' | 'name' | 'revoked_at';
  order?: 'asc' | 'desc';
}): Promise<{
  data: ApiKey[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

interface ApiKey {
  id: string;
  name: string;
  key_suffix: string | null;
  created_at: string;
  revoked_at: string | null;
}

const { data: keys } = await bl.apiKeys.list();
const active = keys.filter(k => !k.revoked_at);

bl.apiKeys.create(name: string): Promise<CreatedApiKey>

interface CreatedApiKey {
  id: string;
  name: string;
  key: string;        // The raw bl_-prefixed key. Shown ONCE.
  created_at: string;
  warning: string;
}

const newKey = await bl.apiKeys.create('production-rotated');
process.env.BLACKLAKE_API_KEY = newKey.key;  // store securely

bl.apiKeys.revoke(id: string): Promise<void>

await bl.apiKeys.revoke('key_01j...');

bl.audit.export(params?: {
  from?: Date | string;
  to?: Date | string;
  kinds?: Array<'evaluation' | 'approval' | 'action_result'>;
  includeArchived?: boolean;
}): Promise<string>

const ndjson = await bl.audit.export({
  from: new Date('2026-04-01'),
  to: new Date('2026-04-30'),
  kinds: ['evaluation', 'action_result'],
});

await fs.writeFile('blacklake-april.ndjson', ndjson);

bl.audit.ingest(event: {
  source: 'gcp' | 'aws' | 'azure' | 'github' | 'other';
  source_event_id?: string;
  event_type?: string;
  resource?: string;
  principal?: string;
  action?: string;
  occurred_at?: string;
  payload?: Record<string, unknown>;
}): Promise<ExternalEvent>

bl.audit.listEvents(params?: {
  source?: string;
  limit?: number;
  offset?: number;
}): Promise<{
  data: ExternalEvent[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

bl.audit.listUncovered(params?: {
  limit?: number;
  offset?: number;
}): Promise<{
  data: ExternalEvent[];
  total: number;
  limit: number;
  offset: number;
  sort: string;
  order: 'asc' | 'desc';
}>

bl.system.mode(): Promise<{ mode: 'local' | 'cloud'; api_key?: string }>

bl.system.health(): Promise<{ status: 'ok' }>

bl.system.me(): Promise<{
  auth_mode: 'session' | 'api_key';
  organisation: { id: string; name: string };
  session: {
    user_id: string;
    user: { id: string; email: string; email_verified_at: string | null; created_at: string };
  } | null;
  api_key: {
    id: string;
    name: string | null;
    key_suffix: string;
    user_id: string | null;
    user: { id: string; email: string } | null;
    created_at: string;
  } | null;
}>

bl.system.quota(): Promise<{
  tier: 'free' | 'team' | 'enterprise';
  status: 'no_subscription' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid';
  quantity: number;
  stripe_customer_id: string | null;
  stripe_subscription_id: string | null;
  stripe_price_id: string | null;
  current_period_start: string | null;
  current_period_end: string | null;
  cancel_at_period_end: boolean;
  canceled_at: string | null;
  trial_end: string | null;
  usage: { used: number; limit: number | null; remaining: number | null; period_key: string };
}>

bl.mcp.list(): Promise<{ servers: Array<{ name: string; connected: boolean; tool_count: number; error?: string | null }> }>

bl.mcp.reconnect(name: string): Promise<{ name: string; connected: boolean; tool_count: number; error?: string | null }>

bl.mcp.rotate(
  upstreamId: string,
  options?: { headers?: Record<string, string> }
): Promise<{ rotation: 'headers_rotated' | 'oauth_reauth_required'; upstream_id: string; authorization_url?: string; upstream?: McpUpstream; message: string }>

bl.mcp.upstreams.list(): Promise<{ upstreams: McpUpstream[] }>
bl.mcp.upstreams.get(id: string): Promise<McpUpstream>
bl.mcp.upstreams.test(id: string): Promise<{ ok: boolean; duration_ms: number; tool_count: number | null; error: string | null }>
bl.mcp.upstreams.health(id: string): Promise<{ is_healthy: boolean; consecutive_failure_count: number; last_status_at: string | null; last_error: string | null; uptime_24h: number; pings: Array<{ ts: string; ok: boolean; duration_ms: number | null }> }>

bl.insights.coverage(): Promise<CoverageInsights>

bl.insights.risk(): Promise<RiskInsights>

bl.insights.healthSnapshot(): Promise<HealthSnapshot>

bl.insights.drift(): Promise<DriftReport>

bl.insights.anomalies(opts?: { includeDismissed?: boolean; limit?: number }): Promise<{ anomalies: ObservationRow[] }>

bl.insights.recomputeAnomalies(windowDays = 7): Promise<{ ok: boolean; detected: number; inserted: number; deduped: number }>

bl.insights.dismissAnomaly(id: string): Promise<void>

bl.insights.observations(opts?: { kind?: string; limit?: number }): Promise<{ observations: ObservationRow[] }>

bl.insights.baselines(windowDays = 30): Promise<unknown>
bl.insights.recomputeBaselines(windowDays = 30): Promise<unknown>

bl.insights.modelChoice(windowDays = 30): Promise<ModelChoiceReport>

bl.insights.modelSubstitution(args: { from: string; to: string; windowDays?: number }): Promise<ModelSubstitutionReport>

bl.insights.coverageTrend(windowDays?: number): Promise<{
  window_days: number;
  series: Array<{ day: string; total: number; by_source: Record<string, number> }>;
}>

bl.insights.explain(evaluationId: string): Promise<{
  evaluation_id: string;
  decision: 'allow' | 'deny' | 'approval_required' | 'default_deny';
  decided_at: string;
  actual_match: { policy_id: string; name: string; outcome: string } | null;
  counterfactual: { would_match: string; name: string; outcome: string; priority: number; note: string } | null;
  policies_considered: Array<{
    policy_id: string; name: string; priority: number; outcome: string;
    enabled: boolean; mode: 'enforce' | 'monitor';
    agent_selector: Record<string, unknown> | null;
    tool_selector: Record<string, unknown> | null;
    agent_match: { matched: boolean; expected?: string; actual?: string };
    tool_match: { matched: boolean; expected?: string; actual?: string };
  }>;
}>

type ActorSource = 'manual' | 'mcp' | 'sdk' | 'ci';

interface Agent {
  id: string;
  organisation_id: string;
  name: string;
  description: string | null;
  environment: 'development' | 'staging' | 'production';
  risk_classification: 'low' | 'medium' | 'high' | 'critical';
  status: 'active' | 'suspended' | 'disabled';
  approval_mode: 'auto_approve' | 'require_approval' | 'block';
  owner: string | null;
  source: ActorSource;
  last_seen_at: string | null;
  created_at: string;
  updated_at: string;
}

interface Tool {
  id: string;
  organisation_id: string;
  name: string;
  description: string | null;
  risk_classification: 'low' | 'medium' | 'high' | 'critical';
  owner: string | null;
  source: ActorSource;
  last_seen_at: string | null;
  created_at: string;
}

interface Policy {
  id: string;
  organisation_id: string;
  name: string;
  priority: number;
  agent_selector: Record<string, unknown>;
  tool_selector: Record<string, unknown>;
  outcome: 'allow' | 'deny' | 'approval_required';
  enabled: boolean;
  requires_two_person: boolean;
  /** When non-empty, a session-authed approver must hold at least one
   *  matching role in their workspace membership. */
  approver_roles: string[] | null;
  created_at: string;
  updated_at: string;
}

type PolicySnapshot = Omit<Policy, 'organisation_id'>;

interface Evaluation {
  id: string;
  organisation_id: string;
  agent_id: string;
  tool_id: string;
  policy_id: string | null;
  policy_name: string | null;
  policy_priority: number | null;
  policy_snapshot: PolicySnapshot | null;
  action_payload: Record<string, unknown> | null;
  decision: 'allow' | 'deny' | 'approval_required' | 'default_deny';
  outcome: 'allow' | 'deny' | 'approval_required' | 'default_deny';
  evaluated_at: string;
  request_context: Record<string, unknown> | null;
}

type ActionResultStatus = 'succeeded' | 'failed' | 'skipped' | 'unknown';

interface ActionResult {
  id: string;
  organisation_id: string;
  evaluation_id: string;
  status: ActionResultStatus;
  external_system: string | null;
  external_id: string | null;
  external_url: string | null;
  duration_ms: number | null;
  exit_code: number | null;
  output_digest: string | null;
  error: string | null;
  metadata: Record<string, unknown> | null;
  recorded_at: string;
}

interface CreateActionResultRequest {
  status: ActionResultStatus;
  external_system?: string;
  external_id?: string;
  external_url?: string;
  duration_ms?: number;
  exit_code?: number;
  output_digest?: string;
  error?: string;
  metadata?: Record<string, unknown>;
}

type VerifyDecisionResult =
  | {
      valid: true;
      evaluation_id: string;
      decision: 'allow' | 'deny' | 'approval_required' | 'default_deny';
      agent_id: string;
      tool_id: string;
      policy_id: string | null;
      policy_name: string | null;
      policy_priority: number | null;
      policy_snapshot: PolicySnapshot | null;
      action_results: ActionResult[];
      evaluated_at: string;
    }
  | {
      valid: false;
      reason: 'evaluation_not_found' | 'malformed' | 'signature_mismatch';
    };

interface PaginatedResponse<T> {
  data: T[];
  total: number;
}

interface Organisation {
  id: string;
  name: string;
  contact_email: string | null;
  created_at: string;
}

interface ToolBinding {
  binding_id: string;
  binding_created_at: string;
  tool: Tool;
}

interface ApiKey {
  id: string;
  name: string;
  key_suffix: string | null;
  created_at: string;
  revoked_at: string | null;
}

interface CreatedApiKey {
  id: string;
  name: string;
  key: string;
  created_at: string;
  warning: string;
}

type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';

interface ApprovalDecisionRecord {
  decided_by: string;
  action: 'approve' | 'reject' | 'break-glass';
  reason: string;
  decided_at: string;
}

interface Approval {
  id: string;
  organisation_id: string;
  evaluation_id: string;
  agent_id: string;
  tool_id: string;
  policy_id: string | null;
  action_payload: Record<string, unknown> | null;
  request_context: Record<string, unknown> | null;
  status: ApprovalStatus;
  decided_by: string | null;
  decision_reason: string | null;
  decided_at: string | null;
  requires_two_person: boolean;
  decisions: ApprovalDecisionRecord[] | null;
  break_glass: boolean;
  created_at: string;
  expires_at: string;
}

interface ApprovalStatusResponse {
  status: ApprovalStatus;
  decided_at: string | null;
  expires_at: string;
}

type WebhookEvent = 'approval.created' | 'approval.approved' | 'approval.rejected';

interface Webhook {
  id: string;
  organisation_id: string;
  url: string;
  secret_suffix: string | null;
  events: WebhookEvent[];
  enabled: boolean;
  created_at: string;
}

interface CreatedWebhook {
  id: string;
  url: string;
  secret: string;        // Raw signing secret. Shown ONCE.
  secret_suffix: string;
  events: WebhookEvent[];
  enabled: boolean;
  created_at: string;
  warning: string;
}

interface WebhookDelivery {
  id: string;
  webhook_id: string;
  event: WebhookEvent;
  payload: Record<string, unknown>;
  status_code: number | null;     // null on network error
  response_body: string | null;   // truncated to 500 chars
  error: string | null;           // network/timeout error message
  delivered_at: string;
  duration_ms: number | null;
}

type CostProvider =
  | 'anthropic'
  | 'openai'
  | 'bedrock'
  | 'vertex'
  | 'foundry'
  | 'gemini'
  | 'ollama'
  | 'unknown';

type CapturePath = 'proxy' | 'sdk' | 'mcp' | 'ci' | 'manual';

interface CostBreakdown {
  pricing_version: string;
  input_usd: number;
  output_usd: number;
  cache_read_usd: number;
  cache_write_usd: number;
  thinking_usd: number;
  total_usd: number;
  rates: {
    input_per_1m: number;
    output_per_1m: number;
    cache_read_per_1m: number;
    cache_write_per_1m: number;
    thinking_per_1m: number;
  };
}

interface CostRecord {
  id: string;
  organisation_id: string;
  evaluation_id: string | null;
  provider: CostProvider;
  model: string;
  input_tokens: number;
  output_tokens: number;
  cache_read_tokens: number;
  cache_write_tokens: number;
  thinking_tokens: number;
  cost_usd: number;
  pricing_version: string;
  capture_path: CapturePath;
  created_at: string | null;
}

interface CostRecordIngest {
  evaluation_id?: string;
  agent?: string;
  agent_id?: string;
  tool?: string;
  tool_id?: string;
  user_id?: string;
  provider: CostProvider;
  model: string;
  input_tokens: number;
  output_tokens: number;
  cache_read_tokens?: number;
  cache_write_tokens?: number;
  thinking_tokens?: number;
  duration_ms?: number;
  capture_path?: CapturePath;
  environment?: string;
  session_id?: string;
  task_id?: string;
  pricing_version?: string;
}

interface CostEstimateRequest {
  provider: CostProvider;
  model: string;
  input_tokens: number;
  output_ceiling_tokens: number;
  pricing_version?: string;
}

interface CostByEvaluation {
  evaluation_id: string;
  receipt_version: number;
  summary: {
    total_usd: number;
    input_tokens: number;
    output_tokens: number;
    cache_read_tokens: number;
    cache_write_tokens: number;
    thinking_tokens: number;
    pricing_version: string;
    record_count: number;
  } | null;
  records: CostRecord[];
  /** v2 decision token (binds cost). null until cost has been captured. */
  decision_token_v2: string | null;
}

type BudgetScope = 'workspace' | 'agent' | 'tool' | 'user';
type BudgetPeriod = 'per_task' | 'day' | 'week' | 'month';

interface Budget {
  id: string;
  organisation_id: string;
  name: string;
  scope_type: BudgetScope;
  scope_id: string | null;
  period: BudgetPeriod;
  timezone: string;
  soft_limit_usd: number | null;
  hard_limit_usd: number;
  enabled: boolean;
  created_at: string | null;
  updated_at: string | null;
}

interface BudgetCreate {
  name: string;
  scope_type: BudgetScope;
  scope_id?: string;
  period: BudgetPeriod;
  timezone?: string;
  soft_limit_usd?: number;
  hard_limit_usd: number;
  enabled?: boolean;
}

interface BudgetStatus {
  budget_id: string;
  period_key: string;
  spend_usd: number;
  soft_limit_usd: number | null;
  hard_limit_usd: number;
  soft_pct: number | null;
  hard_pct: number;
  state: 'ok' | 'soft_50' | 'soft_80' | 'over_soft' | 'over_hard';
}

class BlackLakeError extends Error {
  readonly status: number;  // HTTP status code
  readonly code: string;    // Machine-readable error code
  readonly message: string; // Human-readable explanation
}

import { BlackLake, BlackLakeError } from 'blacklake';

try {
  await bl.agents.get('agent_does_not_exist');
} catch (err) {
  if (err instanceof BlackLakeError) {
    console.error(`[${err.status}] ${err.code}: ${err.message}`);
    // [404] AGENT_NOT_FOUND: Agent agent_does_not_exist not found
  } else {
    throw err;
  }
}