@firstflow/core 0.0.5

package/README.md

@@ -0,0 +1,130 @@
+# @firstflow/core
+
+Server SDK for Firstflow. Two product areas:
+
+1. **Token route** — `firstflowToken()` — one-line Next.js handler that issues short-lived JWTs for your end-users.
+2. **LLM observability** — import a pre-wrapped `OpenAI` / `Anthropic` client and tag each call with `firstflowAgent` + `firstflowSession` to auto-track tokens, latency, cost, and conversations.
+
+Both read `FIRSTFLOW_API_KEY` from env. That's the only required configuration.
+
+## Install
+
+```bash
+npm install @firstflow/core @firstflow/react
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `FIRSTFLOW_API_KEY` | **Required.** Clerk-backed API key scoped to one or more agents (`agent:<id>` scope). Create in dashboard → Settings → API Keys. Secret — never expose to the browser. |
+| `FIRSTFLOW_API_BASE_URL` | Optional. Override Firstflow Cloud base URL. Defaults to `https://api.firstflow.app`. Only set when self-hosting. |
+| `FIRSTFLOW_CAPTURE_LLM_CONTENT` | Optional `true` / `false` (default **`false`**). When **`false`**, prompts/completions are **not** captured by OTel spans (PII-safe default). Set to **`true`** to capture message bodies in LLM analytics. |
+
+## Quick start — widget integration
+
+```ts
+// app/api/firstflow/route.ts
+import { firstflowToken } from "@firstflow/core";
+import { auth, currentUser } from "@clerk/nextjs/server";
+
+export const POST = firstflowToken(async () => {
+  const { userId } = await auth();
+  if (!userId) throw new Error("Unauthorized");
+  const user = await currentUser();
+  return {
+    userId,
+    traits: {
+      name:  user?.fullName,
+      email: user?.emailAddresses[0]?.emailAddress,
+      plan:  user?.publicMetadata?.plan,
+    },
+  };
+});
+```
+
+```tsx
+// app/layout.tsx
+import { FirstflowProvider, FirstflowWidget } from "@firstflow/react";
+
+export default function RootLayout({ children }) {
+  return (
+    <FirstflowProvider agentId="agt_abc123">
+      {children}
+      <FirstflowWidget />
+    </FirstflowProvider>
+  );
+}
+```
+
+That's the full integration. The Provider defaults `tokenEndpoint` to `/api/firstflow` — matches the path you mounted in the route file.
+
+## Quick start — LLM observability
+
+Import the pre-wrapped client and tag each call. No setup step, no async factory.
+
+```ts
+import { OpenAI } from "@firstflow/core/openai";
+
+const openai = new OpenAI();
+
+const response = await openai.chat.completions.create({
+  firstflowAgentId: "agt_abc123",      // the agent this call belongs to
+  sessionId:        "user-session-1",  // the conversation/thread
+  userId:           "u_123",           // the end-user (stable across sessions)
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+});
+```
+
+All three identifiers are required. `firstflowAgentId`, `sessionId`, and `userId` are
+stripped before the request reaches OpenAI / Anthropic. Tokens, latency, cost, and the
+conversation turn are tracked automatically — no extra `observe()` call needed.
+`Anthropic` works the same way on `messages.create`.
+
+The model is **user → sessions → messages**: a user has many sessions; a session has
+many messages.
+
+### Other LLM frameworks
+
+If you don't call the OpenAI / Anthropic SDKs directly (e.g. the Vercel AI SDK),
+record turns with the standalone `observe()`:
+
+```ts
+import { observe } from "@firstflow/core";
+
+observe({
+  firstflowAgentId: "agt_abc123",
+  sessionId:        "user-session-1",
+  userId:           "u_123",
+  role: "assistant",
+  content: text,
+  model: "gpt-4o",
+  inputTokens, outputTokens,
+});
+```
+
+## API surface
+
+### Widget token route
+
+- `firstflowToken(identity, opts?)` — Next.js `POST` handler. `identity()` returns `{ userId, traits? }` for the current request.
+
+### Observability
+
+The SDK is agent-centric: every call is partitioned by `firstflowAgentId`. There is
+no global "active agent" — the agent is always passed per-call. All helpers read
+`FIRSTFLOW_API_KEY` from the environment. The three identifiers (`firstflowAgentId`,
+`sessionId`, `userId`) are required wherever they apply.
+
+- `new OpenAI()` (from `@firstflow/core/openai`) / `new Anthropic()` (from `@firstflow/core/anthropic`) — drop-in clients; tag calls with `firstflowAgentId` + `sessionId` + `userId`. Each subpath loads only its own peer SDK.
+- `observe({ firstflowAgentId, sessionId, userId, role, content, ... })` — record a turn (non-wrapped integrations).
+- `trace({ firstflowAgentId, ... })` — record a trace with optional nested spans.
+- `outcome({ firstflowAgentId, sessionId, userId, outcome })` — signal session outcome (`completed`, `abandoned`, etc.).
+- `feedback({ firstflowAgentId, sessionId, userId, rating })` — record thumbs-up/down.
+- `track({ firstflowAgentId, userId, event })`, `identify({ firstflowAgentId, userId, traits })` — analytics.
+- `wrapClient(client, ctx)` — advanced: wrap a client you construct yourself.
+
+### Internal
+
+- `listAccessibleAgents({ apiKey })` — used by the test SDK's agent picker. Real customers know their agent IDs from the dashboard.

package/dist/anthropic.d.mts

@@ -0,0 +1,19 @@
+import RealAnthropic from '@anthropic-ai/sdk';
+
+interface FirstflowRequestFields {
+    /** Agent this call is attributed to (primary routing key). Required to observe. */
+    firstflowAgentId?: string;
+    /** Session / conversation id for this call. Required to observe. */
+    sessionId?: string;
+    /** The end-user this call belongs to. Required to observe. */
+    userId?: string;
+}
+declare module "@anthropic-ai/sdk/resources/messages/messages" {
+    interface MessageCreateParamsBase extends FirstflowRequestFields {
+    }
+}
+
+/** Drop-in `Anthropic` client with Firstflow observability built in. */
+declare const Anthropic: typeof RealAnthropic;
+
+export { Anthropic };

package/dist/anthropic.d.ts

@@ -0,0 +1,19 @@
+import RealAnthropic from '@anthropic-ai/sdk';
+
+interface FirstflowRequestFields {
+    /** Agent this call is attributed to (primary routing key). Required to observe. */
+    firstflowAgentId?: string;
+    /** Session / conversation id for this call. Required to observe. */
+    sessionId?: string;
+    /** The end-user this call belongs to. Required to observe. */
+    userId?: string;
+}
+declare module "@anthropic-ai/sdk/resources/messages/messages" {
+    interface MessageCreateParamsBase extends FirstflowRequestFields {
+    }
+}
+
+/** Drop-in `Anthropic` client with Firstflow observability built in. */
+declare const Anthropic: typeof RealAnthropic;
+
+export { Anthropic };