@apo-ai/sdk 0.2.0

package/dist/chunk-SZDSIPXC.js

@@ -0,0 +1,74 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+import {
+  emitGenerationAndTools,
+  startGeneration
+} from "./chunk-GDB6SDGN.js";
+
+// src/agent-task/integrations/anthropic.ts
+function createApoAnthropic(client, options) {
+  const { trace, parentSpanId, taskId, turnNumber } = options;
+  const realCreate = client.messages.create.bind(client.messages);
+  const tracedCreate = async (...args) => {
+    const params = args[0] ?? {};
+    const model = String(params.model ?? "unknown");
+    if (params.stream === true) {
+      return realCreate(params);
+    }
+    const { spanId, startedAt } = startGeneration(trace, {
+      model,
+      system: typeof params.system === "string" ? params.system : void 0,
+      messages: params.messages,
+      parentSpanId,
+      taskId,
+      turnNumber
+    });
+    try {
+      const response = await realCreate(params);
+      const blocks = response.content ?? [];
+      const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+      const toolCalls = blocks.filter(
+        (b) => b.type === "tool_use"
+      ).map((b) => ({
+        name: b.name,
+        input: b.input
+      }));
+      emitGenerationAndTools(trace, spanId, startedAt, {
+        text: text || void 0,
+        promptTokens: response.usage?.input_tokens,
+        completionTokens: response.usage?.output_tokens,
+        toolCalls,
+        taskId,
+        turnNumber
+      });
+      return response;
+    } catch (error) {
+      emitGenerationAndTools(trace, spanId, startedAt, {
+        taskId,
+        turnNumber,
+        error: { message: error instanceof Error ? error.message : String(error) }
+      });
+      throw error;
+    }
+  };
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop === "messages") {
+        return new Proxy(target.messages, {
+          get(messagesTarget, messagesProp) {
+            if (messagesProp === "create") {
+              return tracedCreate;
+            }
+            return Reflect.get(messagesTarget, messagesProp);
+          }
+        });
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+
+export {
+  createApoAnthropic
+};
+//# sourceMappingURL=chunk-SZDSIPXC.js.map

package/dist/chunk-SZDSIPXC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent-task/integrations/anthropic.ts"],"sourcesContent":["/**\n * Anthropic JS SDK tracing integration for apo.\n *\n * Wraps an `Anthropic` client so `messages.create()` calls are\n * automatically traced. Tool calls and generations are captured without\n * any manual span code in the adapter.\n *\n * @example\n * ```ts\n * import Anthropic from \"@anthropic-ai/sdk\";\n * import { createApoAnthropic } from \"@apo-ai/sdk/agent-task\";\n *\n * async sendUserTurn(turn, { trace, parentSpanId }) {\n *   const client = createApoAnthropic(\n *     new Anthropic({ apiKey }),\n *     { trace, parentSpanId, taskId: ctx.task.id, turnNumber }\n *   );\n *   const response = await client.messages.create({\n *     model: \"claude-sonnet-4-20250514\",\n *     max_tokens: 1024,\n *     messages: [{ role: \"user\", content: String(turn) }],\n *     tools: [...],\n *   });\n *   const text = response.content.filter(b => b.type === \"text\").map(b => b.text).join(\"\");\n *   return { response: text };\n * }\n * ```\n *\n * @module\n */\n\nimport type { AgentTaskTraceContext } from \"../tracing.ts\";\nimport { startGeneration, emitGenerationAndTools } from \"./span-helpers.ts\";\n\nexport interface CreateApoAnthropicOptions {\n  /** The tee'd trace context from `sendUserTurn`'s second argument. */\n  trace: AgentTaskTraceContext;\n  /** The parent span id for this turn (from `sendUserTurn`'s context). */\n  parentSpanId?: string;\n  /** Optional task id, surfaced in span metadata. */\n  taskId?: string;\n  /** Optional turn number, surfaced in span metadata. */\n  turnNumber?: number;\n}\n\n/**\n * Minimal structural shape of the Anthropic client we intercept.\n */\ninterface AnthropicClientLike {\n  messages: {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    create: (...args: any[]) => Promise<any>;\n  };\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  [key: string]: any;\n}\n\n/**\n * The response shape we read from `messages.create()`.\n */\ninterface AnthropicResponseLike {\n  model?: string;\n  content?: Array<\n    | { type: \"text\"; text: string }\n    | { type: \"tool_use\"; name: string; input?: unknown }\n    | { type: string }\n  >;\n  usage?: {\n    input_tokens?: number;\n    output_tokens?: number;\n  };\n}\n\n/**\n * Wrap an Anthropic client so `messages.create()` is traced.\n * Returns a Proxy-wrapped client — call it exactly as you would the\n * original. Non-streaming only; streaming responses pass through\n * untraced.\n *\n * For SDKs that emit OpenTelemetry natively (Claude Agent SDK, Vercel AI\n * SDK), prefer `configureApoTelemetry()` instead — no wrapper needed.\n * This manual wrapper is for the raw `@anthropic-ai/sdk` package or\n * custom clients that don't emit OTel on their own.\n */\nexport function createApoAnthropic<T extends AnthropicClientLike>(\n  client: T,\n  options: CreateApoAnthropicOptions,\n): T {\n  const { trace, parentSpanId, taskId, turnNumber } = options;\n  const realCreate = client.messages.create.bind(client.messages);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const tracedCreate = async (...args: any[]): Promise<any> => {\n    const params = (args[0] ?? {}) as Record<string, unknown>;\n    const model = String(params.model ?? \"unknown\");\n\n    // Non-streaming: trace fully. Streaming (stream: true): pass through.\n    if (params.stream === true) {\n      return realCreate(params);\n    }\n\n    const { spanId, startedAt } = startGeneration(trace, {\n      model,\n      system: typeof params.system === \"string\" ? params.system : undefined,\n      messages: params.messages,\n      parentSpanId,\n      taskId,\n      turnNumber,\n    });\n\n    try {\n      const response = (await realCreate(params)) as AnthropicResponseLike;\n      const blocks = response.content ?? [];\n      const text = blocks\n        .filter((b): b is { type: \"text\"; text: string } => b.type === \"text\")\n        .map((b) => b.text)\n        .join(\"\\n\");\n      const toolCalls = blocks\n        .filter(\n          (b): b is { type: \"tool_use\"; name: string; input?: unknown } =>\n            b.type === \"tool_use\",\n        )\n        .map((b) => ({\n          name: b.name,\n          input: b.input,\n        }));\n\n      emitGenerationAndTools(trace, spanId, startedAt, {\n        text: text || undefined,\n        promptTokens: response.usage?.input_tokens,\n        completionTokens: response.usage?.output_tokens,\n        toolCalls,\n        taskId,\n        turnNumber,\n      });\n\n      return response;\n    } catch (error) {\n      emitGenerationAndTools(trace, spanId, startedAt, {\n        taskId,\n        turnNumber,\n        error: { message: error instanceof Error ? error.message : String(error) },\n      });\n      throw error;\n    }\n  };\n\n  // Proxy that intercepts client.messages.create but passes\n  // everything else through unchanged.\n  return new Proxy(client, {\n    get(target, prop, receiver) {\n      if (prop === \"messages\") {\n        return new Proxy(target.messages, {\n          get(messagesTarget, messagesProp) {\n            if (messagesProp === \"create\") {\n              return tracedCreate;\n            }\n            return Reflect.get(messagesTarget, messagesProp);\n          },\n        });\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as T;\n}\n"],"mappings":";;;;;;;;AAoFO,SAAS,mBACd,QACA,SACG;AACH,QAAM,EAAE,OAAO,cAAc,QAAQ,WAAW,IAAI;AACpD,QAAM,aAAa,OAAO,SAAS,OAAO,KAAK,OAAO,QAAQ;AAG9D,QAAM,eAAe,UAAU,SAA8B;AAC3D,UAAM,SAAU,KAAK,CAAC,KAAK,CAAC;AAC5B,UAAM,QAAQ,OAAO,OAAO,SAAS,SAAS;AAG9C,QAAI,OAAO,WAAW,MAAM;AAC1B,aAAO,WAAW,MAAM;AAAA,IAC1B;AAEA,UAAM,EAAE,QAAQ,UAAU,IAAI,gBAAgB,OAAO;AAAA,MACnD;AAAA,MACA,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;AAAA,MAC5D,UAAU,OAAO;AAAA,MACjB;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,QAAI;AACF,YAAM,WAAY,MAAM,WAAW,MAAM;AACzC,YAAM,SAAS,SAAS,WAAW,CAAC;AACpC,YAAM,OAAO,OACV,OAAO,CAAC,MAA2C,EAAE,SAAS,MAAM,EACpE,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,IAAI;AACZ,YAAM,YAAY,OACf;AAAA,QACC,CAAC,MACC,EAAE,SAAS;AAAA,MACf,EACC,IAAI,CAAC,OAAO;AAAA,QACX,MAAM,EAAE;AAAA,QACR,OAAO,EAAE;AAAA,MACX,EAAE;AAEJ,6BAAuB,OAAO,QAAQ,WAAW;AAAA,QAC/C,MAAM,QAAQ;AAAA,QACd,cAAc,SAAS,OAAO;AAAA,QAC9B,kBAAkB,SAAS,OAAO;AAAA,QAClC;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAED,aAAO;AAAA,IACT,SAAS,OAAO;AACd,6BAAuB,OAAO,QAAQ,WAAW;AAAA,QAC/C;AAAA,QACA;AAAA,QACA,OAAO,EAAE,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE;AAAA,MAC3E,CAAC;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAIA,SAAO,IAAI,MAAM,QAAQ;AAAA,IACvB,IAAI,QAAQ,MAAM,UAAU;AAC1B,UAAI,SAAS,YAAY;AACvB,eAAO,IAAI,MAAM,OAAO,UAAU;AAAA,UAChC,IAAI,gBAAgB,cAAc;AAChC,gBAAI,iBAAiB,UAAU;AAC7B,qBAAO;AAAA,YACT;AACA,mBAAO,QAAQ,IAAI,gBAAgB,YAAY;AAAA,UACjD;AAAA,QACF,CAAC;AAAA,MACH;AACA,aAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;AAAA,IAC3C;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+export { b as ClientOptions, c as CreateScoreParams, C as CreateSpanParams, d as CreateTraceParams, E as EndSpanParams, I as IngestionEvent, O as ObservationContext, e as ObserveOptions, P as ParameterOverrides, f as TraceEventOptions, T as TraceRunContext, a as TraceRunOptions, g as TraceStepOptions } from './types-C-nrDEVf.js';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+
+type ClientErrorCode = "VALIDATION" | "HTTP" | "NETWORK" | "TIMEOUT" | "DECODE" | "UNKNOWN";
+declare const ClientError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ClientError";
+} & Readonly<A>;
+declare class ClientError extends ClientError_base<{
+    code: ClientErrorCode;
+    message: string;
+    status?: number;
+    body?: string;
+    retryable?: boolean;
+    cause?: unknown;
+}> {
+}
+declare const ConfigurationError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ConfigurationError";
+} & Readonly<A>;
+declare class ConfigurationError extends ConfigurationError_base<{
+    message: string;
+    suggestion?: string;
+}> {
+}
+
+/**
+ * Configuration management for apo SDK.
+ *
+ * Centralizes environment variable reading so all wrappers use the same logic.
+ */
+interface EnvConfig {
+    /** Backend endpoint URL */
+    endpoint: string;
+    /** Project name for optimization tracking */
+    project: string;
+    /**
+     * Public identifier for the two-key model. this is the
+     * ``pk-apo-*`` value, used as the Basic-auth username alongside
+     * ``secretKey``. It is NOT a usable credential on its own — the SDK
+     * never reads ``NEXT_PUBLIC_APO_PUBLIC_KEY`` because publishing a public
+     * identifier in a browser bundle creates a misleading direct-browser
+     * integration. Server-only.
+     */
+    publicKey?: string;
+    /** Secret key for two-key auth (server-only). */
+    secretKey?: string;
+    /** Legacy single-key auth token */
+    apiKey?: string;
+}
+/**
+ * Read optimizer configuration from environment variables.
+ *
+ * This function centralizes all environment variable reading for the SDK,
+ * ensuring consistent behavior across all wrapper functions.
+ *
+ * **Environment Variables (in order of priority):**
+ *
+ * For `endpoint`:
+ * - `NEXT_PUBLIC_APO_BACKEND_URL` (Next.js public env var)
+ * - `APO_BACKEND_URL` (standard env var)
+ * - Falls back to `http://localhost:8000`
+ *
+ * For `project`:
+ * - `APO_PROJECT` (standard env var)
+ * - `NEXT_PUBLIC_APO_PROJECT` (Next.js public env var)
+ * - Falls back to `default-project`
+ *
+ * For `publicKey`:
+ * - `APO_PUBLIC_KEY` (server-side public identifier; paired with
+ *   `APO_SECRET_KEY` to form HTTP Basic credentials). Support for `NEXT_PUBLIC_APO_PUBLIC_KEY` was removed:
+ *   the public identifier alone
+ *   does not authorize ingestion, so publishing it as a browser-safe env
+ *   var is actively misleading.
+ *
+ * For `secretKey`:
+ * - `APO_SECRET_KEY` (server-side only)
+ *
+ * For `apiKey` (legacy single-key auth):
+ * - `APO_API_KEY`
+ *
+ * @example
+ * ```ts
+ * import { readConfig } from "@apo-ai/sdk";
+ *
+ * const config = readConfig();
+ * console.log(config.endpoint); // "http://localhost:8000" or env value
+ * console.log(config.project);  // "default-project" or env value
+ * ```
+ *
+ * @returns Client configuration from environment
+ */
+declare function readConfig(): EnvConfig;
+
+export { ClientError, type ClientErrorCode, ConfigurationError, type EnvConfig, readConfig };

package/dist/index.js

@@ -0,0 +1,39 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+
+// src/errors.ts
+import { Data } from "effect";
+var ClientError = class extends Data.TaggedError("ClientError") {
+};
+var ValidationError = class extends Data.TaggedError("ValidationError") {
+};
+var NetworkError = class extends Data.TaggedError("NetworkError") {
+};
+var DecodeError = class extends Data.TaggedError("DecodeError") {
+};
+var TimeoutError = class extends Data.TaggedError("TimeoutError") {
+};
+var RegisterParametersError = class extends Data.TaggedError(
+  "RegisterParametersError"
+) {
+};
+var ConfigurationError = class extends Data.TaggedError("ConfigurationError") {
+};
+var RenderParameterError = class extends Data.TaggedError("RenderParameterError") {
+};
+
+// src/config.ts
+function readConfig() {
+  const endpoint = process.env.NEXT_PUBLIC_APO_BACKEND_URL ?? process.env.APO_BACKEND_URL ?? "http://localhost:8000";
+  const project = process.env.APO_PROJECT ?? process.env.NEXT_PUBLIC_APO_PROJECT ?? "default-project";
+  const publicKey = process.env.APO_PUBLIC_KEY;
+  const secretKey = process.env.APO_SECRET_KEY;
+  const apiKey = process.env.APO_API_KEY;
+  return { endpoint, project, publicKey, secretKey, apiKey };
+}
+export {
+  ClientError,
+  ConfigurationError,
+  readConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/config.ts"],"sourcesContent":["import { Data } from \"effect\";\n\nexport type ClientErrorCode =\n  | \"VALIDATION\"\n  | \"HTTP\"\n  | \"NETWORK\"\n  | \"TIMEOUT\"\n  | \"DECODE\"\n  | \"UNKNOWN\";\n\nexport class ClientError extends Data.TaggedError(\"ClientError\")<{\n  code: ClientErrorCode;\n  message: string;\n  status?: number;\n  body?: string;\n  retryable?: boolean;\n  cause?: unknown;\n}> {}\n\nexport class ValidationError extends Data.TaggedError(\"ValidationError\")<{}> {}\n\nexport class NetworkError extends Data.TaggedError(\"NetworkError\")<{\n  message: string;\n  cause?: unknown;\n}> {}\n\nexport class DecodeError extends Data.TaggedError(\"DecodeError\")<{\n  message: string;\n  cause?: unknown;\n}> {}\n\nexport class TimeoutError extends Data.TaggedError(\"TimeoutError\")<{\n  message: string;\n  cause?: unknown;\n}> {}\n\nexport class RegisterParametersError extends Data.TaggedError(\n  \"RegisterParametersError\"\n)<{\n  status: number;\n  body: string;\n}> {}\n\nexport class ConfigurationError extends Data.TaggedError(\"ConfigurationError\")<{\n  message: string;\n  suggestion?: string;\n}> {}\n\nconst asMessage = (e: unknown): string =>\n  e instanceof Error\n    ? e.message\n    : typeof e === \"string\"\n    ? e\n    : JSON.stringify(e);\n\nexport const normalizeError = (e: unknown): ClientError => {\n  if (e instanceof ValidationError) {\n    return new ClientError({\n      code: \"VALIDATION\",\n      message: \"Invalid parameter definitions (flowName mismatch / missing).\",\n      cause: e,\n    });\n  }\n\n  if (e instanceof ConfigurationError) {\n    return new ClientError({\n      code: \"VALIDATION\",\n      message: e.message,\n      cause: e,\n    });\n  }\n\n  if (e instanceof RegisterParametersError) {\n    return new ClientError({\n      code: \"HTTP\",\n      message: `Parameter registration failed (HTTP ${e.status}).`,\n      status: e.status,\n      body: e.body,\n      retryable: e.status >= 500 || e.status === 429,\n      cause: e,\n    });\n  }\n\n  if (e instanceof NetworkError) {\n    return new ClientError({\n      code: \"NETWORK\",\n      message: e.message,\n      retryable: true,\n      cause: e,\n    });\n  }\n\n  if (e instanceof DecodeError) {\n    return new ClientError({\n      code: \"DECODE\",\n      message: e.message,\n      retryable: false,\n      cause: e,\n    });\n  }\n\n  if (e instanceof TimeoutError) {\n    return new ClientError({\n      code: \"TIMEOUT\",\n      message: e.message,\n      retryable: true,\n      cause: e,\n    });\n  }\n\n  return new ClientError({\n    code: \"UNKNOWN\",\n    message: asMessage(e) || \"Unknown error.\",\n    retryable: false,\n    cause: e,\n  });\n};\n\nexport class RenderParameterError extends Data.TaggedError(\"RenderParameterError\")<{\n  message: string;\n}> {}\n","/**\n * Configuration management for apo SDK.\n *\n * Centralizes environment variable reading so all wrappers use the same logic.\n */\n\nexport interface EnvConfig {\n  /** Backend endpoint URL */\n  endpoint: string;\n  /** Project name for optimization tracking */\n  project: string;\n  /**\n   * Public identifier for the two-key model. this is the\n   * ``pk-apo-*`` value, used as the Basic-auth username alongside\n   * ``secretKey``. It is NOT a usable credential on its own — the SDK\n   * never reads ``NEXT_PUBLIC_APO_PUBLIC_KEY`` because publishing a public\n   * identifier in a browser bundle creates a misleading direct-browser\n   * integration. Server-only.\n   */\n  publicKey?: string;\n  /** Secret key for two-key auth (server-only). */\n  secretKey?: string;\n  /** Legacy single-key auth token */\n  apiKey?: string;\n}\n\n/**\n * Read optimizer configuration from environment variables.\n *\n * This function centralizes all environment variable reading for the SDK,\n * ensuring consistent behavior across all wrapper functions.\n *\n * **Environment Variables (in order of priority):**\n *\n * For `endpoint`:\n * - `NEXT_PUBLIC_APO_BACKEND_URL` (Next.js public env var)\n * - `APO_BACKEND_URL` (standard env var)\n * - Falls back to `http://localhost:8000`\n *\n * For `project`:\n * - `APO_PROJECT` (standard env var)\n * - `NEXT_PUBLIC_APO_PROJECT` (Next.js public env var)\n * - Falls back to `default-project`\n *\n * For `publicKey`:\n * - `APO_PUBLIC_KEY` (server-side public identifier; paired with\n *   `APO_SECRET_KEY` to form HTTP Basic credentials). Support for `NEXT_PUBLIC_APO_PUBLIC_KEY` was removed:\n *   the public identifier alone\n *   does not authorize ingestion, so publishing it as a browser-safe env\n *   var is actively misleading.\n *\n * For `secretKey`:\n * - `APO_SECRET_KEY` (server-side only)\n *\n * For `apiKey` (legacy single-key auth):\n * - `APO_API_KEY`\n *\n * @example\n * ```ts\n * import { readConfig } from \"@apo-ai/sdk\";\n *\n * const config = readConfig();\n * console.log(config.endpoint); // \"http://localhost:8000\" or env value\n * console.log(config.project);  // \"default-project\" or env value\n * ```\n *\n * @returns Client configuration from environment\n */\nexport function readConfig(): EnvConfig {\n  const endpoint =\n    process.env.NEXT_PUBLIC_APO_BACKEND_URL ??\n    process.env.APO_BACKEND_URL ??\n    \"http://localhost:8000\";\n\n  const project =\n    process.env.APO_PROJECT ??\n    process.env.NEXT_PUBLIC_APO_PROJECT ??\n    \"default-project\";\n\n  const publicKey = process.env.APO_PUBLIC_KEY;\n\n  const secretKey = process.env.APO_SECRET_KEY;\n  const apiKey = process.env.APO_API_KEY;\n\n  return { endpoint, project, publicKey, secretKey, apiKey };\n}\n"],"mappings":";;;;AAAA,SAAS,YAAY;AAUd,IAAM,cAAN,cAA0B,KAAK,YAAY,aAAa,EAO5D;AAAC;AAEG,IAAM,kBAAN,cAA8B,KAAK,YAAY,iBAAiB,EAAM;AAAC;AAEvE,IAAM,eAAN,cAA2B,KAAK,YAAY,cAAc,EAG9D;AAAC;AAEG,IAAM,cAAN,cAA0B,KAAK,YAAY,aAAa,EAG5D;AAAC;AAEG,IAAM,eAAN,cAA2B,KAAK,YAAY,cAAc,EAG9D;AAAC;AAEG,IAAM,0BAAN,cAAsC,KAAK;AAAA,EAChD;AACF,EAGG;AAAC;AAEG,IAAM,qBAAN,cAAiC,KAAK,YAAY,oBAAoB,EAG1E;AAAC;AAwEG,IAAM,uBAAN,cAAmC,KAAK,YAAY,sBAAsB,EAE9E;AAAC;;;ACpDG,SAAS,aAAwB;AACtC,QAAM,WACJ,QAAQ,IAAI,+BACZ,QAAQ,IAAI,mBACZ;AAEF,QAAM,UACJ,QAAQ,IAAI,eACZ,QAAQ,IAAI,2BACZ;AAEF,QAAM,YAAY,QAAQ,IAAI;AAE9B,QAAM,YAAY,QAAQ,IAAI;AAC9B,QAAM,SAAS,QAAQ,IAAI;AAE3B,SAAO,EAAE,UAAU,SAAS,WAAW,WAAW,OAAO;AAC3D;","names":[]}

package/dist/otel/index.d.ts

@@ -0,0 +1,270 @@
+import { Tracer, TracerProvider, Span } from '@opentelemetry/api';
+import { SpanProcessor, SpanExporter } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * OTel-native tracing setup for the apo SDK.
+ *
+ * This module provides the standard OpenTelemetry setup path for apo:
+ *   - ``configureApoTelemetry`` creates a tracer provider with an OTLP exporter
+ *   - ``withApoTrace`` creates root/child spans using standard OTel context
+ *   - Helper functions (``traceTool``, ``traceAgent``, etc.) emit normal OTel
+ *     spans with GenAI or apo vendor attributes
+ *
+ * This replaces the deprecated ``TraceTracker`` custom event protocol. New
+ * users should use this module; existing ``TraceTracker`` code continues to
+ * work through a compatibility bridge.
+ *
+ * @module @apo-ai/sdk/otel
+ */
+
+interface ConfigureApoTelemetryOptions {
+    /** Explicit permission for this standalone helper to own OTel lifecycle. */
+    takeOwnership: true;
+    /**
+     * Full OTLP traces endpoint URL. Falls back to the `APO_OTLP_ENDPOINT` env
+     * var when omitted, then to `http://localhost:8000/api/public/otel/v1/traces`.
+     */
+    endpoint?: string;
+    /**
+     * Diagnostic resource attribute only. Auth owns tenancy — the project is
+     * determined by the API key / service token, never by this field.
+     * Falls back to the `APO_PROJECT` env var when omitted.
+     */
+    project?: string;
+    /**
+     * Service name for the OTel resource (required). Defaults to `"apo-agent"`.
+     */
+    serviceName?: string;
+    /** Service version for the OTel resource. */
+    serviceVersion?: string;
+    /** Deployment environment (production, staging, etc.). */
+    environment?: string;
+    /**
+     * Auth headers (Authorization: Basic/Bearer). Falls back to headers derived
+     * from `APO_PUBLIC_KEY`+`APO_SECRET_KEY` (Basic) or `APO_AUTH_TOKEN` (Bearer)
+     * env vars when omitted. Use {@link buildApoAuthHeaders} to build them
+     * explicitly.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Public key for Basic auth. Falls back to `APO_PUBLIC_KEY` env var.
+     * Used with `secretKey` to build `Authorization: Basic base64(pk:sk)`.
+     */
+    publicKey?: string;
+    /**
+     * Secret key for Basic auth. Falls back to `APO_SECRET_KEY` env var.
+     */
+    secretKey?: string;
+    /**
+     * Bearer auth token. Falls back to `APO_AUTH_TOKEN` env var. Used only when
+     * `publicKey`/`secretKey` are absent.
+     */
+    authToken?: string;
+    /**
+     * @deprecated OTel JS 2.x providers cannot accept processors after
+     * construction. Use `createApoSpanProcessor()` in the host provider's
+     * `spanProcessors` array instead.
+     */
+    provider?: TracerProvider;
+    /** Batch for services; simple is useful for short-lived task subprocesses. */
+    processor?: "batch" | "simple";
+    /**
+     * Whether to register apo's provider as the global tracer provider. Defaults
+     * to false. When true, registration only happens if no global provider is
+     * registered yet — apo never silently replaces an existing global provider.
+     */
+    registerGlobal?: boolean;
+}
+interface ApoTelemetryHandle {
+    /** The OTel tracer for creating spans. */
+    tracer: Tracer;
+    /** The provider, for advanced use. */
+    provider: TracerProvider;
+    /** Export all ended spans without relinquishing provider ownership. */
+    forceFlush(): Promise<void>;
+    /** Gracefully shut down the provider and flush pending spans. */
+    shutdown(): Promise<void>;
+}
+interface ApoTraceExporterOptions {
+    /** Full standard OTLP/HTTP traces endpoint. */
+    endpoint: string;
+    /** Authentication headers sent by the official OTLP exporter. */
+    headers: Record<string, string>;
+}
+interface ApoSpanProcessorOptions extends ApoTraceExporterOptions {
+    /** Batch for long-lived services (default), simple for short-lived jobs. */
+    processor?: "batch" | "simple";
+}
+interface ApoTraceOptions {
+    /** Span name. */
+    name: string;
+    /** apo.observation.type override. */
+    observationType?: string;
+    /** Additional attributes. */
+    attributes?: Record<string, unknown>;
+}
+/** Create the official OTLP/HTTP exporter for a host-owned OTel provider. */
+declare function createApoTraceExporter(options: ApoTraceExporterOptions): SpanExporter;
+/**
+ * Create an apo OTLP processor for inclusion when constructing a host provider.
+ * This factory has no global side effects and transfers lifecycle ownership to
+ * the host provider.
+ */
+declare function createApoSpanProcessor(options: ApoSpanProcessorOptions): SpanProcessor;
+/**
+ * Build the `Authorization` header for apo's OTLP endpoint.
+ *
+ * - If `publicKey` + `secretKey` are given (or read from `APO_PUBLIC_KEY` /
+ *   `APO_SECRET_KEY`), returns HTTP Basic: `Basic base64(pk:sk)`. *   both halves are required — a public identifier alone is not a
+ *   credential, so partial Basic is never synthesized.
+ * - Else if `authToken` is given (or read from `APO_AUTH_TOKEN`), returns
+ *   `Bearer <token>`. (Covers short-lived task-run/attempt tokens and
+ *   secret-bearing legacy API keys.)
+ * - Else returns an empty object (unauthenticated).
+ *
+ * Mirrors Python's `_build_auth_headers` in apo-otel-python.
+ */
+declare function buildApoAuthHeaders(publicKey?: string, secretKey?: string, authToken?: string): Record<string, string>;
+/**
+ * Configure apo's OpenTelemetry tracing.
+ *
+ * Builds apo's trace export from official OTel components: a real
+ * {@link Resource} (service.name, service.version, deployment.environment)
+ * and the official {@link OTLPTraceExporter} (standard OTLP/HTTP, no custom
+ * wire format). This is the explicit standalone bootstrap. Host applications
+ * that already own a provider should use `createApoSpanProcessor()` instead.
+ *
+ * @example
+ * ```ts
+ * import { configureApoTelemetry } from "@apo-ai/sdk/otel";
+ *
+ * const apo = await configureApoTelemetry({
+ *   takeOwnership: true,
+ *   endpoint: "https://apo.example.com/api/public/otel/v1/traces",
+ *   serviceName: "my-agent",
+ *   headers: { Authorization: `Basic ${btoa("pk-apo-...:sk-apo-...")}` },
+ * });
+ *
+ * const result = await withApoTrace({ name: "chat" }, apo.tracer, async (span) => {
+ *   span.setAttribute("gen_ai.request.model", "gpt-4o");
+ *   // ... do work ...
+ *   return "done";
+ * });
+ *
+ * await apo.shutdown();
+ * ```
+ */
+declare function configureApoTelemetry(options: ConfigureApoTelemetryOptions): Promise<ApoTelemetryHandle>;
+/**
+ * Run a function inside an OTel span.
+ *
+ * Creates a span using the active OTel context (standard context propagation,
+ * not apo-specific span IDs passed by hand). The span automatically ends when
+ * the function returns or throws.
+ *
+ * @example
+ * ```ts
+ * const result = await withApoTrace(
+ *   { name: "agent-turn", observationType: "AGENT" },
+ *   apo.tracer,
+ *   async (span) => {
+ *     span.setAttribute("gen_ai.request.model", "gpt-4o");
+ *     return await llm.complete("hello");
+ *   },
+ * );
+ * ```
+ */
+declare function withApoTrace<T>(options: ApoTraceOptions, tracer: Tracer, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Trace a tool execution as an OTel span.
+ *
+ * Creates a span with ``gen_ai.tool.name``, ``gen_ai.tool.call.arguments``,
+ * and ``gen_ai.tool.call.result`` attributes so the backend normalizer
+ * classifies it as a TOOL observation.
+ */
+declare function traceTool<T>(tracer: Tracer, name: string, params: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace an agent invocation as an OTel span.
+ */
+declare function traceAgent<T>(tracer: Tracer, name: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace a chain/step as an OTel span.
+ */
+declare function traceChain<T>(tracer: Tracer, name: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace a retrieval as an OTel span.
+ */
+declare function traceRetriever<T>(tracer: Tracer, query: string, fn: () => Promise<T>): Promise<T>;
+interface ScoreOptions {
+    name: string;
+    value: number | string | boolean;
+    dataType?: "NUMERIC" | "CATEGORICAL" | "BOOLEAN";
+    source?: "API" | "EVAL" | "ANNOTATION";
+    comment?: string;
+    observationId?: string;
+}
+/**
+ * Record a score for a trace (or a specific observation within a trace).
+ *
+ * "A Score is an apo domain record attached to a Trace or
+ * Observation. It is not encoded as a fake span."
+ *
+ * This calls the native score API (`POST /api/v1/traces/{id}/scores` or
+ * `POST /api/v1/observations/{id}/scores`) instead of creating a sentinel
+ * span. The score is stored as a `RunMetricDB` or `CallMetricDB` row.
+ *
+ * @example
+ * ```ts
+ * await score({
+ *   traceId: "abc123...",
+ *   name: "helpfulness",
+ *   value: 0.85,
+ *   dataType: "NUMERIC",
+ *   source: "EVAL",
+ * }, { endpoint: "http://localhost:8000", headers: authHeaders });
+ * ```
+ */
+declare function score(params: ScoreOptions & {
+    traceId: string;
+}, config: {
+    endpoint: string;
+    headers: Record<string, string>;
+}): Promise<void>;
+/**
+ * Inject the current span's trace context into a headers dict for outbound
+ * HTTP/queue calls. Produces a standard W3C `traceparent` header so the
+ * downstream service can extract it and create a child span in the same trace.
+ *
+ * Delegates to OTel's official `W3CTraceContextPropagator`, which also emits
+ * `tracestate` and handles the spec's edge cases.
+ *
+ * @example
+ * ```ts
+ * const headers = injectTraceparent();
+ * await fetch("http://downstream-service/api", { headers });
+ * ```
+ */
+declare function injectTraceparent(): Record<string, string>;
+/**
+ * Extract a W3C trace context from inbound headers and run a function as a
+ * child span within that trace. If no `traceparent` header is present (or it
+ * is malformed), a new root span is created.
+ *
+ * Transport parsing is delegated to OTel's `W3CTraceContextPropagator`; the
+ * span creation on top of the extracted remote parent is apo-specific and
+ * kept here.
+ *
+ * @example
+ * ```ts
+ * // In a downstream HTTP handler:
+ * app.post("/api", (req, res) => {
+ *   const result = await extractTraceparent(req.headers, tracer, async (span) => {
+ *     return await doWork();
+ *   });
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function extractTraceparent<T>(headers: Record<string, string>, tracer: Tracer, fn: (span: Span) => Promise<T>): Promise<T>;
+
+export { type ApoSpanProcessorOptions, type ApoTelemetryHandle, type ApoTraceExporterOptions, type ApoTraceOptions, type ConfigureApoTelemetryOptions, type ScoreOptions, buildApoAuthHeaders, configureApoTelemetry, createApoSpanProcessor, createApoTraceExporter, extractTraceparent, injectTraceparent, score, traceAgent, traceChain, traceRetriever, traceTool, withApoTrace };

package/dist/otel/index.js

@@ -0,0 +1,32 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+import {
+  buildApoAuthHeaders,
+  configureApoTelemetry,
+  createApoSpanProcessor,
+  createApoTraceExporter,
+  extractTraceparent,
+  injectTraceparent,
+  score,
+  traceAgent,
+  traceChain,
+  traceRetriever,
+  traceTool,
+  withApoTrace
+} from "../chunk-PMYLL2H4.js";
+import "../chunk-HWZVL6TS.js";
+export {
+  buildApoAuthHeaders,
+  configureApoTelemetry,
+  createApoSpanProcessor,
+  createApoTraceExporter,
+  extractTraceparent,
+  injectTraceparent,
+  score,
+  traceAgent,
+  traceChain,
+  traceRetriever,
+  traceTool,
+  withApoTrace
+};
+//# sourceMappingURL=index.js.map

package/dist/otel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/tracing-DtbhYQV6.d.ts

@@ -0,0 +1,26 @@
+import { T as TraceRunContext, C as CreateSpanParams, E as EndSpanParams, a as TraceRunOptions } from './types-C-nrDEVf.js';
+
+type AgentTaskTraceContext = TraceRunContext & {
+    createSpan: (options: Omit<CreateSpanParams, "project" | "run_id">) => string;
+    endSpan: (spanId: string, params?: Omit<EndSpanParams, "id">) => void;
+};
+type AgentTaskTraceOptions = {
+    client: {
+        traceRun<T>(params: TraceRunOptions, fn: (trace: AgentTaskTraceContext) => Promise<T>): Promise<T>;
+    };
+    project?: string;
+    flowName?: string;
+    version?: string;
+    environment?: string;
+    tags?: string[];
+    runMetadata?: Record<string, unknown>;
+    /**
+     * The Task Run ID this trace should claim. Emitted as the
+     * `apo.task.run.id` root-span attribute so the backend projector can
+     * atomically link this trace to the task run. Omit for local/programmatic
+     * runs that don't have a backend task run.
+     */
+    taskRunId?: string;
+};
+
+export type { AgentTaskTraceContext as A, AgentTaskTraceOptions as a };