@timefly/ai-sdk 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# @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
+
+```bash
+bun add @timefly/ai-sdk
+```
+
+From this monorepo:
+
+```json
+{
+	"dependencies": {
+		"@timefly/ai-sdk": "workspace:*"
+	}
+}
+```
+
+## Quick example
+
+```typescript
+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 `ai_usage_events`.
+
+## 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](../../docs/INTEGRATIONS.md) for OpenCode and Claude Code examples.

package/dist/auth-credentials.d.ts

@@ -0,0 +1,22 @@
+export type TimeFlyAuthFile = {
+    accessToken: string;
+    refreshToken: string;
+    apiBaseUrl?: string;
+    savedAt?: string;
+};
+export type ResolvedAuthCredentials = {
+    accessToken?: string;
+    refreshToken?: string;
+    apiBaseUrl?: string;
+    authFilePath?: string;
+};
+export declare const resolveDefaultAuthFilePath: () => string;
+export declare const readAuthFile: (authFilePath: string) => Promise<TimeFlyAuthFile | undefined>;
+export declare const writeAuthFile: (authFilePath: string, authFile: TimeFlyAuthFile) => Promise<void>;
+export declare const resolveAuthCredentials: (config: {
+    accessToken?: string;
+    refreshToken?: string;
+    apiBaseUrl?: string;
+    authFilePath?: string;
+}) => Promise<ResolvedAuthCredentials>;
+//# sourceMappingURL=auth-credentials.d.ts.map

package/dist/auth-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-credentials.d.ts","sourceRoot":"","sources":["../src/auth-credentials.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAKD,eAAO,MAAM,0BAA0B,QAAO,MAA2B,CAAA;AAEzE,eAAO,MAAM,YAAY,GAAI,cAAc,MAAM,KAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAM9D,CAAA;AAEzB,eAAO,MAAM,aAAa,GAAI,cAAc,MAAM,EAAE,UAAU,eAAe,KAAG,OAAO,CAAC,IAAI,CAmB3F,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,QAAQ;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,KAAG,OAAO,CAAC,uBAAuB,CA6BlC,CAAA"}

package/dist/auth-credentials.js

@@ -0,0 +1,46 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_AUTH_DIRECTORY = path.join(os.homedir(), '.config', 'opencode');
+const DEFAULT_AUTH_FILE = path.join(DEFAULT_AUTH_DIRECTORY, 'timefly-auth.json');
+export const resolveDefaultAuthFilePath = () => DEFAULT_AUTH_FILE;
+export const readAuthFile = (authFilePath) => readFile(authFilePath, 'utf8')
+    .then((rawContent) => JSON.parse(rawContent))
+    .then((authFile) => typeof authFile.accessToken === 'string' && typeof authFile.refreshToken === 'string' ? authFile : undefined)
+    .catch(() => undefined);
+export const writeAuthFile = (authFilePath, authFile) => {
+    const authDirectory = path.dirname(authFilePath);
+    return mkdir(authDirectory, { recursive: true })
+        .then(() => writeFile(authFilePath, JSON.stringify({
+        ...authFile,
+        savedAt: new Date().toISOString()
+    }, null, 2), 'utf8'))
+        .then(() => undefined);
+};
+export const resolveAuthCredentials = (config) => {
+    const environmentAccessToken = process.env.TIMEFLY_ACCESS_TOKEN;
+    const environmentApiBaseUrl = process.env.TIMEFLY_API_BASE_URL;
+    const authFilePath = config.authFilePath ?? resolveDefaultAuthFilePath();
+    if (config.accessToken) {
+        return Promise.resolve({
+            accessToken: config.accessToken,
+            refreshToken: config.refreshToken,
+            apiBaseUrl: config.apiBaseUrl ?? environmentApiBaseUrl,
+            authFilePath
+        });
+    }
+    if (environmentAccessToken) {
+        return Promise.resolve({
+            accessToken: environmentAccessToken,
+            refreshToken: config.refreshToken,
+            apiBaseUrl: config.apiBaseUrl ?? environmentApiBaseUrl,
+            authFilePath
+        });
+    }
+    return readAuthFile(authFilePath).then((authFile) => ({
+        accessToken: authFile?.accessToken,
+        refreshToken: authFile?.refreshToken ?? config.refreshToken,
+        apiBaseUrl: config.apiBaseUrl ?? authFile?.apiBaseUrl ?? environmentApiBaseUrl,
+        authFilePath
+    }));
+};

package/dist/create-ai-usage-event.d.ts

@@ -0,0 +1,3 @@
+import type { AiUsageEvent, CreateAiUsageEventInput } from './types.js';
+export declare const createAiUsageEvent: (source: AiUsageEvent["source"], sourceVersion: string, input: CreateAiUsageEventInput) => AiUsageEvent;
+//# sourceMappingURL=create-ai-usage-event.d.ts.map

package/dist/create-ai-usage-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-ai-usage-event.d.ts","sourceRoot":"","sources":["../src/create-ai-usage-event.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AASvE,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,YAAY,CAAC,QAAQ,CAAC,EAC9B,eAAe,MAAM,EACrB,OAAO,uBAAuB,KAC5B,YAoBF,CAAA"}

package/dist/create-ai-usage-event.js

@@ -0,0 +1,27 @@
+import { v7 as uuidV7 } from 'uuid';
+const formatLocalDay = (date) => {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+};
+export const createAiUsageEvent = (source, sourceVersion, input) => {
+    const eventAt = input.eventAtUtc ?? new Date();
+    return {
+        eventId: uuidV7(),
+        source,
+        sourceVersion,
+        sessionId: input.sessionId,
+        eventType: input.eventType,
+        eventAtUtc: eventAt.toISOString(),
+        localDay: formatLocalDay(eventAt),
+        modelId: input.modelId,
+        planMode: input.planMode,
+        inputTokens: input.inputTokens,
+        outputTokens: input.outputTokens,
+        totalTokens: input.totalTokens,
+        toolName: input.toolName,
+        durationMs: input.durationMs,
+        metadata: input.metadata
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { resolveAuthCredentials, resolveDefaultAuthFilePath, readAuthFile, writeAuthFile } from './auth-credentials.js';
+export type { ResolvedAuthCredentials, TimeFlyAuthFile } from './auth-credentials.js';
+export { createAiUsageEvent } from './create-ai-usage-event.js';
+export { appendToLocalQueue, readLocalQueue, resolveQueueFilePath } from './local-queue.js';
+export { isSyncFailure, parseSyncFailure } from './sync-error.js';
+export type { SyncFailure } from './sync-error.js';
+export { refreshAccessToken } from './token-refresh.js';
+export { createTimeFlyAiClient, TimeFlyAiClient } from './timefly-ai-client.js';
+export type { RecordResult } from './timefly-ai-client.js';
+export type { AiSdkConfig, AiSyncBatch, AiSyncResponse, AiToolSource, AiUsageEvent, AiUsageEventType, AiUsageMetadata, CreateAiUsageEventInput } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACvH,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC3F,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC/E,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC1D,YAAY,EACX,WAAW,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { resolveAuthCredentials, resolveDefaultAuthFilePath, readAuthFile, writeAuthFile } from './auth-credentials.js';
+export { createAiUsageEvent } from './create-ai-usage-event.js';
+export { appendToLocalQueue, readLocalQueue, resolveQueueFilePath } from './local-queue.js';
+export { isSyncFailure, parseSyncFailure } from './sync-error.js';
+export { refreshAccessToken } from './token-refresh.js';
+export { createTimeFlyAiClient, TimeFlyAiClient } from './timefly-ai-client.js';

package/dist/local-queue.d.ts

@@ -0,0 +1,9 @@
+import type { AiUsageEvent } from './types.js';
+export type LocalQueue = {
+    events: AiUsageEvent[];
+};
+export declare const readLocalQueue: (queueFilePath: string) => Promise<LocalQueue>;
+export declare const appendToLocalQueue: (queueFilePath: string, events: AiUsageEvent[]) => Promise<void>;
+export declare const clearAcceptedFromQueue: (queueFilePath: string, acceptedEventIds: Set<string>) => Promise<void>;
+export declare const resolveQueueFilePath: (customPath?: string) => string;
+//# sourceMappingURL=local-queue.d.ts.map

package/dist/local-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-queue.d.ts","sourceRoot":"","sources":["../src/local-queue.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI9C,MAAM,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,YAAY,EAAE,CAAA;CACtB,CAAA;AAID,eAAO,MAAM,cAAc,GAAI,eAAe,MAAM,KAAG,OAAO,CAAC,UAAU,CAG7C,CAAA;AAE5B,eAAO,MAAM,kBAAkB,GAC9B,eAAe,MAAM,EACrB,QAAQ,YAAY,EAAE,KACpB,OAAO,CAAC,IAAI,CAUd,CAAA;AAED,eAAO,MAAM,sBAAsB,GAClC,eAAe,MAAM,EACrB,kBAAkB,GAAG,CAAC,MAAM,CAAC,KAC3B,OAAO,CAAC,IAAI,CAMS,CAAA;AAExB,eAAO,MAAM,oBAAoB,GAAI,aAAa,MAAM,KAAG,MACA,CAAA"}

package/dist/local-queue.js

@@ -0,0 +1,24 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const DEFAULT_QUEUE_FILE = '.timefly-ai-queue.json';
+const emptyQueue = () => ({ events: [] });
+export const readLocalQueue = (queueFilePath) => readFile(queueFilePath, 'utf8')
+    .then((rawContent) => JSON.parse(rawContent))
+    .catch(() => emptyQueue());
+export const appendToLocalQueue = (queueFilePath, events) => {
+    const directory = path.dirname(queueFilePath);
+    return mkdir(directory, { recursive: true })
+        .then(() => readLocalQueue(queueFilePath))
+        .then((queue) => ({
+        events: [...queue.events, ...events]
+    }))
+        .then((updatedQueue) => writeFile(queueFilePath, JSON.stringify(updatedQueue, null, 2), 'utf8'))
+        .then(() => undefined);
+};
+export const clearAcceptedFromQueue = (queueFilePath, acceptedEventIds) => readLocalQueue(queueFilePath)
+    .then((queue) => ({
+    events: queue.events.filter((event) => !acceptedEventIds.has(event.eventId))
+}))
+    .then((updatedQueue) => writeFile(queueFilePath, JSON.stringify(updatedQueue, null, 2), 'utf8'))
+    .then(() => undefined);
+export const resolveQueueFilePath = (customPath) => customPath ?? path.join(process.cwd(), DEFAULT_QUEUE_FILE);

package/dist/sync-error.d.ts

@@ -0,0 +1,9 @@
+export type SyncFailure = {
+    statusCode: number;
+    message: string;
+    isSupporterRequired: boolean;
+    isUnauthorized: boolean;
+};
+export declare const parseSyncFailure: (statusCode: number, responseBody: string) => SyncFailure;
+export declare const isSyncFailure: (error: unknown) => error is SyncFailure;
+//# sourceMappingURL=sync-error.d.ts.map

package/dist/sync-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-error.d.ts","sourceRoot":"","sources":["../src/sync-error.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,mBAAmB,EAAE,OAAO,CAAA;IAC5B,cAAc,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,EAAE,cAAc,MAAM,KAAG,WAK1E,CAAA;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAIF,CAAA"}

package/dist/sync-error.js

@@ -0,0 +1,10 @@
+export const parseSyncFailure = (statusCode, responseBody) => ({
+    statusCode,
+    message: responseBody || `AI sync failed: ${statusCode}`,
+    isSupporterRequired: statusCode === 403 && responseBody.includes('Supporter'),
+    isUnauthorized: statusCode === 401
+});
+export const isSyncFailure = (error) => typeof error === 'object' &&
+    error !== null &&
+    'statusCode' in error &&
+    typeof error.statusCode === 'number';

package/dist/timefly-ai-client.d.ts

@@ -0,0 +1,29 @@
+import type { AiSdkConfig, AiSyncResponse, AiUsageEvent } from './types.js';
+export type RecordResult = {
+    synced: boolean;
+    queued: boolean;
+    accepted: number;
+};
+export declare class TimeFlyAiClient {
+    private readonly source;
+    private readonly sourceVersion;
+    private readonly queueFilePath;
+    private apiBaseUrl;
+    private accessToken?;
+    private refreshToken?;
+    private authFilePath?;
+    private credentialsLoaded;
+    constructor(config: AiSdkConfig);
+    getSource(): AiSdkConfig['source'];
+    getSourceVersion(): string;
+    recordEvents(events: AiUsageEvent[]): Promise<RecordResult>;
+    flushPendingQueue(): Promise<AiSyncResponse | undefined>;
+    private ensureCredentialsLoaded;
+    private persistRefreshedTokens;
+    private refreshTokensIfPossible;
+    private syncEventsWithRefresh;
+    private parseSyncResponse;
+    private syncEvents;
+}
+export declare const createTimeFlyAiClient: (config: Partial<AiSdkConfig> & Pick<AiSdkConfig, "source" | "sourceVersion">) => TimeFlyAiClient;
+//# sourceMappingURL=timefly-ai-client.d.ts.map

package/dist/timefly-ai-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timefly-ai-client.d.ts","sourceRoot":"","sources":["../src/timefly-ai-client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAe,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAWxF,MAAM,MAAM,YAAY,GAAG;IAC1B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CAChB,CAAA;AAID,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,YAAY,CAAC,CAAQ;IAC7B,OAAO,CAAC,YAAY,CAAC,CAAQ;IAC7B,OAAO,CAAC,iBAAiB,CAAQ;gBAErB,MAAM,EAAE,WAAW;IAU/B,SAAS,IAAI,WAAW,CAAC,QAAQ,CAAC;IAIlC,gBAAgB,IAAI,MAAM;IAI1B,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAiC3D,iBAAiB,IAAI,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAiBxD,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,uBAAuB;IAa/B,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,UAAU;CA+BlB;AAED,eAAO,MAAM,qBAAqB,GAAI,QAAQ,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,eAAe,CAAC,KAAG,eASlH,CAAA"}

package/dist/timefly-ai-client.js

@@ -0,0 +1,158 @@
+import { gzipSync } from 'node:zlib';
+import { resolveAuthCredentials, writeAuthFile } from './auth-credentials.js';
+import { appendToLocalQueue, clearAcceptedFromQueue, readLocalQueue, resolveQueueFilePath } from './local-queue.js';
+import { isSyncFailure, parseSyncFailure } from './sync-error.js';
+import { refreshAccessToken } from './token-refresh.js';
+const buildAiSyncUserAgent = (source, sourceVersion) => `TimeFlyAi|${source}|${sourceVersion}`;
+export class TimeFlyAiClient {
+    source;
+    sourceVersion;
+    queueFilePath;
+    apiBaseUrl;
+    accessToken;
+    refreshToken;
+    authFilePath;
+    credentialsLoaded = false;
+    constructor(config) {
+        this.apiBaseUrl = config.apiBaseUrl.replace(/\/$/, '');
+        this.accessToken = config.accessToken;
+        this.refreshToken = config.refreshToken;
+        this.authFilePath = config.authFilePath;
+        this.source = config.source;
+        this.sourceVersion = config.sourceVersion;
+        this.queueFilePath = resolveQueueFilePath(config.queueFilePath);
+    }
+    getSource() {
+        return this.source;
+    }
+    getSourceVersion() {
+        return this.sourceVersion;
+    }
+    recordEvents(events) {
+        if (!events.length) {
+            return Promise.resolve({ synced: false, queued: false, accepted: 0 });
+        }
+        return this.ensureCredentialsLoaded()
+            .then(() => this.flushPendingQueue())
+            .then(() => this.syncEventsWithRefresh(events))
+            .then((syncResponse) => clearAcceptedFromQueue(this.queueFilePath, new Set(events.map((event) => event.eventId))).then(() => ({
+            synced: true,
+            queued: false,
+            accepted: syncResponse.accepted
+        })))
+            .catch((error) => appendToLocalQueue(this.queueFilePath, events).then(() => {
+            if (isSyncFailure(error)) {
+                throw error;
+            }
+            return {
+                synced: false,
+                queued: true,
+                accepted: 0
+            };
+        }));
+    }
+    flushPendingQueue() {
+        return this.ensureCredentialsLoaded()
+            .then(() => readLocalQueue(this.queueFilePath))
+            .then((queue) => {
+            if (!queue.events.length) {
+                return undefined;
+            }
+            return this.syncEventsWithRefresh(queue.events).then((syncResponse) => clearAcceptedFromQueue(this.queueFilePath, new Set(queue.events.map((event) => event.eventId))).then(() => syncResponse));
+        });
+    }
+    ensureCredentialsLoaded() {
+        if (this.credentialsLoaded) {
+            return Promise.resolve();
+        }
+        return resolveAuthCredentials({
+            accessToken: this.accessToken,
+            refreshToken: this.refreshToken,
+            apiBaseUrl: this.apiBaseUrl,
+            authFilePath: this.authFilePath
+        }).then((credentials) => {
+            this.accessToken = credentials.accessToken;
+            this.refreshToken = credentials.refreshToken;
+            this.authFilePath = credentials.authFilePath;
+            if (credentials.apiBaseUrl) {
+                this.apiBaseUrl = credentials.apiBaseUrl.replace(/\/$/, '');
+            }
+            this.credentialsLoaded = true;
+        });
+    }
+    persistRefreshedTokens(accessToken, refreshToken) {
+        this.accessToken = accessToken;
+        this.refreshToken = refreshToken;
+        if (!this.authFilePath) {
+            return Promise.resolve();
+        }
+        return writeAuthFile(this.authFilePath, {
+            accessToken,
+            refreshToken,
+            apiBaseUrl: this.apiBaseUrl
+        });
+    }
+    refreshTokensIfPossible() {
+        if (!this.refreshToken) {
+            return Promise.reject(parseSyncFailure(401, 'TIMEFLY_ACCESS_TOKEN is required for sync'));
+        }
+        return refreshAccessToken({
+            apiBaseUrl: this.apiBaseUrl,
+            refreshToken: this.refreshToken
+        })
+            .then((refreshedTokens) => this.persistRefreshedTokens(refreshedTokens.accessToken, refreshedTokens.refreshToken))
+            .then(() => undefined);
+    }
+    syncEventsWithRefresh(events, hasRetried = false) {
+        return this.syncEvents(events).catch((error) => {
+            if (!hasRetried && isSyncFailure(error) && error.isUnauthorized) {
+                return this.refreshTokensIfPossible().then(() => this.syncEventsWithRefresh(events, true));
+            }
+            throw error;
+        });
+    }
+    parseSyncResponse(response, responseBody) {
+        if (!response.ok) {
+            throw parseSyncFailure(response.status, responseBody);
+        }
+        const envelope = JSON.parse(responseBody);
+        const accepted = envelope.data?.accepted ?? envelope.data?.queued ?? 0;
+        return { accepted };
+    }
+    syncEvents(events) {
+        if (!this.accessToken) {
+            return Promise.reject(parseSyncFailure(401, 'TIMEFLY_ACCESS_TOKEN is required for sync'));
+        }
+        const batch = { events };
+        const payload = JSON.stringify(batch);
+        const compressedBody = gzipSync(Buffer.from(payload, 'utf8'));
+        const url = `${this.apiBaseUrl}/ai/sync`;
+        return fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+                'Content-Encoding': 'gzip',
+                'Accept-Encoding': 'gzip',
+                'User-Agent': buildAiSyncUserAgent(this.source, this.sourceVersion),
+                'X-TimeFly-Source': this.source,
+                'X-TimeFly-Source-Version': this.sourceVersion
+            },
+            body: compressedBody
+        })
+            .then((response) => response.text().then((responseBody) => ({
+            response,
+            responseBody
+        })))
+            .then(({ response, responseBody }) => this.parseSyncResponse(response, responseBody));
+    }
+}
+export const createTimeFlyAiClient = (config) => new TimeFlyAiClient({
+    apiBaseUrl: config.apiBaseUrl ?? process.env.TIMEFLY_API_BASE_URL ?? 'https://api.timefly.dev',
+    accessToken: config.accessToken ?? process.env.TIMEFLY_ACCESS_TOKEN,
+    refreshToken: config.refreshToken,
+    authFilePath: config.authFilePath,
+    source: config.source,
+    sourceVersion: config.sourceVersion,
+    queueFilePath: config.queueFilePath
+});

package/dist/token-refresh.d.ts

@@ -0,0 +1,16 @@
+export type RefreshTokenResponse = {
+    accessToken: string;
+    refreshToken: string;
+};
+export type RefreshTokenFailure = {
+    statusCode: number;
+    message: string;
+    isSupporterRequired: boolean;
+    isUnauthorized: boolean;
+};
+export declare const refreshAccessToken: (input: {
+    apiBaseUrl: string;
+    refreshToken: string;
+    deviceFingerprint?: string;
+}) => Promise<RefreshTokenResponse>;
+//# sourceMappingURL=token-refresh.d.ts.map

package/dist/token-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-refresh.d.ts","sourceRoot":"","sources":["../src/token-refresh.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,mBAAmB,EAAE,OAAO,CAAA;IAC5B,cAAc,EAAE,OAAO,CAAA;CACvB,CAAA;AA+BD,eAAO,MAAM,kBAAkB,GAAI,OAAO;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,KAAG,OAAO,CAAC,oBAAoB,CAkB/B,CAAA"}

package/dist/token-refresh.js

@@ -0,0 +1,37 @@
+const parseRefreshResponse = (response, responseBody) => {
+    if (!response.ok) {
+        const isSupporterRequired = response.status === 403 && responseBody.includes('Supporter');
+        const failure = {
+            statusCode: response.status,
+            message: responseBody || `Token refresh failed: ${response.status}`,
+            isSupporterRequired,
+            isUnauthorized: response.status === 401
+        };
+        throw failure;
+    }
+    const envelope = JSON.parse(responseBody);
+    const nestedTokens = envelope.data?.tokens ?? envelope.tokens;
+    if (!nestedTokens?.accessToken || !nestedTokens.refreshToken) {
+        throw new Error('Token refresh response missing tokens');
+    }
+    return {
+        accessToken: nestedTokens.accessToken,
+        refreshToken: nestedTokens.refreshToken
+    };
+};
+export const refreshAccessToken = (input) => {
+    const url = `${input.apiBaseUrl.replace(/\/$/, '')}/auth/extension/refresh`;
+    return fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(input.deviceFingerprint ? { 'x-device-fingerprint': input.deviceFingerprint } : {})
+        },
+        body: JSON.stringify({ refreshToken: input.refreshToken })
+    })
+        .then((response) => response.text().then((responseBody) => ({
+        response,
+        responseBody
+    })))
+        .then(({ response, responseBody }) => parseRefreshResponse(response, responseBody));
+};

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export type AiToolSource = 'opencode' | 'claude-code' | 'cursor' | 'copilot' | 'windsurf' | 'unknown';
+export type AiUsageEventType = 'session_start' | 'session_end' | 'llm_request' | 'llm_response' | 'tool_call' | 'tool_result' | 'turn_complete' | 'compaction' | 'error';
+export type AiUsageMetadata = Record<string, string | number | boolean | undefined>;
+export type AiUsageEvent = {
+    eventId: string;
+    source: AiToolSource;
+    sourceVersion: string;
+    sessionId: string;
+    eventType: AiUsageEventType;
+    eventAtUtc: string;
+    localDay: string;
+    modelId?: string;
+    planMode?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    toolName?: string;
+    durationMs?: number;
+    metadata?: AiUsageMetadata;
+};
+export type AiSyncBatch = {
+    events: AiUsageEvent[];
+};
+export type AiSyncResponse = {
+    accepted: number;
+};
+export type AiSdkConfig = {
+    apiBaseUrl: string;
+    accessToken?: string;
+    refreshToken?: string;
+    authFilePath?: string;
+    source: AiToolSource;
+    sourceVersion: string;
+    queueFilePath?: string;
+};
+export type CreateAiUsageEventInput = {
+    sessionId: string;
+    eventType: AiUsageEventType;
+    modelId?: string;
+    planMode?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    toolName?: string;
+    durationMs?: number;
+    metadata?: AiUsageMetadata;
+    eventAtUtc?: Date;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAA;AAErG,MAAM,MAAM,gBAAgB,GACzB,eAAe,GACf,aAAa,GACb,aAAa,GACb,cAAc,GACd,WAAW,GACX,aAAa,GACb,eAAe,GACf,YAAY,GACZ,OAAO,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;AAEnF,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,YAAY,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,YAAY,EAAE,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,YAAY,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,eAAe,CAAA;IAC1B,UAAU,CAAC,EAAE,IAAI,CAAA;CACjB,CAAA"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@timefly/ai-sdk",
+	"version": "0.2.0",
+	"description": "TimeFly SDK for AI usage telemetry",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p test/tsconfig.json --noEmit",
+		"test": "bun test",
+		"prepublishOnly": "bun run build && bun run typecheck && bun test"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/TimeFly-Dev/ai-integrations.git",
+		"directory": "packages/sdk"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"timefly",
+		"telemetry",
+		"ai",
+		"usage",
+		"analytics"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"uuid": "^14.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14",
+		"typescript": "^5.9.3"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}