SDK API

API reference for TrikHub gateway SDKs.

Installation


npm install @trikhub/gateway

TrikGateway

Main class for loading and executing triks.

Constructor


import { TrikGateway } from '@trikhub/gateway';
 
const gateway = new TrikGateway(config?: TrikGatewayConfig);

TrikGatewayConfig:


interface TrikGatewayConfig {
  sessionStorage?: SessionStorage;
}

Methods

load_triks_from_config / loadTriksFromConfig

Load triks from .trikhub/config.json.


async loadTriksFromConfig(options?: LoadFromConfigOptions): Promise<TrikManifest[]>

Options:


interface LoadFromConfigOptions {
  configPath?: string;  // Default: '.trikhub/config.json'
  baseDir?: string;     // Default: directory of config file
}

Example:


const manifests = await gateway.loadTriksFromConfig();
console.log(`Loaded ${manifests.length} triks`);

load_trik / loadTrik

Load a trik from a directory path.


async loadTrik(path: string): Promise<TrikManifest>

Example:


const manifest = await gateway.loadTrik('./my-trik');

execute

Execute a trik action.


async execute<T = unknown>(
  trikId: string,
  action: string,
  input: Record<string, unknown>,
  options?: ExecuteTrikOptions
): Promise<GatewayResultWithSession<T>>

Options:


interface ExecuteTrikOptions {
  sessionId?: string;
}

Example:


const result = await gateway.execute(
  'demo/article-search',
  'search',
  { topic: 'AI' },
  { sessionId: 'sess_123' }
);

get_tool_definitions / getToolDefinitions

Get tool definitions for agent integration.


getToolDefinitions(options?: GetToolDefinitionsOptions): ToolDefinition[]

ToolDefinition:


interface ToolDefinition {
  name: string;           // e.g., 'demo/article-search:search'
  description: string;
  inputSchema: JSONSchema;
  responseMode: 'template' | 'passthrough';
}

deliver_content / deliverContent

Retrieve passthrough content by reference.


deliverContent(ref: string): PassthroughDelivery | null

PassthroughDelivery:


interface PassthroughDelivery {
  content: PassthroughContent;
  receipt: PassthroughDeliveryReceipt;
}

Result Types

GatewayResult

Union type for all possible results:


type GatewayResult =
  | GatewaySuccessTemplate
  | GatewaySuccessPassthrough
  | GatewayError
  | GatewayClarification;

GatewaySuccessTemplate


interface GatewaySuccessTemplate {
  success: true;
  responseMode: 'template';
  agentData: Record<string, unknown>;
  templateText?: string;
}

GatewaySuccessPassthrough


interface GatewaySuccessPassthrough {
  success: true;
  responseMode: 'passthrough';
  userContentRef: string;
}

GatewayError


interface GatewayError {
  success: false;
  error: string;
  code?: string;
}

Passthrough Types

PassthroughContent


interface PassthroughContent {
  contentType: string;
  content: string;
  metadata?: Record<string, unknown>;
}

Session Types

SessionStorage

Interface for custom session storage:


interface SessionStorage {
  get(sessionId: string): Promise<unknown | null>;
  set(sessionId: string, data: unknown, ttlMs: number): Promise<void>;
  delete(sessionId: string): Promise<void>;
}

SessionHistoryEntry


interface SessionHistoryEntry {
  action: string;
  input: unknown;
  agentData?: unknown;
  userContent?: {
    contentType: string;
    content: string;
    metadata?: Record<string, unknown>;
  };
}

LangChain Integration

Import from @trikhub/gateway/langchain:

loadLangChainTriks

Simplified function to load triks as LangChain tools.


async function loadLangChainTriks(
  options?: LoadLangChainTriksOptions
): Promise<LangChainTriksResult>

Options:


interface LoadLangChainTriksOptions {
  onPassthrough?: (content: PassthroughContent) => void;
  debug?: boolean;
  configPath?: string;
  baseDir?: string;
}

Result:


interface LangChainTriksResult {
  tools: DynamicStructuredTool[];
  gateway: TrikGateway;
  loadedTriks: string[];
}

Example:


import { loadLangChainTriks } from '@trikhub/gateway/langchain';
 
const { tools, gateway } = await loadLangChainTriks({
  onPassthrough: (content) => console.log(content.content),
  debug: true,
});

createLangChainTools

Advanced function for manual tool creation.


function createLangChainTools(
  gateway: TrikGateway,
  options?: LangChainAdapterOptions
): DynamicStructuredTool[]

Options:


interface LangChainAdapterOptions {
  getSessionId?: (trikId: string) => string | undefined;
  setSessionId?: (trikId: string, sessionId: string) => void;
  onPassthrough?: (content: PassthroughContent) => void;
  debug?: boolean;
}

parseToolName

Parse LangChain tool name back to trik ID and action.


function parseToolName(toolName: string): {
  trikId: string;
  actionName: string;
}

Example:


const { trikId, actionName } = parseToolName('demo_article_search__search');
// trikId: 'demo/article-search'
// actionName: 'search'

Type Exports

Re-exported from @trikhub/manifest for convenience:


export type {
  TrikManifest,
  ActionDefinition,
  ResponseMode,
  JSONSchema,
  ResponseTemplate,
  SessionCapabilities,
  SessionHistoryEntry,
  TrikSession,
  SessionContext,
  PassthroughContent,
  PassthroughDeliveryReceipt,
  UserContentReference,
};