Metalogue
Docs

TypeScript SDK

Full reference for the Metalogue TypeScript/Node.js SDK.

TypeScript SDK

Official TypeScript/Node.js SDK for the Metalogue API.

Installation

npm install @metalogue/sdk
# or
yarn add @metalogue/sdk
# or
pnpm add @metalogue/sdk

Quick Start

import { MetalogueClient } from '@metalogue/sdk';

const client = new MetalogueClient({
  apiKey: process.env.METALOGUE_API_KEY!,
});

// Federated query
const { results } = await client.query('What was the auth decision?');

for (const result of results) {
  console.log(`[${result.source}] ${result.content}`);
}

Configuration

interface MetalogueConfig {
  apiKey: string;       // Required: API key (mlo_xxx)
  baseUrl?: string;     // Default: https://api.metalogue.xyz
  timeout?: number;     // Default: 30000ms
}

const client = new MetalogueClient({
  apiKey: 'mlo_xxxxxxxxxxxx',
  baseUrl: 'https://api.metalogue.xyz',
  timeout: 30000,
});

Methods

Query

const response = await client.query(
  'What was the decision on auth architecture?',
  {
    limit: 10,
    includeReasoning: true,
    sources: ['slack', 'notion'],
    filters: {
      dateRange: { after: '2026-01-01', before: '2026-01-31' },
      authors: ['alice@example.com'],
      types: ['message', 'document'],
    },
  }
);

// Response types
interface QueryResponse {
  results: QueryResult[];
  reasoning?: string;
  queryId: string;
  latencyMs: number;
}

interface QueryResult {
  id: string;
  content: string;
  source: string;
  sourceType: string;
  score: number;
  metadata: Record<string, any>;
  url?: string;
}

Connectors

// List all connectors
const connectors = await client.listConnectors();

// Get specific connector
const connector = await client.getConnector('slack-123');

// Create connector
const newConnector = await client.createConnector({
  connector_type: 'slack',
  display_name: 'Company Slack',
  credentials: { token: 'xoxb-...' },
  settings: { channels: ['general'] },
});

// Sync connector
await client.syncConnector('slack-123', true); // full sync

// Execute agentic action
await client.executeAction('slack-123', {
  intent: 'Send message to #general',
  context: { priority: 'high' },
  dryRun: false,
});

// Delete connector
await client.deleteConnector('slack-123');

Audit Logs

// Get audit logs
const logs = await client.getAuditLogs({
  limit: 100,
  action: 'query.executed',
  start: '2026-01-01T00:00:00Z',
  end: '2026-01-31T23:59:59Z',
});

// Export SOC2 report
const report = await client.exportSOC2({
  startDate: '2026-01-01',
  endDate: '2026-01-31',
});

Usage & Billing

// Get usage metrics
const usage = await client.getUsage('month');

// Get subscription
const subscription = await client.getSubscription();

Users

// List users
const users = await client.listUsers();

// Invite user
await client.inviteUser('bob@example.com', 'member');

Error Handling

import { 
  MetalogueError, 
  AuthenticationError, 
  RateLimitError,
  NotFoundError,
} from '@metalogue/sdk';

try {
  await client.query('...');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.log('Resource not found');
  } else if (error instanceof MetalogueError) {
    console.log(`API error: ${error.message}`);
  }
}

TypeScript Types

All types are exported for use in your application:

import type {
  MetalogueConfig,
  QueryOptions,
  QueryResult,
  QueryResponse,
  Connector,
  CreateConnectorRequest,
  SyncResponse,
  AuditLogEntry,
  AuditOptions,
  UsageMetrics,
} from '@metalogue/sdk';

Next Steps