Diaphora TypeScript SDK

TypeScript client library for the Diaphora API.

Supported Node.js versions: 20.x, 22.x

Installation

npm install diaphora-typescript

Authentication

The Diaphora client needs your Diaphora credentials. You can either pass these directly to the constructor or via environment variables.

import { BasicAuthenticator } from 'diaphora-typescript';

const auth = new BasicAuthenticator('user@example.com', 'your-password');

Credentials can also be provided via environment variables:

DIAPHORA_USERNAME=user@example.com
DIAPHORA_PASSWORD=your-password

To use a custom auth scheme, extend DiaphoraAuthenticator:

import { DiaphoraAuthenticator } from 'diaphora-typescript';

class MyAuthenticator extends DiaphoraAuthenticator {
  token(): string | Promise<string> {
    return 'my-session-token';
  }
}

Setup

import { FragsStoreClient, FragsRouterClient } from 'diaphora-typescript';

const store = new FragsStoreClient(auth);
const router = new FragsRouterClient(auth);

Quickstart

Search for plans

// namespace is one of: 'all' | 'diaphora' | 'barndoor' | 'none'
const plans = await store.searchPlans(undefined, undefined, 'diaphora');

Show a plan

const plan = await store.showPlan(plans[0]?.id);
console.log(plan.name, plan.description);

Create a plan

const newPlan = await store.createPlan({
  name: 'Daily Summary',
  description: 'Summarizes activity from the past 24 hours',
  visibility: 'organization',
  labels: ['summary', 'daily'],
  text: '<plan definition>',
});

Search results for a plan

const results = await store.searchResults(plan.id, undefined, 'success');

Run a plan

const response = await router.runPlan(plan.id, {
  parameters: { animal_type: 'feline' },
});

Stream a plan execution

import type { StreamEvent } from 'diaphora-typescript';

await router.streamPlan(
  plan.id,
  { parameters: { animal_type: 'feline' } },
  (event: StreamEvent) => {
    if (event.event === 'start') {
      console.log(`[${event.component}] starting...`);
    } else if (event.event === 'end') {
      console.log(`[${event.component}] done`);
    } else if (event.event === 'result') {
      const content = event.content as Record<string, unknown>;
      console.log(content.document);
    }
  }
);

store (FragsStoreClient)

Plans

searchPlans

Search plans visible to the authenticated user, with optional filtering and sorting.

Parameters

Example

const plans = await store.searchPlans(['daily'], 'summary', 'diaphora', 10, 0, 'created_at', 'DESC');

showPlan

Get full details for a single plan, including its text and parameter definitions.

Parameters

Example

const plan = await store.showPlan('plan-uuid');
console.log(plan.name, plan.text);

createPlan

Create a new plan.

Parameters

Example

const plan = await store.createPlan({
  name: 'Daily Summary',
  description: 'Summarises activity from the past 24 hours',
  visibility: 'organization',
  labels: ['summary', 'daily'],
  text: '<plan definition>',
});

updatePlan

Replace all fields of an existing plan.

Parameters

Example

await store.updatePlan('plan-uuid', {
  name: 'Updated Summary',
  description: 'Now covers the past 48 hours',
  visibility: 'organization',
  labels: ['summary', 'daily'],
  text: '<updated plan definition>',
});

deletePlan

Delete a plan by ID. Returns void.

Parameters

Example

await store.deletePlan('plan-uuid');

listPlanLabels

List all unique labels used across plans in the organization.

Example

const labels = await store.listPlanLabels();
console.log(labels); // ['daily', 'summary', 'report']

Results

searchResults

Search execution results, optionally filtering by plan, status, or date range.

Parameters

Example

const results = await store.searchResults(
  plan.id,
  undefined,
  'success',
  20,
  0,
  new Date('2025-01-01'),
  new Date('2025-02-01'),
);

showResults

Get full details for a single result, including the execution data.

Parameters

Example

const result = await store.showResults('result-uuid');
console.log(result.data.document);

createResults

Store a result record manually, useful for persisting results generated outside the router.

Parameters

Example

const result = await store.createResults({
  plan_id: 'plan-uuid',
  plan_name: 'Daily Summary',
  data: {
    result: {},
    document: 'Generated output here',
    warnings: [],
  },
});

deleteResults

Delete a result by ID. Returns void.

Parameters

Example

await store.deleteResults('result-uuid');

listResultStats

Get per-result statistics, optionally filtered to a date range.

Parameters

Example

const stats = await store.listResultStats(
  new Date('2025-01-01'),
  new Date('2025-02-01'),
);

Public Links

listPublicLinks

List all public share links for a result.

Parameters

Example

const links = await store.listPublicLinks('result-uuid');

createPublicLink

Create a public share link for a result with an expiry duration and a display label.

Parameters

Example

const link = await store.createPublicLink('result-uuid', {
  expires_in: '7d',
  label: 'Share with client',
});
console.log(link.id, link.expires_at);

deletePublicLink

Revoke a public link. Returns void.

Parameters

Example

await store.deletePublicLink('result-uuid', 'link-uuid');

showResultPublicLink

Fetch result details via a public link — no authentication required.

Parameters

Example

const result = await store.showResultPublicLink('link-uuid');
console.log(result.data.document);

Tools & Schema

listTools

List all tool configurations available to the organization.

Example

const tools = await store.listTools();

showTool

Get full details of a tool configuration. Facet parameters filter which MCP servers, collections, and API CPs are returned.

Parameters

Example

const tool = await store.showTool('tool-uuid');
console.log(tool.mcp_servers);

showDefaultTools

Get the default tool configuration. Facet parameters work the same as showTool.

Parameters

Example

const defaults = await store.showDefaultTools();

createTool

Create a new tool configuration.

Parameters

Example

const tool = await store.createTool({
  name: 'My Tool',
  default: false,
  mcp_servers: [],
  collections: [],
  api_cps: [],
});

updateTool

Replace all fields of an existing tool configuration.

Parameters

Example

await store.updateTool('tool-uuid', {
  name: 'Updated Tool',
  default: true,
  mcp_servers: [],
  collections: [],
  api_cps: [],
});

showMcpServerDetails

Get the configuration for a specific MCP server within a tool.

Parameters

Example

const server = await store.showMcpServerDetails('tool-uuid', 'server-uuid');
console.log(server.url, server.authentication_method);

showApiCPServerDetails

Get the configuration for a specific API CP server within a tool.

Parameters

Example

const server = await store.showApiCPServerDetails('tool-uuid', 'server-uuid');

getFragsSchema

Fetch the Frags JSON schema used to validate plan definitions.

Example

const schema = await store.getFragsSchema();

getFragsSkill

Fetch the Frags skill definition as a markdown string, suitable for use as an LLM system prompt.

Example

const skill = await store.getFragsSkill();

router (FragsRouterClient)

Plan Execution

streamPlan delivers StreamEvent objects to the callback:

runPlan

Execute a plan synchronously and return the result once complete.

Parameters

Example

const result = await router.runPlan('plan-uuid', {
  parameters: { animal_type: 'feline' },
});
console.log(result.document);

streamPlan

Execute a plan and receive StreamEvent objects via a callback as each component starts and finishes. Returns the final result content once the stream closes, or undefined if the stream ends without a result event.

Parameters

Unlike runPlan, the returned promise can resolve to undefined (the stream may end without ever emitting a result event) — always guard with ?. or a null check.

Example

import type { StreamEvent } from 'diaphora-typescript';

const result = await router.streamPlan(
  'plan-uuid',
  { parameters: { animal_type: 'feline' } },
  (event: StreamEvent) => {
    if (event.event === 'start') {
      console.log(`[${event.component}] starting...`);
    } else if (event.event === 'result') {
      const content = event.content as Record<string, unknown>;
      console.log(content.document);
    }
  },
);
console.log(result?.document);

MCP Tools

checkPlanMcpRequirements

Check which MCP and API CP servers a plan requires and whether they are currently authenticated.

Parameters

Example

const requirements = await router.checkPlanMcpRequirements('plan-uuid');
for (const req of requirements) {
  console.log(req.name, req.status); // 'ready' or 'not_ready'
}

refreshPlanMcpRequirements

Force-refresh the MCP requirement status for a plan, clearing any cached auth state.

Parameters

Example

await router.refreshPlanMcpRequirements('plan-uuid');

checkToolMcpRequirements

Check the MCP and API CP authentication status across all tool configurations globally.

Example

const requirements = await router.checkToolMcpRequirements();

listToolCommands

List all available commands on a specific MCP server within a tool configuration.

Parameters

Example

const commands = await router.listToolCommands('tool-uuid', 'server-uuid');
for (const cmd of commands) {
  console.log(cmd.name, cmd.description);
}

callToolCommand

Execute a named command on an MCP server and return the result.

Parameters

Example

const result = await router.callToolCommand(
  'tool-uuid',
  'server-uuid',
  'list_issues',
  { repo: 'my-org/my-repo' },
);

listMcpAuthCache

List currently cached MCP OAuth tokens.

Example

const cache = await router.listMcpAuthCache();
for (const entry of cache) {
  console.log(entry.id, entry.expiry);
}

deleteMcpAuthCache

Revoke a cached MCP OAuth token. Returns void.

Parameters

Example

await router.deleteMcpAuthCache('cache-id');

mcpCallback

Handle the OAuth redirect callback after a user completes MCP authentication in their browser. Called automatically by the OAuth flow — you typically do not need to call this directly.

Parameters

Example

await router.mcpCallback(stateParam, codeParam);

renderTemplate

Render a Go template string with a provided scope object and return the result as a string.

Parameters

Example

const output = await router.renderTemplate({
  template: 'Hello {{ .name }}!',
  scope: { name: 'World' },
});
console.log(output); // 'Hello World!'