ardea 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+import https from 'node:https';
+import http from 'node:http';
+
+/** SDK configuration. */
+interface ArdeaConfig {
+    /** Canary API key (must start with cnry_sk_). */
+    apiKey: string;
+    /** Backend endpoint URL. */
+    endpoint?: string;
+    /** Automatically start periodic flush. */
+    autoFlush?: boolean;
+}
+/** @deprecated Use ArdeaConfig instead. */
+type CanaryConfig = ArdeaConfig;
+interface BaseEvent {
+    ts: number;
+    sdk_instance_id?: string;
+    process_id?: number;
+    parent_process_id?: number;
+    process_kind?: string;
+    process_label?: string;
+    thread_id?: number;
+    call_sequence?: number;
+    framework_session_id?: string;
+    agent_name?: string;
+    agent_version?: string;
+    source?: string;
+    source_plane?: "declared";
+    capture_mode?: "declared";
+}
+/** Agent feedback event. */
+interface FeedbackEvent extends BaseEvent {
+    event_type: "feedback";
+    source: string;
+    worked: boolean;
+    context: string;
+    friction_points?: string[];
+    provider?: string;
+    endpoint_pattern?: string;
+}
+/** Union of all event types. */
+type CanaryEvent = FeedbackEvent;
+
+/**
+ * Event buffer with ring buffer, gzip flush, retry, and session cache.
+ *
+ * Mirrors sdk/src/ardea/buffer.py.
+ */
+
+declare class EventBuffer {
+    private _buffer;
+    private _sessionCache;
+    private _sessionCacheEventCount;
+    private _apiKey;
+    private _endpoint;
+    private _timer;
+    private _stopped;
+    /** Reference to the original (unpatched) https.request for anti-recursion. */
+    private _originalHttpsRequest;
+    /** Reference to the original (unpatched) http.request for anti-recursion. */
+    private _originalHttpRequest;
+    constructor(apiKey: string, endpoint?: string, autoFlush?: boolean, originalHttpsRequest?: typeof https.request, originalHttpRequest?: typeof http.request);
+    /** Add an event to the ring buffer. */
+    push(event: CanaryEvent): void;
+    /** Return a copy of events for the given session from the cache. */
+    getSessionEvents(sessionId: string): CanaryEvent[];
+    /** Remove session events from the cache. */
+    clearSession(sessionId: string): void;
+    /** Remove and return up to `count` events from the buffer. */
+    drain(count: number): CanaryEvent[];
+    /** Get all buffered events (without draining). For reporter access. */
+    peek(): CanaryEvent[];
+    /** Number of buffered events. */
+    get length(): number;
+    /** Drain a batch and send to backend. */
+    flush(): Promise<void>;
+    /** Stop flush timer and drain all remaining events. */
+    shutdown(): Promise<void>;
+    /** POST events to the backend with gzip compression. */
+    private _send;
+}
+
+/**
+ * Session correlation via AsyncLocalStorage.
+ *
+ * Node.js equivalent of sdk/src/canary/context.py using
+ * AsyncLocalStorage instead of ContextVar.
+ */
+interface SessionSignals {
+    sdk_instance_id: string;
+    process_id: number;
+    parent_process_id?: number;
+    process_kind?: string;
+    process_label?: string;
+    thread_id: number;
+    call_sequence: number;
+    framework_session_id?: string;
+    agent_name?: string;
+    agent_version?: string;
+}
+/**
+ * Return session correlation signals for the current execution context.
+ */
+declare function getSessionSignals(): SessionSignals;
+/**
+ * Set the framework session ID for the current async context.
+ *
+ * If no async context is active, this becomes the default session ID used
+ * by subsequent feedback/reporting calls on this process.
+ */
+declare function setFrameworkSession(sessionId: string): void;
+/**
+ * Clear the framework session ID for the current async context.
+ */
+declare function clearFrameworkSession(): void;
+/**
+ * Run a function with a scoped framework session ID.
+ *
+ * The session ID propagates through async call chains automatically.
+ */
+declare function runWithSession<T>(sessionId: string, fn: () => T): T;
+
+/**
+ * Detect which AI agent framework is running via environment variables.
+ */
+interface AgentInfo {
+    agent_name: string | null;
+    agent_version: string | null;
+}
+declare function detectAgent(): AgentInfo;
+declare function resetAgentCache(): void;
+
+/**
+ * ardea — MCP tools for AI agents to report API experiences.
+ */
+
+/**
+ * Initialize Canary SDK for manual feedback submission.
+ */
+declare function init(config: CanaryConfig): void;
+/**
+ * Shut down the SDK and flush any queued feedback events.
+ */
+declare function shutdown(): Promise<void>;
+/**
+ * Submit manual feedback.
+ */
+declare function survey(options: {
+    worked?: boolean;
+    context?: string;
+    frictionPoints?: string[];
+    provider?: string;
+    sessionId?: string;
+}): void;
+/**
+ * Get the global EventBuffer (for advanced usage / adapters).
+ */
+declare function getBuffer(): EventBuffer | null;
+
+/** Alias for init — Ardea rebrand entry point. */
+declare const Ardea: {
+    init: typeof init;
+    shutdown: typeof shutdown;
+    survey: typeof survey;
+    getBuffer: typeof getBuffer;
+};
+/** @deprecated Use Ardea instead. */
+declare const Canary: {
+    init: typeof init;
+    shutdown: typeof shutdown;
+    survey: typeof survey;
+    getBuffer: typeof getBuffer;
+};
+
+export { Ardea, type ArdeaConfig, Canary, type CanaryConfig, type CanaryEvent, type FeedbackEvent, clearFrameworkSession, detectAgent, getBuffer, getSessionSignals, init, resetAgentCache, runWithSession, setFrameworkSession, shutdown, survey };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import https from 'node:https';
+import http from 'node:http';
+
+/** SDK configuration. */
+interface ArdeaConfig {
+    /** Canary API key (must start with cnry_sk_). */
+    apiKey: string;
+    /** Backend endpoint URL. */
+    endpoint?: string;
+    /** Automatically start periodic flush. */
+    autoFlush?: boolean;
+}
+/** @deprecated Use ArdeaConfig instead. */
+type CanaryConfig = ArdeaConfig;
+interface BaseEvent {
+    ts: number;
+    sdk_instance_id?: string;
+    process_id?: number;
+    parent_process_id?: number;
+    process_kind?: string;
+    process_label?: string;
+    thread_id?: number;
+    call_sequence?: number;
+    framework_session_id?: string;
+    agent_name?: string;
+    agent_version?: string;
+    source?: string;
+    source_plane?: "declared";
+    capture_mode?: "declared";
+}
+/** Agent feedback event. */
+interface FeedbackEvent extends BaseEvent {
+    event_type: "feedback";
+    source: string;
+    worked: boolean;
+    context: string;
+    friction_points?: string[];
+    provider?: string;
+    endpoint_pattern?: string;
+}
+/** Union of all event types. */
+type CanaryEvent = FeedbackEvent;
+
+/**
+ * Event buffer with ring buffer, gzip flush, retry, and session cache.
+ *
+ * Mirrors sdk/src/ardea/buffer.py.
+ */
+
+declare class EventBuffer {
+    private _buffer;
+    private _sessionCache;
+    private _sessionCacheEventCount;
+    private _apiKey;
+    private _endpoint;
+    private _timer;
+    private _stopped;
+    /** Reference to the original (unpatched) https.request for anti-recursion. */
+    private _originalHttpsRequest;
+    /** Reference to the original (unpatched) http.request for anti-recursion. */
+    private _originalHttpRequest;
+    constructor(apiKey: string, endpoint?: string, autoFlush?: boolean, originalHttpsRequest?: typeof https.request, originalHttpRequest?: typeof http.request);
+    /** Add an event to the ring buffer. */
+    push(event: CanaryEvent): void;
+    /** Return a copy of events for the given session from the cache. */
+    getSessionEvents(sessionId: string): CanaryEvent[];
+    /** Remove session events from the cache. */
+    clearSession(sessionId: string): void;
+    /** Remove and return up to `count` events from the buffer. */
+    drain(count: number): CanaryEvent[];
+    /** Get all buffered events (without draining). For reporter access. */
+    peek(): CanaryEvent[];
+    /** Number of buffered events. */
+    get length(): number;
+    /** Drain a batch and send to backend. */
+    flush(): Promise<void>;
+    /** Stop flush timer and drain all remaining events. */
+    shutdown(): Promise<void>;
+    /** POST events to the backend with gzip compression. */
+    private _send;
+}
+
+/**
+ * Session correlation via AsyncLocalStorage.
+ *
+ * Node.js equivalent of sdk/src/canary/context.py using
+ * AsyncLocalStorage instead of ContextVar.
+ */
+interface SessionSignals {
+    sdk_instance_id: string;
+    process_id: number;
+    parent_process_id?: number;
+    process_kind?: string;
+    process_label?: string;
+    thread_id: number;
+    call_sequence: number;
+    framework_session_id?: string;
+    agent_name?: string;
+    agent_version?: string;
+}
+/**
+ * Return session correlation signals for the current execution context.
+ */
+declare function getSessionSignals(): SessionSignals;
+/**
+ * Set the framework session ID for the current async context.
+ *
+ * If no async context is active, this becomes the default session ID used
+ * by subsequent feedback/reporting calls on this process.
+ */
+declare function setFrameworkSession(sessionId: string): void;
+/**
+ * Clear the framework session ID for the current async context.
+ */
+declare function clearFrameworkSession(): void;
+/**
+ * Run a function with a scoped framework session ID.
+ *
+ * The session ID propagates through async call chains automatically.
+ */
+declare function runWithSession<T>(sessionId: string, fn: () => T): T;
+
+/**
+ * Detect which AI agent framework is running via environment variables.
+ */
+interface AgentInfo {
+    agent_name: string | null;
+    agent_version: string | null;
+}
+declare function detectAgent(): AgentInfo;
+declare function resetAgentCache(): void;
+
+/**
+ * ardea — MCP tools for AI agents to report API experiences.
+ */
+
+/**
+ * Initialize Canary SDK for manual feedback submission.
+ */
+declare function init(config: CanaryConfig): void;
+/**
+ * Shut down the SDK and flush any queued feedback events.
+ */
+declare function shutdown(): Promise<void>;
+/**
+ * Submit manual feedback.
+ */
+declare function survey(options: {
+    worked?: boolean;
+    context?: string;
+    frictionPoints?: string[];
+    provider?: string;
+    sessionId?: string;
+}): void;
+/**
+ * Get the global EventBuffer (for advanced usage / adapters).
+ */
+declare function getBuffer(): EventBuffer | null;
+
+/** Alias for init — Ardea rebrand entry point. */
+declare const Ardea: {
+    init: typeof init;
+    shutdown: typeof shutdown;
+    survey: typeof survey;
+    getBuffer: typeof getBuffer;
+};
+/** @deprecated Use Ardea instead. */
+declare const Canary: {
+    init: typeof init;
+    shutdown: typeof shutdown;
+    survey: typeof survey;
+    getBuffer: typeof getBuffer;
+};
+
+export { Ardea, type ArdeaConfig, Canary, type CanaryConfig, type CanaryEvent, type FeedbackEvent, clearFrameworkSession, detectAgent, getBuffer, getSessionSignals, init, resetAgentCache, runWithSession, setFrameworkSession, shutdown, survey };