@particle-academy/fancy-connector-core 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ 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.11.0] - 2026-10-28
+
+### Added
+
+- **`decodeFormFieldJson` / `FormFieldJson::decode`: the form-field-json
+  payload transform.** It reads a form-encoded body whose one named field
+  holds JSON, which is how Slack posts every interactivity callback
+  (`payload=<json>`). It runs AFTER signature verification, over the same raw
+  bytes. `+` and `%20` are both spaces. Every `%` must be `%XX` across the
+  WHOLE body, and the bytes must be UTF-8. A missing, doubled or malformed
+  field, or one that is not JSON, is refused BY NAME (`missing-field`,
+  `duplicate-field`, `bad-encoding`, `not-json`; `FormFieldJsonError.reason` /
+  `FormFieldJsonException->reason`). Neither runtime uses its built-in
+  decoder, because `decodeURIComponent` throws on `%zz` where `urldecode`
+  silently keeps it, and a field sent twice is refused rather than resolved
+  first-wins or last-wins. Both runtimes reproduce the hand-authored corpus
+  under `fixtures/form-field-json/`. In PHP, JSON objects come back as
+  arrays, so an empty `{}` is `[]`, as in `Mime::toArray()`.
+- **`TriggerDescriptor.decode` + `decodeDelivery` / `DeliveryDecode::apply`.**
+  A webhook trigger may declare how its verified body is read:
+  `{kind: "form-field-json", field: "payload"}`. A host verifies the raw
+  bytes, then calls the dispatcher with the declaration, then starts the run.
+  An unknown kind is refused by name, never passed through as raw bytes. The
+  kinds ship as data (`DELIVERY_DECODE_KINDS` / `DeliveryDecode::KINDS`).
+  Absent `decode` means a host reads the body as it always has.
+
+`CONNECTOR_API_VERSION` is unchanged: an optional descriptor field changes
+nothing a connector must implement.
+
 ## [0.10.1] - 2026-10-10
 
 ### Fixed

package/dist/index.cjs

@@ -38,8 +38,11 @@ __export(src_exports, {
   ConnectorUnreachable: () => ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: () => DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY: () => DEFAULT_RETRY,
+  DELIVERY_DECODE_KINDS: () => DELIVERY_DECODE_KINDS,
   EXPIRES_AT_UNITS: () => EXPIRES_AT_UNITS,
   FAKE_EPOCH: () => FAKE_EPOCH,
+  FORM_FIELD_JSON_REASONS: () => FORM_FIELD_JSON_REASONS,
+  FormFieldJsonError: () => FormFieldJsonError,
   MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING: () => NO_IDEMPOTENCY_KEY_WARNING,
   PROBLEM_SEVERITIES: () => PROBLEM_SEVERITIES,
@@ -60,6 +63,8 @@ __export(src_exports, {
   compareShape: () => compareShape,
   connectionsFor: () => connectionsFor,
   constantTimeEquals: () => constantTimeEquals,
+  decodeDelivery: () => decodeDelivery,
+  decodeFormFieldJson: () => decodeFormFieldJson,
   deliver: () => deliver,
   fakeRequest: () => fakeRequest,
   fakeValues: () => fakeValues,
@@ -1789,6 +1794,77 @@ function parseMime(raw) {
   };
 }
 
+// src/form-field-json.ts
+var FORM_FIELD_JSON_REASONS = ["missing-field", "duplicate-field", "bad-encoding", "not-json"];
+var FormFieldJsonError = class extends Error {
+  constructor(reason, field, message) {
+    super(message);
+    this.reason = reason;
+    this.field = field;
+    this.name = "FormFieldJsonError";
+  }
+  reason;
+  field;
+};
+var UTF8 = new TextDecoder("utf-8", { fatal: true });
+var HEX = /^[0-9A-Fa-f]{2}$/;
+function decodeFormFieldJson(raw, field) {
+  const text = typeof raw === "string" ? raw : latin12(raw);
+  const found = [];
+  for (const pair of text.split("&")) {
+    if (pair === "") continue;
+    const eq = pair.indexOf("=");
+    const name = component(eq === -1 ? pair : pair.slice(0, eq), field);
+    const value2 = component(eq === -1 ? "" : pair.slice(eq + 1), field);
+    if (name === field) found.push(value2);
+  }
+  if (found.length === 0) {
+    throw new FormFieldJsonError("missing-field", field, `the body has no "${field}" field`);
+  }
+  if (found.length > 1) {
+    throw new FormFieldJsonError("duplicate-field", field, `the body has "${field}" ${found.length} times`);
+  }
+  const [value] = found;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new FormFieldJsonError("not-json", field, `"${field}" is not JSON: ${error.message}`);
+  }
+}
+function component(encoded, field) {
+  const bytes = [];
+  for (let i = 0; i < encoded.length; i++) {
+    const char = encoded[i];
+    if (char === "+") {
+      bytes.push(32);
+    } else if (char === "%") {
+      const hex = encoded.slice(i + 1, i + 3);
+      if (!HEX.test(hex)) {
+        throw new FormFieldJsonError("bad-encoding", field, `a "%" at byte ${i} is not followed by two hex digits`);
+      }
+      bytes.push(parseInt(hex, 16));
+      i += 2;
+    } else {
+      bytes.push(encoded.charCodeAt(i) & 255);
+    }
+  }
+  try {
+    return UTF8.decode(new Uint8Array(bytes));
+  } catch {
+    throw new FormFieldJsonError("bad-encoding", field, "the decoded bytes are not valid UTF-8");
+  }
+}
+var DELIVERY_DECODE_KINDS = ["form-field-json"];
+function decodeDelivery(decode, raw) {
+  if (decode.kind === "form-field-json") return decodeFormFieldJson(raw, decode.field);
+  throw new Error(`unknown decode kind ${JSON.stringify(decode.kind)}`);
+}
+function latin12(bytes) {
+  let out = "";
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -2211,8 +2287,11 @@ function hasDelivery(value) {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  DELIVERY_DECODE_KINDS,
   EXPIRES_AT_UNITS,
   FAKE_EPOCH,
+  FORM_FIELD_JSON_REASONS,
+  FormFieldJsonError,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
   PROBLEM_SEVERITIES,
@@ -2233,6 +2312,8 @@ function hasDelivery(value) {
   compareShape,
   connectionsFor,
   constantTimeEquals,
+  decodeDelivery,
+  decodeFormFieldJson,
   deliver,
   fakeRequest,
   fakeValues,