@lmnr-ai/client 0.8.27 → 0.8.29

package/dist/index.d.cts

@@ -1,11 +1,34 @@
-import { Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
+import { CachedSpan, Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
 
 //#region src/resources/index.d.ts
+/**
+ * Unified auth for every resource. A discriminated union so a single object
+ * drives both the URL prefix and the request headers:
+ *
+ *  - `apiKey`    → project API key (SDK / app surfaces). Routes to `/v1/*`,
+ *    Bearer is the project key, no `x-lmnr-project-id` header.
+ *  - `userToken` → BetterAuth user access JWT (the CLI user-token surface).
+ *    Routes to `/v1/cli/*`, Bearer is the JWT, carries the target project in
+ *    the `x-lmnr-project-id` header.
+ */
+type LaminarAuth = {
+  type: "apiKey";
+  key: string;
+} | {
+  type: "userToken";
+  token: string;
+  projectId: string;
+};
 declare class BaseResource {
   protected readonly baseHttpUrl: string;
-  protected readonly projectApiKey: string;
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  protected readonly auth: LaminarAuth;
+  /** The bearer credential, regardless of auth type (project key or user JWT). */
+  protected readonly credential: string;
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
+  /** API path prefix: `/v1/cli` for CLI user-token auth, `/v1` otherwise. */
+  protected get apiPrefix(): string;
   protected headers(): {
+    "x-lmnr-project-id"?: string | undefined;
     Authorization: string;
     "Content-Type": string;
     Accept: string;
@@ -15,7 +38,7 @@ declare class BaseResource {
 //#endregion
 //#region src/resources/browser-events.d.ts
 declare class BrowserEventsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   send({
     sessionId,
     traceId,
@@ -27,9 +50,31 @@ declare class BrowserEventsResource extends BaseResource {
   }): Promise<void>;
 }
 //#endregion
+//#region src/resources/cli.d.ts
+interface CliProject {
+  id: string;
+  name: string;
+  workspaceId: string;
+  workspaceName: string;
+}
+/**
+ * User-scoped CLI endpoints that don't target a specific project. Authed by the
+ * BetterAuth user JWT (the `credential`); deliberately does NOT send an
+ * `x-lmnr-project-id` header (these routes are project discovery, pre-selection).
+ *
+ * Discovery exception: this resource always hits `/v1/cli/projects` with the
+ * bare bearer and overrides `BaseResource.headers()`/`apiPrefix`, so it works
+ * even when constructed with a `userToken` auth that has no real project id yet.
+ */
+declare class CliResource extends BaseResource {
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
+  /** Workspaces + projects the authenticated user can access. */
+  listProjects(): Promise<CliProject[]>;
+}
+//#endregion
 //#region src/resources/datasets.d.ts
 declare class DatasetsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * List all datasets.
    *
@@ -92,7 +137,7 @@ declare class DatasetsResource extends BaseResource {
 //#endregion
 //#region src/resources/evals.d.ts
 declare class EvalsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Initialize an evaluation.
    *
@@ -224,7 +269,7 @@ type ScoreOptions = {
  * Resource for creating evaluator scores
  */
 declare class EvaluatorsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Create a score for a span or trace
    *
@@ -257,8 +302,26 @@ declare class EvaluatorsResource extends BaseResource {
 }
 //#endregion
 //#region src/resources/rollout-sessions.d.ts
+/**
+ * Result of a debug-replay cache lookup (debug-replay v2).
+ *
+ *  - `hit`  — the server served a cached response for this input hash; replay it
+ *             and mark the span CACHED.
+ *  - `miss` — no cache entry; the caller latches process-wide live mode and runs
+ *             every subsequent call live.
+ *  - `live` — run THIS call live without latching (server COLD warmup-timeout
+ *             degrade, or any non-OK / transport error here).
+ */
+type CacheOutcome = {
+  kind: "hit";
+  cached: CachedSpan;
+} | {
+  kind: "miss";
+} | {
+  kind: "live";
+};
 declare class RolloutSessionsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Idempotently register (upsert) a debug session on the backend, keyed on the
    * SDK-supplied session id. The backend stores the row so the session is
@@ -287,6 +350,31 @@ declare class RolloutSessionsResource extends BaseResource {
     sessionId: string;
     name: string;
   }): Promise<void>;
+  /**
+   * Look up the debug-replay cache for a single LLM call (debug-replay v2).
+   *
+   * The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+   * system-stripped input messages). It returns one of three outcomes:
+   *   - `{ outcome: "hit", response }` — a cached response to replay.
+   *   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+   *   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+   *
+   * Error posture: a non-OK response or a transport error degrades to
+   * `{ kind: "live" }` for THIS call only — it never throws and never latches
+   * the process-wide live flag (only a real MISS does that). This keeps a flaky
+   * cache backend from turning a replay into a crash.
+   */
+  cache({
+    sessionId,
+    replayTraceId,
+    cacheUntil,
+    inputHash
+  }: {
+    sessionId: string;
+    replayTraceId: string;
+    cacheUntil: string;
+    inputHash: string;
+  }): Promise<CacheOutcome>;
   delete({
     sessionId
   }: {
@@ -296,14 +384,14 @@ declare class RolloutSessionsResource extends BaseResource {
 //#endregion
 //#region src/resources/sql.d.ts
 declare class SqlResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   query(sql: string, parameters?: Record<string, any>): Promise<Array<Record<string, any>>>;
 }
 //#endregion
 //#region src/resources/tags.d.ts
 declare class TagsResource extends BaseResource {
   /** Resource for tagging traces. */
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Tag a trace with a list of tags. Note that the trace must be ended before
    * tagging it. You may want to call `await Laminar.flush()` after the trace
@@ -342,7 +430,7 @@ declare class TagsResource extends BaseResource {
 //#region src/resources/traces.d.ts
 declare class TracesResource extends BaseResource {
   /** Resource for post-factum operations on existing traces. */
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Push a metadata patch to an existing trace.
    *
@@ -401,8 +489,9 @@ declare class TracesResource extends BaseResource {
 //#region src/index.d.ts
 declare class LaminarClient {
   private baseUrl;
-  private projectApiKey;
+  private auth;
   private _browserEvents;
+  private _cli;
   private _datasets;
   private _evals;
   private _evaluators;
@@ -412,14 +501,45 @@ declare class LaminarClient {
   private _traces;
   constructor({
     baseUrl,
+    port,
+    auth,
     projectApiKey,
-    port
+    cliUserProjectId
   }?: {
     baseUrl?: string;
-    projectApiKey?: string;
     port?: number;
+    /**
+     * Unified auth. A discriminated union that drives both the URL prefix and
+     * the request headers:
+     *  - `{ type: "apiKey", key }`               → project key, `/v1/*`.
+     *  - `{ type: "userToken", token, projectId }` → user JWT, `/v1/cli/*` with
+     *    `x-lmnr-project-id`.
+     * When omitted, the legacy `projectApiKey` / `cliUserProjectId` fields (or
+     * `LMNR_PROJECT_API_KEY`) are normalized into this union.
+     */
+    auth?: LaminarAuth;
+    /**
+     * @deprecated Pass `auth: { type: "apiKey", key }` instead. Kept for
+     * backward compatibility — normalized into the unified `auth` union.
+     */
+    projectApiKey?: string;
+    /**
+     * @deprecated Pass `auth: { type: "userToken", token, projectId }` instead.
+     * Kept for backward compatibility: when set, the legacy `projectApiKey` is
+     * treated as a user JWT and routes to `/v1/cli/*` with this project id.
+     */
+    cliUserProjectId?: string;
   });
+  /**
+   * Normalize the constructor's auth inputs into a {@link LaminarAuth} union.
+   * Precedence: an explicit `auth` wins; otherwise the legacy
+   * `projectApiKey` (+ optional `cliUserProjectId`) is mapped — a present
+   * `cliUserProjectId` selects the user-token surface, otherwise the project
+   * key surface. Falls back to `LMNR_PROJECT_API_KEY` as a project key.
+   */
+  private static normalizeAuth;
   get browserEvents(): BrowserEventsResource;
+  get cli(): CliResource;
   get datasets(): DatasetsResource;
   get evals(): EvalsResource;
   get evaluators(): EvaluatorsResource;
@@ -429,5 +549,5 @@ declare class LaminarClient {
   get traces(): TracesResource;
 }
 //#endregion
-export { LaminarClient };
+export { type CacheOutcome, type CliProject, type LaminarAuth, LaminarClient, RolloutSessionsResource };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,11 +1,34 @@
-import { Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
+import { CachedSpan, Datapoint, Dataset, EvaluationDatapoint, GetDatapointsResponse, InitEvaluationResponse, PushDatapointsResponse, StringUUID } from "@lmnr-ai/types";
 
 //#region src/resources/index.d.ts
+/**
+ * Unified auth for every resource. A discriminated union so a single object
+ * drives both the URL prefix and the request headers:
+ *
+ *  - `apiKey`    → project API key (SDK / app surfaces). Routes to `/v1/*`,
+ *    Bearer is the project key, no `x-lmnr-project-id` header.
+ *  - `userToken` → BetterAuth user access JWT (the CLI user-token surface).
+ *    Routes to `/v1/cli/*`, Bearer is the JWT, carries the target project in
+ *    the `x-lmnr-project-id` header.
+ */
+type LaminarAuth = {
+  type: "apiKey";
+  key: string;
+} | {
+  type: "userToken";
+  token: string;
+  projectId: string;
+};
 declare class BaseResource {
   protected readonly baseHttpUrl: string;
-  protected readonly projectApiKey: string;
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  protected readonly auth: LaminarAuth;
+  /** The bearer credential, regardless of auth type (project key or user JWT). */
+  protected readonly credential: string;
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
+  /** API path prefix: `/v1/cli` for CLI user-token auth, `/v1` otherwise. */
+  protected get apiPrefix(): string;
   protected headers(): {
+    "x-lmnr-project-id"?: string | undefined;
     Authorization: string;
     "Content-Type": string;
     Accept: string;
@@ -15,7 +38,7 @@ declare class BaseResource {
 //#endregion
 //#region src/resources/browser-events.d.ts
 declare class BrowserEventsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   send({
     sessionId,
     traceId,
@@ -27,9 +50,31 @@ declare class BrowserEventsResource extends BaseResource {
   }): Promise<void>;
 }
 //#endregion
+//#region src/resources/cli.d.ts
+interface CliProject {
+  id: string;
+  name: string;
+  workspaceId: string;
+  workspaceName: string;
+}
+/**
+ * User-scoped CLI endpoints that don't target a specific project. Authed by the
+ * BetterAuth user JWT (the `credential`); deliberately does NOT send an
+ * `x-lmnr-project-id` header (these routes are project discovery, pre-selection).
+ *
+ * Discovery exception: this resource always hits `/v1/cli/projects` with the
+ * bare bearer and overrides `BaseResource.headers()`/`apiPrefix`, so it works
+ * even when constructed with a `userToken` auth that has no real project id yet.
+ */
+declare class CliResource extends BaseResource {
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
+  /** Workspaces + projects the authenticated user can access. */
+  listProjects(): Promise<CliProject[]>;
+}
+//#endregion
 //#region src/resources/datasets.d.ts
 declare class DatasetsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * List all datasets.
    *
@@ -92,7 +137,7 @@ declare class DatasetsResource extends BaseResource {
 //#endregion
 //#region src/resources/evals.d.ts
 declare class EvalsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Initialize an evaluation.
    *
@@ -224,7 +269,7 @@ type ScoreOptions = {
  * Resource for creating evaluator scores
  */
 declare class EvaluatorsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Create a score for a span or trace
    *
@@ -257,8 +302,26 @@ declare class EvaluatorsResource extends BaseResource {
 }
 //#endregion
 //#region src/resources/rollout-sessions.d.ts
+/**
+ * Result of a debug-replay cache lookup (debug-replay v2).
+ *
+ *  - `hit`  — the server served a cached response for this input hash; replay it
+ *             and mark the span CACHED.
+ *  - `miss` — no cache entry; the caller latches process-wide live mode and runs
+ *             every subsequent call live.
+ *  - `live` — run THIS call live without latching (server COLD warmup-timeout
+ *             degrade, or any non-OK / transport error here).
+ */
+type CacheOutcome = {
+  kind: "hit";
+  cached: CachedSpan;
+} | {
+  kind: "miss";
+} | {
+  kind: "live";
+};
 declare class RolloutSessionsResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Idempotently register (upsert) a debug session on the backend, keyed on the
    * SDK-supplied session id. The backend stores the row so the session is
@@ -287,6 +350,31 @@ declare class RolloutSessionsResource extends BaseResource {
     sessionId: string;
     name: string;
   }): Promise<void>;
+  /**
+   * Look up the debug-replay cache for a single LLM call (debug-replay v2).
+   *
+   * The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+   * system-stripped input messages). It returns one of three outcomes:
+   *   - `{ outcome: "hit", response }` — a cached response to replay.
+   *   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+   *   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+   *
+   * Error posture: a non-OK response or a transport error degrades to
+   * `{ kind: "live" }` for THIS call only — it never throws and never latches
+   * the process-wide live flag (only a real MISS does that). This keeps a flaky
+   * cache backend from turning a replay into a crash.
+   */
+  cache({
+    sessionId,
+    replayTraceId,
+    cacheUntil,
+    inputHash
+  }: {
+    sessionId: string;
+    replayTraceId: string;
+    cacheUntil: string;
+    inputHash: string;
+  }): Promise<CacheOutcome>;
   delete({
     sessionId
   }: {
@@ -296,14 +384,14 @@ declare class RolloutSessionsResource extends BaseResource {
 //#endregion
 //#region src/resources/sql.d.ts
 declare class SqlResource extends BaseResource {
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   query(sql: string, parameters?: Record<string, any>): Promise<Array<Record<string, any>>>;
 }
 //#endregion
 //#region src/resources/tags.d.ts
 declare class TagsResource extends BaseResource {
   /** Resource for tagging traces. */
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Tag a trace with a list of tags. Note that the trace must be ended before
    * tagging it. You may want to call `await Laminar.flush()` after the trace
@@ -342,7 +430,7 @@ declare class TagsResource extends BaseResource {
 //#region src/resources/traces.d.ts
 declare class TracesResource extends BaseResource {
   /** Resource for post-factum operations on existing traces. */
-  constructor(baseHttpUrl: string, projectApiKey: string);
+  constructor(baseHttpUrl: string, auth: LaminarAuth);
   /**
    * Push a metadata patch to an existing trace.
    *
@@ -401,8 +489,9 @@ declare class TracesResource extends BaseResource {
 //#region src/index.d.ts
 declare class LaminarClient {
   private baseUrl;
-  private projectApiKey;
+  private auth;
   private _browserEvents;
+  private _cli;
   private _datasets;
   private _evals;
   private _evaluators;
@@ -412,14 +501,45 @@ declare class LaminarClient {
   private _traces;
   constructor({
     baseUrl,
+    port,
+    auth,
     projectApiKey,
-    port
+    cliUserProjectId
   }?: {
     baseUrl?: string;
-    projectApiKey?: string;
     port?: number;
+    /**
+     * Unified auth. A discriminated union that drives both the URL prefix and
+     * the request headers:
+     *  - `{ type: "apiKey", key }`               → project key, `/v1/*`.
+     *  - `{ type: "userToken", token, projectId }` → user JWT, `/v1/cli/*` with
+     *    `x-lmnr-project-id`.
+     * When omitted, the legacy `projectApiKey` / `cliUserProjectId` fields (or
+     * `LMNR_PROJECT_API_KEY`) are normalized into this union.
+     */
+    auth?: LaminarAuth;
+    /**
+     * @deprecated Pass `auth: { type: "apiKey", key }` instead. Kept for
+     * backward compatibility — normalized into the unified `auth` union.
+     */
+    projectApiKey?: string;
+    /**
+     * @deprecated Pass `auth: { type: "userToken", token, projectId }` instead.
+     * Kept for backward compatibility: when set, the legacy `projectApiKey` is
+     * treated as a user JWT and routes to `/v1/cli/*` with this project id.
+     */
+    cliUserProjectId?: string;
   });
+  /**
+   * Normalize the constructor's auth inputs into a {@link LaminarAuth} union.
+   * Precedence: an explicit `auth` wins; otherwise the legacy
+   * `projectApiKey` (+ optional `cliUserProjectId`) is mapped — a present
+   * `cliUserProjectId` selects the user-token surface, otherwise the project
+   * key surface. Falls back to `LMNR_PROJECT_API_KEY` as a project key.
+   */
+  private static normalizeAuth;
   get browserEvents(): BrowserEventsResource;
+  get cli(): CliResource;
   get datasets(): DatasetsResource;
   get evals(): EvalsResource;
   get evaluators(): EvaluatorsResource;
@@ -429,5 +549,5 @@ declare class LaminarClient {
   get traces(): TracesResource;
 }
 //#endregion
-export { LaminarClient };
+export { type CacheOutcome, type CliProject, type LaminarAuth, LaminarClient, RolloutSessionsResource };
 //# sourceMappingURL=index.d.mts.map