@datagol/lens-js 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataGOL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# @datagol/lens-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node/TypeScript SDK for [Datagol Lens](../README.md) — ships LLM-call and
+agent tool-call traces to the Datagol Lens API. This is the Node counterpart
+to the Python SDK at [`../sdk`](../sdk); the two talk the same
+`POST /api/v1/projects/{project_id}/traces` wire format (see
+`backend/app/schemas.py`) but are otherwise independent — this package
+authenticates with a **project API key** only, not a user login/JWT (see
+"Auth" below).
+
+## Install
+
+```bash
+npm install @datagol/lens-js
+```
+
+Node 18 or newer. To work on the package itself: `npm install && npm test` in
+this directory.
+
+## Auth
+
+Trace-writing endpoints accept a project-scoped API key
+(`Authorization: Bearer dgl_...`), separate from the human-login JWT the
+dashboard uses. Mint one as a logged-in user:
+
+```bash
+curl -X POST https://<lens-host>/api/v1/projects/<project_id>/api-keys \
+  -H "Authorization: Bearer <your-jwt>" \
+  -H "content-type: application/json" \
+  -d '{"name": "my-service"}'
+# → { "token": "dgl_...", ... }  — shown once, store it as a secret
+```
+
+Then configure the SDK with that token — either via environment variables
+(`DATAGOL_LENS_API_URL`, `DATAGOL_LENS_API_KEY`, `DATAGOL_LENS_PROJECT_ID`)
+or constructor options.
+
+## Usage
+
+### Low-level: `DatagolLensClient`
+
+```ts
+import { DatagolLensClient } from "@datagol/lens-js";
+
+const client = new DatagolLensClient({
+  apiUrl: "https://lens.example.com",
+  apiKey: process.env.DATAGOL_LENS_API_KEY,
+  projectId: process.env.DATAGOL_LENS_PROJECT_ID,
+});
+
+await client.postTrace({
+  name: "qa-agent",
+  input: { question: "..." },
+  output: { answer: "..." },
+  model: "claude-sonnet-4-6",
+  prompt_tokens: 120,
+  completion_tokens: 40,
+  total_tokens: 160,
+  total_cost: 0.0009,
+  status: "success",
+});
+```
+
+### Ergonomic: `TraceBuilder`
+
+Accumulates spans (LLM calls, tool calls, retriever calls, ...) and ships one
+`Trace` with all of them nested, mirroring the Python SDK's `TraceContext`:
+
+```ts
+import { DatagolLensClient, TraceBuilder } from "@datagol/lens-js";
+
+const client = new DatagolLensClient();
+const trace = new TraceBuilder(client, {
+  name: "qa-agent",
+  input: { question: "..." },
+  sessionId: "chat-abc123",
+  externalUserId: "user-42",
+});
+
+try {
+  const start = Date.now();
+  const answer = await callLlm(/* ... */);
+  trace.addSpan({
+    name: "llm-call",
+    spanType: "llm",
+    model: "claude-sonnet-4-6",
+    input: { messages: [/* ... */] },
+    output: { text: answer },
+    promptTokens: 120,
+    completionTokens: 40,
+    cost: 0.0009,
+    latencyMs: Date.now() - start,
+  });
+  trace.setOutput({ answer });
+} catch (err) {
+  trace.setError(String(err));
+  throw err;
+} finally {
+  await trace.flush();
+}
+```
+
+### Budgets and attribution
+
+Pass `companyId`, `agentKey` and `agentName` (plus `externalUserId`) to
+`TraceBuilder` and Lens counts the trace's cost against that company, agent and
+user. Lens prices spans that don't report a `cost` from their model and tokens.
+Before a run, check the budgets:
+
+```ts
+import { BudgetExceeded, LensRequestError } from "@datagol/lens-js";
+
+const { company_ids } = await client.getEnforcedCompanies();   // cache this
+if (company_ids.includes(companyId)) {
+  const result = await client.checkBudget({ companyId, userId, agentKey });
+  if (!result.allowed) throw new BudgetExceeded("over budget", result);
+}
+```
+
+Both calls throw `LensRequestError` on a timeout (2 s by default), a network
+error, a non-2xx status or a body that isn't JSON, so you choose whether to
+fail open or closed.
+
+## Scope
+
+This package covers trace/span ingestion only — no redaction or guardrails
+port yet (the Python SDK's `redaction.py`/`guardrails.py` have no JS
+equivalent here). If a Node consumer needs PII redaction before data leaves
+the process, that's a natural follow-up; for now, configure redaction rules
+server-side (`GET /api/v1/projects/{project_id}/redaction-rules`) or scrub
+`input`/`output` yourself before calling `postTrace`/`addSpan`.

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+import type { BudgetCheckResponse, BudgetStatus, EnforcedCompanies, TraceCreate, TraceOut } from "./types.js";
+/** A Lens API call failed: network error, timeout, non-2xx status or a bad body.
+ *  `status` is set when the server answered with a non-2xx status. */
+export declare class LensRequestError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** Thrown by callers when a budget check blocks a request; `budget` is the
+ *  check's `blocked_by`. */
+export declare class BudgetExceeded extends Error {
+    readonly result?: BudgetCheckResponse | undefined;
+    readonly budget: BudgetStatus | null;
+    constructor(message: string, result?: BudgetCheckResponse | undefined);
+}
+export interface DatagolLensClientOptions {
+    /** Base URL of the Datagol Lens API. Defaults to DATAGOL_LENS_API_URL, then http://localhost:8000. */
+    apiUrl?: string;
+    /** A project-scoped API key ("dgl_..."), minted via
+     *  POST /api/v1/projects/{project_id}/api-keys (requires a logged-in user), or
+     *  a platform key ("dglp_...") from Lens Admin. Defaults to DATAGOL_LENS_API_KEY. */
+    apiKey?: string;
+    /** Default project id used when a call site doesn't pass one explicitly.
+     *  Defaults to DATAGOL_LENS_PROJECT_ID. */
+    projectId?: string;
+    /** Override fetch (e.g. for tests). Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** Minimal HTTP client for the Datagol Lens tracing API. Authenticates with a
+ *  project-scoped API key only — this SDK is meant for server-side/agent
+ *  tracing (see app/auth.py's get_trace_actor), not interactive human use, so
+ *  it deliberately doesn't support the user-JWT login flow the Python SDK's
+ *  DatagolLensClient predates this one with. */
+export declare class DatagolLensClient {
+    readonly apiUrl: string;
+    readonly apiKey: string;
+    readonly projectId: string | undefined;
+    private readonly fetchImpl;
+    constructor(options?: DatagolLensClientOptions);
+    /** POST one trace (with its spans nested inline). Throws on a non-2xx response. */
+    postTrace(trace: TraceCreate, projectId?: string | undefined): Promise<TraceOut>;
+    /** Check a company (and optionally a user and agent) against its Lens budgets
+     *  before starting a run. Throws LensRequestError on any failure, so the
+     *  caller decides whether to fail open or closed. */
+    checkBudget(request: {
+        companyId: string;
+        userId?: string;
+        agentKey?: string;
+        scopes?: Record<string, string>;
+    }, projectId?: string | undefined, timeoutMs?: number): Promise<BudgetCheckResponse>;
+    /** The company ids with budget enforcement on, so callers can skip the check
+     *  for everyone else. Throws LensRequestError on any failure. */
+    getEnforcedCompanies(projectId?: string | undefined, timeoutMs?: number): Promise<EnforcedCompanies>;
+    private requestJson;
+}

package/dist/client.js

@@ -0,0 +1,104 @@
+/** A Lens API call failed: network error, timeout, non-2xx status or a bad body.
+ *  `status` is set when the server answered with a non-2xx status. */
+export class LensRequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "LensRequestError";
+    }
+}
+/** Thrown by callers when a budget check blocks a request; `budget` is the
+ *  check's `blocked_by`. */
+export class BudgetExceeded extends Error {
+    result;
+    budget;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = "BudgetExceeded";
+        this.budget = result?.blocked_by ?? null;
+    }
+}
+/** Minimal HTTP client for the Datagol Lens tracing API. Authenticates with a
+ *  project-scoped API key only — this SDK is meant for server-side/agent
+ *  tracing (see app/auth.py's get_trace_actor), not interactive human use, so
+ *  it deliberately doesn't support the user-JWT login flow the Python SDK's
+ *  DatagolLensClient predates this one with. */
+export class DatagolLensClient {
+    apiUrl;
+    apiKey;
+    projectId;
+    fetchImpl;
+    constructor(options = {}) {
+        this.apiUrl = (options.apiUrl ?? process.env["DATAGOL_LENS_API_URL"] ?? "http://localhost:8000").replace(/\/+$/, "");
+        this.apiKey = options.apiKey ?? process.env["DATAGOL_LENS_API_KEY"] ?? "";
+        this.projectId = options.projectId ?? process.env["DATAGOL_LENS_PROJECT_ID"];
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        if (!this.apiKey) {
+            throw new Error("DatagolLensClient requires an API key (a project-scoped `dgl_...` key — mint one via " +
+                "POST /api/v1/projects/{project_id}/api-keys). Pass `apiKey` or set DATAGOL_LENS_API_KEY.");
+        }
+    }
+    /** POST one trace (with its spans nested inline). Throws on a non-2xx response. */
+    async postTrace(trace, projectId = this.projectId) {
+        if (!projectId) {
+            throw new Error("postTrace requires a projectId (constructor `projectId` option or a per-call argument).");
+        }
+        const res = await this.fetchImpl(`${this.apiUrl}/api/v1/projects/${projectId}/traces`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(trace),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`DatagolLensClient.postTrace failed: ${res.status} ${res.statusText} ${body}`);
+        }
+        return (await res.json());
+    }
+    /** Check a company (and optionally a user and agent) against its Lens budgets
+     *  before starting a run. Throws LensRequestError on any failure, so the
+     *  caller decides whether to fail open or closed. */
+    async checkBudget(request, projectId = this.projectId, timeoutMs = 2000) {
+        const body = {
+            company_id: request.companyId,
+            user_id: request.userId ?? null,
+            agent_key: request.agentKey ?? null,
+            ...(request.scopes ? { scopes: request.scopes } : {}),
+        };
+        return this.requestJson("POST", projectId, "budget/check", timeoutMs, body);
+    }
+    /** The company ids with budget enforcement on, so callers can skip the check
+     *  for everyone else. Throws LensRequestError on any failure. */
+    async getEnforcedCompanies(projectId = this.projectId, timeoutMs = 2000) {
+        return this.requestJson("GET", projectId, "budget/enforced-companies", timeoutMs);
+    }
+    async requestJson(method, projectId, path, timeoutMs, body) {
+        if (!projectId)
+            throw new LensRequestError(`${path} requires a projectId`);
+        const url = `${this.apiUrl}/api/v1/projects/${projectId}/${path}`;
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers: { "content-type": "application/json", authorization: `Bearer ${this.apiKey}` },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            throw new LensRequestError(`${method} ${path} failed: ${err.message}`);
+        }
+        if (!res.ok)
+            throw new LensRequestError(`${method} ${path} returned ${res.status}`, res.status);
+        try {
+            return (await res.json());
+        }
+        catch {
+            throw new LensRequestError(`${method} ${path} returned a body that isn't JSON`, res.status);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BudgetExceeded, DatagolLensClient, LensRequestError } from "./client.js";
+export type { DatagolLensClientOptions } from "./client.js";
+export { TraceBuilder } from "./tracer.js";
+export type { AddSpanOptions, TraceBuilderOptions } from "./tracer.js";
+export type { BudgetCheckRequest, BudgetCheckResponse, BudgetStatus, BudgetWindow, EnforcedCompanies, SpanCreate, SpanOut, SpanType, TraceCreate, TraceOut, TraceStatus, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BudgetExceeded, DatagolLensClient, LensRequestError } from "./client.js";
+export { TraceBuilder } from "./tracer.js";

package/dist/tracer.d.ts

@@ -0,0 +1,70 @@
+import type { DatagolLensClient } from "./client.js";
+import type { SpanType, TraceOut, TraceStatus } from "./types.js";
+export interface TraceBuilderOptions {
+    name: string;
+    input?: Record<string, unknown>;
+    tags?: string[] | Record<string, string>;
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    externalUserId?: string;
+    /** Budget attribution (see TraceCreate.company_id). */
+    companyId?: string;
+    agentKey?: string;
+    agentName?: string;
+}
+export interface AddSpanOptions {
+    /** Defaults to a fresh UUID. The returned id is what `parentId` should reference. */
+    id?: string;
+    name: string;
+    spanType?: SpanType;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown> | null;
+    model?: string | null;
+    promptTokens?: number;
+    completionTokens?: number;
+    /** Defaults to promptTokens + completionTokens when omitted. */
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    /** True when the cache counts are already inside promptTokens (OpenAI shape). */
+    cacheTokensInPrompt?: boolean;
+    status?: "ok" | "error";
+    error?: string | null;
+    cost?: number;
+    latencyMs?: number;
+    /** Defaults to `now - latencyMs` (spans are usually added right after the
+     *  operation finishes, so "now" is the end time). */
+    startTime?: Date;
+    endTime?: Date;
+    metadata?: Record<string, unknown>;
+    parentId?: string;
+}
+/**
+ * Accumulates spans client-side, then ships one Trace (with nested spans) in a
+ * single POST — the same "collect, then flush" shape as the Python SDK's
+ * TraceContext, adapted for explicit `.flush()` instead of a `with` block
+ * (call it from a `finally`/`agent_settled`-style hook so it always runs).
+ */
+export declare class TraceBuilder {
+    private readonly client;
+    private readonly options;
+    /** Sent with the trace so a retried flush is idempotent on the server. */
+    readonly id: string;
+    private readonly startedAt;
+    private readonly spans;
+    private output;
+    private error;
+    private model;
+    private totalTokens;
+    private promptTokens;
+    private completionTokens;
+    private totalCost;
+    private flushed;
+    constructor(client: DatagolLensClient, options: TraceBuilderOptions);
+    addSpan(span: AddSpanOptions): string;
+    setOutput(output: Record<string, unknown>): void;
+    setError(error: string): void;
+    /** Idempotent — safe to call more than once; only the first call ships anything. */
+    flush(status?: TraceStatus, projectId?: string): Promise<TraceOut | undefined>;
+}

package/dist/tracer.js

@@ -0,0 +1,113 @@
+function newId() {
+    const c = globalThis.crypto;
+    return c?.randomUUID ? c.randomUUID() : `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+/**
+ * Accumulates spans client-side, then ships one Trace (with nested spans) in a
+ * single POST — the same "collect, then flush" shape as the Python SDK's
+ * TraceContext, adapted for explicit `.flush()` instead of a `with` block
+ * (call it from a `finally`/`agent_settled`-style hook so it always runs).
+ */
+export class TraceBuilder {
+    client;
+    options;
+    /** Sent with the trace so a retried flush is idempotent on the server. */
+    id = newId();
+    startedAt = new Date();
+    spans = [];
+    output = null;
+    error = null;
+    model;
+    totalTokens = 0;
+    promptTokens = 0;
+    completionTokens = 0;
+    totalCost = 0;
+    flushed = false;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+    }
+    addSpan(span) {
+        const id = span.id ?? newId();
+        const latencyMs = span.latencyMs;
+        const endTime = span.endTime ?? new Date();
+        const startTime = span.startTime ?? (latencyMs !== undefined ? new Date(endTime.getTime() - latencyMs) : endTime);
+        const totalTokens = span.totalTokens ?? (span.promptTokens ?? 0) + (span.completionTokens ?? 0);
+        const cost = span.cost ?? 0;
+        this.spans.push({
+            id,
+            name: span.name,
+            span_type: span.spanType ?? "llm",
+            input: span.input ?? {},
+            output: span.output ?? null,
+            model: span.model ?? null,
+            total_tokens: totalTokens,
+            prompt_tokens: span.promptTokens ?? 0,
+            completion_tokens: span.completionTokens ?? 0,
+            cache_read_tokens: span.cacheReadTokens ?? 0,
+            cache_write_tokens: span.cacheWriteTokens ?? 0,
+            reasoning_tokens: span.reasoningTokens ?? 0,
+            cache_tokens_in_prompt: span.cacheTokensInPrompt ?? false,
+            status: span.status ?? (span.error ? "error" : "ok"),
+            error: span.error ?? null,
+            cost,
+            latency_ms: latencyMs,
+            start_time: startTime.toISOString(),
+            end_time: endTime.toISOString(),
+            metadata: span.metadata ?? {},
+            parent_id: span.parentId,
+        });
+        this.totalTokens += totalTokens;
+        this.promptTokens += span.promptTokens ?? 0;
+        this.completionTokens += span.completionTokens ?? 0;
+        this.totalCost += cost;
+        if (span.model)
+            this.model = span.model;
+        return id;
+    }
+    setOutput(output) {
+        this.output = output;
+    }
+    setError(error) {
+        this.error = error;
+    }
+    /** Idempotent — safe to call more than once; only the first call ships anything. */
+    async flush(status, projectId) {
+        if (this.flushed)
+            return undefined;
+        this.flushed = true;
+        const now = new Date();
+        const trace = {
+            id: this.id,
+            name: this.options.name,
+            input: this.options.input ?? {},
+            output: this.output,
+            error: this.error,
+            start_time: this.startedAt.toISOString(),
+            end_time: now.toISOString(),
+            latency_ms: now.getTime() - this.startedAt.getTime(),
+            total_tokens: this.totalTokens,
+            prompt_tokens: this.promptTokens,
+            completion_tokens: this.completionTokens,
+            total_cost: this.totalCost,
+            model: this.model,
+            status: status ?? (this.error ? "error" : "success"),
+            tags: this.options.tags ?? [],
+            metadata: this.options.metadata ?? {},
+            external_user_id: this.options.externalUserId,
+            session_id: this.options.sessionId,
+            company_id: this.options.companyId,
+            agent_key: this.options.agentKey,
+            agent_name: this.options.agentName,
+            spans: this.spans,
+        };
+        try {
+            return await this.client.postTrace(trace, projectId);
+        }
+        catch {
+            // Never let a tracing failure crash the caller — matches the Python SDK's
+            // TraceContext._flush, which also swallows post_trace errors.
+            return undefined;
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Wire types for the Datagol Lens tracing API. Mirror backend/app/schemas.py's
+ * SpanCreate/SpanOut/TraceCreate/TraceOut — keep these two in sync by hand (no
+ * shared codegen between the Python backend and this package yet).
+ */
+export type SpanType = "llm" | "tool" | "agent" | "retriever" | "workflow" | "guardrail" | "routing_attempt";
+export type TraceStatus = "running" | "success" | "error";
+export interface SpanCreate {
+    /** Optional client id so `parent_id` can reference a sibling span. */
+    id?: string;
+    name: string;
+    span_type?: SpanType;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown> | null;
+    /** ISO 8601. Omit to let the server default to "now". */
+    start_time?: string;
+    end_time?: string;
+    latency_ms?: number;
+    total_tokens?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+    reasoning_tokens?: number;
+    /** True when the cache counts are already inside prompt_tokens (OpenAI shape). */
+    cache_tokens_in_prompt?: boolean;
+    cost?: number;
+    model?: string | null;
+    status?: "ok" | "error";
+    error?: string | null;
+    recovered?: boolean;
+    metadata?: Record<string, unknown>;
+    parent_id?: string | null;
+    redacted?: boolean;
+    redacted_fields?: number;
+}
+export interface SpanOut {
+    id: string;
+    trace_id: string;
+    parent_id: string | null;
+    name: string;
+    span_type: SpanType;
+    input: unknown;
+    output: unknown;
+    start_time: string;
+    end_time: string | null;
+    latency_ms: number | null;
+    total_tokens: number;
+    cost: number;
+    model: string | null;
+    redacted: boolean;
+    redacted_fields: number;
+}
+export interface TraceCreate {
+    /** Client id; re-posting it is idempotent on the server. */
+    id?: string;
+    name: string;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown> | null;
+    error?: string | null;
+    start_time?: string;
+    end_time?: string;
+    latency_ms?: number;
+    total_tokens?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_cost?: number;
+    model?: string | null;
+    status?: TraceStatus;
+    /** Flat labels (["chat", "production"]) or key-value tags (e.g.
+     *  { user_id, user_email }) — Datagol Lens's grouped trace view groups by
+     *  a tag key, so key-value tags are what make a trace groupable. */
+    tags?: string[] | Record<string, string>;
+    metadata?: Record<string, unknown>;
+    /** The end-user of the *calling application* (e.g. the DataGOL platform user
+     *  running the agent) — not the tracing credential. Use this + session_id to
+     *  answer "who ran what" for a given trace. */
+    external_user_id?: string | null;
+    session_id?: string | null;
+    /** Budget attribution: the calling platform's company id (e.g. a DataGOL
+     *  companyId), and the agent's stable key and display name. Lens counts the
+     *  trace's cost against that company, agent and external_user_id. */
+    company_id?: string | null;
+    agent_key?: string | null;
+    agent_name?: string | null;
+    virtual_key_id?: string | null;
+    redacted?: boolean;
+    redacted_fields?: number;
+    blocked?: boolean;
+    guardrail_violations?: Record<string, unknown>[];
+    spans?: SpanCreate[];
+}
+export interface TraceOut {
+    id: string;
+    project_id: string;
+    name: string;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    start_time: string;
+    end_time: string | null;
+    latency_ms: number | null;
+    total_tokens: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_cost: number;
+    model: string | null;
+    status: TraceStatus;
+    tags: unknown;
+    external_user_id: string | null;
+    session_id: string | null;
+    virtual_key_id: string | null;
+    redacted: boolean;
+    redacted_fields: number;
+    blocked: boolean;
+    guardrail_violations: unknown;
+    created_at: string;
+    spans: SpanOut[];
+}
+export type BudgetWindow = "hourly" | "daily" | "monthly";
+/** POST /api/v1/projects/{project_id}/budget/check body. */
+export interface BudgetCheckRequest {
+    company_id: string;
+    user_id?: string | null;
+    agent_key?: string | null;
+    /** Values for any other scope type, by its id (e.g. { model: "gpt-4o" }). */
+    scopes?: Record<string, string>;
+}
+export interface BudgetStatus {
+    budget_id: string;
+    scope_type: string;
+    scope_external_id: string | null;
+    window: BudgetWindow;
+    limit_usd: number;
+    spent_usd: number;
+    warn_at_pct: number;
+    /** ISO 8601 UTC. */
+    resets_at: string;
+}
+export interface BudgetCheckResponse {
+    allowed: boolean;
+    decision: "allow" | "warn" | "block";
+    blocked_by: BudgetStatus | null;
+    warnings: BudgetStatus[];
+}
+export interface EnforcedCompanies {
+    company_ids: string[];
+    version: string;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Wire types for the Datagol Lens tracing API. Mirror backend/app/schemas.py's
+ * SpanCreate/SpanOut/TraceCreate/TraceOut — keep these two in sync by hand (no
+ * shared codegen between the Python backend and this package yet).
+ */
+export {};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@datagol/lens-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Node/TypeScript SDK for DataGOL Lens: trace LLM calls and agent tool spans, attribute cost, check budgets.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "homepage": "https://datagol.ai",
+  "keywords": [
+    "llm",
+    "observability",
+    "tracing",
+    "datagol"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/client.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}