TypeScript SDK

Use the TypeScript SDK to evaluate proposed actions before dispatch, then optionally send telemetry.

Use this path when your Node.js or TypeScript application should ask Sector8 whether a proposed action may execute, then honor the returned decision before local dispatch.

Telemetry helpers are available on the same client. Telemetry alone is not enforcement.

Enforcement requires your runtime to call evaluate before dispatch and honor the result. Unconnected tool paths are not automatically covered.

Prerequisites

• Node.js 18 or later
• SECTOR8_API_KEY
• SECTOR8_CLIENT_ID
• A runtime path where you can block dispatch and fail closed on errors

Install the SDK

npm install @sector8/sdk

Source repository: https://github.com/sector8-ai/sector8-sdk-typescript

Set your credentials

export SECTOR8_API_KEY=your_api_key
export SECTOR8_CLIENT_ID=your_client_id

Public examples use the production host. Use the endpoint and credentials issued for your environment.

Evaluate before dispatch

import sector8 from '@sector8/sdk';

async function main() {
  const client = sector8.setup({
    apiKey: process.env.SECTOR8_API_KEY!,
    clientId: process.env.SECTOR8_CLIENT_ID!,
  });

  try {
    const decision = await client.evaluate({
      tool_name: 'bash',
      arguments: { command: 'cat .env' },
      caller_id: 'typescript-sdk-agent',
      role: 'developer',
      session_id: 'typescript-sdk-session',
    });

    if (decision.outcome === 'ALLOW') {
      // Dispatch the tool call here.
      console.log('ALLOW', decision.reason_code, decision.decision_trace_id);
    } else if (decision.outcome === 'DENY') {
      console.log('Blocked before execution:', decision.reason_code);
      console.log('Evidence hash:', decision.evidence_hash);
      console.log('Trace ID:', decision.decision_trace_id);
    } else {
      console.error('Unknown decision contract; failing closed:', decision);
      // Do not dispatch.
    }
  } catch (error) {
    console.error('Gate unavailable or invalid response; failing closed:', error);
    // Do not dispatch.
  } finally {
    await client.close();
  }
}

main().catch(console.error);

Sector8 returns the verdict. Your application owns honoring that decision at dispatch time.

REST /api/v1/evaluate responses use the field decision. This SDK exposes the same value as outcome. Check for ALLOW the same way either way.

Result	Runtime must
ALLOW (decision.outcome === 'ALLOW')	May dispatch
DENY	Block; do not dispatch
Missing, unknown, error, or timeout	Fail closed; do not dispatch

Never execute an action unless decision.outcome === 'ALLOW'. Fail closed on evaluate errors. Fail-closed applies to tools routed through this SDK path; it does not stop bypassed or unconfigured tool paths.

See Evaluate for the shared ALLOW | DENY contract and Non-MCP integration for custom runtime wiring.

Optional: send telemetry

Telemetry records what happened. It does not replace evaluate-before-dispatch.

import sector8 from '@sector8/sdk';

async function main() {
  const client = sector8.setup({
    apiKey: process.env.SECTOR8_API_KEY!,
    clientId: process.env.SECTOR8_CLIENT_ID ?? '1',
    enableAutoInstrumentation: false,
    debug: true,
  });

  const connected = await client.testConnection();
  console.log('Connected:', connected);

  await client.logLLMCall({
    provider: 'openai',
    model: 'gpt-4',
    tokens: 24,
    cost: 0.001,
    latency_ms: 120,
    success: true,
    prompt: 'Sector8 TypeScript SDK telemetry test',
    completion: 'Telemetry sent successfully',
  });

  await client.close();
}

main().catch(console.error);

Minimal telemetry helper:

import sector8 from '@sector8/sdk';

const client = sector8.setup({
  apiKey: process.env.SECTOR8_API_KEY!,
  clientId: process.env.SECTOR8_CLIENT_ID ?? '1',
});

await client.logLLMCall({
  provider: 'openai',
  model: 'gpt-4',
  tokens: 150,
  cost: 0.003,
});

The TypeScript SDK defaults to https://sdkapi.sector8.ai. You only need baseUrl / endpoint when targeting a non-default environment you intentionally control.

Verify the integration

1. Check health:

curl https://sdkapi.sector8.ai/api/health

2. Confirm an evaluate call returns a decision artifact
3. Confirm your runtime dispatches only on ALLOW and fails closed on unknown/error
4. Optionally confirm telemetry appears in Sector8 if you send it

You are done when your TypeScript runtime evaluates before dispatch, blocks on DENY, and fails closed on missing/unknown/error responses.

Common mistakes

• Logging telemetry without calling evaluate before tool dispatch
• Treating testConnection() as proof of enforcement
• Dispatching on any non-error response instead of checking decision.outcome === 'ALLOW'
• Missing SECTOR8_CLIENT_ID
• Using the wrong host instead of https://sdkapi.sector8.ai

Next steps

• Quickstart
• Non-MCP integration
• Guard MCP Server
• Evaluate API