@particle-academy/fancy-flow 0.47.1 → 0.48.0

package/dist/connectors.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+// src/connectors.ts
+var SELECTABLE_SANDBOX = ["credential", "base-url", "separate-account"];
+function connectionFields(meta) {
+  const modes = [
+    { value: "auto", label: "Auto \u2014 sandbox locally, live in production" },
+    { value: "fake", label: "Fake \u2014 no credentials, no network" }
+  ];
+  if (SELECTABLE_SANDBOX.includes(meta.sandbox)) {
+    modes.push({ value: "sandbox", label: sandboxLabel(meta.sandbox) });
+  }
+  modes.push({ value: "live", label: "Live \u2014 the real account" });
+  return [
+    {
+      type: "credential",
+      key: "connection",
+      label: `${meta.serviceTitle} connection`,
+      credentialType: `connector:${meta.service}`,
+      description: `Which configured ${meta.serviceTitle} connection to use. Credentials live in the host's configuration, never in the workflow \u2014 a graph is exported, committed and handed to agents.`
+    },
+    {
+      type: "select",
+      key: "mode",
+      label: "Environment",
+      options: modes,
+      default: "auto",
+      description: sandboxNote(meta)
+    }
+  ];
+}
+function sandboxLabel(kind) {
+  return kind === "base-url" ? "Sandbox \u2014 the provider's separate test host" : kind === "separate-account" ? "Sandbox \u2014 your separate test account" : "Sandbox \u2014 the provider's test estate";
+}
+function sandboxNote(meta) {
+  if (meta.sandbox === "restricted-reach") {
+    return `${meta.serviceTitle} has no separate test estate \u2014 an unreviewed app posts only to its own developers, or privately. Same credentials, same endpoints: only the audience changes, and nothing here selects it. A restricted run looks exactly like a successful one, so confirm reach on the provider's own surface.`;
+  }
+  if (meta.sandbox === "unverified") {
+    return `Nobody has verified what test estate ${meta.serviceTitle} offers, so "sandbox" is not offered \u2014 and "auto" means fake locally and live in production. Find out before pointing a workflow at it.`;
+  }
+  if (meta.sandbox === "none") {
+    return `${meta.serviceTitle} has no sandbox estate, so "auto" means fake locally and live in production.`;
+  }
+  return "Auto follows the environment. Setting this explicitly overrides it everywhere, including in production.";
+}
+function defineConnectorKind(meta, kind) {
+  return {
+    ...kind,
+    // `category` stays fancy-flow's own taxonomy — it describes what the node
+    // does to the GRAPH, which is what the palette groups by. Connector-ness is
+    // a separate axis and is carried separately; overloading one field with two
+    // meanings would make "show me the triggers" and "hide the connectors"
+    // impossible to ask at the same time.
+    category: kind.category ?? (meta.role === "trigger" ? "trigger" : "io"),
+    accent: kind.accent ?? DOMAIN_ACCENT[meta.domain],
+    configSchema: [...connectionFields(meta), ...kind.configSchema ?? []],
+    connector: meta
+  };
+}
+function summarize(meta, config, detail) {
+  const mode = typeof config.mode === "string" ? config.mode : "auto";
+  const where = mode === "fake" ? " (faked \u2014 nothing leaves this machine)" : mode === "sandbox" ? " in the sandbox" : mode === "live" ? " on the live account" : "";
+  const what = detail?.trim() ? detail.trim() : meta.operation.replace(/_/g, " ");
+  return meta.role === "trigger" ? `When ${meta.serviceTitle} reports ${what}${where}` : `Then ${meta.serviceTitle} will ${what}${where}`;
+}
+function ingredients(fields) {
+  return fields;
+}
+var DOMAIN_ACCENT = {
+  payments: "#635bff",
+  commerce: "#96bf48",
+  messaging: "#4a154b",
+  email: "#0f9d58",
+  crm: "#00a1e0",
+  support: "#03363d",
+  storage: "#ff9900",
+  calendar: "#4285f4",
+  productivity: "#2f3437",
+  database: "#336791",
+  devtools: "#24292f",
+  analytics: "#f9a03c",
+  marketing: "#1877f2",
+  ai: "#d97757",
+  forms: "#262627",
+  hr: "#5c4ee5",
+  geo: "#34a853"
+};
+
+exports.connectionFields = connectionFields;
+exports.defineConnectorKind = defineConnectorKind;
+exports.ingredients = ingredients;
+exports.summarize = summarize;
+//# sourceMappingURL=connectors.cjs.map
+//# sourceMappingURL=connectors.cjs.map

package/dist/connectors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors.ts"],"names":[],"mappings":"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","file":"connectors.cjs","sourcesContent":["/**\n * The authoring surface every connector node shares.\n *\n * ## Why this is in fancy-flow and not in fancy-connector-core\n *\n * `fancy-connector-core` owns the WIRE — delivery, classification, retries,\n * estate selection — and deliberately knows nothing about flow. This module\n * builds a node's `ConfigField[]` and its `NodeKindDefinition`, which are\n * fancy-flow concepts, so putting it there would couple the runtime to the\n * editor and force a non-flow consumer to install one to make an HTTP call.\n *\n * It lived as vendored source in the node marketplace until 0.48.0, which was\n * fine for a node (a copy costs a consumer no dependency) and impossible for a\n * PACKAGE — a package cannot import vendored sandbox source, so every generated\n * `<provider>-ui` package carried its own copy of a file only this repo can\n * correctly change. At the scale the connector estate is heading for that is\n * the exact \"a copy cannot be upgraded\" problem the packages exist to solve.\n *\n * ## The model, and where it came from\n *\n * IFTTT's authoring UX is the one non-engineers actually complete, and three of\n * its four ideas map onto fancy-flow without distortion:\n *\n * 1. **Service first, then capability.** You pick Stripe, *then* pick what about\n *    Stripe. Not a flat wall of four hundred nodes. Here that lives in the\n *    registry — `connector.service` groups a provider's nodes, and the listing\n *    tools narrow in two steps.\n * 2. **The connection is a thing, not a field.** You authorize a service once\n *    and every applet reuses it. Here: `connection.ts` in the runtime, and the\n *    single `connection` config field below.\n * 3. **Ingredients.** A trigger's output fields become named tokens you drop\n *    into a downstream action's fields. fancy-flow already has the machinery —\n *    `outputShape` on the kind, `availableVariables()` reading it off direct\n *    predecessors — so a connector's job is simply to DECLARE its shape. See\n *    `ingredients.ts`.\n * 4. **A sentence, not a form dump.** `summarize()` below.\n *\n * ## Where it does NOT map, and what we did instead\n *\n * An IFTTT applet is one trigger and one action, so \"the ingredients\" is\n * unambiguous: there is only one upstream. A fancy-flow graph branches, fans\n * out, merges and nests, so a connector node several hops downstream has no\n * single trigger to draw from — `availableVariables()` deliberately offers only\n * DIRECT predecessors, because a grandparent's field resolves to `null` at run\n * time and a suggestion that silently produces nothing is worse than no\n * suggestion.\n *\n * We did not paper over that. Connector triggers publish their event as a\n * single object with a declared shape, so the natural thing an author does —\n * carry it forward on the wire — keeps the ingredients available at each step.\n * Reaching further up the graph is a fancy-flow concern, recorded as a finding\n * rather than reimplemented per node.\n */\n\nimport type { ConfigField, NodeKindDefinition } from \"./registry/types\";\nimport type { OutputField } from \"./expressions/variables\";\n\n// Re-exported so a connector package needs ONE import rather than two entries.\nexport type { OutputField };\n\n/** The domains the catalogue is grouped by. Mirrors the plan's taxonomy. */\nexport type ConnectorDomain =\n  | \"payments\"\n  | \"commerce\"\n  | \"messaging\"\n  | \"email\"\n  | \"crm\"\n  | \"support\"\n  | \"storage\"\n  | \"calendar\"\n  | \"productivity\"\n  | \"database\"\n  | \"devtools\"\n  | \"analytics\"\n  | \"marketing\"\n  | \"ai\"\n  | \"forms\"\n  | \"hr\"\n  | \"geo\";\n\n/** What a connector node does in the graph — IFTTT's \"this\" versus \"that\". */\nexport type ConnectorRole = \"trigger\" | \"action\" | \"search\";\n\n/**\n * How the provider exposes a test estate. Kept in step with the runtime's\n * `SandboxKind`, and `vendoring.test.ts` compares the two declarations — a\n * hand-maintained mirror with nothing checking it is the shape this repository\n * keeps finding.\n *\n * Two of these are answers people skip. `unverified` means NOBODY HAS CHECKED —\n * a real state, and the right one until somebody has. `restricted-reach` is the\n * dangerous one: same credentials, same endpoints, same estate, and only the\n * AUDIENCE restricted, so it looks exactly like a successful post nobody can\n * see. Neither is `none`, and neither can be selected as a mode.\n */\nexport type SandboxKind =\n  | \"credential\"\n  | \"base-url\"\n  | \"separate-account\"\n  | \"restricted-reach\"\n  | \"none\"\n  | \"unverified\";\n\n/** The kinds a `sandbox` mode can actually point at. Mirrors `sandboxIsSelectable`. */\nconst SELECTABLE_SANDBOX: readonly SandboxKind[] = [\"credential\", \"base-url\", \"separate-account\"];\n\nexport type ConnectorMeta = {\n  service: string;\n  serviceTitle: string;\n  domain: ConnectorDomain;\n  role: ConnectorRole;\n  /** The provider's name for this operation, so search finds what people type. */\n  operation: string;\n  sandbox: SandboxKind;\n  /** Link to the provider documentation this node was written against. */\n  docs?: string;\n};\n\n/**\n * The two fields EVERY connector node carries, in the same order, with the same\n * keys.\n *\n * Uniformity is the feature. An agent that has configured one connector has\n * configured all of them, and a human who has learned where the sandbox switch\n * lives never has to look for it again.\n */\nexport function connectionFields(meta: ConnectorMeta): ConfigField[] {\n  const modes: Array<{ value: string; label: string }> = [\n    { value: \"auto\", label: \"Auto — sandbox locally, live in production\" },\n    { value: \"fake\", label: \"Fake — no credentials, no network\" },\n  ];\n\n  // Only offer sandbox where one exists. A select listing a mode the provider\n  // does not have is an invitation to pick it and then read an error.\n  if (SELECTABLE_SANDBOX.includes(meta.sandbox)) {\n    modes.push({ value: \"sandbox\", label: sandboxLabel(meta.sandbox) });\n  }\n  modes.push({ value: \"live\", label: \"Live — the real account\" });\n\n  return [\n    {\n      type: \"credential\",\n      key: \"connection\",\n      label: `${meta.serviceTitle} connection`,\n      credentialType: `connector:${meta.service}`,\n      description:\n        `Which configured ${meta.serviceTitle} connection to use. Credentials live in the host's ` +\n        \"configuration, never in the workflow — a graph is exported, committed and handed to agents.\",\n    },\n    {\n      type: \"select\",\n      key: \"mode\",\n      label: \"Environment\",\n      options: modes,\n      default: \"auto\",\n      description: sandboxNote(meta),\n    },\n  ];\n}\n\nfunction sandboxLabel(kind: SandboxKind): string {\n  return kind === \"base-url\"\n    ? \"Sandbox — the provider's separate test host\"\n    : kind === \"separate-account\"\n      ? \"Sandbox — your separate test account\"\n      : \"Sandbox — the provider's test estate\";\n}\n\n/**\n * What \"auto\" means for this provider, said where the author is choosing.\n *\n * The two non-selectable kinds get their own sentence rather than sharing\n * `none`'s. `restricted-reach` in particular has to be said HERE — on the field\n * somebody is filling in — because the failure it produces is a run that looks\n * completely successful and reached nobody, and by the time that is visible the\n * author has stopped looking at this screen.\n */\nfunction sandboxNote(meta: ConnectorMeta): string {\n  if (meta.sandbox === \"restricted-reach\") {\n    return (\n      `${meta.serviceTitle} has no separate test estate — an unreviewed app posts only to its own developers, ` +\n      \"or privately. Same credentials, same endpoints: only the audience changes, and nothing here selects it. \" +\n      \"A restricted run looks exactly like a successful one, so confirm reach on the provider's own surface.\"\n    );\n  }\n\n  if (meta.sandbox === \"unverified\") {\n    return (\n      `Nobody has verified what test estate ${meta.serviceTitle} offers, so \"sandbox\" is not offered — and ` +\n      '\"auto\" means fake locally and live in production. Find out before pointing a workflow at it.'\n    );\n  }\n\n  if (meta.sandbox === \"none\") {\n    return `${meta.serviceTitle} has no sandbox estate, so \"auto\" means fake locally and live in production.`;\n  }\n\n  return \"Auto follows the environment. Setting this explicitly overrides it everywhere, including in production.\";\n}\n\n/**\n * Build a connector node's authoring surface.\n *\n * Prepends the shared connection fields, applies the domain accent, and stamps\n * the metadata the registry reads. A connector that hand-rolled these would\n * drift from its siblings in exactly the small ways that make a catalogue feel\n * like a pile.\n */\nexport function defineConnectorKind(\n  meta: ConnectorMeta,\n  kind: Omit<NodeKindDefinition, \"category\"> & { category?: NodeKindDefinition[\"category\"] },\n): NodeKindDefinition & { connector: ConnectorMeta } {\n  return {\n    ...kind,\n    // `category` stays fancy-flow's own taxonomy — it describes what the node\n    // does to the GRAPH, which is what the palette groups by. Connector-ness is\n    // a separate axis and is carried separately; overloading one field with two\n    // meanings would make \"show me the triggers\" and \"hide the connectors\"\n    // impossible to ask at the same time.\n    category: kind.category ?? (meta.role === \"trigger\" ? \"trigger\" : \"io\"),\n    accent: kind.accent ?? DOMAIN_ACCENT[meta.domain],\n    configSchema: [...connectionFields(meta), ...(kind.configSchema ?? [])],\n    connector: meta,\n  };\n}\n\n/**\n * One line describing what a configured node will do, in IFTTT's register.\n *\n * A configured connector should read as a sentence, not as a form dump — it is\n * what makes a canvas skimmable, and it is also what an agent quotes back to a\n * human when asking whether to proceed.\n */\nexport function summarize(meta: ConnectorMeta, config: Record<string, unknown>, detail?: string): string {\n  const mode = typeof config.mode === \"string\" ? config.mode : \"auto\";\n  const where =\n    mode === \"fake\"\n      ? \" (faked — nothing leaves this machine)\"\n      : mode === \"sandbox\"\n        ? \" in the sandbox\"\n        : mode === \"live\"\n          ? \" on the live account\"\n          : \"\";\n\n  const what = detail?.trim() ? detail.trim() : meta.operation.replace(/_/g, \" \");\n\n  return meta.role === \"trigger\"\n    ? `When ${meta.serviceTitle} reports ${what}${where}`\n    : `Then ${meta.serviceTitle} will ${what}${where}`;\n}\n\n/** Declare a trigger's event fields — the \"ingredients\" downstream nodes pick from. */\nexport function ingredients(fields: OutputField[]): OutputField[] {\n  return fields;\n}\n\nconst DOMAIN_ACCENT: Record<ConnectorDomain, string> = {\n  payments: \"#635bff\",\n  commerce: \"#96bf48\",\n  messaging: \"#4a154b\",\n  email: \"#0f9d58\",\n  crm: \"#00a1e0\",\n  support: \"#03363d\",\n  storage: \"#ff9900\",\n  calendar: \"#4285f4\",\n  productivity: \"#2f3437\",\n  database: \"#336791\",\n  devtools: \"#24292f\",\n  analytics: \"#f9a03c\",\n  marketing: \"#1877f2\",\n  ai: \"#d97757\",\n  forms: \"#262627\",\n  hr: \"#5c4ee5\",\n  geo: \"#34a853\",\n};\n"]}

package/dist/connectors.d.cts

@@ -0,0 +1,122 @@
+import { C as ConfigField, N as NodeKindDefinition, O as OutputField } from './types-BO8TgI2M.cjs';
+import 'react';
+import './types-Jx1TwehV.cjs';
+import '@xyflow/react';
+import './pause-9iT4tCEV.cjs';
+
+/**
+ * The authoring surface every connector node shares.
+ *
+ * ## Why this is in fancy-flow and not in fancy-connector-core
+ *
+ * `fancy-connector-core` owns the WIRE — delivery, classification, retries,
+ * estate selection — and deliberately knows nothing about flow. This module
+ * builds a node's `ConfigField[]` and its `NodeKindDefinition`, which are
+ * fancy-flow concepts, so putting it there would couple the runtime to the
+ * editor and force a non-flow consumer to install one to make an HTTP call.
+ *
+ * It lived as vendored source in the node marketplace until 0.48.0, which was
+ * fine for a node (a copy costs a consumer no dependency) and impossible for a
+ * PACKAGE — a package cannot import vendored sandbox source, so every generated
+ * `<provider>-ui` package carried its own copy of a file only this repo can
+ * correctly change. At the scale the connector estate is heading for that is
+ * the exact "a copy cannot be upgraded" problem the packages exist to solve.
+ *
+ * ## The model, and where it came from
+ *
+ * IFTTT's authoring UX is the one non-engineers actually complete, and three of
+ * its four ideas map onto fancy-flow without distortion:
+ *
+ * 1. **Service first, then capability.** You pick Stripe, *then* pick what about
+ *    Stripe. Not a flat wall of four hundred nodes. Here that lives in the
+ *    registry — `connector.service` groups a provider's nodes, and the listing
+ *    tools narrow in two steps.
+ * 2. **The connection is a thing, not a field.** You authorize a service once
+ *    and every applet reuses it. Here: `connection.ts` in the runtime, and the
+ *    single `connection` config field below.
+ * 3. **Ingredients.** A trigger's output fields become named tokens you drop
+ *    into a downstream action's fields. fancy-flow already has the machinery —
+ *    `outputShape` on the kind, `availableVariables()` reading it off direct
+ *    predecessors — so a connector's job is simply to DECLARE its shape. See
+ *    `ingredients.ts`.
+ * 4. **A sentence, not a form dump.** `summarize()` below.
+ *
+ * ## Where it does NOT map, and what we did instead
+ *
+ * An IFTTT applet is one trigger and one action, so "the ingredients" is
+ * unambiguous: there is only one upstream. A fancy-flow graph branches, fans
+ * out, merges and nests, so a connector node several hops downstream has no
+ * single trigger to draw from — `availableVariables()` deliberately offers only
+ * DIRECT predecessors, because a grandparent's field resolves to `null` at run
+ * time and a suggestion that silently produces nothing is worse than no
+ * suggestion.
+ *
+ * We did not paper over that. Connector triggers publish their event as a
+ * single object with a declared shape, so the natural thing an author does —
+ * carry it forward on the wire — keeps the ingredients available at each step.
+ * Reaching further up the graph is a fancy-flow concern, recorded as a finding
+ * rather than reimplemented per node.
+ */
+
+/** The domains the catalogue is grouped by. Mirrors the plan's taxonomy. */
+type ConnectorDomain = "payments" | "commerce" | "messaging" | "email" | "crm" | "support" | "storage" | "calendar" | "productivity" | "database" | "devtools" | "analytics" | "marketing" | "ai" | "forms" | "hr" | "geo";
+/** What a connector node does in the graph — IFTTT's "this" versus "that". */
+type ConnectorRole = "trigger" | "action" | "search";
+/**
+ * How the provider exposes a test estate. Kept in step with the runtime's
+ * `SandboxKind`, and `vendoring.test.ts` compares the two declarations — a
+ * hand-maintained mirror with nothing checking it is the shape this repository
+ * keeps finding.
+ *
+ * Two of these are answers people skip. `unverified` means NOBODY HAS CHECKED —
+ * a real state, and the right one until somebody has. `restricted-reach` is the
+ * dangerous one: same credentials, same endpoints, same estate, and only the
+ * AUDIENCE restricted, so it looks exactly like a successful post nobody can
+ * see. Neither is `none`, and neither can be selected as a mode.
+ */
+type SandboxKind = "credential" | "base-url" | "separate-account" | "restricted-reach" | "none" | "unverified";
+type ConnectorMeta = {
+    service: string;
+    serviceTitle: string;
+    domain: ConnectorDomain;
+    role: ConnectorRole;
+    /** The provider's name for this operation, so search finds what people type. */
+    operation: string;
+    sandbox: SandboxKind;
+    /** Link to the provider documentation this node was written against. */
+    docs?: string;
+};
+/**
+ * The two fields EVERY connector node carries, in the same order, with the same
+ * keys.
+ *
+ * Uniformity is the feature. An agent that has configured one connector has
+ * configured all of them, and a human who has learned where the sandbox switch
+ * lives never has to look for it again.
+ */
+declare function connectionFields(meta: ConnectorMeta): ConfigField[];
+/**
+ * Build a connector node's authoring surface.
+ *
+ * Prepends the shared connection fields, applies the domain accent, and stamps
+ * the metadata the registry reads. A connector that hand-rolled these would
+ * drift from its siblings in exactly the small ways that make a catalogue feel
+ * like a pile.
+ */
+declare function defineConnectorKind(meta: ConnectorMeta, kind: Omit<NodeKindDefinition, "category"> & {
+    category?: NodeKindDefinition["category"];
+}): NodeKindDefinition & {
+    connector: ConnectorMeta;
+};
+/**
+ * One line describing what a configured node will do, in IFTTT's register.
+ *
+ * A configured connector should read as a sentence, not as a form dump — it is
+ * what makes a canvas skimmable, and it is also what an agent quotes back to a
+ * human when asking whether to proceed.
+ */
+declare function summarize(meta: ConnectorMeta, config: Record<string, unknown>, detail?: string): string;
+/** Declare a trigger's event fields — the "ingredients" downstream nodes pick from. */
+declare function ingredients(fields: OutputField[]): OutputField[];
+
+export { type ConnectorDomain, type ConnectorMeta, type ConnectorRole, OutputField, type SandboxKind, connectionFields, defineConnectorKind, ingredients, summarize };

package/dist/connectors.d.ts

@@ -0,0 +1,122 @@
+import { C as ConfigField, N as NodeKindDefinition, O as OutputField } from './types-DJAmfiJC.js';
+import 'react';
+import './types-Jx1TwehV.js';
+import '@xyflow/react';
+import './pause-9iT4tCEV.js';
+
+/**
+ * The authoring surface every connector node shares.
+ *
+ * ## Why this is in fancy-flow and not in fancy-connector-core
+ *
+ * `fancy-connector-core` owns the WIRE — delivery, classification, retries,
+ * estate selection — and deliberately knows nothing about flow. This module
+ * builds a node's `ConfigField[]` and its `NodeKindDefinition`, which are
+ * fancy-flow concepts, so putting it there would couple the runtime to the
+ * editor and force a non-flow consumer to install one to make an HTTP call.
+ *
+ * It lived as vendored source in the node marketplace until 0.48.0, which was
+ * fine for a node (a copy costs a consumer no dependency) and impossible for a
+ * PACKAGE — a package cannot import vendored sandbox source, so every generated
+ * `<provider>-ui` package carried its own copy of a file only this repo can
+ * correctly change. At the scale the connector estate is heading for that is
+ * the exact "a copy cannot be upgraded" problem the packages exist to solve.
+ *
+ * ## The model, and where it came from
+ *
+ * IFTTT's authoring UX is the one non-engineers actually complete, and three of
+ * its four ideas map onto fancy-flow without distortion:
+ *
+ * 1. **Service first, then capability.** You pick Stripe, *then* pick what about
+ *    Stripe. Not a flat wall of four hundred nodes. Here that lives in the
+ *    registry — `connector.service` groups a provider's nodes, and the listing
+ *    tools narrow in two steps.
+ * 2. **The connection is a thing, not a field.** You authorize a service once
+ *    and every applet reuses it. Here: `connection.ts` in the runtime, and the
+ *    single `connection` config field below.
+ * 3. **Ingredients.** A trigger's output fields become named tokens you drop
+ *    into a downstream action's fields. fancy-flow already has the machinery —
+ *    `outputShape` on the kind, `availableVariables()` reading it off direct
+ *    predecessors — so a connector's job is simply to DECLARE its shape. See
+ *    `ingredients.ts`.
+ * 4. **A sentence, not a form dump.** `summarize()` below.
+ *
+ * ## Where it does NOT map, and what we did instead
+ *
+ * An IFTTT applet is one trigger and one action, so "the ingredients" is
+ * unambiguous: there is only one upstream. A fancy-flow graph branches, fans
+ * out, merges and nests, so a connector node several hops downstream has no
+ * single trigger to draw from — `availableVariables()` deliberately offers only
+ * DIRECT predecessors, because a grandparent's field resolves to `null` at run
+ * time and a suggestion that silently produces nothing is worse than no
+ * suggestion.
+ *
+ * We did not paper over that. Connector triggers publish their event as a
+ * single object with a declared shape, so the natural thing an author does —
+ * carry it forward on the wire — keeps the ingredients available at each step.
+ * Reaching further up the graph is a fancy-flow concern, recorded as a finding
+ * rather than reimplemented per node.
+ */
+
+/** The domains the catalogue is grouped by. Mirrors the plan's taxonomy. */
+type ConnectorDomain = "payments" | "commerce" | "messaging" | "email" | "crm" | "support" | "storage" | "calendar" | "productivity" | "database" | "devtools" | "analytics" | "marketing" | "ai" | "forms" | "hr" | "geo";
+/** What a connector node does in the graph — IFTTT's "this" versus "that". */
+type ConnectorRole = "trigger" | "action" | "search";
+/**
+ * How the provider exposes a test estate. Kept in step with the runtime's
+ * `SandboxKind`, and `vendoring.test.ts` compares the two declarations — a
+ * hand-maintained mirror with nothing checking it is the shape this repository
+ * keeps finding.
+ *
+ * Two of these are answers people skip. `unverified` means NOBODY HAS CHECKED —
+ * a real state, and the right one until somebody has. `restricted-reach` is the
+ * dangerous one: same credentials, same endpoints, same estate, and only the
+ * AUDIENCE restricted, so it looks exactly like a successful post nobody can
+ * see. Neither is `none`, and neither can be selected as a mode.
+ */
+type SandboxKind = "credential" | "base-url" | "separate-account" | "restricted-reach" | "none" | "unverified";
+type ConnectorMeta = {
+    service: string;
+    serviceTitle: string;
+    domain: ConnectorDomain;
+    role: ConnectorRole;
+    /** The provider's name for this operation, so search finds what people type. */
+    operation: string;
+    sandbox: SandboxKind;
+    /** Link to the provider documentation this node was written against. */
+    docs?: string;
+};
+/**
+ * The two fields EVERY connector node carries, in the same order, with the same
+ * keys.
+ *
+ * Uniformity is the feature. An agent that has configured one connector has
+ * configured all of them, and a human who has learned where the sandbox switch
+ * lives never has to look for it again.
+ */
+declare function connectionFields(meta: ConnectorMeta): ConfigField[];
+/**
+ * Build a connector node's authoring surface.
+ *
+ * Prepends the shared connection fields, applies the domain accent, and stamps
+ * the metadata the registry reads. A connector that hand-rolled these would
+ * drift from its siblings in exactly the small ways that make a catalogue feel
+ * like a pile.
+ */
+declare function defineConnectorKind(meta: ConnectorMeta, kind: Omit<NodeKindDefinition, "category"> & {
+    category?: NodeKindDefinition["category"];
+}): NodeKindDefinition & {
+    connector: ConnectorMeta;
+};
+/**
+ * One line describing what a configured node will do, in IFTTT's register.
+ *
+ * A configured connector should read as a sentence, not as a form dump — it is
+ * what makes a canvas skimmable, and it is also what an agent quotes back to a
+ * human when asking whether to proceed.
+ */
+declare function summarize(meta: ConnectorMeta, config: Record<string, unknown>, detail?: string): string;
+/** Declare a trigger's event fields — the "ingredients" downstream nodes pick from. */
+declare function ingredients(fields: OutputField[]): OutputField[];
+
+export { type ConnectorDomain, type ConnectorMeta, type ConnectorRole, OutputField, type SandboxKind, connectionFields, defineConnectorKind, ingredients, summarize };

package/dist/connectors.js

@@ -0,0 +1,90 @@
+// src/connectors.ts
+var SELECTABLE_SANDBOX = ["credential", "base-url", "separate-account"];
+function connectionFields(meta) {
+  const modes = [
+    { value: "auto", label: "Auto \u2014 sandbox locally, live in production" },
+    { value: "fake", label: "Fake \u2014 no credentials, no network" }
+  ];
+  if (SELECTABLE_SANDBOX.includes(meta.sandbox)) {
+    modes.push({ value: "sandbox", label: sandboxLabel(meta.sandbox) });
+  }
+  modes.push({ value: "live", label: "Live \u2014 the real account" });
+  return [
+    {
+      type: "credential",
+      key: "connection",
+      label: `${meta.serviceTitle} connection`,
+      credentialType: `connector:${meta.service}`,
+      description: `Which configured ${meta.serviceTitle} connection to use. Credentials live in the host's configuration, never in the workflow \u2014 a graph is exported, committed and handed to agents.`
+    },
+    {
+      type: "select",
+      key: "mode",
+      label: "Environment",
+      options: modes,
+      default: "auto",
+      description: sandboxNote(meta)
+    }
+  ];
+}
+function sandboxLabel(kind) {
+  return kind === "base-url" ? "Sandbox \u2014 the provider's separate test host" : kind === "separate-account" ? "Sandbox \u2014 your separate test account" : "Sandbox \u2014 the provider's test estate";
+}
+function sandboxNote(meta) {
+  if (meta.sandbox === "restricted-reach") {
+    return `${meta.serviceTitle} has no separate test estate \u2014 an unreviewed app posts only to its own developers, or privately. Same credentials, same endpoints: only the audience changes, and nothing here selects it. A restricted run looks exactly like a successful one, so confirm reach on the provider's own surface.`;
+  }
+  if (meta.sandbox === "unverified") {
+    return `Nobody has verified what test estate ${meta.serviceTitle} offers, so "sandbox" is not offered \u2014 and "auto" means fake locally and live in production. Find out before pointing a workflow at it.`;
+  }
+  if (meta.sandbox === "none") {
+    return `${meta.serviceTitle} has no sandbox estate, so "auto" means fake locally and live in production.`;
+  }
+  return "Auto follows the environment. Setting this explicitly overrides it everywhere, including in production.";
+}
+function defineConnectorKind(meta, kind) {
+  return {
+    ...kind,
+    // `category` stays fancy-flow's own taxonomy — it describes what the node
+    // does to the GRAPH, which is what the palette groups by. Connector-ness is
+    // a separate axis and is carried separately; overloading one field with two
+    // meanings would make "show me the triggers" and "hide the connectors"
+    // impossible to ask at the same time.
+    category: kind.category ?? (meta.role === "trigger" ? "trigger" : "io"),
+    accent: kind.accent ?? DOMAIN_ACCENT[meta.domain],
+    configSchema: [...connectionFields(meta), ...kind.configSchema ?? []],
+    connector: meta
+  };
+}
+function summarize(meta, config, detail) {
+  const mode = typeof config.mode === "string" ? config.mode : "auto";
+  const where = mode === "fake" ? " (faked \u2014 nothing leaves this machine)" : mode === "sandbox" ? " in the sandbox" : mode === "live" ? " on the live account" : "";
+  const what = detail?.trim() ? detail.trim() : meta.operation.replace(/_/g, " ");
+  return meta.role === "trigger" ? `When ${meta.serviceTitle} reports ${what}${where}` : `Then ${meta.serviceTitle} will ${what}${where}`;
+}
+function ingredients(fields) {
+  return fields;
+}
+var DOMAIN_ACCENT = {
+  payments: "#635bff",
+  commerce: "#96bf48",
+  messaging: "#4a154b",
+  email: "#0f9d58",
+  crm: "#00a1e0",
+  support: "#03363d",
+  storage: "#ff9900",
+  calendar: "#4285f4",
+  productivity: "#2f3437",
+  database: "#336791",
+  devtools: "#24292f",
+  analytics: "#f9a03c",
+  marketing: "#1877f2",
+  ai: "#d97757",
+  forms: "#262627",
+  hr: "#5c4ee5",
+  geo: "#34a853"
+};
+
+export { connectionFields, defineConnectorKind, ingredients, summarize };
+//# sourceMappingURL=connectors.js.map
+//# sourceMappingURL=connectors.js.map

package/dist/connectors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors.ts"],"names":[],"mappings":"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","file":"connectors.js","sourcesContent":["/**\n * The authoring surface every connector node shares.\n *\n * ## Why this is in fancy-flow and not in fancy-connector-core\n *\n * `fancy-connector-core` owns the WIRE — delivery, classification, retries,\n * estate selection — and deliberately knows nothing about flow. This module\n * builds a node's `ConfigField[]` and its `NodeKindDefinition`, which are\n * fancy-flow concepts, so putting it there would couple the runtime to the\n * editor and force a non-flow consumer to install one to make an HTTP call.\n *\n * It lived as vendored source in the node marketplace until 0.48.0, which was\n * fine for a node (a copy costs a consumer no dependency) and impossible for a\n * PACKAGE — a package cannot import vendored sandbox source, so every generated\n * `<provider>-ui` package carried its own copy of a file only this repo can\n * correctly change. At the scale the connector estate is heading for that is\n * the exact \"a copy cannot be upgraded\" problem the packages exist to solve.\n *\n * ## The model, and where it came from\n *\n * IFTTT's authoring UX is the one non-engineers actually complete, and three of\n * its four ideas map onto fancy-flow without distortion:\n *\n * 1. **Service first, then capability.** You pick Stripe, *then* pick what about\n *    Stripe. Not a flat wall of four hundred nodes. Here that lives in the\n *    registry — `connector.service` groups a provider's nodes, and the listing\n *    tools narrow in two steps.\n * 2. **The connection is a thing, not a field.** You authorize a service once\n *    and every applet reuses it. Here: `connection.ts` in the runtime, and the\n *    single `connection` config field below.\n * 3. **Ingredients.** A trigger's output fields become named tokens you drop\n *    into a downstream action's fields. fancy-flow already has the machinery —\n *    `outputShape` on the kind, `availableVariables()` reading it off direct\n *    predecessors — so a connector's job is simply to DECLARE its shape. See\n *    `ingredients.ts`.\n * 4. **A sentence, not a form dump.** `summarize()` below.\n *\n * ## Where it does NOT map, and what we did instead\n *\n * An IFTTT applet is one trigger and one action, so \"the ingredients\" is\n * unambiguous: there is only one upstream. A fancy-flow graph branches, fans\n * out, merges and nests, so a connector node several hops downstream has no\n * single trigger to draw from — `availableVariables()` deliberately offers only\n * DIRECT predecessors, because a grandparent's field resolves to `null` at run\n * time and a suggestion that silently produces nothing is worse than no\n * suggestion.\n *\n * We did not paper over that. Connector triggers publish their event as a\n * single object with a declared shape, so the natural thing an author does —\n * carry it forward on the wire — keeps the ingredients available at each step.\n * Reaching further up the graph is a fancy-flow concern, recorded as a finding\n * rather than reimplemented per node.\n */\n\nimport type { ConfigField, NodeKindDefinition } from \"./registry/types\";\nimport type { OutputField } from \"./expressions/variables\";\n\n// Re-exported so a connector package needs ONE import rather than two entries.\nexport type { OutputField };\n\n/** The domains the catalogue is grouped by. Mirrors the plan's taxonomy. */\nexport type ConnectorDomain =\n  | \"payments\"\n  | \"commerce\"\n  | \"messaging\"\n  | \"email\"\n  | \"crm\"\n  | \"support\"\n  | \"storage\"\n  | \"calendar\"\n  | \"productivity\"\n  | \"database\"\n  | \"devtools\"\n  | \"analytics\"\n  | \"marketing\"\n  | \"ai\"\n  | \"forms\"\n  | \"hr\"\n  | \"geo\";\n\n/** What a connector node does in the graph — IFTTT's \"this\" versus \"that\". */\nexport type ConnectorRole = \"trigger\" | \"action\" | \"search\";\n\n/**\n * How the provider exposes a test estate. Kept in step with the runtime's\n * `SandboxKind`, and `vendoring.test.ts` compares the two declarations — a\n * hand-maintained mirror with nothing checking it is the shape this repository\n * keeps finding.\n *\n * Two of these are answers people skip. `unverified` means NOBODY HAS CHECKED —\n * a real state, and the right one until somebody has. `restricted-reach` is the\n * dangerous one: same credentials, same endpoints, same estate, and only the\n * AUDIENCE restricted, so it looks exactly like a successful post nobody can\n * see. Neither is `none`, and neither can be selected as a mode.\n */\nexport type SandboxKind =\n  | \"credential\"\n  | \"base-url\"\n  | \"separate-account\"\n  | \"restricted-reach\"\n  | \"none\"\n  | \"unverified\";\n\n/** The kinds a `sandbox` mode can actually point at. Mirrors `sandboxIsSelectable`. */\nconst SELECTABLE_SANDBOX: readonly SandboxKind[] = [\"credential\", \"base-url\", \"separate-account\"];\n\nexport type ConnectorMeta = {\n  service: string;\n  serviceTitle: string;\n  domain: ConnectorDomain;\n  role: ConnectorRole;\n  /** The provider's name for this operation, so search finds what people type. */\n  operation: string;\n  sandbox: SandboxKind;\n  /** Link to the provider documentation this node was written against. */\n  docs?: string;\n};\n\n/**\n * The two fields EVERY connector node carries, in the same order, with the same\n * keys.\n *\n * Uniformity is the feature. An agent that has configured one connector has\n * configured all of them, and a human who has learned where the sandbox switch\n * lives never has to look for it again.\n */\nexport function connectionFields(meta: ConnectorMeta): ConfigField[] {\n  const modes: Array<{ value: string; label: string }> = [\n    { value: \"auto\", label: \"Auto — sandbox locally, live in production\" },\n    { value: \"fake\", label: \"Fake — no credentials, no network\" },\n  ];\n\n  // Only offer sandbox where one exists. A select listing a mode the provider\n  // does not have is an invitation to pick it and then read an error.\n  if (SELECTABLE_SANDBOX.includes(meta.sandbox)) {\n    modes.push({ value: \"sandbox\", label: sandboxLabel(meta.sandbox) });\n  }\n  modes.push({ value: \"live\", label: \"Live — the real account\" });\n\n  return [\n    {\n      type: \"credential\",\n      key: \"connection\",\n      label: `${meta.serviceTitle} connection`,\n      credentialType: `connector:${meta.service}`,\n      description:\n        `Which configured ${meta.serviceTitle} connection to use. Credentials live in the host's ` +\n        \"configuration, never in the workflow — a graph is exported, committed and handed to agents.\",\n    },\n    {\n      type: \"select\",\n      key: \"mode\",\n      label: \"Environment\",\n      options: modes,\n      default: \"auto\",\n      description: sandboxNote(meta),\n    },\n  ];\n}\n\nfunction sandboxLabel(kind: SandboxKind): string {\n  return kind === \"base-url\"\n    ? \"Sandbox — the provider's separate test host\"\n    : kind === \"separate-account\"\n      ? \"Sandbox — your separate test account\"\n      : \"Sandbox — the provider's test estate\";\n}\n\n/**\n * What \"auto\" means for this provider, said where the author is choosing.\n *\n * The two non-selectable kinds get their own sentence rather than sharing\n * `none`'s. `restricted-reach` in particular has to be said HERE — on the field\n * somebody is filling in — because the failure it produces is a run that looks\n * completely successful and reached nobody, and by the time that is visible the\n * author has stopped looking at this screen.\n */\nfunction sandboxNote(meta: ConnectorMeta): string {\n  if (meta.sandbox === \"restricted-reach\") {\n    return (\n      `${meta.serviceTitle} has no separate test estate — an unreviewed app posts only to its own developers, ` +\n      \"or privately. Same credentials, same endpoints: only the audience changes, and nothing here selects it. \" +\n      \"A restricted run looks exactly like a successful one, so confirm reach on the provider's own surface.\"\n    );\n  }\n\n  if (meta.sandbox === \"unverified\") {\n    return (\n      `Nobody has verified what test estate ${meta.serviceTitle} offers, so \"sandbox\" is not offered — and ` +\n      '\"auto\" means fake locally and live in production. Find out before pointing a workflow at it.'\n    );\n  }\n\n  if (meta.sandbox === \"none\") {\n    return `${meta.serviceTitle} has no sandbox estate, so \"auto\" means fake locally and live in production.`;\n  }\n\n  return \"Auto follows the environment. Setting this explicitly overrides it everywhere, including in production.\";\n}\n\n/**\n * Build a connector node's authoring surface.\n *\n * Prepends the shared connection fields, applies the domain accent, and stamps\n * the metadata the registry reads. A connector that hand-rolled these would\n * drift from its siblings in exactly the small ways that make a catalogue feel\n * like a pile.\n */\nexport function defineConnectorKind(\n  meta: ConnectorMeta,\n  kind: Omit<NodeKindDefinition, \"category\"> & { category?: NodeKindDefinition[\"category\"] },\n): NodeKindDefinition & { connector: ConnectorMeta } {\n  return {\n    ...kind,\n    // `category` stays fancy-flow's own taxonomy — it describes what the node\n    // does to the GRAPH, which is what the palette groups by. Connector-ness is\n    // a separate axis and is carried separately; overloading one field with two\n    // meanings would make \"show me the triggers\" and \"hide the connectors\"\n    // impossible to ask at the same time.\n    category: kind.category ?? (meta.role === \"trigger\" ? \"trigger\" : \"io\"),\n    accent: kind.accent ?? DOMAIN_ACCENT[meta.domain],\n    configSchema: [...connectionFields(meta), ...(kind.configSchema ?? [])],\n    connector: meta,\n  };\n}\n\n/**\n * One line describing what a configured node will do, in IFTTT's register.\n *\n * A configured connector should read as a sentence, not as a form dump — it is\n * what makes a canvas skimmable, and it is also what an agent quotes back to a\n * human when asking whether to proceed.\n */\nexport function summarize(meta: ConnectorMeta, config: Record<string, unknown>, detail?: string): string {\n  const mode = typeof config.mode === \"string\" ? config.mode : \"auto\";\n  const where =\n    mode === \"fake\"\n      ? \" (faked — nothing leaves this machine)\"\n      : mode === \"sandbox\"\n        ? \" in the sandbox\"\n        : mode === \"live\"\n          ? \" on the live account\"\n          : \"\";\n\n  const what = detail?.trim() ? detail.trim() : meta.operation.replace(/_/g, \" \");\n\n  return meta.role === \"trigger\"\n    ? `When ${meta.serviceTitle} reports ${what}${where}`\n    : `Then ${meta.serviceTitle} will ${what}${where}`;\n}\n\n/** Declare a trigger's event fields — the \"ingredients\" downstream nodes pick from. */\nexport function ingredients(fields: OutputField[]): OutputField[] {\n  return fields;\n}\n\nconst DOMAIN_ACCENT: Record<ConnectorDomain, string> = {\n  payments: \"#635bff\",\n  commerce: \"#96bf48\",\n  messaging: \"#4a154b\",\n  email: \"#0f9d58\",\n  crm: \"#00a1e0\",\n  support: \"#03363d\",\n  storage: \"#ff9900\",\n  calendar: \"#4285f4\",\n  productivity: \"#2f3437\",\n  database: \"#336791\",\n  devtools: \"#24292f\",\n  analytics: \"#f9a03c\",\n  marketing: \"#1877f2\",\n  ai: \"#d97757\",\n  forms: \"#262627\",\n  hr: \"#5c4ee5\",\n  geo: \"#34a853\",\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "description": "Workflow editor + runner. Six built-in node kits (trigger / action / decision / output / note / subgraph), tokenized theme, topological execution with per-node status. React-flow bundled; consumers npm install fancy-flow and get nothing extra.",
   "repository": {
     "type": "git",
@@ -43,6 +43,16 @@
         "default": "./dist/registry.cjs"
       }
     },
+    "./connectors": {
+      "import": {
+        "types": "./dist/connectors.d.ts",
+        "default": "./dist/connectors.js"
+      },
+      "require": {
+        "types": "./dist/connectors.d.cts",
+        "default": "./dist/connectors.cjs"
+      }
+    },
     "./schema": {
       "import": {
         "types": "./dist/schema/index.d.ts",