@timefly/ai-sdk

Public SDK for sending AI usage telemetry to TimeFly from any integration.

No prompt content is sent — only metadata (model, tokens, tool names, session lifecycle).

Install

bun add @timefly/ai-sdk

From this monorepo:

{
	"dependencies": {
		"@timefly/ai-sdk": "workspace:*"
	}
}

Quick example

import { createAiUsageEvent, createTimeFlyAiClient } from '@timefly/ai-sdk'

const client = createTimeFlyAiClient({
	source: 'opencode',
	sourceVersion: '1.0.0',
	accessToken: process.env.TIMEFLY_ACCESS_TOKEN
})

const event = createAiUsageEvent('opencode', '1.0.0', {
	sessionId: 'session-abc',
	eventType: 'llm_request',
	modelId: 'claude-sonnet-4',
	inputTokens: 1200,
	outputTokens: 340
})

client.recordEvents([event]).then((result) => {
	console.log(result.synced ? 'synced' : 'queued locally', result.accepted)
})

API

| Export | Description | |--------|-------------| | createAiUsageEvent | Build a typed AiUsageEvent | | createTimeFlyAiClient | HTTP client with local offline queue | | TimeFlyAiClient | Class with recordEvents / flushPendingQueue |

Endpoint

POST {apiBaseUrl}/ai/sync — gzip JSON body { events: AiUsageEvent[] }

Stored in ClickHouse table activity_events as ai.* activities.

Environment

| Variable | Description | |----------|-------------| | TIMEFLY_API_BASE_URL | Default https://api.timefly.dev | | TIMEFLY_ACCESS_TOKEN | Bearer token from TimeFly account |

Build your own integration

1. Map your tool's lifecycle hooks to AiUsageEvent fields.
2. Call client.recordEvents([...]) — failures are queued to .timefly-ai-queue.json.
3. Document install steps in your package README.

See docs/INTEGRATIONS.md for OpenCode and Claude Code examples.