@scoutline-ai/middleware 0.0.0-stage → 0.2.0

package/dist/outcomes.d.ts

@@ -0,0 +1,56 @@
+export type OutcomeOptions = {
+    /** Outcome key. Falls back to the SCOUTLINE_OUTCOME_KEY environment variable. */
+    key?: string;
+    /** Collector URL, for self-hosting or testing. Falls back to SCOUTLINE_ENDPOINT. */
+    endpoint?: string;
+    /**
+     * Sends the visitor's IP from `headers` so the collector can find its country
+     * and network. The collector never stores it. Default true.
+     */
+    sendClientIp?: boolean;
+};
+export type EventDetails = {
+    /**
+     * Makes repeats safe: the same id counts once, so use your order or signup
+     * id. It is hashed before sending, so the id itself never leaves your server.
+     */
+    id?: string;
+    /** Your id for the piece of work. Shows this event in its Workflow timeline. */
+    taskId?: string;
+    sessionId?: string;
+    resourceId?: string;
+    contentVersion?: string;
+    /** Your own opaque reference for who the agent acted for. Never an email. */
+    principalRef?: string;
+    accountRef?: string;
+    /** The incoming request's headers, to record who acted and the trace id. */
+    headers?: Headers | Record<string, string | string[] | undefined>;
+    errorCategory?: string;
+    status?: number;
+    durationMs?: number;
+};
+/** Something the server knows happened, short of a confirmed outcome. */
+export type ServerEventFamily = "search" | "comparison" | "tool_invocation" | "authentication_required" | "permission_denied" | "quote_created" | "checkout_attempted" | "payment_required" | "payment_settled" | "approval_requested" | "human_takeover" | "workflow_resumed";
+export type SendResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * For the things only your server can confirm. Outcomes are never inferred from
+ * a 200, because a page loading doesn't prove the order went through.
+ *
+ * Nothing here throws, so a Scoutline problem can't fail your action. Events
+ * are sent straight away rather than queued, because a serverless function can
+ * stop as soon as it returns. Each one is sent at most twice, up to 2 seconds
+ * each. Don't await it if your action can't spare that.
+ *
+ *   const outcomes = createOutcomes();
+ *   await outcomes.confirm("order.placed", { id: order.id, taskId });
+ */
+export declare function createOutcomes(options?: OutcomeOptions): {
+    confirm: (outcomeKey: string, details?: EventDetails) => Promise<SendResult>;
+    record: (family: ServerEventFamily, details?: EventDetails) => Promise<SendResult>;
+    wrap: <Result>(outcomeKey: string, action: () => Promise<Result>, details?: EventDetails | ((result: Result) => EventDetails)) => Promise<Result>;
+};

package/dist/outcomes.js

@@ -0,0 +1,144 @@
+import { classify, CLASSIFIER_VERSION } from "./classify.js";
+import { DEFAULT_ENDPOINT, env } from "./config.js";
+import { hostFromHeaders, requestFacts, traceId } from "./index.js";
+const SEND_TIMEOUT_MS = 2000;
+const MAX_ID_CHARS = 128;
+function toHeaders(headers) {
+    if (!headers || headers instanceof Headers)
+        return headers ?? new Headers();
+    const result = new Headers();
+    for (const [name, value] of Object.entries(headers)) {
+        if (value !== undefined) {
+            result.set(name, Array.isArray(value) ? value.join(", ") : value);
+        }
+    }
+    return result;
+}
+function bounded(value) {
+    return value && value.length <= MAX_ID_CHARS ? value : undefined;
+}
+async function stableId(parts) {
+    const bytes = new TextEncoder().encode(parts.join("\0"));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    const hex = [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    return `sdk_${hex.slice(0, 40)}`;
+}
+/** Retries can't help with these, so only a failed delivery goes again. */
+function shouldRetry(status) {
+    return status === undefined || status >= 500;
+}
+/**
+ * For the things only your server can confirm. Outcomes are never inferred from
+ * a 200, because a page loading doesn't prove the order went through.
+ *
+ * Nothing here throws, so a Scoutline problem can't fail your action. Events
+ * are sent straight away rather than queued, because a serverless function can
+ * stop as soon as it returns. Each one is sent at most twice, up to 2 seconds
+ * each. Don't await it if your action can't spare that.
+ *
+ *   const outcomes = createOutcomes();
+ *   await outcomes.confirm("order.placed", { id: order.id, taskId });
+ */
+export function createOutcomes(options = {}) {
+    const key = options.key ?? env("SCOUTLINE_OUTCOME_KEY");
+    const endpoint = (options.endpoint ||
+        env("SCOUTLINE_ENDPOINT") ||
+        DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    if (!key) {
+        console.warn("[scoutline] Missing SCOUTLINE_OUTCOME_KEY, so outcomes aren't sent.");
+    }
+    async function post(event) {
+        let status;
+        try {
+            const response = await fetch(`${endpoint}/v1/events`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${key}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ events: [event] }),
+                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+            });
+            status = response.status;
+            if (status !== 202) {
+                await response.body?.cancel();
+                return { status };
+            }
+            const body = (await response.json());
+            return { status, rejected: body.rejected?.[0]?.reason };
+        }
+        catch {
+            return { status };
+        }
+    }
+    async function send(family, outcomeKey, details) {
+        if (!key)
+            return { ok: false, reason: "no_key" };
+        try {
+            const headers = toHeaders(details.headers);
+            const userAgent = headers.get("user-agent");
+            const event = {
+                eventId: details.id
+                    ? await stableId([family, outcomeKey ?? "", details.id])
+                    : crypto.randomUUID(),
+                occurredAt: Date.now(),
+                family,
+                outcomeKey,
+                actor: classify(userAgent),
+                ...requestFacts(headers, { sendClientIp: options.sendClientIp }),
+                host: hostFromHeaders(headers)?.toLowerCase() ?? undefined,
+                interface: "app",
+                traceId: traceId(headers),
+                taskId: bounded(details.taskId),
+                sessionId: bounded(details.sessionId),
+                resourceId: bounded(details.resourceId),
+                contentVersion: bounded(details.contentVersion),
+                principalRef: bounded(details.principalRef),
+                accountRef: bounded(details.accountRef),
+                errorCategory: bounded(details.errorCategory),
+                status: details.status,
+                durationMs: details.durationMs,
+                sampleRate: 1,
+                classifierVersion: CLASSIFIER_VERSION,
+            };
+            let result = await post(event);
+            if (shouldRetry(result.status))
+                result = await post(event);
+            if (result.status === 202 && !result.rejected)
+                return { ok: true };
+            const reason = result.rejected ?? `status_${result.status ?? "none"}`;
+            console.warn(`[scoutline] ${family} wasn't accepted: ${reason}`);
+            return { ok: false, reason };
+        }
+        catch {
+            return { ok: false, reason: "failed" };
+        }
+    }
+    /** Records that the outcome really happened. */
+    function confirm(outcomeKey, details = {}) {
+        return send("outcome_completed", outcomeKey, details);
+    }
+    /** Records a server event, such as a failed checkout, on the timeline. */
+    function record(family, details = {}) {
+        return send(family, undefined, details);
+    }
+    /**
+     * Runs your action and confirms the outcome only if it succeeds. A failure is
+     * rethrown unchanged. Pass a function to take the id from the result.
+     */
+    async function wrap(outcomeKey, action, details = {}) {
+        const result = await action();
+        let resolved = {};
+        try {
+            resolved = typeof details === "function" ? details(result) : details;
+        }
+        catch {
+            // Observation is optional. The customer's action already succeeded.
+        }
+        await confirm(outcomeKey, resolved);
+        return result;
+    }
+    return { confirm, record, wrap };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@scoutline-ai/middleware",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "In-path agent observation for Scoutline. Fails open and adds no work to the hot path.",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./outcomes": {
+      "types": "./dist/outcomes.d.ts",
+      "default": "./dist/outcomes.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "default": "./dist/fetch.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "scoutline",
+    "ai agents",
+    "analytics",
+    "middleware"
+  ],
+  "homepage": "https://scoutline.ai"
+}