@firstflow/core 0.0.5

package/dist/index.d.mts

@@ -0,0 +1,257 @@
+/** A recent conversation turn forwarded as sliding-window context. */
+type RecentMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+/** LLM call metadata captured automatically by the proxy wrapper. */
+type LlmCallMeta = {
+    model?: string;
+    provider?: "openai" | "anthropic";
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    finishReason?: string;
+    isError?: boolean;
+    error?: string;
+    inputCostUsd?: number;
+    outputCostUsd?: number;
+    totalCostUsd?: number;
+    httpStatus?: number;
+};
+type ObserveArgs = {
+    /** The agent this message is attributed to. Primary routing key. */
+    agentId: string;
+    conversationId: string;
+    userId: string;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    /**
+     * Bounded sliding window of recent turns (from the LLM request). Sent with an
+     * assistant observe so the backend can give classify nodes / widget
+     * composition real conversation context. Never the full transcript.
+     */
+    recentMessages?: RecentMessage[];
+    /** Arbitrary metadata forwarded alongside the message (e.g. plan tier, A/B variant). */
+    properties?: Record<string, unknown>;
+} & LlmCallMeta;
+type SpanType = "generation" | "tool_call" | "retrieval" | "embedding" | "span";
+type SpanInput = {
+    spanId?: string;
+    parentSpanId?: string;
+    type?: SpanType;
+    name?: string;
+    model?: string;
+    provider?: string;
+    /** Full input payload (messages array, prompt, etc.) */
+    input?: unknown;
+    /** Raw LLM response or tool output */
+    output?: unknown;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    finishReason?: string;
+    isError?: boolean;
+    error?: string;
+    inputCostUsd?: number;
+    outputCostUsd?: number;
+    totalCostUsd?: number;
+    toolsCalled?: string[];
+    toolCallCount?: number;
+    inputState?: unknown;
+    outputState?: unknown;
+    httpStatus?: number;
+    properties?: Record<string, unknown>;
+    startedAt?: Date | string;
+    endedAt?: Date | string;
+};
+type TraceInput = {
+    traceId?: string;
+    /** Link this trace to a conversation — pass the same session id used on the LLM call. */
+    sessionId?: string;
+    userId?: string;
+    name?: string;
+    inputState?: unknown;
+    outputState?: unknown;
+    latencyMs?: number;
+    isError?: boolean;
+    error?: string;
+    properties?: Record<string, unknown>;
+    startedAt?: Date | string;
+    endedAt?: Date | string;
+    spans?: SpanInput[];
+};
+/**
+ * The outcome of a user session with the AI agent.
+ * Built-in values: 'completed', 'abandoned', 'escalated'.
+ * Any custom string is also accepted (e.g. 'onboarding-finished', 'support-needed').
+ */
+type SessionOutcome = "completed" | "abandoned" | "escalated" | (string & {});
+/** Arguments for `outcome()` — signals what happened at the end of a session. */
+type OutcomeInput = {
+    /** The agent this outcome is attributed to. */
+    firstflowAgentId: string;
+    /** The session/conversation id (same value passed on the LLM call). */
+    sessionId: string;
+    /** The end-user this session belongs to. */
+    userId: string;
+    /**
+     * What happened at the end of the session.
+     * Use 'completed' (user accomplished their goal), 'abandoned' (user left without finishing),
+     * 'escalated' (handed off to human support), or any custom label.
+     */
+    outcome?: SessionOutcome;
+    /**
+     * What the user was trying to accomplish. Free-form label grouped in analytics.
+     * e.g. 'onboarding-setup', 'billing-question', 'how-to', 'troubleshooting'.
+     */
+    intent?: string;
+};
+/** Arguments for `feedback()` — records thumbs-up or thumbs-down for a session. */
+type FeedbackInput = {
+    /** The agent this feedback is attributed to. */
+    firstflowAgentId: string;
+    /** The session/conversation id this feedback belongs to. */
+    sessionId: string;
+    /** The end-user who submitted the feedback. */
+    userId: string;
+    /** 1 = thumbs up, -1 = thumbs down. */
+    rating: 1 | -1;
+    /** Optional free-text comment from the user. Max 500 chars. */
+    comment?: string;
+    /** Optional: the specific message the feedback applies to. */
+    messageId?: string;
+};
+/** Arguments for `track()`. */
+type TrackArgs = {
+    /** The agent this event is attributed to. */
+    firstflowAgentId: string;
+    /** The end-user who triggered the event. */
+    userId: string;
+    event: string;
+    properties?: Record<string, unknown>;
+};
+/** Arguments for `identify()`. */
+type IdentifyArgs = {
+    /** The agent this identity is attributed to. */
+    firstflowAgentId: string;
+    /** The end-user being identified. */
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+/** Arguments for `trace()` — an agent-scoped trace with optional nested spans. */
+type TraceArgs = TraceInput & {
+    /** The agent this trace is attributed to. */
+    firstflowAgentId: string;
+};
+/**
+ * Arguments for the standalone `observe()` — record a single conversation turn.
+ * For integrations that don't use the pre-wrapped `OpenAI` / `Anthropic`
+ * clients (e.g. the Vercel AI SDK, LangChain, or a custom gateway).
+ */
+type ObserveInput = {
+    /** The agent this message is attributed to. */
+    firstflowAgentId: string;
+    /** The session / conversation id this message belongs to. */
+    sessionId: string;
+    /** The end-user this message belongs to. */
+    userId: string;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    recentMessages?: RecentMessage[];
+    properties?: Record<string, unknown>;
+} & LlmCallMeta;
+
+/**
+ * Record a single conversation turn. Use this when you can't use the
+ * pre-wrapped `OpenAI` / `Anthropic` clients (e.g. the Vercel AI SDK or a
+ * custom LLM gateway). Fire-and-forget — never throws.
+ */
+declare function observe(input: ObserveInput): void;
+/** Signal what happened at the end of a session (completed / abandoned / escalated / custom). */
+declare function outcome(input: OutcomeInput): void;
+/** Record explicit thumbs-up (+1) or thumbs-down (-1) feedback for a session. */
+declare function feedback(input: FeedbackInput): void;
+/** Record an analytics event for a user under an agent. */
+declare function track(args: TrackArgs): void;
+/** Attach traits to a user under an agent. */
+declare function identify(args: IdentifyArgs): void;
+/** Record a trace (with optional nested spans) for detailed LLM observability. */
+declare function trace(args: TraceArgs): void;
+
+type WrapContext = {
+    apiKey: string;
+    baseUrl: string;
+    onAssistantComplete?: (args: ObserveArgs) => void;
+    /** Fired once per user turn (when the LLM request ends with a user message). */
+    onUserMessage?: (args: ObserveArgs) => void;
+    /** Fired when the LLM call throws. Re-throws after firing; never swallows errors. */
+    onError?: (args: Pick<ObserveArgs, "agentId" | "conversationId" | "userId"> & LlmCallMeta) => void;
+};
+/**
+ * Transparent `Proxy` over an OpenAI or Anthropic SDK client. Strips `firstflow`
+ * from request bodies, threads `firstflow.user_id` baggage for OTel, and fires
+ * observe hooks with full LLM metadata (model, tokens, latency, cost) once each
+ * call completes.
+ */
+declare function wrapClient<T extends object>(client: T, ctx: WrapContext): T;
+
+/**
+ * Default Firstflow Cloud base URL. The host is intentional and matches
+ * production. To verify if a future regression is suspected:
+ *
+ *   $ nslookup api.firstflow.app
+ *
+ * To override per-instance, pass `baseUrl` to `new Firstflow({...})`.
+ */
+declare const DEFAULT_FIRSTFLOW_BASE_URL = "https://api.firstflow.app";
+declare const FIRSTFLOW_SERVER_PACKAGE_VERSION: "0.0.1-alpha.0";
+
+type AccessibleAgent = {
+    id: string;
+    name: string | null;
+};
+type AccessibleAgentsResult = {
+    /** Agents this API key has access to. */
+    agents: AccessibleAgent[];
+    /**
+     * The workspace (Clerk org) that owns this API key.
+     * Returned by the backend from the API key's subject — no extra env var needed.
+     */
+    workspaceId: string;
+    /**
+     * The workspace's browser-safe publishable key (`pk_live_...`).
+     * Pass directly as `publishableKey` on `<FirstflowProvider />`.
+     * May be `null` if the backend does not yet support this field.
+     */
+    publishableKey: string | null;
+};
+type ListAccessibleAgentsOptions = {
+    /**
+     * Clerk-backed API key that carries `agent:<id>` scopes.
+     * Secret — never expose to the browser.
+     */
+    apiKey: string;
+    /**
+     * Override the Firstflow Cloud base URL.
+     * Defaults to `https://api.firstflow.app`.
+     */
+    baseUrl?: string;
+};
+/**
+ * Returns the agents this API key has access to, plus the workspace ID
+ * derived from the key itself — no extra env var required.
+ *
+ * @example
+ * const { agents, workspaceId } = await Firstflow.listAccessibleAgents({
+ *   apiKey: process.env.FIRSTFLOW_API_KEY!,
+ * });
+ */
+declare function listAccessibleAgents(opts: ListAccessibleAgentsOptions): Promise<AccessibleAgentsResult>;
+
+export { type AccessibleAgent, type AccessibleAgentsResult, DEFAULT_FIRSTFLOW_BASE_URL, FIRSTFLOW_SERVER_PACKAGE_VERSION, type FeedbackInput, type IdentifyArgs, type ListAccessibleAgentsOptions, type LlmCallMeta, type ObserveArgs, type ObserveInput, type OutcomeInput, type RecentMessage, type SessionOutcome, type SpanInput, type SpanType, type TraceArgs, type TraceInput, type TrackArgs, type WrapContext, feedback, identify, listAccessibleAgents, observe, outcome, trace, track, wrapClient };

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+/** A recent conversation turn forwarded as sliding-window context. */
+type RecentMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+/** LLM call metadata captured automatically by the proxy wrapper. */
+type LlmCallMeta = {
+    model?: string;
+    provider?: "openai" | "anthropic";
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    finishReason?: string;
+    isError?: boolean;
+    error?: string;
+    inputCostUsd?: number;
+    outputCostUsd?: number;
+    totalCostUsd?: number;
+    httpStatus?: number;
+};
+type ObserveArgs = {
+    /** The agent this message is attributed to. Primary routing key. */
+    agentId: string;
+    conversationId: string;
+    userId: string;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    /**
+     * Bounded sliding window of recent turns (from the LLM request). Sent with an
+     * assistant observe so the backend can give classify nodes / widget
+     * composition real conversation context. Never the full transcript.
+     */
+    recentMessages?: RecentMessage[];
+    /** Arbitrary metadata forwarded alongside the message (e.g. plan tier, A/B variant). */
+    properties?: Record<string, unknown>;
+} & LlmCallMeta;
+type SpanType = "generation" | "tool_call" | "retrieval" | "embedding" | "span";
+type SpanInput = {
+    spanId?: string;
+    parentSpanId?: string;
+    type?: SpanType;
+    name?: string;
+    model?: string;
+    provider?: string;
+    /** Full input payload (messages array, prompt, etc.) */
+    input?: unknown;
+    /** Raw LLM response or tool output */
+    output?: unknown;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    latencyMs?: number;
+    timeToFirstTokenMs?: number;
+    finishReason?: string;
+    isError?: boolean;
+    error?: string;
+    inputCostUsd?: number;
+    outputCostUsd?: number;
+    totalCostUsd?: number;
+    toolsCalled?: string[];
+    toolCallCount?: number;
+    inputState?: unknown;
+    outputState?: unknown;
+    httpStatus?: number;
+    properties?: Record<string, unknown>;
+    startedAt?: Date | string;
+    endedAt?: Date | string;
+};
+type TraceInput = {
+    traceId?: string;
+    /** Link this trace to a conversation — pass the same session id used on the LLM call. */
+    sessionId?: string;
+    userId?: string;
+    name?: string;
+    inputState?: unknown;
+    outputState?: unknown;
+    latencyMs?: number;
+    isError?: boolean;
+    error?: string;
+    properties?: Record<string, unknown>;
+    startedAt?: Date | string;
+    endedAt?: Date | string;
+    spans?: SpanInput[];
+};
+/**
+ * The outcome of a user session with the AI agent.
+ * Built-in values: 'completed', 'abandoned', 'escalated'.
+ * Any custom string is also accepted (e.g. 'onboarding-finished', 'support-needed').
+ */
+type SessionOutcome = "completed" | "abandoned" | "escalated" | (string & {});
+/** Arguments for `outcome()` — signals what happened at the end of a session. */
+type OutcomeInput = {
+    /** The agent this outcome is attributed to. */
+    firstflowAgentId: string;
+    /** The session/conversation id (same value passed on the LLM call). */
+    sessionId: string;
+    /** The end-user this session belongs to. */
+    userId: string;
+    /**
+     * What happened at the end of the session.
+     * Use 'completed' (user accomplished their goal), 'abandoned' (user left without finishing),
+     * 'escalated' (handed off to human support), or any custom label.
+     */
+    outcome?: SessionOutcome;
+    /**
+     * What the user was trying to accomplish. Free-form label grouped in analytics.
+     * e.g. 'onboarding-setup', 'billing-question', 'how-to', 'troubleshooting'.
+     */
+    intent?: string;
+};
+/** Arguments for `feedback()` — records thumbs-up or thumbs-down for a session. */
+type FeedbackInput = {
+    /** The agent this feedback is attributed to. */
+    firstflowAgentId: string;
+    /** The session/conversation id this feedback belongs to. */
+    sessionId: string;
+    /** The end-user who submitted the feedback. */
+    userId: string;
+    /** 1 = thumbs up, -1 = thumbs down. */
+    rating: 1 | -1;
+    /** Optional free-text comment from the user. Max 500 chars. */
+    comment?: string;
+    /** Optional: the specific message the feedback applies to. */
+    messageId?: string;
+};
+/** Arguments for `track()`. */
+type TrackArgs = {
+    /** The agent this event is attributed to. */
+    firstflowAgentId: string;
+    /** The end-user who triggered the event. */
+    userId: string;
+    event: string;
+    properties?: Record<string, unknown>;
+};
+/** Arguments for `identify()`. */
+type IdentifyArgs = {
+    /** The agent this identity is attributed to. */
+    firstflowAgentId: string;
+    /** The end-user being identified. */
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+/** Arguments for `trace()` — an agent-scoped trace with optional nested spans. */
+type TraceArgs = TraceInput & {
+    /** The agent this trace is attributed to. */
+    firstflowAgentId: string;
+};
+/**
+ * Arguments for the standalone `observe()` — record a single conversation turn.
+ * For integrations that don't use the pre-wrapped `OpenAI` / `Anthropic`
+ * clients (e.g. the Vercel AI SDK, LangChain, or a custom gateway).
+ */
+type ObserveInput = {
+    /** The agent this message is attributed to. */
+    firstflowAgentId: string;
+    /** The session / conversation id this message belongs to. */
+    sessionId: string;
+    /** The end-user this message belongs to. */
+    userId: string;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    recentMessages?: RecentMessage[];
+    properties?: Record<string, unknown>;
+} & LlmCallMeta;
+
+/**
+ * Record a single conversation turn. Use this when you can't use the
+ * pre-wrapped `OpenAI` / `Anthropic` clients (e.g. the Vercel AI SDK or a
+ * custom LLM gateway). Fire-and-forget — never throws.
+ */
+declare function observe(input: ObserveInput): void;
+/** Signal what happened at the end of a session (completed / abandoned / escalated / custom). */
+declare function outcome(input: OutcomeInput): void;
+/** Record explicit thumbs-up (+1) or thumbs-down (-1) feedback for a session. */
+declare function feedback(input: FeedbackInput): void;
+/** Record an analytics event for a user under an agent. */
+declare function track(args: TrackArgs): void;
+/** Attach traits to a user under an agent. */
+declare function identify(args: IdentifyArgs): void;
+/** Record a trace (with optional nested spans) for detailed LLM observability. */
+declare function trace(args: TraceArgs): void;
+
+type WrapContext = {
+    apiKey: string;
+    baseUrl: string;
+    onAssistantComplete?: (args: ObserveArgs) => void;
+    /** Fired once per user turn (when the LLM request ends with a user message). */
+    onUserMessage?: (args: ObserveArgs) => void;
+    /** Fired when the LLM call throws. Re-throws after firing; never swallows errors. */
+    onError?: (args: Pick<ObserveArgs, "agentId" | "conversationId" | "userId"> & LlmCallMeta) => void;
+};
+/**
+ * Transparent `Proxy` over an OpenAI or Anthropic SDK client. Strips `firstflow`
+ * from request bodies, threads `firstflow.user_id` baggage for OTel, and fires
+ * observe hooks with full LLM metadata (model, tokens, latency, cost) once each
+ * call completes.
+ */
+declare function wrapClient<T extends object>(client: T, ctx: WrapContext): T;
+
+/**
+ * Default Firstflow Cloud base URL. The host is intentional and matches
+ * production. To verify if a future regression is suspected:
+ *
+ *   $ nslookup api.firstflow.app
+ *
+ * To override per-instance, pass `baseUrl` to `new Firstflow({...})`.
+ */
+declare const DEFAULT_FIRSTFLOW_BASE_URL = "https://api.firstflow.app";
+declare const FIRSTFLOW_SERVER_PACKAGE_VERSION: "0.0.1-alpha.0";
+
+type AccessibleAgent = {
+    id: string;
+    name: string | null;
+};
+type AccessibleAgentsResult = {
+    /** Agents this API key has access to. */
+    agents: AccessibleAgent[];
+    /**
+     * The workspace (Clerk org) that owns this API key.
+     * Returned by the backend from the API key's subject — no extra env var needed.
+     */
+    workspaceId: string;
+    /**
+     * The workspace's browser-safe publishable key (`pk_live_...`).
+     * Pass directly as `publishableKey` on `<FirstflowProvider />`.
+     * May be `null` if the backend does not yet support this field.
+     */
+    publishableKey: string | null;
+};
+type ListAccessibleAgentsOptions = {
+    /**
+     * Clerk-backed API key that carries `agent:<id>` scopes.
+     * Secret — never expose to the browser.
+     */
+    apiKey: string;
+    /**
+     * Override the Firstflow Cloud base URL.
+     * Defaults to `https://api.firstflow.app`.
+     */
+    baseUrl?: string;
+};
+/**
+ * Returns the agents this API key has access to, plus the workspace ID
+ * derived from the key itself — no extra env var required.
+ *
+ * @example
+ * const { agents, workspaceId } = await Firstflow.listAccessibleAgents({
+ *   apiKey: process.env.FIRSTFLOW_API_KEY!,
+ * });
+ */
+declare function listAccessibleAgents(opts: ListAccessibleAgentsOptions): Promise<AccessibleAgentsResult>;
+
+export { type AccessibleAgent, type AccessibleAgentsResult, DEFAULT_FIRSTFLOW_BASE_URL, FIRSTFLOW_SERVER_PACKAGE_VERSION, type FeedbackInput, type IdentifyArgs, type ListAccessibleAgentsOptions, type LlmCallMeta, type ObserveArgs, type ObserveInput, type OutcomeInput, type RecentMessage, type SessionOutcome, type SpanInput, type SpanType, type TraceArgs, type TraceInput, type TrackArgs, type WrapContext, feedback, identify, listAccessibleAgents, observe, outcome, trace, track, wrapClient };