@softr/sdk 0.0.92 → 0.0.93-alpha.0

package/dist/agent/agent-fns.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import * as _tanstack_react_start9 from "@tanstack/react-start";
+
+//#region src/agent/agent-fns.d.ts
+
+declare const agentSchema: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** An agent the visitor may chat with. */
+type Agent = z.infer<typeof agentSchema>;
+/**
+ * The agents the visitor may chat with in this app. The builder attaches them
+ * in Studio, and each one's visibility settings decide who sees it.
+ */
+declare const listAgents: _tanstack_react_start9.OptionalFetcher<undefined, undefined, Promise<{
+  id: string;
+  title: string;
+  avatar?: string | null | undefined;
+  thumbnail?: string | null | undefined;
+}[]>>;
+/** One past chat with an agent. `title` is null until the agent names the chat. */
+type AgentChatSummary = {
+  id: string;
+  title: string | null;
+};
+//#endregion
+export { Agent, AgentChatSummary, listAgents };

package/dist/agent/agent-fns.js

@@ -0,0 +1,215 @@
+import { assert } from "../assertions.js";
+import { softrApiUrl } from "../softr-api.js";
+import { fetch } from "../fetch.js";
+import { sessionConfig } from "../auth/config.js";
+import { readSessionToken } from "../auth/session.js";
+import { describeFailure, refererHeader } from "../datasource/record.js";
+import { z } from "zod";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+
+//#region src/agent/agent-fns.ts
+const AGENTS_PRODUCTION = "https://agents-api.softr.io";
+const PLATFORM_HOST = /^(platform-api|platform-preview-api|preview-api)(?=[.-])/;
+/**
+* Where the agents service is. It sits next to the platform API, so unless
+* `SOFTR_AGENTS_API_URL` says otherwise, it's the platform's host with
+* `agents-api` in place of the platform's name. Live and preview share one
+* agents service.
+*/
+function agentsApiUrl() {
+	const explicit = process.env.SOFTR_AGENTS_API_URL;
+	if (explicit) return explicit.replace(/\/+$/, "");
+	if (!process.env.SOFTR_PLATFORM_API_URL) return AGENTS_PRODUCTION;
+	const platform = new URL(softrApiUrl("SOFTR_PLATFORM_API_URL"));
+	assert(PLATFORM_HOST.test(platform.hostname), () => `can't tell the agents API from ${platform.origin}, set SOFTR_AGENTS_API_URL`);
+	platform.hostname = platform.hostname.replace(PLATFORM_HOST, "agents-api");
+	return platform.origin;
+}
+function agentsFetch(path, init = {}) {
+	const token = readSessionToken();
+	return fetch(`${agentsApiUrl()}/v1/agents/${path}`, {
+		method: init.method ?? "GET",
+		signal: init.signal,
+		headers: {
+			"Content-Type": "application/json",
+			...token ? { Authorization: `Bearer ${token}` } : {},
+			"Softr-Application-ID": sessionConfig().applicationId,
+			...refererHeader(),
+			...init.headers
+		},
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+	});
+}
+const chatSchema = z.object({
+	agentId: z.string().min(1),
+	message: z.string(),
+	sessionId: z.string().nullable(),
+	timezone: z.string(),
+	pageName: z.string(),
+	pageUrl: z.string(),
+	record: z.object({
+		id: z.string(),
+		fields: z.record(z.string(), z.unknown())
+	}).nullable()
+});
+/**
+* Sends one message and streams the reply back as it comes, one JSON event per line.
+*
+* Takes FormData so the browser can call it with plain `fetch` and read the
+* stream itself. A failed call passes the agents service's status and message on.
+*/
+const agentChatFn = createServerFn({ method: "POST" }).validator((data) => {
+	const payload = data.get("payload");
+	assert(typeof payload === "string", "agent chat: payload is required");
+	return chatSchema.parse(JSON.parse(payload));
+}).handler(async ({ data }) => {
+	const upstream = await agentsFetch(`${encodeURIComponent(data.agentId)}/chat`, {
+		method: "POST",
+		signal: getRequest().signal,
+		headers: {
+			Accept: "application/x-ndjson",
+			"X-User-Timezone": data.timezone
+		},
+		body: {
+			message: data.message,
+			...data.sessionId ? { sessionId: data.sessionId } : {},
+			context: {
+				pageName: data.pageName,
+				pageUrl: data.pageUrl,
+				...data.record ? { currentRecord: { data: data.record } } : {}
+			}
+		}
+	});
+	return new Response(upstream.body, {
+		status: upstream.status,
+		headers: { "Content-Type": upstream.headers.get("Content-Type") ?? "application/x-ndjson" }
+	});
+});
+const agentSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	avatar: z.string().nullish(),
+	thumbnail: z.string().nullish()
+});
+/**
+* The agents the visitor may chat with in this app. The builder attaches them
+* in Studio, and each one's visibility settings decide who sees it.
+*/
+const listAgents = createServerFn({ method: "GET" }).handler(async () => {
+	const token = readSessionToken();
+	const res = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${sessionConfig().applicationId}/agents`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+	if (!res.ok) throw new Error(`Loading agents failed: ${await describeFailure(res)}`);
+	return z.array(agentSchema).parse(await res.json());
+});
+const listAgentChatsFn = createServerFn({ method: "POST" }).validator(z.object({ agentId: z.string().min(1) })).handler(async ({ data }) => {
+	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions`);
+	if (!res.ok) throw new Error(`Loading chats failed: ${await describeFailure(res)}`);
+	return z.array(z.object({
+		id: z.string(),
+		title: z.string().nullable()
+	})).parse(await res.json());
+});
+const historySchema = z.object({
+	messages: z.array(z.object({
+		id: z.string(),
+		role: z.enum(["USER", "ASSISTANT"]),
+		content: z.string(),
+		createdAt: z.number()
+	})),
+	toolCalls: z.array(z.object({
+		id: z.string(),
+		messageId: z.string(),
+		toolName: z.string(),
+		input: z.string(),
+		createdAt: z.number(),
+		metadata: z.object({
+			innerThought: z.string().nullish(),
+			durationMs: z.number().nullish(),
+			failed: z.boolean().nullish()
+		})
+	}))
+});
+const CHAT_GONE = [
+	401,
+	403,
+	404,
+	410
+];
+/** What a past chat holds, or `null` when it's gone or belongs to someone else. */
+const loadAgentChatFn = createServerFn({ method: "POST" }).validator(z.object({
+	agentId: z.string().min(1),
+	sessionId: z.string().min(1)
+})).handler(async ({ data }) => {
+	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions/${encodeURIComponent(data.sessionId)}`);
+	if (CHAT_GONE.includes(res.status)) return null;
+	if (!res.ok) throw new Error(`Loading the chat failed: ${await describeFailure(res)}`);
+	return historySchema.parse(await res.json());
+});
+/** Saves the visitor's answer. `false` when the chat is gone, see `loadAgentChatFn`. */
+const decideAgentToolFn = createServerFn({ method: "POST" }).validator(z.object({
+	agentId: z.string().min(1),
+	sessionId: z.string().min(1),
+	toolCallId: z.string().min(1),
+	toolName: z.string().min(1),
+	decision: z.enum(["APPROVE", "REJECT"]),
+	scope: z.enum([
+		"ONCE",
+		"SESSION",
+		"USER"
+	])
+})).handler(async ({ data: { agentId,...decision } }) => {
+	const res = await agentsFetch(`${encodeURIComponent(agentId)}/tool-permission-decisions`, {
+		method: "POST",
+		body: decision
+	});
+	if (CHAT_GONE.includes(res.status)) return false;
+	if (!res.ok) throw new Error(`Saving the answer failed: ${await describeFailure(res)}`);
+	return true;
+});
+const connectionSchema = z.object({
+	integration: z.string().min(1),
+	requestId: z.string().min(1)
+});
+function connectionUrl({ integration, requestId }, step) {
+	const { applicationId } = sessionConfig();
+	const provider = encodeURIComponent(integration.toLowerCase());
+	return `${`${softrApiUrl("SOFTR_DATASOURCE_API_URL")}/v1/datasource/applications/${applicationId}`}/integrations/${provider}/oauth/${step}?${new URLSearchParams({ requestId })}`;
+}
+/** The sign-in page to open in the popup. */
+const startAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
+	const token = readSessionToken();
+	const res = await fetch(connectionUrl(data, "register"), {
+		method: "POST",
+		headers: {
+			...token ? { Authorization: `Bearer ${token}` } : {},
+			...refererHeader()
+		}
+	});
+	if (!res.ok) throw new Error(`Starting the connection failed: ${await describeFailure(res)}`);
+	return z.object({ url: z.string() }).parse(await res.json()).url;
+});
+/** Waits a while for the visitor to finish signing in. `false` when they haven't yet. */
+const awaitAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
+	const res = await fetch(connectionUrl(data, "register-result"), { signal: getRequest().signal });
+	if (res.status === 503) return false;
+	if (!res.ok) throw new Error(`Connecting failed: ${await describeFailure(res)}`);
+	return true;
+});
+/** Tells the agent the account is connected. `false` when the chat is gone, see `loadAgentChatFn`. */
+const finishAgentConnectionFn = createServerFn({ method: "POST" }).validator(z.object({
+	agentId: z.string().min(1),
+	sessionId: z.string().min(1),
+	toolCallId: z.string().min(1)
+})).handler(async ({ data: { agentId,...completion } }) => {
+	const res = await agentsFetch(`${encodeURIComponent(agentId)}/integration-auth-completions`, {
+		method: "POST",
+		body: completion
+	});
+	if (CHAT_GONE.includes(res.status)) return false;
+	if (!res.ok) throw new Error(`Finishing the connection failed: ${await describeFailure(res)}`);
+	return true;
+});
+
+//#endregion
+export { agentChatFn, awaitAgentConnectionFn, decideAgentToolFn, finishAgentConnectionFn, listAgentChatsFn, listAgents, loadAgentChatFn, startAgentConnectionFn };

package/dist/agent/use-agent-chat.d.ts

@@ -0,0 +1,106 @@
+import { AgentChatSummary } from "./agent-fns.js";
+
+//#region src/agent/use-agent-chat.d.ts
+/** A step of the agent's work: a tool it calls, and where that call stands. */
+type AgentToolCall = {
+  type: "tool";
+  id: string;
+  name: string;
+  /** The tool's input as the agent sent it, usually JSON. */
+  input?: string;
+  /**
+   * `awaiting-approval` waits for `approve` or `reject`. `awaiting-connection`
+   * waits for the visitor to `connect` their own `integration` account, and is
+   * `connecting` while they sign in.
+   */
+  status: "running" | "done" | "failed" | "awaiting-approval" | "approved" | "rejected" | "awaiting-connection" | "connecting";
+  error?: string;
+  integration?: string;
+  /** Why the agent calls it, in its own words. */
+  thought?: string;
+  /** How long a finished call took. */
+  durationMs?: number;
+};
+type AgentTodo = {
+  content: string;
+  status: "pending" | "in_progress" | "completed";
+};
+type AgentQuestion = {
+  question: string;
+  header: string;
+  options: Array<{
+    label: string;
+    description: string;
+  }>;
+  multiSelect: boolean;
+};
+/**
+ * One piece of a message, in the order the agent produced it. A tool waiting for
+ * the visitor comes last, below the text that asks for it, until they answer.
+ */
+type AgentBlock = {
+  type: "text";
+  text: string;
+} | AgentToolCall
+/** The agent's plan. It replaces itself as the agent works through it. */ | {
+  type: "todo";
+  todos: AgentTodo[];
+}
+/** The agent asks the visitor to pick. They answer by sending a message. */ | {
+  type: "question";
+  questions: AgentQuestion[];
+} | {
+  type: "error";
+  message: string;
+};
+type AgentMessage = {
+  id: string;
+  role: "user" | "assistant";
+  blocks: AgentBlock[];
+};
+type AgentChat = {
+  /** The whole chat, oldest first. While the agent replies, its reply is the last one and grows. */
+  messages: AgentMessage[];
+  /** `thinking` until the first part of the reply arrives, `replying` until it ends. */
+  status: "idle" | "thinking" | "replying";
+  /** True while a past chat loads, including the one reopened on mount. */
+  loading: boolean;
+  /** Why the last request failed. Cleared by the next one. */
+  error: Error | null;
+  /** The chat the next message goes to, `null` for a new one. */
+  chatId: string | null;
+  send: (text: string) => void;
+  /** Stops the reply. What arrived so far stays. */
+  stop: () => void;
+  newChat: () => void;
+  /** Opens a past chat from `listChats`. */
+  openChat: (chatId: string) => void;
+  /** The visitor's past chats with this agent. */
+  listChats: () => Promise<AgentChatSummary[]>;
+  /** Lets a tool waiting for approval run: once, for the rest of this chat, or for this agent from now on. */
+  approve: (toolCallId: string, scope?: "ONCE" | "SESSION" | "USER") => void;
+  reject: (toolCallId: string) => void;
+  /** Opens the sign-in for a tool's `integration` in a popup. Call it from a click, or the browser blocks the popup. */
+  connect: (toolCallId: string) => void;
+};
+type AgentChatOptions = {
+  /**
+   * The record the visitor is looking at, so they can say "this one". Sent
+   * with each message. Keys are what the agent reads, so use field names.
+   */
+  record?: {
+    id: string;
+    fields: Record<string, unknown>;
+  } | null;
+};
+/**
+ * A chat with one of the app's Softr agents, as the signed-in visitor. No UI:
+ * render `messages` with the app's own components.
+ *
+ * @example
+ * const chat = useAgentChat(AGENT_ID, { record: ticket && { id: ticket.id, fields: ticket.fields } })
+ * <form onSubmit={(e) => { e.preventDefault(); chat.send(draft) }}>
+ */
+declare function useAgentChat(agentId: string, options?: AgentChatOptions): AgentChat;
+//#endregion
+export { AgentBlock, AgentChat, AgentChatOptions, AgentMessage, AgentQuestion, AgentTodo, AgentToolCall, useAgentChat };