@teliagen/client

Universal HTTP client for Teliagen applications.

Overview

@teliagen/client provides a lightweight HTTP transport for calling Teliagen actions:

• Universal – Works in Node.js and browsers
• Type-Safe – Full TypeScript support
• Simple API – Call actions by name with typed inputs
• Configurable – Custom headers, auth, interceptors

Installation

npm install @teliagen/client
# or
pnpm add @teliagen/client

Quick Start

import { TeliagenTransport } from '@teliagen/client';

const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api'
});

// Call an action
const user = await client.execute<LoginInput, LoginOutput>(
  'login',
  { email: '[email protected]', password: 'secret' }
);

console.log(user.token);

Configuration

interface TeliagenClientConfig {
  // Required
  baseUrl: string;              // API base URL
  
  // Optional
  headers?: Record<string, string>;  // Default headers
  timeout?: number;             // Request timeout (ms)
  
  // Authentication
  token?: string;               // Bearer token
  apiKey?: string;              // API key header
  
  // Callbacks
  onError?: (error: any) => void;
  onRequest?: (config: any) => any;
  onResponse?: (response: any) => any;
}

Examples

Basic Usage

import { TeliagenTransport } from '@teliagen/client';

const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api'
});

// Simple action call
const users = await client.execute('listUsers', {});

// With types
interface CreateUserInput {
  email: string;
  name: string;
}

interface User {
  id: string;
  email: string;
  name: string;
}

const newUser = await client.execute<CreateUserInput, User>(
  'createUser',
  { email: '[email protected]', name: 'Alice' }
);

With Authentication

const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api',
  token: localStorage.getItem('authToken')
});

// Token is sent as: Authorization: Bearer <token>

// Or use API key
const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api',
  apiKey: 'your-api-key'
});

// API key is sent as: x-teliagen-key: <apiKey>

Module and Provider Routing

// Call action in specific module/provider
const result = await client.execute(
  'getOrderDetails',
  { orderId: '123' },
  {
    module: 'orders',
    provider: 'OrderActions'
  }
);

// Calls: POST /api/actions/getOrderDetails
// Headers: x-teliagen-module: orders
//          x-teliagen-provider: OrderActions

Cross-Service Calls

// Call action on a federated service
const result = await client.execute(
  'processPayment',
  { amount: 99.99 },
  {
    server: 'payments'
  }
);

// Calls: POST /api/actions/processPayment
// Headers: x-teliagen-server: payments

Dynamic Token

const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api',
  onRequest: (config) => {
    // Add fresh token on each request
    const token = localStorage.getItem('authToken');
    if (token) {
      config.headers['Authorization'] = `Bearer ${token}`;
    }
    return config;
  }
});

Error Handling

const client = new TeliagenTransport({
  baseUrl: 'http://localhost:3000/api',
  onError: (error) => {
    if (error.response?.status === 401) {
      // Redirect to login
      window.location.href = '/login';
    }
  }
});

try {
  const result = await client.execute('protectedAction', {});
} catch (error) {
  console.error('Action failed:', error.message);
}

TeliagenTransport API

class TeliagenTransport {
  constructor(config: TeliagenClientConfig);
  
  // Execute an action
  execute<TInput, TOutput>(
    action: string,
    input: TInput,
    options?: {
      module?: string;
      provider?: string;
      server?: string;
      prefix?: string;
      headers?: Record<string, string>;
    }
  ): Promise<TOutput>;
  
  // Update configuration
  setToken(token: string): void;
  setHeader(key: string, value: string): void;
  removeHeader(key: string): void;
}

Response Types

interface TeliagenResponse<T> {
  data: T;
  status: number;
  headers: Record<string, string>;
}

// The execute method returns the data directly
// For full response, use executeRaw:
const response = await client.executeRaw<Input, Output>('action', input);
console.log(response.status);  // 200
console.log(response.data);    // { ... }

Browser Usage

<script src="https://cdn.example.com/@teliagen/client/dist/client.umd.js"></script>
<script>
  const client = new TeliagenClient.TeliagenTransport({
    baseUrl: 'http://localhost:3000/api'
  });
  
  client.execute('listProducts', {})
    .then(products => console.log(products));
</script>

Integration with Frameworks

React

Use @teliagen/react for React integration with hooks.

Vue

// composables/useTeliagen.ts
import { ref } from 'vue';
import { TeliagenTransport } from '@teliagen/client';

const client = new TeliagenTransport({
  baseUrl: import.meta.env.VITE_API_URL
});

export function useAction<TInput, TOutput>(action: string) {
  const data = ref<TOutput>();
  const loading = ref(false);
  const error = ref<Error>();

  const execute = async (input: TInput) => {
    loading.value = true;
    try {
      data.value = await client.execute<TInput, TOutput>(action, input);
    } catch (e) {
      error.value = e as Error;
    } finally {
      loading.value = false;
    }
  };

  return { data, loading, error, execute };
}

Svelte

// stores/teliagen.ts
import { writable } from 'svelte/store';
import { TeliagenTransport } from '@teliagen/client';

export const client = new TeliagenTransport({
  baseUrl: import.meta.env.VITE_API_URL
});

export function createActionStore<TInput, TOutput>(action: string) {
  const { subscribe, set } = writable<TOutput | null>(null);
  
  return {
    subscribe,
    execute: async (input: TInput) => {
      const result = await client.execute<TInput, TOutput>(action, input);
      set(result);
      return result;
    }
  };
}

Requirements

• Node.js >= 18.0.0 (for Node.js usage)
• Modern browser (for browser usage)

Related Packages

• @teliagen/react – React hooks integration
• @teliagen/vite-plugin – Vite plugin for code generation

Documentation

For full documentation, visit docs.teliagen.org.

License

Apache-2.0