@introspection-sdk/introspection-browser 0.4.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @introspection-sdk/introspection-browser@0.1.0 build /Users/julian/projects/introspection-org/introspection-js-sdk/packages/introspection-browser
+> tsc
+

package/.turbo/turbo-check-types.log

@@ -0,0 +1,5 @@
+
+
+> @introspection-sdk/introspection-browser@0.1.0 check-types /Users/julian/projects/introspection-org/introspection-js-sdk/packages/introspection-browser
+> tsc --noEmit
+

package/.turbo/turbo-lint.log

@@ -0,0 +1,4 @@
+
+> @introspection-sdk/introspection-browser@0.1.0 lint /Users/julian/projects/introspection-org/introspection-js-sdk/packages/introspection-browser
+> eslint . --max-warnings 0
+

package/dist/client.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Introspection Client for Browser
+ * Provides an API for tracking events and feedback using OTLP Logs.
+ *
+ * Identity and gen_ai context can be managed via baggage (requires OpenTelemetry
+ * browser SDK with Zone.js for automatic propagation) or via client instance.
+ */
+import { type IntrospectionClientOptions, type FeedbackOptions, type UserTraits } from "./types.js";
+/**
+ * Introspection client for tracking events and feedback in the browser using OTLP Logs.
+ *
+ * Identity (user_id, anonymous_id) and gen_ai context (conversation_id, previous_response_id, agent)
+ * can be managed via client instance (persisted to localStorage) or via OpenTelemetry baggage
+ * for scoped context.
+ *
+ * Note: Automatic baggage propagation in browsers requires Zone.js from @opentelemetry/context-zone.
+ *
+ * @example
+ * ```typescript
+ * const client = new IntrospectionClient({
+ *   token: "intro_xxx",
+ *   debug: true,
+ * });
+ *
+ * // Set identity once (persisted to localStorage)
+ * client.identify("user_123", { email: "user@example.com" });
+ *
+ * // Simple feedback
+ * client.feedback("thumbs_up", { comments: "Great response!" });
+ *
+ * // With explicit gen_ai context
+ * client.feedback("thumbs_down", {
+ *   conversationId: "conv_456",
+ *   previousResponseId: "msg_123",
+ *   comments: "Off topic",
+ * });
+ *
+ * // With scoped baggage context
+ * await client.withConversation("conv_456", undefined, async () => {
+ *   client.feedback("thumbs_up"); // automatically includes conversation_id
+ * });
+ *
+ * // Track a custom event
+ * client.track("Button Clicked", { buttonId: "submit" });
+ * ```
+ */
+export declare class IntrospectionClient {
+    private loggerProvider;
+    private otelLogger;
+    private userId;
+    private anonymousId;
+    private traits;
+    private logger;
+    /**
+     * @param options - Client configuration (token, service name, advanced settings).
+     */
+    constructor(options?: IntrospectionClientOptions);
+    /**
+     * Load anonymous ID from localStorage, or generate a new one
+     */
+    private loadAnonymousId;
+    /**
+     * Persist anonymous ID to localStorage
+     */
+    private persistAnonymousId;
+    /**
+     * Load user ID from localStorage
+     */
+    private loadUserId;
+    /**
+     * Persist user ID to localStorage
+     */
+    private persistUserId;
+    /**
+     * Load traits from localStorage
+     */
+    private loadTraits;
+    /**
+     * Persist traits to localStorage
+     */
+    private persistTraits;
+    /** Get gen_ai context from baggage */
+    private getGenAiFromContext;
+    /** Get identity from baggage or client instance */
+    private getIdentityFromContext;
+    /**
+     * Get current timestamp as OpenTelemetry HrTime.
+     * Uses performance.now() for high-resolution timing in browsers.
+     */
+    private getTimestamp;
+    /**
+     * Build log record attributes.
+     */
+    private buildAttributes;
+    /**
+     * Track a custom event.
+     *
+     * @param eventName - The event name (e.g., `"Button Clicked"`).
+     * @param properties - Optional properties to attach to the event.
+     * @param options - Optional overrides (e.g., custom `eventId`).
+     *
+     * @example
+     * ```ts
+     * client.track("Button Clicked", { buttonId: "submit" });
+     * ```
+     */
+    track(eventName: string, properties?: Record<string, unknown>, options?: {
+        eventId?: string;
+    }): void;
+    /**
+     * Track feedback on a message or response.
+     *
+     * gen_ai.conversation.id, gen_ai.request.previous_response_id, and agent context
+     * are automatically extracted from baggage if not provided explicitly.
+     *
+     * @param name - Feedback name/action (e.g., "thumbs_up", "thumbs_down")
+     * @param options - Optional feedback options
+     *
+     * @example
+     * ```typescript
+     * // Simple feedback
+     * client.feedback("thumbs_up");
+     *
+     * // With comments
+     * client.feedback("thumbs_down", { comments: "Off topic" });
+     *
+     * // With explicit gen_ai context
+     * client.feedback("thumbs_up", {
+     *   conversationId: "conv_456",
+     *   previousResponseId: "msg_123",
+     * });
+     *
+     * // With baggage context
+     * await client.withConversation("conv_456", undefined, async () => {
+     *   client.feedback("thumbs_up"); // auto-includes conversation_id
+     * });
+     * ```
+     */
+    feedback(name: string, options?: FeedbackOptions): void;
+    /**
+     * Identify a user and persist their traits to `localStorage`.
+     *
+     * @param userId - The user's unique identifier.
+     * @param traits - Optional user traits (email, name, plan, etc.).
+     * @param anonymousId - Optional anonymous ID to associate.
+     * @param eventId - Optional event ID (auto-generated if omitted).
+     *
+     * @example
+     * ```ts
+     * client.identify("user-123", { email: "user@example.com", plan: "pro" });
+     * ```
+     */
+    identify(userId: string, traits?: UserTraits, anonymousId?: string, eventId?: string): void;
+    /**
+     * Set the authenticated user ID and persist it to `localStorage`.
+     *
+     * @param userId - The user's unique identifier.
+     *
+     * @example
+     * ```ts
+     * client.setUserId("user-123");
+     * ```
+     */
+    setUserId(userId: string): void;
+    /**
+     * Override the anonymous ID and persist it to `localStorage`.
+     *
+     * @param anonymousId - The anonymous visitor identifier.
+     *
+     * @example
+     * ```ts
+     * client.setAnonymousId("anon-abc");
+     * ```
+     */
+    setAnonymousId(anonymousId: string): void;
+    /**
+     * Get the current anonymous visitor identifier.
+     *
+     * @returns The anonymous ID (auto-generated on first access if not set).
+     *
+     * @example
+     * ```ts
+     * const anonId = client.getAnonymousId();
+     * ```
+     */
+    getAnonymousId(): string;
+    /**
+     * Create a context with baggage values set.
+     * Use with context.with() to run code in that context.
+     *
+     * Note: In browsers, automatic context propagation requires Zone.js.
+     * Without it, you must manually pass context through async operations.
+     *
+     * @param values - Key/value pairs to set as baggage
+     * @returns Context with baggage set
+     *
+     * @example
+     * ```typescript
+     * const ctx = client.createBaggageContext({
+     *   "gen_ai.agent.name": "support-bot",
+     *   "gen_ai.conversation.id": "conv_456"
+     * });
+     *
+     * await context.with(ctx, async () => {
+     *   client.feedback("thumbs_up"); // picks up baggage
+     * });
+     * ```
+     */
+    createBaggageContext(values: Record<string, string>): import("@opentelemetry/api").Context;
+    /**
+     * Helper to set multiple baggage values and run a callback.
+     *
+     * @param values - Key/value pairs to set as baggage.
+     * @param callback - Function to run with baggage context.
+     * @returns The return value of the callback.
+     *
+     * @example
+     * ```typescript
+     * await client.withBaggage({
+     *   "gen_ai.conversation.id": "conv_456",
+     *   "gen_ai.request.previous_response_id": "resp_123"
+     * }, async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     * ```
+     */
+    withBaggage<T>(values: Record<string, string>, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Helper to set agent baggage and run a callback.
+     *
+     * @param agentName - Name of the agent.
+     * @param agentId - Optional unique identifier for the agent.
+     * @param callback - Function to run with agent context.
+     * @returns The return value of the callback.
+     *
+     * @example
+     * ```typescript
+     * await client.withAgent("support-bot", "agent_123", async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     * ```
+     */
+    withAgent<T>(agentName: string, agentId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Helper to set conversation baggage and run a callback.
+     *
+     * @param conversationId - Unique identifier for the conversation (optional).
+     * @param previousResponseId - Previous response ID for conversation continuity (optional).
+     * @param callback - Function to run with conversation context.
+     * @returns The return value of the callback.
+     *
+     * @example
+     * ```typescript
+     * // Simple conversation context
+     * await client.withConversation("conv_456", undefined, async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     *
+     * // With previous response for conversation continuity
+     * await client.withConversation("conv_456", "resp_123", async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     *
+     * // Just previousResponseId when already in a conversation
+     * await client.withConversation("conv_456", undefined, async () => {
+     *   await client.withConversation(undefined, "resp_1", async () => {
+     *     client.feedback("thumbs_up");
+     *   });
+     * });
+     * ```
+     */
+    withConversation<T>(conversationId: string | undefined, previousResponseId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Helper to set user ID baggage and run a callback.
+     *
+     * @param userId - User identifier.
+     * @param callback - Function to run with user context.
+     * @returns The return value of the callback.
+     *
+     * @example
+     * ```typescript
+     * await client.withUserId("user_123", async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     * ```
+     */
+    withUserId<T>(userId: string, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Helper to set anonymous ID baggage and run a callback.
+     *
+     * @param anonymousId - Anonymous visitor identifier.
+     * @param callback - Function to run with anonymous context.
+     * @returns The return value of the callback.
+     *
+     * @example
+     * ```ts
+     * await client.withAnonymousId("anon-abc", async () => {
+     *   client.feedback("thumbs_up");
+     * });
+     * ```
+     */
+    withAnonymousId<T>(anonymousId: string, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Reset the client state, clearing user identity and generating a new
+     * anonymous ID. Equivalent to a logout operation.
+     *
+     * @example
+     * ```ts
+     * client.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Flush all queued log records to the Introspection backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the client, flushing all pending log records.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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