@foir/sdk 0.29.0 → 0.30.1

package/dist/data.js

@@ -1782,7 +1782,8 @@ function describe(payload) {
 var MODEL_SUBSCRIPTION_METHODS = /* @__PURE__ */ new Set(["onChange"]);
 var NAMESPACE_SUBSCRIPTION_METHODS = {
   notifications: /* @__PURE__ */ new Set(["onNotification"]),
-  operations: /* @__PURE__ */ new Set(["onJobProgress", "onExecution"])
+  operations: /* @__PURE__ */ new Set(["onJobProgress", "onExecution"]),
+  agents: /* @__PURE__ */ new Set(["onRun"])
 };
 function isModelSubscriptionMethod(name) {
   return MODEL_SUBSCRIPTION_METHODS.has(name);
@@ -1866,6 +1867,25 @@ var FoirSubscriptionRouter = class {
         { ...handlers, onData: (event) => handlers.onData(executionEventWithEnumStatus(event)) }
       );
     }
+    if (namespace === "agents" && method === "onRun") {
+      const id = input.id;
+      if (typeof id !== "string" || id === "") {
+        throw new FoirRequestError("[foir] onRun requires a run `id`");
+      }
+      const args = [{ name: "id", type: "String!" }];
+      const variables = { id };
+      for (const name of ["after", "visitorToken"]) {
+        const v = input[name];
+        if (typeof v === "string" && v !== "") {
+          args.push({ name, type: "String" });
+          variables[name] = v;
+        }
+      }
+      return this.open(
+        { field: "agentRun", operationName: "FoirAgentRun", args, variables },
+        handlers
+      );
+    }
     throw new FoirRequestError(`[foir] ns.${namespace}.${method} is not a subscription`);
   }
   /**
@@ -1949,12 +1969,24 @@ function normalise(value) {
 }
 
 // src/data/subjects.ts
+function markToken(modelKey, recordId, field) {
+  const text = `${modelKey}\0${recordId}\0${field}`;
+  let fnv = 2166136261;
+  let djb = 5381;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    fnv = Math.imul(fnv ^ code, 16777619) >>> 0;
+    djb = (Math.imul(djb, 33) ^ code) >>> 0;
+  }
+  return `f${fnv.toString(36)}${djb.toString(36)}`;
+}
 var keyOf = (modelKey, recordId) => `${modelKey}\0${recordId}`;
 function createFoirSubjectRegistry(options = {}) {
   const held = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const pinned = { subject: null };
   const latest = { key: null };
+  const marks = /* @__PURE__ */ new Map();
   const notify = () => {
     const failures = [];
     for (const listener of [...listeners]) {
@@ -2025,6 +2057,25 @@ function createFoirSubjectRegistry(options = {}) {
       return () => {
         listeners.delete(listener);
       };
+    },
+    field(subject, field, fieldOptions = {}) {
+      if (!subject.modelKey || !subject.recordId || !field) {
+        throw new FoirRequestError(
+          "[foir] a field mark needs a modelKey, a recordId and a field \u2014 a mark missing one points at nothing a note can be filed against"
+        );
+      }
+      const token = markToken(subject.modelKey, subject.recordId, field);
+      const mark = {
+        subject: { modelKey: subject.modelKey, recordId: subject.recordId },
+        field
+      };
+      if (subject.label) mark.subject.label = subject.label;
+      if (fieldOptions.label) mark.label = fieldOptions.label;
+      marks.set(token, mark);
+      return { "data-foir-field": token };
+    },
+    pointedAt(token) {
+      return marks.get(token);
     }
   };
 }
@@ -2716,6 +2767,119 @@ var FoirDecimal = class _FoirDecimal {
 function decimal(value) {
   return new FoirDecimal(value);
 }
+
+// src/data/agents.ts
+async function uploadAgentFile(foir, options) {
+  const agents = foir.ns.agents;
+  if (typeof agents?.createAgentAttachment !== "function") {
+    throw new Error("[foir] uploadAgentFile: this client sends no agent files. Its key runs none of the project's agents, or the project has released none.");
+  }
+  const { blob, mediaType, filename } = fileParts(options.file);
+  const up = await agents.createAgentAttachment({
+    agent: options.agent,
+    filename,
+    mediaType,
+    size: blob.size,
+    ...options.visitorToken ? { visitorToken: options.visitorToken } : {}
+  });
+  const put = await (options.fetch ?? fetch)(up.uploadUrl, { method: "PUT", headers: { "content-type": mediaType }, body: blob });
+  if (!put.ok) throw new Error(`[foir] uploadAgentFile: ${filename} was not uploaded (${put.status}).`);
+  return up.attachment;
+}
+function fileParts(file) {
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    const name = file.name;
+    return { blob: file, mediaType: file.type, filename: name || "file" };
+  }
+  const { data, mediaType, filename } = file;
+  const blob = data instanceof Blob ? data : new Blob([data], { type: mediaType });
+  return { blob, mediaType, filename: filename || "file" };
+}
+var FINAL = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "SKIPPED", "CANCELLED", "HELD"]);
+async function askAgent(foir, options) {
+  const agents = foir.ns.agents;
+  if (typeof agents?.startAgentRun !== "function" || typeof agents.onRun !== "function") {
+    throw new Error(
+      "[foir] askAgent: this client offers no agents. Its key runs none of the project's agents (agents:execute), or the project has released none."
+    );
+  }
+  const { onText, onEvent, signal, files, ...args } = options;
+  if (files?.length) {
+    const sent = await Promise.all(files.map((file) => uploadAgentFile(foir, { agent: args.agent, file, visitorToken: args.visitorToken })));
+    args.attachmentIds = [...args.attachmentIds ?? [], ...sent.map((a) => a.id)];
+  }
+  const run = await agents.startAgentRun(args);
+  const reply = {
+    runId: run.id,
+    threadId: run.threadId ?? null,
+    status: run.status,
+    answer: run.answer ?? "",
+    error: run.error ?? null,
+    ...run.output === void 0 || run.output === null ? {} : { output: run.output }
+  };
+  if (FINAL.has(run.status) && run.status !== "HELD") return reply;
+  let written = "";
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (sub2, err) => {
+      if (settled) return;
+      settled = true;
+      sub2?.unsubscribe();
+      if (err !== void 0) reject(err);
+      else resolve({ ...reply, answer: reply.answer || written });
+    };
+    let sub = null;
+    sub = agents.onRun({
+      id: run.id,
+      visitorToken: args.visitorToken,
+      onData: (event) => {
+        onEvent?.(event);
+        if (event.kind === "TEXT" && event.text) {
+          written += event.text;
+          onText?.(event.text);
+        }
+        if (event.kind === "STATUS" && event.status) {
+          reply.status = event.status;
+          if (event.answer) reply.answer = event.answer;
+          if (event.error) reply.error = event.error;
+          if (event.output !== void 0 && event.output !== null) reply.output = event.output;
+          if (FINAL.has(event.status)) finish(sub);
+        }
+      },
+      onError: (err) => finish(sub, err),
+      onComplete: () => finish(sub)
+    });
+    signal?.addEventListener("abort", () => finish(sub), { once: true });
+  });
+}
+var VISITOR_KEY = "foir:agents:visitor";
+function visitorToken(storage = browserStorage(), key = VISITOR_KEY) {
+  try {
+    const kept = storage?.getItem(key);
+    if (kept) return kept;
+  } catch {
+  }
+  const made = randomSecret();
+  try {
+    storage?.setItem(key, made);
+  } catch {
+  }
+  return made;
+}
+function browserStorage() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+function randomSecret() {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
 export {
   FOIR_VISITOR_IP_HEADER,
   FoirAuthDowngradedError,
@@ -2724,6 +2888,7 @@ export {
   FoirSchemaDriftError,
   FoirSessionExpiredError,
   FoirSocketTransport,
+  askAgent,
   createFoirClient,
   createFoirClientFromEnv,
   createFoirSubjectRegistry,
@@ -2737,5 +2902,7 @@ export {
   planFoirNamespaceCall,
   printSubscriptionDocument,
   recordFoirSubjects,
-  stepUpRequired
+  stepUpRequired,
+  uploadAgentFile,
+  visitorToken
 };

package/dist/placement.js

@@ -32,6 +32,12 @@ var GRANT_TABLE = [
   ["operations:write", "none", [], []],
   ["operations:complete", "none", [], []],
   ["status:write", "none", [], []],
+  ["agents:read", "none", [], []],
+  ["agents:execute", "agent", [], []],
+  ["agents:write", "none", [], []],
+  ["agenttools:execute", "agent_tool", [], []],
+  ["brief:read", "none", [], []],
+  ["brief:write", "none", [], []],
   ["appconfig:read", "none", [], []],
   ["schedules:read", "none", [], []],
   ["schedules:write", "none", [], []],
@@ -81,7 +87,7 @@ var GRANT_TABLE = [
   ["projects:read", "none", [], []],
   ["projects:write", "none", [], []],
   ["project:stand", "none", [], []],
-  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
+  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "agents:read", "agents:execute", "agents:write", "agenttools:execute", "brief:read", "brief:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
   ["projects:create", "none", [], []],
   ["projects:delete", "none", [], []],
   ["tenants:read", "none", [], []],

package/dist/react/FoirFeedback.d.ts

@@ -59,6 +59,23 @@ export interface FoirFeedbackProps {
      * with a backdrop, closed by Escape, the backdrop or its Close button.
      */
     layout?: 'inline' | 'dialog';
+    /**
+     * Show the button fixed in a corner of the viewport, rather than where the
+     * component is placed, with the inline panel opening above it. Default: where
+     * it is placed.
+     */
+    launcher?: 'bottom-right' | 'bottom-left';
+    /**
+     * Let the reader point at the part of the page they mean: a field the host
+     * marked with `subjects.field(record, key, { label })`. The note is then filed
+     * against that record and names the field, so a page showing two records (a
+     * menu and an article) files each comment against the right one.
+     *
+     * Needs `subjects`, and is offered only while the page shows a marked field.
+     * A mouse points by clicking; the keyboard by Tab and Enter; Escape cancels.
+     * Default false.
+     */
+    pointing?: boolean;
     /**
      * The built-in styles' colours, radius and type. See
      * `FoirFeedbackAppearance`: each is also a CSS custom property, so a
@@ -121,4 +138,4 @@ export interface FoirFeedbackAppearance {
     /** `--foir-feedback-font-size`. Default: inherited. */
     fontSize?: string;
 }
-export declare function FoirFeedback({ client, subjects, subject, label, triggerLabel, title, placeholder, defaultOpen, onSignIn, signIn, layout, appearance, onSubmitted, onVisitorSubmitted, onError, className, }: FoirFeedbackProps): import("react/jsx-runtime").JSX.Element;
+export declare function FoirFeedback({ client, subjects, subject, label, triggerLabel, title, placeholder, defaultOpen, onSignIn, signIn, layout, launcher, pointing, appearance, onSubmitted, onVisitorSubmitted, onError, className, }: FoirFeedbackProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/SignIn.d.ts

@@ -2,7 +2,7 @@ import type { FoirUser } from '../auth';
 export interface SignInProps {
     /** `password` (default) or `otp` (email one-time code). Ignored when `hostedUrl` is set. */
     method?: 'password' | 'otp';
-    /** Render a single button that redirects to a hosted login page instead of an embedded form. */
+    /** Render a single button that redirects to the hosted sign-in page instead of an embedded form. */
     hostedUrl?: string;
     /** Show OAuth provider buttons below the form. Default true. */
     oauth?: boolean;
@@ -15,7 +15,7 @@ export interface SignInProps {
 /**
  * A drop-in user sign-in. Renders an email/password (or OTP) form and,
  * unless disabled, OAuth provider buttons. Set `hostedUrl` to instead render a
- * button that redirects to a hosted login page. All state is handled through
+ * button that redirects to the hosted sign-in page. All state is handled through
  * {@link FoirProvider}; on success it calls `onSignIn` and optionally navigates
  * to `afterSignInUrl`.
  */

package/dist/react/feedback-notes.d.ts

@@ -113,6 +113,8 @@ export interface FoirFeedbackSubmission {
      */
     subject: FoirSubject;
     body: string;
+    /** The field of the subject the reader pointed at, when they pointed at one. */
+    anchorField?: string;
     /** The still the visitor chose to attach, or null. */
     screenshot: FoirScreenCapture | null;
     /** Injectable for the presigned PUT. Defaults to `globalThis.fetch`. */
@@ -132,6 +134,11 @@ export interface FoirVisitorSubmission {
     /** What the note is about, as for a signed-in user's. */
     subject: FoirSubject;
     body: string;
+    /**
+     * The field of the subject the visitor pointed at. The data API takes a
+     * field the visitor can read and refuses any other.
+     */
+    anchorField?: string;
     /**
      * Where the project's team may reply, as the visitor typed it. Sent only
      * when it is not blank, and never verified by anyone.