house-client

Minimal Node.js client SDK for the LLM Logging System.

Features

• Non-blocking: Log sending doesn't block your main process
• Batch sending: Multiple operations sent together for efficiency
• Graceful shutdown: Ensures all logs are sent before process exit
• TypeScript support: Full type definitions included
• Minimal dependencies: Works in Node 18+ and Bun

Installation

npm install house-client
# or
yarn add house-client
# or
bun add house-client

Usage

import { LogClient } from 'house-client'

const logClient = new LogClient({
  baseUrl: 'http://localhost:9001',
  apiKey: 'sk_your_api_key_here',
  onError: ({ error }) => {
    console.error('Log send failed:', error.message)
  },
})

// Start a generation (non-blocking - returns immediately)
// generationId and requestId are auto-generated
const gen = logClient.generationStart({
  // Required
  threadId: 'thread-456',
  userId: 'user-789',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
  // Optional
  tenantId: 'tenant-123', // Tenant ID (auto-created if not exists)
  requestId: 'req-001', // Request ID (defaults to generationId)
  threadTitle: 'Chat about Paris', // Thread title (auto-upserts thread)
  name: 'chat', // Generation name
})

console.log(gen.generationId) // Auto-generated ID

try {
  const result = await streamText({
    // ... your LLM call
    onFinish: ({ usage, response }) => {
      // End generation (non-blocking)
      // latencyMs is auto-calculated
      gen.end({
        responseMessages: response.messages,
        usage,
      })
    },
  })
} catch (error) {
  // Record error (non-blocking)
  gen.error({
    kind: 'error',
    message: error.message,
    stack: error.stack,
  })
}

// Upload a file (sent immediately)
await gen.uploadFile({
  file: fileBuffer,
  filename: 'diagram.png',
  contentType: 'image/png',
})

Graceful Shutdown

Ensure all pending logs are sent before your process exits:

process.on('SIGTERM', async () => {
  await logClient.shutdown()
  process.exit(0)
})

// Or manually flush
await logClient.flush()

API Reference

LogClient

new LogClient({
  baseUrl: string,           // Server URL
  apiKey: string,            // API key
  concurrency?: number,      // Max concurrent requests (default: 5)
  onError?: (params) => void // Error callback
})

| Method | Returns | Description | | ------------------------- | ----------------------- | ------------------------------------------ | | generationStart(params) | Generation | Start a new generation. Non-blocking. | | flush() | Promise<void> | Force send all pending logs | | shutdown() | Promise<void> | Graceful shutdown (flush + stop accepting) | | getQueueStatus() | { pending, inFlight } | Get queue status |

Generation

| Property | Type | Description | | -------------- | -------- | ------------------------ | | generationId | string | Auto-generated unique ID |

| Method | Returns | Description | | -------------------- | --------------------- | ---------------------------------- | | end(params) | void | Complete generation. Non-blocking. | | error(params) | void | Record an error. Non-blocking. | | uploadFile(params) | Promise<{ fileId }> | Upload a file (sent immediately) |

Publishing to npm

Prerequisites

1. npm account with publish access
2. Logged in to npm: npm login

Publish steps

# 1. Navigate to client-sdk directory
cd packages/client-sdk

# 2. Update version (choose one)
npm version patch  # 0.1.0 -> 0.1.1
npm version minor  # 0.1.0 -> 0.2.0
npm version major  # 0.1.0 -> 1.0.0

# 3. Build (runs automatically via prepublishOnly)
bun run build

# 4. Dry run to verify package contents
npm publish --dry-run

# 5. Publish to npm
npm publish

# 6. (Optional) Push version tag to git
git push && git push --tags

Verify published package

# Check package info
npm info house-client

# Install in a test project
npm install house-client

CI/CD Publishing

For automated publishing, set the NPM_TOKEN environment variable:

# In CI environment
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
npm publish