@particle-academy/fancy-connector-core 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,140 @@ 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.5.0] - 2026-09-13
+
+### Fixed
+
+- **A failed call arrived with no HTTP status, in both runtimes, on every
+  host.** `classifyHttp()` / `HttpErrors::classify()` built the right error — a
+  `ConnectorAuthError` with `status: 401` — and `deliver()` read its
+  classification and dropped it: a `DeliveryOutcome` carried `attempts`,
+  `gaveUp` and `kind`, never the error. So `failureFrom()` rebuilt the thrown
+  error from the call context alone. The message still quoted the `401`; the
+  `status` field was empty.
+
+  It surfaced in `fancy-connectors`' scheduled Drift workflow, which asks each
+  real provider to refuse an impossible credential and reads `error.status` to
+  see the refusal. Bluesky, Mastodon and Telegram answered `401` and Discord
+  `404` — exactly right — and all four probes reported *"the request failed
+  before any status arrived"*, on all 25 runs since the workflow was added.
+
+  A failed call now keeps what the provider said: **`status`**,
+  **`providerCode`** (see Added), and the classified error itself as the
+  standard **`cause`** (TS) / **`getPrevious()`** (PHP). Unchanged: the message,
+  including the *go and look* wording of an ambiguous refusal, `kind`,
+  `retryable`, and, in TypeScript, `attempts` and `idempotent`. Retry decisions
+  are untouched — they read `kind`, which was always right.
+
+  **What a consumer must DO: nothing**, unless you relied on `status` being
+  empty (a host that read "no status" as "the provider never answered" now sees
+  the number it should always have seen), or on the class — see Changed.
+
+### Changed
+
+- **The thrown class is now the one the failure was classified as**, in both
+  runtimes, and the two runtimes now agree. A `401`/`403` throws
+  `ConnectorAuthError` / `ConnectorAuthException`, a `429` throws
+  `ConnectorRateLimited` / `ConnectorRateLimitedException` carrying the
+  provider's `retryAfter`, and every other failure throws the class its `kind`
+  names: `ConnectorTransient`, `ConnectorRequestError`, `ConnectorUnreachable`,
+  `ConnectorAmbiguous` (and their `*Exception` twins).
+
+  Why the specific class rather than status on a generic one: the table at the
+  top of `errors.ts` / `ConnectorException.php` is the taxonomy's documented
+  promise, and a host catching `ConnectorAuthError` to send someone to
+  re-authenticate never received one from a call. `kind` cannot express that
+  distinction — a rejected credential and a malformed request are both
+  `rejected`, a throttle and a 5xx are both `refused-explicitly` — so it has to
+  come from the classified error. And the two runtimes already disagreed:
+  TypeScript threw a bare `ConnectorError`, PHP mapped by kind and so threw a
+  `ConnectorRequestException` for a rejected credential and a
+  `ConnectorTransientException` for a throttle, losing `retryAfter`.
+
+  - **TypeScript — what to DO: nothing**, unless you compared
+    `error.name === "ConnectorError"` or `error.constructor === ConnectorError`.
+    Every new class extends `ConnectorError`, so `instanceof ConnectorError`
+    still matches; use that. A 2xx whose body is not JSON now throws
+    `ConnectorRequestError` (same `kind`, `rejected`), as PHP always did.
+  - **PHP — BREAKING for one catch shape.** The exception classes are `final`
+    siblings, so `catch (ConnectorRequestException)` written to see a rejected
+    credential, or `catch (ConnectorTransientException)` written to see a
+    throttle, **no longer catches it**. Add `ConnectorAuthException` /
+    `ConnectorRateLimitedException` to that clause, or catch
+    `ConnectorException` and branch on `kind()` / `status`. A clause catching
+    `ConnectorException` needs nothing.
+
+  The Fancy-Friends connector packages were checked before release: none
+  catches these classes or reads `status`; they surface the message, which is
+  unchanged.
+
+### Added
+
+- **`ServiceDescriptor.providerCodeFrom`** (both runtimes) — where a provider
+  puts its OWN error code on a failed response, carried as
+  `error.providerCode`. **Declared per service, never guessed**: Bluesky's
+  `error` is a code (`"AuthenticationRequired"`), Mastodon's `error` is a
+  sentence, Discord's code is an integer under `code`. A generic reader would
+  publish Mastodon's sentence as a code. Undeclared, `providerCode` is absent.
+  A string or an integer is carried; a blank string, anything else, or a
+  **throw** leaves it absent — a reader choking on an HTML error page never
+  turns an explicit `401` into an unclassified failure. Optional; nothing a
+  connector declares has to change, so `CONNECTOR_API_VERSION` stays `1`.
+
+  Before this, `providerCode` existed on both error classes and nothing
+  anywhere set it.
+- **`DeliveryOutcome.error`** — the last failure as it was thrown, absent when
+  the call worked.
+- TypeScript: `ConnectorError` and `ConnectorRateLimited` take a standard
+  `ErrorOptions` third argument (`{ cause }`), and `classifyThrown()` now chains
+  the original transport error as `cause`, as the PHP twin always passed it as
+  `$previous`.
+- PHP: `ConnectorRateLimitedException` takes a trailing `?Throwable $previous`,
+  and `HttpErrors::classify()` a trailing `?string $providerCode`. Both are
+  appended and optional.
+
+## [0.4.0] - 2026-09-12
+
+### Fixed
+
+- **An idempotency key was fitted to the catalogue CEILING, never to the
+  provider's own limit.** `MAX_KEY_LENGTH` / `MAX_IDEMPOTENCY_KEY_LENGTH` is 255
+  — the widest any provider in the catalogue accepts. A provider declares its
+  own, and the connector index carries it as `idempotencyMaxLength`; Discord's
+  `discord_message` declares **25**.
+
+  So a legitimate engine-derived key — `lane_<16 hex>:subject`, 29 characters —
+  came back unshortened and the connector's own validation refused it:
+  `message_create: idempotencyKey must be at most 25 characters`. The run failed
+  at the node, and the only workaround available to a host was choosing a
+  shorter run identity, which is a workflow-authoring decision being forced by a
+  string length in a library.
+
+  The subtle part is that nothing was malformed: the key was correct and the
+  validation was correct. This package simply never asked how long the key was
+  allowed to be.
+
+  `keyFor(..., maxLength:)` in PHP and `{ maxLength }` in `IdempotencyOptions`
+  now carry the provider's limit, and the smaller of it and the ceiling always
+  applies — a descriptor claiming more than any provider accepts is one to
+  distrust, not obey. The digest still makes the shortened key **stable across
+  attempts**, which is the entire point of one: a key that varied per attempt
+  would defeat the dedupe it exists to provide.
+
+  A limit too small to carry `<head>~<digest>` yields the digest alone. That
+  loses the greppable prefix, which is a real cost — but a key that is hard to
+  trace still dedupes, while the alternative is a negative slice length.
+
+  **Both runtimes had this, identically**, so the parity suite comparing them
+  stayed green throughout. Agreement is not correctness, and that is the whole
+  reason this needed an outside report to surface: it came from the connector
+  lab, which hit it on Discord and worked around it by keeping its run key
+  artificially short.
+
+  Not a breaking change — the parameter is optional and omitting it preserves
+  the previous behaviour exactly. It lands as a MINOR because callers that
+  should pass a limit now can, and the connector emitters will.
+
 ## [0.3.1] - 2026-08-20
 
 ### Fixed

package/README.md

@@ -71,6 +71,28 @@ shouldRetry(classifyError(err).kind, { idempotent: connector.delivery.idempotent
 `Idempotency-Key`, or the absence of one — because `idempotent: true` is the one
 claim whose failure is a public duplicate.
 
+### What a failed call carries
+
+The error a host catches is the class the failure was classified as, and it keeps
+what the provider said:
+
+```ts
+try {
+  await callConnector(service, options);
+} catch (error) {
+  if (error instanceof ConnectorAuthError) error.status;  // 401 or 403
+  error.kind;          // the retry primitive
+  error.providerCode;  // only where the service declared `providerCodeFrom`
+  error.cause;         // the classified error; for a thrown transport, the original below it
+}
+```
+
+PHP is the same: `ConnectorAuthException`, `->status`, `->providerCode`,
+`->getPrevious()`. A provider's own error code is read only where its
+`ServiceDescriptor` says where it lives (`providerCodeFrom`) — Bluesky's `error`
+is a code and Mastodon's `error` is a sentence, so a guess would be wrong in the
+most plausible way available.
+
 ---
 
 ## Text, and two one-line bugs that ASCII hides

package/dist/index.cjs

@@ -245,7 +245,8 @@ async function deliver(send, policy = DEFAULT_RETRY, sleep = (ms) => new Promise
           ok: false,
           attempts,
           kind: classified.kind,
-          gaveUp: classified.kind === "ambiguous" ? `${AMBIGUOUS_REFUSAL} (${classified.detail})` : classified.detail
+          gaveUp: classified.kind === "ambiguous" ? `${AMBIGUOUS_REFUSAL} (${classified.detail})` : classified.detail,
+          error
         };
       }
       if (attempt >= budget) {
@@ -254,7 +255,8 @@ async function deliver(send, policy = DEFAULT_RETRY, sleep = (ms) => new Promise
           ok: false,
           attempts,
           kind: classified.kind,
-          gaveUp: `Gave up after ${attempt} attempts. ${classified.detail}`
+          gaveUp: `Gave up after ${attempt} attempts. ${classified.detail}`,
+          error
         };
       }
       const backoff = Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs);
@@ -292,8 +294,14 @@ var ConnectorError = class extends Error {
    * failure must not be assumed safe.
    */
   kind = "ambiguous";
-  constructor(message, ctx) {
-    super(message);
+  /**
+   * `options.cause` is the standard `Error` cause — what this error was built
+   * from. A failed call's error carries the classified error there, and a thrown
+   * transport's carries the original exception, so nothing below is lost when
+   * the message is rewritten for a person.
+   */
+  constructor(message, ctx, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
     this.name = new.target.name;
     this.service = ctx.service;
     this.operation = ctx.operation;
@@ -325,8 +333,8 @@ var ConnectorRateLimited = class extends ConnectorError {
   kind = "refused-explicitly";
   /** Seconds to wait, when the provider said. */
   retryAfter;
-  constructor(message, ctx) {
-    super(message, ctx);
+  constructor(message, ctx, options) {
+    super(message, ctx, options);
     this.retryAfter = ctx.retryAfter;
   }
   get classified() {
@@ -373,7 +381,7 @@ function classifyHttp(status, ctx, body, retryAfter) {
 function classifyThrown(cause, ctx) {
   const classified = classifyError(cause);
   const message = `${ctx.service}.${ctx.operation}: ${classified.detail}`;
-  return classified.kind === "unreachable" ? new ConnectorUnreachable(message, ctx) : new ConnectorAmbiguous(message, ctx);
+  return classified.kind === "unreachable" ? new ConnectorUnreachable(message, ctx, { cause }) : new ConnectorAmbiguous(message, ctx, { cause });
 }
 function httpFailure(status, body, retryAfter) {
   const classified = classifyStatus(status, body, retryAfter);
@@ -604,7 +612,13 @@ async function callConnector(service, options) {
       if (response.status < 400) {
         return response.body.trim() === "" ? null : parseJson(response.body, ctx);
       }
-      throw classifyHttp(response.status, ctx, response.body, readRetryAfter(response.headers));
+      const providerCode = readProviderCode(service, response);
+      throw classifyHttp(
+        response.status,
+        providerCode === void 0 ? ctx : { ...ctx, providerCode },
+        response.body,
+        readRetryAfter(response.headers)
+      );
     },
     {
       ...DEFAULT_RETRY,
@@ -623,12 +637,39 @@ async function callConnector(service, options) {
 function failureFrom(outcome, ctx, idempotent) {
   const last = outcome.attempts.at(-1);
   const kind = outcome.kind ?? last?.kind ?? "ambiguous";
-  const error = new ConnectorError(outcome.gaveUp ?? `${ctx.service}.${ctx.operation} failed.`, ctx);
+  const message = outcome.gaveUp ?? `${ctx.service}.${ctx.operation} failed.`;
+  const cause = outcome.error;
+  const said = cause instanceof ConnectorError ? cause : void 0;
+  const context = {
+    ...ctx,
+    ...said?.status === void 0 ? {} : { status: said.status },
+    ...said?.providerCode === void 0 ? {} : { providerCode: said.providerCode }
+  };
+  const error = failureOfClass(kind, said, message, context, cause === void 0 ? void 0 : { cause });
   Object.defineProperty(error, "kind", { value: kind, enumerable: false });
   Object.defineProperty(error, "attempts", { value: outcome.attempts, enumerable: false });
   Object.defineProperty(error, "idempotent", { value: idempotent, enumerable: false });
   return error;
 }
+function failureOfClass(kind, said, message, context, options) {
+  if (said?.kind === kind && said instanceof ConnectorAuthError) {
+    return new ConnectorAuthError(message, context, options);
+  }
+  if (said?.kind === kind && said instanceof ConnectorRateLimited) {
+    const retryAfter = said.retryAfter === void 0 ? {} : { retryAfter: said.retryAfter };
+    return new ConnectorRateLimited(message, { ...context, ...retryAfter }, options);
+  }
+  switch (kind) {
+    case "unreachable":
+      return new ConnectorUnreachable(message, context, options);
+    case "refused-explicitly":
+      return new ConnectorTransient(message, context, options);
+    case "rejected":
+      return new ConnectorRequestError(message, context, options);
+    case "ambiguous":
+      return new ConnectorAmbiguous(message, context, options);
+  }
+}
 async function prepare(service, connection, options) {
   const base = connection.baseUrl ?? service.baseUrls[connection.mode];
   if (!base) {
@@ -709,6 +750,17 @@ function parseJson(body, ctx) {
     throw error;
   }
 }
+function readProviderCode(service, response) {
+  if (!service.providerCodeFrom) return void 0;
+  let code;
+  try {
+    code = service.providerCodeFrom(response);
+  } catch {
+    return void 0;
+  }
+  if (typeof code === "number") return Number.isSafeInteger(code) ? String(code) : void 0;
+  return typeof code === "string" && code.trim() !== "" ? code : void 0;
+}
 function readRetryAfter(headers) {
   const raw = headers["retry-after"];
   if (!raw) return void 0;
@@ -937,7 +989,7 @@ function idempotencyKeyFor(ctx, nodeId, options = {}) {
   const windowSeconds = options.windowSeconds === void 0 ? DEFAULT_IDEMPOTENCY_WINDOW_SECONDS : options.windowSeconds;
   if (!identity) {
     const runKey = runKeyFrom(ctx);
-    return runKey === null ? null : fit(`${runKey}:${nodeId}`);
+    return runKey === null ? null : fit(`${runKey}:${nodeId}`, options.maxLength);
   }
   if (!identity.isReplaySafe(windowSeconds, options.now ?? /* @__PURE__ */ new Date())) {
     throw new ConnectorIdempotencyExpiredError(
@@ -949,13 +1001,15 @@ function idempotencyKeyFor(ctx, nodeId, options = {}) {
       }
     );
   }
-  return fit(identity.stepKey(nodeId, options.occurrence));
+  return fit(identity.stepKey(nodeId, options.occurrence), options.maxLength);
 }
 var NO_IDEMPOTENCY_KEY_WARNING = "no run identity available, so this write is being sent WITHOUT an idempotency key. A retry would repeat the effect rather than recover from it \u2014 the node is marked unsafe-to-replay, so a durable runner will give it one attempt. Durable runs supply an identity automatically; for a synchronous run, pass `run` in RunOptions.";
-function fit(key) {
-  if (key.length <= MAX_IDEMPOTENCY_KEY_LENGTH) return key;
+function fit(key, maxLength) {
+  const limit = maxLength === void 0 || maxLength === null ? MAX_IDEMPOTENCY_KEY_LENGTH : Math.max(1, Math.min(maxLength, MAX_IDEMPOTENCY_KEY_LENGTH));
+  if (key.length <= limit) return key;
   const digest = fnv1a(key);
-  const head = key.slice(0, MAX_IDEMPOTENCY_KEY_LENGTH - digest.length - 1);
+  if (limit <= digest.length + 1) return digest.slice(0, limit);
+  const head = key.slice(0, limit - digest.length - 1);
   return `${head}~${digest}`;
 }
 function fnv1a(value) {