@particle-academy/fancy-connector-core 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,33 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.15.0] - 2026-11-08
+
+### Added
+
+- **`SetupStep` says who does each step and what it yields.** New optional
+  fields, in both runtimes:
+  - `actor`: `person` (the default when absent) or `agent`; `SETUP_ACTORS` /
+    `Setup::ACTORS` ship it as data.
+  - `prompt`: what an agent is asked to do. Required for an agent step.
+  - `copy`: `[{label, value}]` values the person pastes somewhere, such as a
+    callback URL.
+  - `fields`: the credential keys the step yields.
+  - `done`: how the person knows the step is done.
+
+  PHP's `SetupStep` gains `fromArray()` / `toArray()`. Absent stays absent:
+  a field nobody wrote is omitted, never null.
+- **`renderSetup` / `Setup::render`: a connector's steps rendered for one
+  app.** `{{appUrl}}`, `{{appName}}` and `{{connector}}` are filled in every
+  text a person or an agent reads.
+  - Any other `{{...}}` is refused as `unknown-token`, so a person never
+    pastes a literal brace into a provider console.
+  - A token with no value, or an empty one, is refused as `missing-context`,
+    so a callback never becomes `/hooks/twilio`.
+  - `appUrl` loses one trailing slash first, and a value is never expanded
+    again.
+  - Held to `fixtures/setup-render/cases.json` in both runtimes.
+
 ## [0.14.0] - 2026-11-07
 
 ### Added

package/dist/index.cjs

@@ -55,8 +55,12 @@ __export(src_exports, {
   RENDERER_VERSION: () => RENDERER_VERSION,
   REVIEW_STALE_DAYS: () => REVIEW_STALE_DAYS,
   SANDBOX_KINDS: () => SANDBOX_KINDS,
+  SETUP_ACTORS: () => SETUP_ACTORS,
+  SETUP_RENDER_REASONS: () => SETUP_RENDER_REASONS,
+  SETUP_TOKENS: () => SETUP_TOKENS,
   SIGNED_URI_RULES: () => SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API: () => SUPPORTED_CONNECTOR_API,
+  SetupRenderError: () => SetupRenderError,
   assertConnectorApi: () => assertConnectorApi,
   byteRangeOf: () => byteRangeOf,
   callConnector: () => callConnector,
@@ -110,6 +114,7 @@ __export(src_exports, {
   registerConnectionHost: () => registerConnectionHost,
   registerTransport: () => registerTransport,
   render: () => render,
+  renderSetup: () => renderSetup,
   reported: () => reported,
   resetRateState: () => resetRateState,
   resolveConnection: () => resolveConnection,
@@ -2496,6 +2501,53 @@ function withResolvedLimit(rules, limit) {
 var CREDENTIAL_SCOPES = ["provider", "account"];
 var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
+var SETUP_ACTORS = ["person", "agent"];
+
+// src/setup.ts
+var SETUP_TOKENS = ["appUrl", "appName", "connector"];
+var SETUP_RENDER_REASONS = ["unknown-token", "missing-context"];
+var SetupRenderError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "SetupRenderError";
+  }
+  reason;
+};
+var TOKEN = /\{\{([^{}]*)\}\}/g;
+function fill(text, context) {
+  return text.replace(TOKEN, (whole, name) => {
+    if (!SETUP_TOKENS.includes(name)) {
+      throw new SetupRenderError(
+        "unknown-token",
+        `setup step text uses ${whole}, which is not one of ${SETUP_TOKENS.map((t) => `{{${t}}}`).join(", ")}`
+      );
+    }
+    let value = context[name];
+    if (value === void 0 || value === null || value === "") {
+      throw new SetupRenderError("missing-context", `setup step text uses ${whole} and the host gave no value for ${name}`);
+    }
+    if (name === "appUrl" && value.endsWith("/")) value = value.slice(0, -1);
+    return value;
+  });
+}
+function renderSetup(steps, context) {
+  return steps.map((step) => {
+    const out = {
+      title: fill(step.title, context),
+      detail: fill(step.detail, context),
+      actor: step.actor ?? "person",
+      fields: [...step.fields ?? []]
+    };
+    if (step.url !== void 0) out.url = fill(step.url, context);
+    if (step.prompt !== void 0) out.prompt = fill(step.prompt, context);
+    if (step.done !== void 0) out.done = fill(step.done, context);
+    if (step.copy !== void 0) {
+      out.copy = step.copy.map((c) => ({ label: fill(c.label, context), value: fill(c.value, context) }));
+    }
+    return out;
+  });
+}
 
 // src/trigger.ts
 function isOidcJwtSpec(spec) {
@@ -2601,8 +2653,12 @@ function hasDelivery(value) {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SETUP_ACTORS,
+  SETUP_RENDER_REASONS,
+  SETUP_TOKENS,
   SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
+  SetupRenderError,
   assertConnectorApi,
   byteRangeOf,
   callConnector,
@@ -2656,6 +2712,7 @@ function hasDelivery(value) {
   registerConnectionHost,
   registerTransport,
   render,
+  renderSetup,
   reported,
   resetRateState,
   resolveConnection,