TTC Origin Server

A lightweight server wrapper for ttc-rpc that exposes your decorated classes as RPC endpoints with automatic API discovery. Designed for building AI assistant origins with real-time messaging capabilities.

Installation

bun add ttc-origin-server
# or
npm install ttc-origin-server

Quick Start

1. Create a module using ttc-rpc decorators

// src/test.ts
import { ttc } from "ttc-rpc";
import z from "zod";
import { BaseModule, ActionableClient } from 'ttc-origin-server';

export class HelloWorldModule extends BaseModule {
    @ttc.describe({
        doc: 'some info',
        inputSchema: z.object({
            name: z.string()
        }),
        outputSchema: z.string(),
        validate: true,
        auth: true
    })
    hello(name: string): string {
        return `Hello, ${name}!`;
    }

    // Optional: Handle assistant connections
    onConnect(client: ActionableClient, credentials: Record<string, string>): void {
        console.log(`Assistant ${client.id} connected`);
    }

    // Optional: Handle incoming messages from assistants
    onMessage(assistantId: string, message: string): void {
        console.log(`Message from ${assistantId}: ${message}`);
    }
}

2. Start the server

// src/index.ts
import { runServer } from 'ttc-origin-server';
import { HelloWorldModule } from './test';

runServer({
    name: 'my-service',
    description: 'My awesome AI service',
    modules: [HelloWorldModule],
    port: 3000,
    credentials: [
        { provider: 'OpenAI', credentialKeys: ['apiKey'] }
    ],
    authCb: async (req) => {
        // Your authentication logic
        return true;
    },
    cacheClient: true,
    getAssistantMessages: true
});

3. Run

bun run src/index.ts

API

runServer(config)

Starts a TTC Origin server.

Config options:

• name (string) – Service name (will be normalized to lowercase with underscores)
• description (string) – Optional service description
• modules (any[]) – Array of classes decorated with @ttc.describe, should extend BaseModule
• port (number) – Port to listen on
• credentials (CredentialSpecification[]) – Required API keys for third-party services
• authCb (req => Promise) – Authentication callback for RPC methods
• cacheClient (boolean) – Whether to cache connected clients
• getAssistantMessages (boolean) – Whether to receive messages from connected assistants
• onPing (origin => Promise) – Callback fired when origin receives a ping
• app (express.Express) – Optional existing Express app instance
• modifyable (boolean) – If true, exposes working directory

Types

BaseModule

Base class for origin modules with optional lifecycle hooks:

class MyModule extends BaseModule {
    onConnect?(client: ActionableClient, credentials: Record<string, string>): void | Promise<void>
    onMessage?(assistantId: string, message: string): void | Promise<void>
}

ActionableClient

Connected assistant client interface:

{
    id: string;
    message: (message: string) => Promise<void>;
    trigger: (triggerMessage: string) => Promise<void>;
}

CredentialSpecification

Define required credentials:

{
    provider: string;      // e.g., 'OpenAI', 'Twilio'
    credentialKeys: string[];  // e.g., ['apiKey', 'secret']
}

Helper Functions

• getClientById(id: string) – Retrieve a connected client by ID
• getClient(args: any) – Get client from request context
• getAuthKey(args: any, { provider, credentialKey }) – Extract API keys from request

Endpoints

• GET /rpc/info – Service metadata and configuration
• GET /rpc/functions – Lists all RPC methods (auto-discovered)
• GET /rpc/connect – WebSocket-style endpoint for assistant connections
• POST /rpc/:module/:method – Invoke an RPC method (handled by ttc-rpc)

Decorator Usage

Refer to the ttc-rpc npm package for full documentation on the @ttc.describe decorator and its options.

Development

git clone https://github.com/tentarcles/ttc-origin-server.git
cd ttc-origin-server
bun install
bun run dev

License

MIT © Tentarcles