@arizeai/phoenix-client 6.8.1 → 6.9.0

package/dist/esm/constants/serverRequirements.d.ts

@@ -18,6 +18,7 @@ export declare const DELETE_SESSIONS: RouteRequirement;
 export declare const LIST_PROJECT_SESSIONS: RouteRequirement;
 export declare const ANNOTATE_SESSIONS: RouteRequirement;
 export declare const ADD_TRACE_NOTE: RouteRequirement;
+export declare const ADD_SESSION_NOTE: RouteRequirement;
 export declare const GET_SPANS_TRACE_IDS: ParameterRequirement;
 export declare const GET_SPANS_FILTERS: ParameterRequirement;
 export declare const LIST_PROJECT_TRACES: RouteRequirement;

package/dist/esm/constants/serverRequirements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serverRequirements.d.ts","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,gBAK7B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAK/B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,oBAMjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,oBAM/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,gBAKjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,oBAMpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,oBAMxC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,qBAAqB,EAYnD,CAAC"}
+{"version":3,"file":"serverRequirements.d.ts","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,gBAK7B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAK/B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,gBAK9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,oBAMjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,oBAM/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,gBAKjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,oBAMpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,oBAMxC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,qBAAqB,EAanD,CAAC"}

package/dist/esm/constants/serverRequirements.js

@@ -47,6 +47,12 @@ export const ADD_TRACE_NOTE = {
     path: "/v1/trace_notes",
     minServerVersion: [14, 13, 0],
 };
+export const ADD_SESSION_NOTE = {
+    kind: "route",
+    method: "POST",
+    path: "/v1/session_notes",
+    minServerVersion: [14, 17, 0],
+};
 export const GET_SPANS_TRACE_IDS = {
     kind: "parameter",
     parameterName: "trace_id",
@@ -94,6 +100,7 @@ export const ALL_REQUIREMENTS = [
     LIST_PROJECT_SESSIONS,
     ANNOTATE_SESSIONS,
     ADD_TRACE_NOTE,
+    ADD_SESSION_NOTE,
     GET_SPANS_TRACE_IDS,
     GET_SPANS_FILTERS,
     GET_SPANS_BY_ATTRIBUTE,

package/dist/esm/constants/serverRequirements.js.map

@@ -1 +1 @@
-{"version":3,"file":"serverRequirements.js","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serverRequirements.js","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"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"}

package/dist/esm/sessions/addSessionNote.d.ts

@@ -0,0 +1,45 @@
+import type { ClientFn } from "../types/core.js";
+/**
+ * Parameters for a single session note.
+ */
+export interface SessionNote {
+    /**
+     * The session ID used to track a conversation, thread, or session.
+     */
+    sessionId: string;
+    /**
+     * The note text to add to the session.
+     */
+    note: string;
+}
+/**
+ * Parameters to add a session note.
+ */
+export interface AddSessionNoteParams extends ClientFn {
+    sessionNote: SessionNote;
+}
+/**
+ * Add a note to a session.
+ *
+ * Notes are a special type of annotation that allow multiple entries per session.
+ * Each note gets a unique UUIDv4 identifier.
+ *
+ * @param params - The parameters to add a session note.
+ * @returns The ID of the created note annotation.
+ *
+ * @requires Phoenix server >= 14.17.0
+ *
+ * @example
+ * ```ts
+ * const result = await addSessionNote({
+ *   sessionNote: {
+ *     sessionId: "my-session",
+ *     note: "Needs review"
+ *   }
+ * });
+ * ```
+ */
+export declare function addSessionNote({ client: _client, sessionNote, }: AddSessionNoteParams): Promise<{
+    id: string;
+}>;
+//# sourceMappingURL=addSessionNote.d.ts.map

package/dist/esm/sessions/addSessionNote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addSessionNote.d.ts","sourceRoot":"","sources":["../../../src/sessions/addSessionNote.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,QAAQ;IACpD,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAAC,EACnC,MAAM,EAAE,OAAO,EACf,WAAW,GACZ,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBhD"}

package/dist/esm/sessions/addSessionNote.js

@@ -0,0 +1,45 @@
+import { createClient } from "../client.js";
+import { ADD_SESSION_NOTE } from "../constants/serverRequirements.js";
+import { formatApiError } from "../utils/apiErrorUtils.js";
+import { ensureServerCapability } from "../utils/serverVersionUtils.js";
+/**
+ * Add a note to a session.
+ *
+ * Notes are a special type of annotation that allow multiple entries per session.
+ * Each note gets a unique UUIDv4 identifier.
+ *
+ * @param params - The parameters to add a session note.
+ * @returns The ID of the created note annotation.
+ *
+ * @requires Phoenix server >= 14.17.0
+ *
+ * @example
+ * ```ts
+ * const result = await addSessionNote({
+ *   sessionNote: {
+ *     sessionId: "my-session",
+ *     note: "Needs review"
+ *   }
+ * });
+ * ```
+ */
+export async function addSessionNote({ client: _client, sessionNote, }) {
+    const client = _client ?? createClient();
+    await ensureServerCapability({ client, requirement: ADD_SESSION_NOTE });
+    const { data, error } = await client.POST("/v1/session_notes", {
+        body: {
+            data: {
+                session_id: sessionNote.sessionId.trim(),
+                note: sessionNote.note,
+            },
+        },
+    });
+    if (error) {
+        throw new Error(`Failed to add session note: ${formatApiError(error)}`);
+    }
+    if (!data?.data) {
+        throw new Error("Failed to add session note: no data returned");
+    }
+    return data.data;
+}
+//# sourceMappingURL=addSessionNote.js.map

package/dist/esm/sessions/addSessionNote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addSessionNote.js","sourceRoot":"","sources":["../../../src/sessions/addSessionNote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuBrE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EACnC,MAAM,EAAE,OAAO,EACf,WAAW,GACU;IACrB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IACzC,MAAM,sBAAsB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAExE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE;QAC7D,IAAI,EAAE;YACJ,IAAI,EAAE;gBACJ,UAAU,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,EAAE;gBACxC,IAAI,EAAE,WAAW,CAAC,IAAI;aACvB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,+BAA+B,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/dist/esm/sessions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./addSessionAnnotation.js";
+export * from "./addSessionNote.js";
 export * from "./deleteSession.js";
 export * from "./deleteSessions.js";
 export * from "./getSession.js";

package/dist/esm/sessions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}

package/dist/esm/sessions/index.js

@@ -1,4 +1,5 @@
 export * from "./addSessionAnnotation.js";
+export * from "./addSessionNote.js";
 export * from "./deleteSession.js";
 export * from "./deleteSessions.js";
 export * from "./getSession.js";

package/dist/esm/sessions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}

package/dist/esm/spans/addSpanNote.d.ts

@@ -21,9 +21,11 @@ export interface AddSpanNoteParams extends ClientFn {
 /**
  * Add a note to a span.
  *
- * Notes are a special type of annotation that allow multiple entries per span
- * (unlike regular annotations which are unique by name and identifier).
- * Each note gets a unique UUIDv4 identifier.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same span. Structured
+ * annotations, by contrast, are keyed by `(name, spanId, identifier)` — to keep
+ * multiple structured annotations with the same name on a span, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation

package/dist/esm/spans/addSpanNote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addSpanNote.d.ts","sourceRoot":"","sources":["../../../src/spans/addSpanNote.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,EAChC,MAAM,EAAE,OAAO,EACf,QAAQ,GACT,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB7C"}
+{"version":3,"file":"addSpanNote.d.ts","sourceRoot":"","sources":["../../../src/spans/addSpanNote.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,WAAW,CAAC,EAChC,MAAM,EAAE,OAAO,EACf,QAAQ,GACT,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB7C"}

package/dist/esm/spans/addSpanNote.js

@@ -1,10 +1,13 @@
 import { createClient } from "../client.js";
+import { formatApiError } from "../utils/apiErrorUtils.js";
 /**
  * Add a note to a span.
  *
- * Notes are a special type of annotation that allow multiple entries per span
- * (unlike regular annotations which are unique by name and identifier).
- * Each note gets a unique UUIDv4 identifier.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same span. Structured
+ * annotations, by contrast, are keyed by `(name, spanId, identifier)` — to keep
+ * multiple structured annotations with the same name on a span, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation
@@ -30,7 +33,7 @@ export async function addSpanNote({ client: _client, spanNote, }) {
         },
     });
     if (error) {
-        throw new Error(`Failed to add span note: ${error}`);
+        throw new Error(`Failed to add span note: ${formatApiError(error)}`);
     }
     if (!data?.data) {
         throw new Error("Failed to add span note: no data returned");

package/dist/esm/spans/addSpanNote.js.map

@@ -1 +1 @@
-{"version":3,"file":"addSpanNote.js","sourceRoot":"","sources":["../../../src/spans/addSpanNote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAwBzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,MAAM,EAAE,OAAO,EACf,QAAQ,GACU;IAClB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE;QAC1D,IAAI,EAAE;YACJ,IAAI,EAAE;gBACJ,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC/B,IAAI,EAAE,QAAQ,CAAC,IAAI;aACpB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}
+{"version":3,"file":"addSpanNote.js","sourceRoot":"","sources":["../../../src/spans/addSpanNote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAuBxD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,MAAM,EAAE,OAAO,EACf,QAAQ,GACU;IAClB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE;QAC1D,IAAI,EAAE;YACJ,IAAI,EAAE;gBACJ,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC/B,IAAI,EAAE,QAAQ,CAAC,IAAI;aACpB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/dist/esm/traces/addTraceAnnotation.d.ts

@@ -0,0 +1,43 @@
+import type { ClientFn } from "../types/core.js";
+import type { TraceAnnotation } from "./types.js";
+/**
+ * Parameters to add a trace annotation
+ */
+export interface AddTraceAnnotationParams extends ClientFn {
+    traceAnnotation: TraceAnnotation;
+    /**
+     * If true, the request will be fulfilled synchronously and return the annotation ID.
+     * If false, the request will be processed asynchronously and return null.
+     * @default false
+     */
+    sync?: boolean;
+}
+/**
+ * Add an annotation to a trace.
+ *
+ * The annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to add a trace annotation
+ * @returns The ID of the created or updated annotation
+ *
+ * @example
+ * ```ts
+ * const result = await addTraceAnnotation({
+ *   traceAnnotation: {
+ *     traceId: "abc123",
+ *     name: "correctness",
+ *     label: "correct",
+ *     score: 1.0,
+ *     annotatorKind: "HUMAN",
+ *     identifier: "custom_id_123",
+ *     metadata: { reviewer: "alice" }
+ *   },
+ *   sync: true,
+ * });
+ * ```
+ */
+export declare function addTraceAnnotation({ client: _client, traceAnnotation, sync, }: AddTraceAnnotationParams): Promise<{
+    id: string;
+} | null>;
+//# sourceMappingURL=addTraceAnnotation.d.ts.map

package/dist/esm/traces/addTraceAnnotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addTraceAnnotation.d.ts","sourceRoot":"","sources":["../../../src/traces/addTraceAnnotation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,QAAQ;IACxD,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,MAAM,EAAE,OAAO,EACf,eAAe,EACf,IAAY,GACb,EAAE,wBAAwB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB3D"}

package/dist/esm/traces/addTraceAnnotation.js

@@ -0,0 +1,43 @@
+import { createClient } from "../client.js";
+import { toTraceAnnotationData } from "./types.js";
+/**
+ * Add an annotation to a trace.
+ *
+ * The annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to add a trace annotation
+ * @returns The ID of the created or updated annotation
+ *
+ * @example
+ * ```ts
+ * const result = await addTraceAnnotation({
+ *   traceAnnotation: {
+ *     traceId: "abc123",
+ *     name: "correctness",
+ *     label: "correct",
+ *     score: 1.0,
+ *     annotatorKind: "HUMAN",
+ *     identifier: "custom_id_123",
+ *     metadata: { reviewer: "alice" }
+ *   },
+ *   sync: true,
+ * });
+ * ```
+ */
+export async function addTraceAnnotation({ client: _client, traceAnnotation, sync = false, }) {
+    const client = _client ?? createClient();
+    const { data, error } = await client.POST("/v1/trace_annotations", {
+        params: {
+            query: { sync },
+        },
+        body: {
+            data: [toTraceAnnotationData(traceAnnotation)],
+        },
+    });
+    if (error) {
+        throw new Error(`Failed to add trace annotation: ${error}`);
+    }
+    return data?.data?.[0] || null;
+}
+//# sourceMappingURL=addTraceAnnotation.js.map

package/dist/esm/traces/addTraceAnnotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addTraceAnnotation.js","sourceRoot":"","sources":["../../../src/traces/addTraceAnnotation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAehD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,MAAM,EAAE,OAAO,EACf,eAAe,EACf,IAAI,GAAG,KAAK,GACa;IACzB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE;QACjE,MAAM,EAAE;YACN,KAAK,EAAE,EAAE,IAAI,EAAE;SAChB;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC;SAC/C;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACjC,CAAC"}

package/dist/esm/traces/addTraceNote.d.ts

@@ -21,8 +21,11 @@ export interface AddTraceNoteParams extends ClientFn {
 /**
  * Add a note to a trace.
  *
- * Notes are a special type of annotation that allow multiple entries per trace.
- * Each note gets a unique timestamp-based identifier.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same trace. Structured
+ * annotations, by contrast, are keyed by `(name, traceId, identifier)` — to keep
+ * multiple structured annotations with the same name on a trace, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a trace note.
  * @returns The ID of the created note annotation.

package/dist/esm/traces/addTraceNote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addTraceNote.d.ts","sourceRoot":"","sources":["../../../src/traces/addTraceNote.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAClD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAM,EAAE,OAAO,EACf,SAAS,GACV,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9C"}
+{"version":3,"file":"addTraceNote.d.ts","sourceRoot":"","sources":["../../../src/traces/addTraceNote.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAClD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAM,EAAE,OAAO,EACf,SAAS,GACV,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9C"}

package/dist/esm/traces/addTraceNote.js

@@ -1,11 +1,15 @@
 import { createClient } from "../client.js";
 import { ADD_TRACE_NOTE } from "../constants/serverRequirements.js";
+import { formatApiError } from "../utils/apiErrorUtils.js";
 import { ensureServerCapability } from "../utils/serverVersionUtils.js";
 /**
  * Add a note to a trace.
  *
- * Notes are a special type of annotation that allow multiple entries per trace.
- * Each note gets a unique timestamp-based identifier.
+ * Notes are append-only: each call creates a new note with an auto-generated
+ * UUIDv4 identifier, so multiple notes accumulate on the same trace. Structured
+ * annotations, by contrast, are keyed by `(name, traceId, identifier)` — to keep
+ * multiple structured annotations with the same name on a trace, supply distinct
+ * identifiers; otherwise re-writing the same name overwrites the existing one.
  *
  * @param params - The parameters to add a trace note.
  * @returns The ID of the created note annotation.
@@ -32,7 +36,7 @@ export async function addTraceNote({ client: _client, traceNote, }) {
         },
     });
     if (error) {
-        throw new Error(`Failed to add trace note: ${error}`);
+        throw new Error(`Failed to add trace note: ${formatApiError(error)}`);
     }
     if (!data?.data) {
         throw new Error("Failed to add trace note: no data returned");

package/dist/esm/traces/addTraceNote.js.map

@@ -1 +1 @@
-{"version":3,"file":"addTraceNote.js","sourceRoot":"","sources":["../../../src/traces/addTraceNote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuBrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,MAAM,EAAE,OAAO,EACf,SAAS,GACU;IACnB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IACzC,MAAM,sBAAsB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC,CAAC;IAEtE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;QAC3D,IAAI,EAAE;YACJ,IAAI,EAAE;gBACJ,QAAQ,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE;gBAClC,IAAI,EAAE,SAAS,CAAC,IAAI;aACrB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}
+{"version":3,"file":"addTraceNote.js","sourceRoot":"","sources":["../../../src/traces/addTraceNote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuBrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,MAAM,EAAE,OAAO,EACf,SAAS,GACU;IACnB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IACzC,MAAM,sBAAsB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC,CAAC;IAEtE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;QAC3D,IAAI,EAAE;YACJ,IAAI,EAAE;gBACJ,QAAQ,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE;gBAClC,IAAI,EAAE,SAAS,CAAC,IAAI;aACrB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,6BAA6B,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/dist/esm/traces/index.d.ts

@@ -1,3 +1,6 @@
+export * from "./addTraceAnnotation.js";
 export * from "./addTraceNote.js";
 export * from "./getTraces.js";
+export * from "./logTraceAnnotations.js";
+export type { TraceAnnotation } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/traces/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/esm/traces/index.js

@@ -1,3 +1,5 @@
+export * from "./addTraceAnnotation.js";
 export * from "./addTraceNote.js";
 export * from "./getTraces.js";
+export * from "./logTraceAnnotations.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/traces/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/esm/traces/logTraceAnnotations.d.ts

@@ -0,0 +1,53 @@
+import type { ClientFn } from "../types/core.js";
+import type { TraceAnnotation } from "./types.js";
+/**
+ * Parameters to log multiple trace annotations
+ */
+export interface LogTraceAnnotationsParams extends ClientFn {
+    /**
+     * The trace annotations to log
+     */
+    traceAnnotations: TraceAnnotation[];
+    /**
+     * If true, the request will be fulfilled synchronously and return the annotation IDs.
+     * If false, the request will be processed asynchronously and return null.
+     * @default false
+     */
+    sync?: boolean;
+}
+/**
+ * Log multiple trace annotations in a single request.
+ *
+ * Each annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to log trace annotations
+ * @returns The IDs of the created or updated annotations
+ *
+ * @example
+ * ```ts
+ * const results = await logTraceAnnotations({
+ *   traceAnnotations: [
+ *     {
+ *       traceId: "abc123",
+ *       name: "correctness",
+ *       label: "correct",
+ *       score: 1.0,
+ *       annotatorKind: "HUMAN",
+ *     },
+ *     {
+ *       traceId: "def456",
+ *       name: "faithfulness",
+ *       label: "faithful",
+ *       score: 0.9,
+ *       annotatorKind: "LLM",
+ *     },
+ *   ],
+ *   sync: true,
+ * });
+ * ```
+ */
+export declare function logTraceAnnotations({ client: _client, traceAnnotations, sync, }: LogTraceAnnotationsParams): Promise<{
+    id: string;
+}[]>;
+//# sourceMappingURL=logTraceAnnotations.d.ts.map

package/dist/esm/traces/logTraceAnnotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logTraceAnnotations.d.ts","sourceRoot":"","sources":["../../../src/traces/logTraceAnnotations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,QAAQ;IACzD;;OAEG;IACH,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,MAAM,EAAE,OAAO,EACf,gBAAgB,EAChB,IAAY,GACb,EAAE,yBAAyB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAiBvD"}

package/dist/esm/traces/logTraceAnnotations.js

@@ -0,0 +1,50 @@
+import { createClient } from "../client.js";
+import { toTraceAnnotationData } from "./types.js";
+/**
+ * Log multiple trace annotations in a single request.
+ *
+ * Each annotation can be of type "LLM", "CODE", or "HUMAN" and can include a label, score, and metadata.
+ * If an identifier is provided and an annotation with that identifier already exists, it will be updated.
+ *
+ * @param params - The parameters to log trace annotations
+ * @returns The IDs of the created or updated annotations
+ *
+ * @example
+ * ```ts
+ * const results = await logTraceAnnotations({
+ *   traceAnnotations: [
+ *     {
+ *       traceId: "abc123",
+ *       name: "correctness",
+ *       label: "correct",
+ *       score: 1.0,
+ *       annotatorKind: "HUMAN",
+ *     },
+ *     {
+ *       traceId: "def456",
+ *       name: "faithfulness",
+ *       label: "faithful",
+ *       score: 0.9,
+ *       annotatorKind: "LLM",
+ *     },
+ *   ],
+ *   sync: true,
+ * });
+ * ```
+ */
+export async function logTraceAnnotations({ client: _client, traceAnnotations, sync = false, }) {
+    const client = _client ?? createClient();
+    const { data, error } = await client.POST("/v1/trace_annotations", {
+        params: {
+            query: { sync },
+        },
+        body: {
+            data: traceAnnotations.map(toTraceAnnotationData),
+        },
+    });
+    if (error) {
+        throw new Error(`Failed to log trace annotations: ${error}`);
+    }
+    return data?.data || [];
+}
+//# sourceMappingURL=logTraceAnnotations.js.map

package/dist/esm/traces/logTraceAnnotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logTraceAnnotations.js","sourceRoot":"","sources":["../../../src/traces/logTraceAnnotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAkBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EACxC,MAAM,EAAE,OAAO,EACf,gBAAgB,EAChB,IAAI,GAAG,KAAK,GACc;IAC1B,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE;QACjE,MAAM,EAAE;YACN,KAAK,EAAE,EAAE,IAAI,EAAE;SAChB;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,qBAAqB,CAAC;SAClD;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/esm/traces/types.d.ts

@@ -0,0 +1,24 @@
+import type { paths } from "../__generated__/api/v1.js";
+import type { Annotation } from "../types/annotations.js";
+type TraceAnnotationData = paths["/v1/trace_annotations"]["post"]["requestBody"]["content"]["application/json"]["data"][0];
+/**
+ * Parameters for a single trace annotation
+ */
+export interface TraceAnnotation extends Annotation {
+    /**
+     * The OpenTelemetry Trace ID (hex format without 0x prefix)
+     */
+    traceId: string;
+    /**
+     * The kind of annotator used for the annotation
+     * Can be "HUMAN", "LLM", or "CODE"
+     * @default "HUMAN"
+     */
+    annotatorKind?: TraceAnnotationData["annotator_kind"];
+}
+/**
+ * Convert a TraceAnnotation to the API format
+ */
+export declare function toTraceAnnotationData(annotation: TraceAnnotation): TraceAnnotationData;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/traces/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/traces/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAEzE,KAAK,mBAAmB,GACtB,KAAK,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAElG;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AA8BD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,eAAe,GAC1B,mBAAmB,CAgBrB"}

package/dist/esm/traces/types.js

@@ -0,0 +1,38 @@
+/**
+ * Build and validate annotation result fields
+ */
+function buildTraceAnnotationResult(annotation) {
+    const result = {};
+    if (annotation.label !== undefined) {
+        result.label = annotation.label.trim() || null;
+    }
+    if (annotation.score !== undefined) {
+        result.score = annotation.score;
+    }
+    if (annotation.explanation !== undefined) {
+        result.explanation = annotation.explanation.trim() || null;
+    }
+    const hasValidResult = result.label || result.score !== undefined || result.explanation;
+    if (!hasValidResult) {
+        throw new Error("At least one of label, score, or explanation must be provided for trace annotation");
+    }
+    return result;
+}
+/**
+ * Convert a TraceAnnotation to the API format
+ */
+export function toTraceAnnotationData(annotation) {
+    if (annotation.name.trim() === "note") {
+        throw new Error('The name "note" is reserved for trace and span notes. Use addTraceNote instead.');
+    }
+    const result = buildTraceAnnotationResult(annotation);
+    return {
+        trace_id: annotation.traceId.trim(),
+        name: annotation.name.trim(),
+        annotator_kind: annotation.annotatorKind ?? "HUMAN",
+        result,
+        metadata: annotation.metadata ?? null,
+        identifier: annotation.identifier?.trim() ?? "",
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/traces/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/traces/types.ts"],"names":[],"mappings":"AAsBA;;GAEG;AACH,SAAS,0BAA0B,CACjC,UAAoE;IAEpE,MAAM,MAAM,GAAqB,EAAE,CAAC;IAEpC,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IACjD,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;IAClC,CAAC;IACD,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC7D,CAAC;IAED,MAAM,cAAc,GAClB,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC;IACnE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,oFAAoF,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,UAA2B;IAE3B,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,0BAA0B,CAAC,UAAU,CAAC,CAAC;IAEtD,OAAO;QACL,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE;QACnC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE;QAC5B,cAAc,EAAE,UAAU,CAAC,aAAa,IAAI,OAAO;QACnD,MAAM;QACN,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,IAAI;QACrC,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE;KAChD,CAAC;AACJ,CAAC"}