@apo-ai/sdk 0.2.2 → 0.3.0

package/dist/{types-C-nrDEVf.d.ts → tracing-BE53Q8Ru.d.ts}

@@ -1,14 +1,3 @@
-type ParameterOverrides = Record<string, unknown>;
-interface ClientOptions {
-    parameterOverrides?: ParameterOverrides;
-    runEvals?: boolean;
-}
-interface IngestionEvent {
-    id: string;
-    timestamp: Date;
-    type: "run-create" | "call-create" | "call-update" | "score-create";
-    body: Record<string, unknown>;
-}
 interface CreateTraceParams {
     id?: string;
     project: string;
@@ -88,53 +77,28 @@ interface CreateScoreParams {
     comment?: string;
     observationId?: string;
 }
-interface ObserveOptions {
-    /** Unique ID for this observation (trace or span) */
-    id?: string;
-    /** Project name for grouping traces */
+
+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;
-    /** Flow name (alternative to project) */
     flowName?: string;
-    /** Step name for spans */
-    stepName?: string;
-    /** Observation name (defaults to method name if not provided) */
-    name?: string;
-    /** User ID for tracking */
-    userId?: string;
-    /** Session ID for session tracking */
-    sessionId?: string;
-    /** Environment (e.g., "production", "development") */
+    version?: string;
     environment?: string;
-    /** External ID for linking to external systems */
-    externalId?: string;
-    /** Tags for filtering and grouping */
     tags?: string[];
-    /** Metadata for additional context */
-    metadata?: Record<string, unknown>;
-    /** Model name (for spans) */
-    model?: string;
-    /** Explicit input data (overrides automatic extraction) */
-    input?: Record<string, unknown>;
-    /** Messages array (for chat completions) */
-    messages?: Record<string, unknown>[];
-    /** Observation type (Langfuse-style) */
-    observationType?: "GENERATION" | "SPAN" | "TOOL" | "CHAIN" | "RETRIEVER" | "EVALUATOR" | "EMBEDDING" | "GUARDRAIL" | "AGENT";
-    /** Shorthand for observation type */
-    as?: "tool" | "retriever" | "chain" | "agent" | "guardrail" | "embedding";
-    /** Observation level */
-    level?: "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
-    /** Whether to capture output (default: true) */
-    captureOutput?: boolean;
-}
-interface ObservationContext {
-    /** Trace ID (run ID) */
-    traceId: string;
-    /** Current span ID */
-    spanId: string;
-    /** Flow name */
-    flowName: string;
-    /** Project name */
-    projectName: 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 { CreateSpanParams as C, EndSpanParams as E, IngestionEvent as I, ObservationContext as O, ParameterOverrides as P, TraceRunContext as T, TraceRunOptions as a, ClientOptions as b, CreateScoreParams as c, CreateTraceParams as d, ObserveOptions as e, TraceEventOptions as f, TraceStepOptions as g };
+export type { AgentTaskTraceContext as A, AgentTaskTraceOptions as a };

package/package.json

@@ -1,10 +1,8 @@
 {
   "name": "@apo-ai/sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "TypeScript SDK for testing and observing AI agents with Apo",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "LICENSE",
@@ -24,11 +22,6 @@
     "url": "https://github.com/samikuikka/apo/issues"
   },
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
     "./otel": {
       "types": "./dist/otel/index.d.ts",
       "import": "./dist/otel/index.js",
@@ -76,8 +69,7 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
     "@opentelemetry/resources": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/semantic-conventions": "^1.43.0",
-    "effect": "^3.19.12"
+    "@opentelemetry/semantic-conventions": "^1.43.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.type-tests.json",

package/dist/index.d.ts

@@ -1,95 +0,0 @@
-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

@@ -1,39 +0,0 @@
-// 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

@@ -1 +0,0 @@
-{"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/tracing-DtbhYQV6.d.ts

@@ -1,26 +0,0 @@
-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 };