Node.js Integration Guide

# ON-DEVICE — the decision is made in your process.
# Exports the Tork class. govern() is synchronous.
npm install tork-governance

# CLOUD — Tork makes the decision server-side and writes a
# receipt to your dashboard. Exports TorkClient.
npm install @torknetwork/sdk

# The REST examples below need no SDK at all (fetch is built in).
npm install axios  # optional, only for the axios example

Supply an API key and the SDK additionally reports a metadata-only attestation of each decision — the action taken, PII type labels and counts, a risk classification, policy labels and a salted fingerprint. It never sends input text, output text or PII values. The decision itself is still made on-device and is never delayed or changed by reporting. Those attestations appear in your dashboard and are included in the daily on-chain anchor — each one recorded as a client attestation (capture_mode=edge, attested_by=client), a claim Tork recorded but did not execute and cannot independently verify. Requires tork-governance 0.24.0+ (PyPI) or 0.11.0+ (npm).

A decision reported by an on-device SDK is recorded as a client attestation (capture_mode=edge, attested_by=client): a claim Tork recorded but did not execute and cannot independently verify. A decision made by @torknetwork/sdk is recorded as capture_mode=cloud, attested_by=tork — Tork made that call itself. Both are equally immutable once anchored; they differ in what is immutable. A client attestation freezes your claim. A server-governed receipt freezes Tork's own decision.

# .env
# Used by the REST examples below. The on-device package does not
# require an API key, and the published builds never send one.
TORK_API_KEY=tork_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Never commit your API key to version control. Add .env to your .gitignore.

// tork.js - Reusable REST wrapper (server-governed path)
const TORK_API_URL = 'https://tork.network/api/v1';

export async function governContent(content, options = {}) {
  const { mode = 'redact' } = options;

  const response = await fetch(`${TORK_API_URL}/govern`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TORK_API_KEY}`
    },
    body: JSON.stringify({ content, options: { mode } })
  });

  if (!response.ok) {
    throw new Error(`Tork API error: ${response.status}`);
  }

  return response.json();
}

// Usage — returns { action, output, receipt_id, ... }
const result = await governContent(userInput);

async function safeGovern(content) {
  try {
    const response = await fetch('https://tork.network/api/v1/govern', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.TORK_API_KEY}`
      },
      body: JSON.stringify({ content, options: { mode: 'redact' } })
    });

    // Handle HTTP errors
    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Invalid API key');
      }
      if (response.status === 429) {
        throw new Error('Rate limit exceeded. Please retry later.');
      }
      throw new Error(`API error: ${response.status}`);
    }

    return await response.json();

  } catch (error) {
    // Network errors, timeouts, etc.
    if (error.name === 'AbortError') {
      throw new Error('Request timed out');
    }
    throw error;
  }
}

// With timeout
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);

try {
  const response = await fetch(url, { signal: controller.signal });
  // ...
} finally {
  clearTimeout(timeout);
}

Common Error Codes

// middleware/torkGuard.js
import { Tork } from 'tork-governance';

// On-device: construct once and share. No client to close, and no
// network call in the request path.
const tork = new Tork();

export function torkGuard(options = {}) {
  const { blockDenied = true, logOnly = false } = options;

  return (req, res, next) => {
    // Skip if there is no body to govern
    if (!req.body?.message && !req.body?.content) {
      return next();
    }

    const content = req.body.message || req.body.content;

    try {
      // Synchronous — no await.
      const result = tork.govern(content);

      // Attach the governed result for downstream handlers
      req.torkResult = result;

      if (result.action !== 'allow') {
        console.warn('Governance action taken:', {
          action: result.action,
          piiTypes: result.pii.types,
          receiptId: result.receipt.receiptId
        });

        if (result.action === 'deny' && blockDenied && !logOnly) {
          return res.status(400).json({
            error: 'Content blocked by policy',
            receiptId: result.receipt.receiptId
          });
        }
      }

      next();

    } catch (error) {
      // Your own error-handling policy: decide whether a failure in
      // YOUR governance call lets the request through or blocks it.
      console.error('Governance call threw:', error);
      if (options.failClosed) {
        return res.status(503).json({ error: 'Governance check failed' });
      }
      next();
    }
  };
}

import express from 'express';
import { Tork } from 'tork-governance';
import { torkGuard } from './middleware/torkGuard.js';

const tork = new Tork();
const app = express();
app.use(express.json());

// Apply Tork guard to all AI-related routes
app.use('/api/chat', torkGuard({ context: 'chatbot' }));
app.use('/api/generate', torkGuard({ context: 'content-generation' }));

// Chat endpoint with Tork protection
app.post('/api/chat', async (req, res) => {
  const { conversationId } = req.body;

  // Content already governed by middleware.
  // req.torkResult holds the full GovernanceResult.
  const governed = req.torkResult;

  try {
    // Send the REDACTED text to your model, not the raw message.
    const aiResponse = await generateAIResponse(governed.output, conversationId);

    // Govern the model's output on the way back out too.
    const outputResult = tork.govern(aiResponse);

    res.json({
      response: outputResult.output,
      filtered: outputResult.action !== 'allow'
    });

  } catch (error) {
    res.status(500).json({ error: 'Failed to generate response' });
  }
});

app.listen(3000, () => {
  console.log('Server running with Tork protection');
});

// The on-device package ships its own types — import them directly.
import {
  Tork,
  type GovernanceResult,
  type GovernanceAction,
  type PIIDetectionResult,
} from 'tork-governance';

const tork = new Tork();

// govern() is synchronous: GovernanceResult, not Promise<GovernanceResult>.
const result: GovernanceResult = tork.govern('john@example.com');

const action: GovernanceAction = result.action;   // 'allow'|'deny'|'redact'|'escalate'
const pii: PIIDetectionResult = result.pii;       // { hasPII, types, count, matches, redactedText }
const receiptId: string = result.receipt.receiptId;

// --- REST path (server-governed) types you write yourself ---
interface TorkGovernRequest {
  content: string;
  options?: { mode?: 'detect' | 'redact' | 'deny' };
}

interface TorkGovernResponse {
  action: 'allow' | 'redact' | 'deny';
  output: string;
  receipt_id: string;
  latency_ms: number;
  pii_detected?: Array<{ type: string; count: number }>;
}

async function governContent(
  request: TorkGovernRequest
): Promise<TorkGovernResponse> {
  const response = await fetch('https://tork.network/api/v1/govern', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.TORK_API_KEY}`
    },
    body: JSON.stringify(request)
  });

  if (!response.ok) {
    throw new Error(`Tork API error: ${response.status}`);
  }

  return response.json();
}

import { Tork } from 'tork-governance';

// ON-DEVICE: no network, no rate limit, nothing to batch around.
// A plain synchronous loop is the fastest correct answer.
const tork = new Tork();

const messages = [
  'Hello, how are you?',
  'My email is john@example.com',
  'Card 4111 1111 1111 1111',
];

const results = messages.map(content => tork.govern(content));
const flagged = results.filter(r => r.action !== 'allow');

console.log(`${flagged.length} of ${results.length} were redacted or denied`);

// ---------------------------------------------------------------
// CLOUD/REST: here batching and pacing DO matter, because each
// item is a metered HTTP round-trip subject to rate limits.
async function governBatchViaRest(items, { concurrency = 5, delayMs = 100 } = {}) {
  const out = [];

  for (let i = 0; i < items.length; i += concurrency) {
    const batch = items.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map(item =>
        governContent(item.content).catch(err => ({ error: err.message, item }))
      )
    );

    out.push(...batchResults);

    if (i + concurrency < items.length) {
      await new Promise(r => setTimeout(r, delayMs));
    }
  }

  return out;
}