SDK Integration

The gateway package lets you load and execute triks programmatically.

Installation


npm install @trikhub/gateway

Quick Start


import { TrikGateway } from '@trikhub/gateway'
 
// Create gateway
const gateway = new TrikGateway()
 
// Load triks from config
await gateway.loadTriksFromConfig()
 
// Execute an action
const result = await gateway.execute(
  '@molefas/article-search',  // trik ID
  'search',                    // action name
  { topic: 'AI' }              // input
)

Loading Triks

From Config File

The recommended way. Loads triks listed in .trikhub/config.json:


const gateway = new TrikGateway()
 
const manifests = await gateway.loadTriksFromConfig({
  configPath: '.trikhub/config.json',  // optional, this is default
  baseDir: process.cwd(),               // optional
})
 
console.log(`Loaded ${manifests.length} triks`)

Manual Loading

For advanced use cases:


const gateway = new TrikGateway()
 
// Load from path
await gateway.loadTrik('./my-triks/article-search')

Executing Actions

Basic Execution


const result = await gateway.execute(
  'demo/article-search',
  'search',
  { topic: 'artificial intelligence' }
)
 
if (result.success) {
  console.log('Response mode:', result.responseMode)
 
  if (result.responseMode === 'template') {
    console.log('Agent data:', result.agentData)
    console.log('Template text:', result.templateText)
  } else {
    console.log('User content ref:', result.userContentRef)
  }
}

With Sessions

For multi-turn conversations:


// First call - no session
const result1 = await gateway.execute(
  'demo/article-search',
  'search',
  { topic: 'AI' }
)
 
const sessionId = result1.sessionId
 
// Second call - with session
const result2 = await gateway.execute(
  'demo/article-search',
  'details',
  { reference: 'the second one' },
  { sessionId }
)

Handling Passthrough Content

When responseMode is passthrough, content goes directly to the user:


const result = await gateway.execute(
  'demo/article-search',
  'details',
  { articleId: 'art-001' }
)
 
if (result.success && result.responseMode === 'passthrough') {
  // Deliver content to user
  const delivery = gateway.deliverContent(result.userContentRef)
 
  if (delivery) {
    console.log('Content type:', delivery.receipt.contentType)
    console.log('Content:', delivery.content.content)
  }
}

Tool Definitions

Get tool definitions for integration with agent frameworks:


const toolDefs = gateway.getToolDefinitions()
 
for (const tool of toolDefs) {
  console.log(`${tool.name}: ${tool.description}`)
  console.log(`  Mode: ${tool.responseMode}`)
  console.log(`  Schema:`, tool.inputSchema)
}

Output:


demo/article-search:search: Search for articles by topic
  Mode: template
  Schema: { type: 'object', properties: { topic: { type: 'string' } }, required: ['topic'] }

Result Types

Template Result


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

Passthrough Result


interface GatewaySuccessPassthrough {
  success: true;
  responseMode: 'passthrough';
  userContentRef: string;  // Reference to retrieve content
  sessionId?: string;
}

Error Result


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

Error Handling


try {
  const result = await gateway.execute('demo/article-search', 'search', { topic: 'AI' })
 
  if (!result.success) {
    console.error('Execution failed:', result.error)
    return
  }
 
  // Handle success...
} catch (error) {
  // Gateway-level errors (e.g., trik not found)
  console.error('Gateway error:', error)
}

Next Steps

Learn how to create your own triks.