@particle-academy/fancy-connector-core 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,138 @@ 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.6.0] - 2026-09-13
+
+Additive only. **What a consumer must DO: nothing** — see each entry.
+
+### Added
+
+- **PHP: the exception a failed call throws now carries `attempts` and
+  `idempotent`**, as the TypeScript error has since 0.1.0. `attempts` is every
+  failed attempt of the call, in order, as `list<Attempt>`; `idempotent` is
+  what the call declared. Without them a PHP host could see *what* failed but
+  not whether a timeout went unretried because the connector is not idempotent
+  or was retried until the budget ran out — which is the difference between
+  *go and look* and *run it again*.
+
+  Both are `null` on any exception that did not end a call — one you construct
+  yourself, one from `HttpErrors::classify()`, and the classified exception
+  chained as `getPrevious()`. Deliberately not `[]` / `false`, which would
+  claim nothing was tried, or that the connector declared a retry unsafe.
+  TypeScript is unchanged: there they stay absent.
+
+  **What a consumer must DO: nothing.** Both are new trailing, optional
+  constructor parameters on `ConnectorException` and
+  `ConnectorRateLimitedException`, so existing `new …Exception(...)` calls,
+  positional or named, keep working. A subclass of `ConnectorException` that
+  declares its own constructor does not need to pass them.
+
+### Changed
+
+- **CI now runs `pint --test` on the PHP tree**, and the tree passes it. Pint
+  was already a dev dependency and `composer lint` already called it, but no
+  workflow did, so three files had drifted (`RenderRules.php`,
+  `ServiceDescriptor.php`, `Socialite/SocialiteBridge.php`) — formatting only,
+  no behaviour change.
+- **Line endings are pinned to LF in `.gitattributes`.** A Windows clone with
+  `core.autocrlf=true` checked every file out as CRLF, which made `pint --test`
+  fail on nearly every PHP file locally while CI saw three, and made
+  `scripts/vendor.mjs` generate a `_connector/` copy whose bytes depended on
+  the machine it ran on. **What a consumer must DO: nothing** — the published
+  files were already LF; only a checkout of this repository changes.
+
+## [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
@@ -279,6 +411,11 @@ clock; this package is the runtime it is written on.
   satisfies it with no dependency in either direction and a host that has never
   heard of a workflow engine can implement it.
 
-[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Particle-Academy/fancy-connector-core/releases/tag/v0.1.0

package/README.md

@@ -71,6 +71,34 @@ 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
+  // Set at runtime but not declared on the `ConnectorError` type, so read them
+  // through a narrowing of your own:
+  (error as { attempts?: Attempt[] }).attempts;       // every failed attempt of the call, in order
+  (error as { idempotent?: boolean }).idempotent;     // what the call declared — "never allowed to retry" vs "retries ran out"
+}
+```
+
+PHP is the same: `ConnectorAuthException`, `->status`, `->providerCode`,
+`->getPrevious()`, `->attempts`, `->idempotent`. The last two are set only on the
+error a call throws; anywhere else they are absent (TS) or `null` (PHP), never
+`[]` or `false`. 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;