@openattribution/telemetry 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+/**
+ * OpenAttribution Telemetry — TypeScript types.
+ *
+ * Mirrors the Python schema (schema.py) exactly. JSON wire format uses
+ * snake_case; these TypeScript types use camelCase with explicit mapping
+ * in the client layer.
+ *
+ * Specification: https://openattribution.org/telemetry
+ */
+/** Supported event types for telemetry tracking. */
+type EventType = "content_retrieved" | "content_displayed" | "content_engaged" | "content_cited" | "turn_started" | "turn_completed" | "product_viewed" | "product_compared" | "cart_add" | "cart_remove" | "checkout_started" | "checkout_completed" | "checkout_abandoned";
+/** Session outcome classifications. */
+type OutcomeType = "conversion" | "abandonment" | "browse";
+/**
+ * Privacy levels for conversation data sharing.
+ * - `full`: Complete query and response text included.
+ * - `summary`: LLM-generated summary of the conversation.
+ * - `intent`: Only classified intent/topic, no raw text.
+ * - `minimal`: Only metadata (token counts, content URLs).
+ */
+type PrivacyLevel = "full" | "summary" | "intent" | "minimal";
+/** Standardised intent categories for conversation classification. */
+type IntentCategory = "product_research" | "comparison" | "how_to" | "troubleshooting" | "general_question" | "purchase_intent" | "price_check" | "availability_check" | "review_seeking" | "chitchat" | "other";
+/** Actor type for the session initiator. */
+type InitiatorType = "user" | "agent";
+/** How a cited piece of content was used in an agent response. */
+type CitationType = "direct_quote" | "paraphrase" | "reference" | "contradiction";
+/** Prominence of cited content within a response. */
+type CitationPosition = "primary" | "supporting" | "mentioned";
+/** Identity of the initiating agent (when initiator_type is "agent"). */
+interface Initiator {
+    agentId?: string;
+    manifestRef?: string;
+    operatorId?: string;
+}
+/**
+ * User context for segmentation and attribution.
+ * Do not include PII — use hashed or synthetic identifiers.
+ */
+interface UserContext {
+    externalId?: string;
+    segments?: string[];
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Captured conversation turn with privacy controls.
+ * Populate only the fields appropriate for your privacy level.
+ */
+interface ConversationTurn {
+    privacyLevel?: PrivacyLevel;
+    queryText?: string;
+    responseText?: string;
+    queryIntent?: IntentCategory;
+    responseType?: string;
+    topics?: string[];
+    contentUrlsRetrieved?: string[];
+    contentUrlsCited?: string[];
+    queryTokens?: number;
+    responseTokens?: number;
+    modelId?: string;
+}
+/** Single telemetry event within a session. */
+interface TelemetryEvent {
+    /** Unique event identifier (UUID v4). */
+    id: string;
+    type: EventType;
+    /** UTC timestamp in ISO 8601 format. */
+    timestamp: string;
+    /** Associated content URL, if applicable. */
+    contentUrl?: string;
+    /** Associated product UUID, if applicable. */
+    productId?: string;
+    /** Conversation turn data for turn_started/turn_completed events. */
+    turn?: ConversationTurn;
+    /** Additional event-specific metadata. */
+    data?: Record<string, unknown>;
+}
+/** Session outcome for attribution calculation. */
+interface SessionOutcome {
+    type: OutcomeType;
+    /** Monetary value in minor currency units (e.g. 4999 = $49.99). */
+    valueAmount?: number;
+    /** ISO 4217 currency code. Default: "USD". */
+    currency?: string;
+    /** Product UUIDs involved in the outcome. */
+    products?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Options for starting a new session. */
+interface StartSessionOptions {
+    contentScope?: string;
+    agentId?: string;
+    externalSessionId?: string;
+    userContext?: UserContext;
+    manifestRef?: string;
+    priorSessionIds?: string[];
+    initiatorType?: InitiatorType;
+    initiator?: Initiator;
+}
+/** Complete telemetry session (for bulk upload). */
+interface TelemetrySession {
+    schemaVersion?: string;
+    sessionId: string;
+    initiatorType?: InitiatorType;
+    initiator?: Initiator;
+    agentId?: string;
+    contentScope?: string;
+    manifestRef?: string;
+    priorSessionIds?: string[];
+    startedAt: string;
+    endedAt?: string;
+    userContext?: UserContext;
+    events: TelemetryEvent[];
+    outcome?: SessionOutcome;
+}
+/** Options for TelemetryClient. */
+interface TelemetryClientOptions {
+    /** Base URL of the OpenAttribution Telemetry server. */
+    endpoint: string;
+    /** API key sent as X-API-Key header. */
+    apiKey?: string;
+    /**
+     * If true, failed requests are logged and swallowed rather than thrown.
+     * Default: true.
+     */
+    failSilently?: boolean;
+    /** Request timeout in milliseconds. Default: 30_000. */
+    timeout?: number;
+    /** Maximum retry attempts for transient errors. Default: 3. */
+    maxRetries?: number;
+}
+
+/**
+ * OpenAttribution Telemetry — HTTP client.
+ *
+ * Zero dependencies — uses native fetch (Node 18+, Deno, browsers, Edge).
+ */
+
+/**
+ * Async client for recording OpenAttribution telemetry.
+ *
+ * Works in Node.js ≥ 18, Deno, browsers, and Edge runtimes (Vercel, Cloudflare).
+ *
+ * @example
+ * ```ts
+ * const client = new TelemetryClient({
+ *   endpoint: "https://telemetry.example.com",
+ *   apiKey: "your-api-key",
+ *   failSilently: true,
+ * });
+ *
+ * const sessionId = await client.startSession({ contentScope: "my-mix" });
+ *
+ * await client.recordEvents(sessionId, [
+ *   { id: crypto.randomUUID(), type: "content_retrieved",
+ *     timestamp: new Date().toISOString(), contentUrl: "https://..." }
+ * ]);
+ *
+ * await client.endSession(sessionId, { type: "browse" });
+ * ```
+ */
+declare class TelemetryClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly failSilently;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(options: TelemetryClientOptions);
+    private headers;
+    private post;
+    /**
+     * Start a new telemetry session.
+     *
+     * @returns Session ID string, or null on silent failure.
+     */
+    startSession(options?: StartSessionOptions): Promise<string | null>;
+    /**
+     * Record a single telemetry event.
+     */
+    recordEvent(sessionId: string | null, eventType: EventType, options?: {
+        contentUrl?: string;
+        productId?: string;
+        turn?: ConversationTurn;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Record a batch of telemetry events.
+     */
+    recordEvents(sessionId: string | null, events: TelemetryEvent[]): Promise<void>;
+    /**
+     * End a session with an outcome.
+     */
+    endSession(sessionId: string | null, outcome: SessionOutcome): Promise<void>;
+    /**
+     * Upload a complete session in one request (bulk path).
+     *
+     * Useful for post-hoc reporting or when you've built the session
+     * locally and want to submit it in one shot.
+     *
+     * @returns Server-assigned session ID, or null on silent failure.
+     */
+    uploadSession(session: TelemetrySession): Promise<string | null>;
+}
+
+/**
+ * OpenAttribution Telemetry — MCP session tracker.
+ *
+ * Provides session continuity across stateless MCP tool calls.
+ * The calling agent passes a stable `sessionId` string; this module
+ * maps it to an OA session UUID and reuses it across tool calls within
+ * the same server process.
+ *
+ * Usage in an MCP tool:
+ *
+ * ```ts
+ * import { TelemetryClient, MCPSessionTracker } from "@openattribution/telemetry";
+ *
+ * const client = new TelemetryClient({ endpoint: "...", apiKey: "..." });
+ * const tracker = new MCPSessionTracker(client, "my-agent");
+ *
+ * // In your MCP tool handler:
+ * server.tool("search_products", { query: z.string(), sessionId: z.string().optional() },
+ *   async ({ query, sessionId }) => {
+ *     const results = await searchProducts(query);
+ *     await tracker.trackRetrieved(sessionId, results.map(r => r.url));
+ *     return formatResults(results);
+ *   }
+ * );
+ * ```
+ */
+
+/**
+ * Session tracker for MCP agents.
+ *
+ * Maintains an in-process mapping of external session IDs to OA session UUIDs.
+ * Sessions are created on first use and reused across subsequent tool calls.
+ *
+ * The in-process registry is intentionally simple — it works correctly for
+ * single-process MCP servers. For distributed deployments, pass a shared
+ * external store to the constructor.
+ */
+declare class MCPSessionTracker {
+    private readonly client;
+    private readonly contentScope;
+    private readonly registry;
+    /**
+     * @param client - Configured TelemetryClient instance.
+     * @param contentScope - Stable identifier for this agent's content scope
+     *   (e.g. mix ID, manifest reference, or descriptive slug like "my-shopping-agent").
+     */
+    constructor(client: TelemetryClient, contentScope?: string);
+    /**
+     * Get or create an OA session for the given external session ID.
+     *
+     * If `externalSessionId` is undefined, a new anonymous session is created
+     * on every call (no continuity across tool calls).
+     *
+     * @returns OA session ID string, or null on silent failure.
+     */
+    getOrCreateSession(externalSessionId: string | undefined): Promise<string | null>;
+    /**
+     * Emit `content_retrieved` events for a list of URLs.
+     *
+     * Call this after fetching products, search results, or any content
+     * that influenced the agent's response.
+     *
+     * @param externalSessionId - Caller-supplied conversation identifier.
+     * @param urls - URLs of content retrieved during this tool call.
+     */
+    trackRetrieved(externalSessionId: string | undefined, urls: string[]): Promise<void>;
+    /**
+     * Emit `content_cited` events for content explicitly referenced in a response.
+     *
+     * Call this when you know which content the agent cited — e.g. the top
+     * search result, an editorial quote, or a product recommendation.
+     *
+     * @param externalSessionId - Caller-supplied conversation identifier.
+     * @param urls - URLs of content cited in the agent's response.
+     * @param options - Optional citation metadata.
+     */
+    trackCited(externalSessionId: string | undefined, urls: string[], options?: {
+        citationType?: "direct_quote" | "paraphrase" | "reference" | "contradiction";
+        position?: "primary" | "supporting" | "mentioned";
+    }): Promise<void>;
+    /**
+     * End a session with an outcome.
+     *
+     * Call this when the conversation concludes — at checkout, after
+     * the user clicks a link, or when the session times out.
+     */
+    endSession(externalSessionId: string | undefined, outcome: {
+        type: "conversion" | "abandonment" | "browse";
+        valueAmount?: number;
+        currency?: string;
+    }): Promise<void>;
+    /** Number of active sessions in the registry. */
+    get sessionCount(): number;
+}
+
+/**
+ * OpenAttribution Telemetry — content URL extraction utilities.
+ *
+ * Helpers for extracting content URLs from AI-generated text, so they
+ * can be recorded as telemetry events without manual instrumentation.
+ */
+/**
+ * Extract all HTTP/HTTPS URLs from Markdown-formatted text.
+ *
+ * Finds URLs in two forms:
+ * - Markdown links: `[anchor text](https://...)`
+ * - Bare URLs: `https://...`
+ *
+ * Results are deduplicated. Useful for extracting citation URLs from
+ * AI model responses that include web search results.
+ *
+ * @example
+ * ```ts
+ * const text = "According to [Wirecutter](https://nytimes.com/wirecutter/reviews/...), ...";
+ * const urls = extractCitationUrls(text);
+ * // ["https://nytimes.com/wirecutter/reviews/..."]
+ * ```
+ */
+declare function extractCitationUrls(text: string): string[];
+/**
+ * Extract URLs from a list of search result objects.
+ *
+ * Accepts any object with a `url` string property — works with
+ * Channel3, Exa, Tavily, and most search API responses.
+ *
+ * @example
+ * ```ts
+ * const products = await channel3.search({ query: "headphones" });
+ * const urls = extractResultUrls(products);
+ * await tracker.trackRetrieved(sessionId, urls);
+ * ```
+ */
+declare function extractResultUrls(results: Array<{
+    url?: string | null;
+    link?: string | null;
+}>): string[];
+
+/**
+ * OpenAttribution Telemetry — ACP (Agentic Commerce Protocol) bridge.
+ *
+ * Converts a TelemetrySession into the `content_attribution` object
+ * defined in the ACP RFC. Include this in a CheckoutSessionCreateRequest
+ * or CheckoutSessionCompleteRequest.
+ *
+ * Reference: acp/rfc.content_attribution.md
+ */
+
+interface ContentAttributionRetrieved {
+    content_url: string;
+    timestamp: string;
+}
+interface ContentAttributionCited {
+    content_url: string;
+    timestamp: string;
+    citation_type?: string;
+    excerpt_tokens?: number;
+    position?: string;
+    content_hash?: string;
+}
+interface ConversationSummary {
+    turn_count: number;
+    topics: string[];
+}
+/**
+ * ACP `content_attribution` object.
+ * Include in CheckoutSessionCreateRequest.content_attribution.
+ */
+interface ContentAttribution {
+    content_scope?: string;
+    content_retrieved: ContentAttributionRetrieved[];
+    content_cited?: ContentAttributionCited[];
+    conversation_summary?: ConversationSummary;
+}
+/**
+ * Convert a TelemetrySession into an ACP `content_attribution` object.
+ *
+ * @example
+ * ```ts
+ * import { sessionToContentAttribution } from "@openattribution/telemetry/acp";
+ *
+ * const attribution = sessionToContentAttribution(session);
+ *
+ * // Include in ACP checkout request:
+ * await acp.createCheckout({
+ *   cart: { ... },
+ *   content_attribution: attribution,
+ * });
+ * ```
+ */
+declare function sessionToContentAttribution(session: TelemetrySession): ContentAttribution;
+
+/**
+ * OpenAttribution Telemetry — UCP (Universal Checkout Protocol) bridge.
+ *
+ * Converts a TelemetrySession into the UCP attribution extension object.
+ *
+ * Reference: ucp/EXTENSION.md
+ */
+
+interface UCPAttribution {
+    content_scope?: string;
+    prior_session_ids?: string[];
+    content_retrieved: Array<{
+        content_url: string;
+        timestamp: string;
+    }>;
+    content_cited?: Array<{
+        content_url: string;
+        timestamp: string;
+        citation_type?: string;
+        position?: string;
+    }>;
+    conversation_summary?: {
+        turn_count: number;
+        topics: string[];
+    };
+}
+/**
+ * Convert a TelemetrySession into a UCP attribution extension object.
+ *
+ * @example
+ * ```ts
+ * import { sessionToAttribution } from "@openattribution/telemetry/ucp";
+ *
+ * const attribution = sessionToAttribution(session);
+ *
+ * // Include in UCP checkout:
+ * await ucp.completeCheckout({
+ *   order: { ... },
+ *   extensions: { "org.openattribution.telemetry": attribution },
+ * });
+ * ```
+ */
+declare function sessionToAttribution(session: TelemetrySession): UCPAttribution;
+
+export { type CitationPosition, type CitationType, type ContentAttribution, type ContentAttributionCited, type ContentAttributionRetrieved, type ConversationTurn, type EventType, type Initiator, type InitiatorType, type IntentCategory, MCPSessionTracker, type OutcomeType, type PrivacyLevel, type SessionOutcome, type StartSessionOptions, TelemetryClient, type TelemetryClientOptions, type TelemetryEvent, type TelemetrySession, type UCPAttribution, type UserContext, extractCitationUrls, extractResultUrls, sessionToAttribution, sessionToContentAttribution };