@astralbeam/sdk 0.0.1 → 0.0.2

package/dist/client-utils-DyEcBInP.js

@@ -0,0 +1 @@
+const e=`AstralBeam`,t=`/api/chat`,n=`system`,r=`astralbeam-root`,i=e=>`background:${e};color:#fff;border-radius:3px;padding:1px 5px`,a=`${i(`#7c3aed`)};font-weight:600`,o={mount:`#7c3aed`,auth:`#be185d`,theme:`#8b5cf6`,send:`#2563eb`,run:`#0891b2`,stream:`#0e7490`,text:`#16a34a`,reasoning:`#64748b`,tool:`#d97706`,widget:`#db2777`,attachment:`#0d9488`,questionnaire:`#9333ea`,status:`#475569`,error:`#dc2626`};function s(e){if(e)return(e,t,n)=>{console.log(`%cAstralBeam%c ${new Date().toISOString().slice(11,19)} %c${e}%c ${t}`,a,`color:#94a3b8;font-weight:400`,i(o[e]),``,...n===void 0?[]:[n])}}export{r as a,e as i,n,t as r,s as t};

package/dist/client.d.ts

@@ -1,4 +1,129 @@
+//#region src/lib/client-types.d.ts
+interface StandardSchemaV1 {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => unknown;
+  };
+}
+/** A plain JSON Schema object, the same shape tool definitions use for their parameters. */
+interface JsonSchemaObject {
+  type: "object";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [keyword: string]: unknown;
+}
+/** Schema of the input the agent supplies to a widget or tool, like a tool definition's parameters. */
+type ParametersSchema = StandardSchemaV1 | JsonSchemaObject;
+interface WidgetDefinition {
+  /** Tells the agent what the widget shows so it can decide when to render it. */
+  description: string;
+  /**
+   * Forwarded to the agent as JSON Schema. Only a Standard Schema also validates the
+   * props before `render` runs; with a plain JSON Schema, treat the props as untrusted.
+   */
+  parameters?: ParametersSchema;
+  /**
+   * Draws the widget with the agent-chosen props into `container`, a light-DOM child of
+   * the mount target. May return a cleanup, called before a re-render and on unmount.
+   */
+  render: (props: Record<string, unknown>, container: HTMLElement) => (() => void) | void;
+}
+interface ToolDefinition {
+  /** Tells the agent what the tool does so it can decide when to call it. */
+  description: string;
+  /**
+   * Forwarded to the agent as JSON Schema. Only a Standard Schema also validates the
+   * input before `execute` runs; with a plain JSON Schema, treat the input as untrusted.
+   */
+  parameters?: ParametersSchema;
+  /**
+   * Runs in the host page with the agent-chosen input. The resolved value is returned
+   * to the agent as the tool result; a thrown error is returned as a tool error.
+   */
+  execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+/**
+ * Limits and accepted types for the composer's file attachments. Every field is optional;
+ * omitting the whole option leaves attachments enabled with the defaults below.
+ */
+interface AstralBeamChatAttachmentOptions {
+  /** Hides the attach button (and ignores drops and pastes) when `false`. Default `true`. */
+  enabled?: boolean | undefined;
+  /** How many files one message may carry. Default `5`. */
+  maxFiles?: number | undefined;
+  /**
+   * Ceiling for a single file, in bytes. The widget also applies its own per-kind caps
+   * (5 MB image, 10 MB PDF, 1 MB text file), so the smaller of the two wins.
+   */
+  maxFileBytes?: number | undefined;
+  /** Ceiling for all files on one message, in bytes. Default 20 MB. */
+  maxTotalBytes?: number | undefined;
+  /**
+   * Narrows what the composer takes, as MIME types or `type/*` patterns (`["image/*"]` for
+   * images only). Omit to accept everything the chat endpoint supports: PNG, JPEG, WebP and
+   * GIF images, PDFs, and text files (which the endpoint reads as text for the agent).
+   */
+  accept?: readonly string[] | undefined;
+}
+/** Color scheme of the chat widget; `"system"` follows the OS `prefers-color-scheme` setting. */
+type AstralBeamChatColorScheme = "light" | "dark" | "system";
+/** Overrides for the widget's theming CSS variables, keyed by custom-property name (`"--primary"`). */
+type AstralBeamChatThemeVariables = Record<`--${string}`, string>;
+/**
+ * Custom values for the CSS variables the widget's shadcn theme exposes (`--background`,
+ * `--primary`, `--radius`, and the `--font-sans`/`--font-heading`/`--font-mono` stacks, ...),
+ * mirroring shadcn's `:root`/`.dark` split: `light` is the base applied in both color schemes,
+ * and `dark` overrides it when the resolved scheme is dark.
+ */
+interface AstralBeamChatTheme {
+  light?: AstralBeamChatThemeVariables | undefined;
+  dark?: AstralBeamChatThemeVariables | undefined;
+}
+interface MountAstralBeamChatOptions {
+  /** Name shown in the widget's header. Default `"AstralBeam"`. */
+  title?: string | undefined;
+  /** URL of the AstralBeam chat endpoint the widget streams from. Fixed at mount. Default `"/api/chat"`. */
+  chatEndpoint?: string | undefined;
+  /** Application endpoint that mints a short-lived chat JWT. Fixed at mount; omit for guest chat. */
+  authEndpoint?: string | undefined;
+  /** Host-specific instructions the endpoint appends to the agent's system prompt. */
+  systemPrompt?: string | undefined;
+  /** Host-defined tools the agent can call, executed in the host page, keyed by tool name. */
+  tools?: Record<string, ToolDefinition> | undefined;
+  /** Host-defined widgets the agent can render inline in the conversation, keyed by identifier. */
+  widgets?: Record<string, WidgetDefinition>;
+  /**
+   * File attachments in the composer, on by default. `false` turns them off; an options object
+   * narrows the limits and accepted types.
+   */
+  attachments?: boolean | AstralBeamChatAttachmentOptions | undefined;
+  /** Color scheme of the widget. Default `"system"`. */
+  colorScheme?: AstralBeamChatColorScheme;
+  /** Custom values for the widget's theming CSS variables, per color scheme. */
+  theme?: AstralBeamChatTheme | undefined;
+  /**
+   * Logs every SDK action to the browser console with UTC timestamps and full payloads,
+   * and asks the endpoint (via the forwarded props) to log its side of the run too.
+   */
+  debug?: boolean | undefined;
+}
+/**
+ * Mount options the handle can change afterwards. `chatEndpoint` is excluded on purpose: the
+ * streaming connection is constructed once, so a new endpoint would mean a new client and a
+ * discarded transcript.
+ */
+type AstralBeamChatUpdate = Partial<Omit<MountAstralBeamChatOptions, "chatEndpoint" | "authEndpoint">>;
+interface AstralBeamChatHandle {
+  unmount: () => void;
+  /**
+   * Merges option changes into the live mount options and applies them in place, keeping the
+   * transcript, the chat session, and live widget renders. Only the keys given are replaced.
+   */
+  update: (options: AstralBeamChatUpdate) => void;
+}
+//#endregion
 //#region src/client.d.ts
-declare const entrypoint = "client";
+declare function mountAstralBeamChat(target: HTMLElement, options?: MountAstralBeamChatOptions): AstralBeamChatHandle;
 //#endregion
-export { entrypoint };
+export { type AstralBeamChatAttachmentOptions, type AstralBeamChatColorScheme, type AstralBeamChatHandle, type AstralBeamChatTheme, type AstralBeamChatThemeVariables, type AstralBeamChatUpdate, type JsonSchemaObject, type MountAstralBeamChatOptions, type ParametersSchema, type StandardSchemaV1, type ToolDefinition, type WidgetDefinition, mountAstralBeamChat };

package/dist/client.js

@@ -1,4 +1 @@
-//#region src/client.ts
-const entrypoint = "client";
-//#endregion
-export { entrypoint };
+import{a as e,t}from"./client-utils-DyEcBInP.js";function n(n,r={}){let i={...r},a=t(i.debug);a?.(`mount`,`mounting chat widget`,{title:i.title??`AstralBeam`,chatEndpoint:i.chatEndpoint??`/api/chat`,authentication:i.authEndpoint?`configured`:`guest`,colorScheme:i.colorScheme??`system`,theme:i.theme,systemPrompt:i.systemPrompt,tools:Object.keys(i.tools??{}),widgets:Object.keys(i.widgets??{}),attachments:i.attachments??!0});let o=n.shadowRoot??n.attachShadow({mode:`open`}),s=document.createElement(`div`);s.className=e,s.style.height=`100%`,o.append(s);let c=matchMedia(`(prefers-color-scheme: dark)`),l=new Set,u=e=>{for(let e of l)s.style.removeProperty(e);l.clear();let t={...i.theme?.light,...e?i.theme?.dark:void 0};for(let[e,n]of Object.entries(t))e.startsWith(`--`)&&(s.style.setProperty(e,n),l.add(e))},d=()=>{let e=i.colorScheme??`system`,t=e===`dark`||e===`system`&&c.matches;s.classList.toggle(`dark`,t),u(t),a?.(`theme`,`color scheme "${e}" resolved to ${t?`dark`:`light`}`,{themeVariables:[...l]})};d(),c.addEventListener(`change`,d);let f=!1,p;return import(`./chat-DdU0uj9s.js`).then(({renderChat:e})=>{a?.(`mount`,`chat chunk loaded`),f||(p=e(o,s,i))}),{update:e=>{i={...i,...e},a=t(i.debug),a?.(`mount`,`options updated`,{changed:Object.keys(e)}),d(),p?.update(i)},unmount:()=>{a?.(`mount`,`unmounting chat widget`),f=!0,c.removeEventListener(`change`,d),p?.dispose(),p=void 0,s.remove()}}}export{n as mountAstralBeamChat};

package/dist/react.d.ts

@@ -1,4 +1,47 @@
+import { ReactNode } from "react";
+import { AstralBeamChatAttachmentOptions, AstralBeamChatColorScheme, AstralBeamChatTheme, ToolDefinition, WidgetDefinition as WidgetDefinition$1 } from "@astralbeam/sdk/client";
+
 //#region src/react.d.ts
-declare const entrypoint = "react";
+interface WidgetDefinition extends Omit<WidgetDefinition$1, "render"> {
+  /** Draws the widget with the agent-chosen props, in the host's own React tree. */
+  render: (props: Record<string, unknown>) => ReactNode;
+}
+interface AstralBeamChatProps {
+  /** Name shown in the widget's header; prop changes apply immediately. Default `"AstralBeam"`. */
+  title?: string;
+  /** URL of the AstralBeam chat endpoint the widget streams from. Default `"/api/chat"`. */
+  chatEndpoint?: string;
+  /** Application endpoint that mints a short-lived chat JWT; omit for guest chat. */
+  authEndpoint?: string;
+  /** Host-specific instructions the endpoint appends to the agent's system prompt. */
+  systemPrompt?: string;
+  /** Host-defined tools the agent can call, executed in the host's React app, keyed by name. */
+  tools?: Record<string, ToolDefinition>;
+  /** Host-defined widgets the agent can render inline in the conversation, keyed by identifier. */
+  widgets?: Record<string, WidgetDefinition>;
+  /** Color scheme of the chat widget; prop changes apply immediately. Default `"system"`. */
+  colorScheme?: AstralBeamChatColorScheme;
+  /** Custom values for the widget's theming CSS variables, per color scheme; changes apply immediately. */
+  theme?: AstralBeamChatTheme | undefined;
+  /** File attachments in the composer, on by default; `false` turns them off. */
+  attachments?: boolean | AstralBeamChatAttachmentOptions;
+  /**
+   * Logs every SDK action to the browser console with UTC timestamps and full payloads,
+   * and asks the endpoint to log its side of the run too; prop changes apply immediately.
+   */
+  debug?: boolean;
+}
+declare function AstralBeamChat({
+  title,
+  chatEndpoint,
+  authEndpoint,
+  systemPrompt,
+  tools,
+  widgets,
+  colorScheme,
+  theme,
+  attachments,
+  debug
+}: AstralBeamChatProps): import("react").JSX.Element;
 //#endregion
-export { entrypoint };
+export { AstralBeamChat, type AstralBeamChatAttachmentOptions, type AstralBeamChatColorScheme, AstralBeamChatProps, type AstralBeamChatTheme, type ToolDefinition, WidgetDefinition };

package/dist/react.js

@@ -1,4 +1,92 @@
-//#region src/react.ts
-const entrypoint = "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { mountAstralBeamChat } from "@astralbeam/sdk/client";
+import { jsx } from "react/jsx-runtime";
+//#region src/lib/client-constants.ts
+/** Color scheme used when the mount options and the React prop give none. */
+const DEFAULT_COLOR_SCHEME = "system";
 //#endregion
-export { entrypoint };
+//#region src/react.tsx
+function AstralBeamChat({ title, chatEndpoint, authEndpoint, systemPrompt, tools, widgets = {}, colorScheme = DEFAULT_COLOR_SCHEME, theme, attachments, debug }) {
+	const targetRef = useRef(null);
+	const handleRef = useRef(null);
+	const [activeRenders, setActiveRenders] = useState(/* @__PURE__ */ new Map());
+	const toolsRef = useRef(tools);
+	useEffect(() => {
+		toolsRef.current = tools;
+	});
+	const nextRenderKey = useRef(0);
+	const hostTools = useMemo(() => Object.fromEntries(Object.entries(tools ?? {}).map(([name, definition]) => [name, {
+		...definition,
+		execute: (input) => {
+			const current = toolsRef.current?.[name];
+			if (!current) throw new Error(`Tool "${name}" is no longer registered`);
+			return current.execute(input);
+		}
+	}])), [tools]);
+	const hostWidgets = useMemo(() => Object.fromEntries(Object.entries(widgets).map(([name, definition]) => [name, {
+		...definition,
+		render: (props, container) => {
+			const key = `astralbeam-render-${nextRenderKey.current++}`;
+			setActiveRenders((previous) => new Map(previous).set(key, {
+				widget: name,
+				container,
+				props
+			}));
+			return () => {
+				setActiveRenders((previous) => {
+					const next = new Map(previous);
+					next.delete(key);
+					return next;
+				});
+			};
+		}
+	}])), [widgets]);
+	const live = useMemo(() => ({
+		title,
+		systemPrompt,
+		colorScheme,
+		theme,
+		attachments,
+		debug,
+		tools: hostTools,
+		widgets: hostWidgets
+	}), [
+		title,
+		systemPrompt,
+		colorScheme,
+		theme,
+		attachments,
+		debug,
+		hostTools,
+		hostWidgets
+	]);
+	const liveRef = useRef(live);
+	liveRef.current = live;
+	useEffect(() => {
+		if (!targetRef.current) return;
+		const handle = mountAstralBeamChat(targetRef.current, {
+			...liveRef.current,
+			chatEndpoint,
+			authEndpoint
+		});
+		handleRef.current = handle;
+		return () => {
+			handleRef.current = null;
+			handle.unmount();
+		};
+	}, []);
+	useEffect(() => {
+		handleRef.current?.update(live);
+	}, [live]);
+	return /* @__PURE__ */ jsx("div", {
+		style: { height: "100%" },
+		ref: targetRef,
+		children: [...activeRenders].map(([key, { widget, container, props }]) => {
+			const definition = widgets[widget];
+			return definition ? createPortal(definition.render(props), container, key) : null;
+		})
+	});
+}
+//#endregion
+export { AstralBeamChat };

package/dist/server.d.ts

@@ -1,4 +1,33 @@
 //#region src/server.d.ts
-declare const entrypoint = "server";
+declare const ASTRALBEAM_CHAT_TOKEN_AUDIENCE = "astralbeam-chat";
+declare const ASTRALBEAM_CHAT_TOKEN_ISSUER = "astralbeam-global";
+declare const ASTRALBEAM_CHAT_TOKEN_TYPE = "astralbeam-chat+jwt";
+declare const ASTRALBEAM_CHAT_TOKEN_KEY_ID = "global-v1";
+declare const ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS = 300;
+declare const ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS = 600;
+interface AstralBeamChatUser {
+  id: string;
+  name?: string | undefined;
+  email?: string | undefined;
+  avatarUrl?: string | undefined;
+}
+interface AstralBeamChatTenant {
+  id: string;
+  name?: string | undefined;
+  logoUrl?: string | undefined;
+}
+interface CreateAstralBeamChatTokenOptions {
+  secret: string | Uint8Array;
+  user: AstralBeamChatUser;
+  tenant: AstralBeamChatTenant;
+  expiresInSeconds?: number | undefined;
+}
+/** Creates the short-lived bearer token returned by an application's auth endpoint. */
+declare function createAstralBeamChatToken({
+  secret,
+  user,
+  tenant,
+  expiresInSeconds
+}: CreateAstralBeamChatTokenOptions): Promise<string>;
 //#endregion
-export { entrypoint };
+export { ASTRALBEAM_CHAT_TOKEN_AUDIENCE, ASTRALBEAM_CHAT_TOKEN_ISSUER, ASTRALBEAM_CHAT_TOKEN_KEY_ID, ASTRALBEAM_CHAT_TOKEN_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_MAX_LIFETIME_SECONDS, ASTRALBEAM_CHAT_TOKEN_TYPE, AstralBeamChatTenant, AstralBeamChatUser, CreateAstralBeamChatTokenOptions, createAstralBeamChatToken };