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

package/dist/index.d.cts

@@ -346,6 +346,19 @@ type DeliveryOutcome<T> = {
     gaveUp?: string;
     /** The classification of the last failure, so a host can route on it. */
     kind?: FailureKind;
+    /**
+     * The last failure **as it was thrown** — absent when the call worked.
+     *
+     * `kind` and `gaveUp` are what `deliver()` concluded; this is what it
+     * concluded it FROM. Until 0.5.0 an outcome carried only the conclusions, so
+     * everything the error knew beyond them — the HTTP status, the provider's own
+     * code, the class it was raised as — stopped here, and every failed
+     * `callConnector` reached its host with none of it. See `failureFrom()` in
+     * `client.ts`.
+     *
+     * `unknown`, because `send` may throw anything.
+     */
+    error?: unknown;
 };
 /**
  * The message a person reads when an ambiguous failure could not be retried.
@@ -774,6 +787,26 @@ type ServiceDescriptor = {
     faker: ConnectorFaker;
     /** Header the provider uses for idempotency, when it has one. */
     idempotencyHeader?: string;
+    /**
+     * Where this provider puts its OWN error code on a failed response, when it
+     * publishes one — read only for a status of 400 or above, and carried as
+     * `error.providerCode`.
+     *
+     * **Declared per service, never guessed.** The shapes do not agree, and the
+     * near-misses are the dangerous part: Bluesky's `error` is a code
+     * (`"AuthenticationRequired"`), Mastodon's `error` is a sentence
+     * (`"The access token is invalid"`), Discord's code is a number under `code`,
+     * and some providers use a header. A generic reader would publish Mastodon's
+     * sentence as a code — the plausible answer that is wrong. With no
+     * declaration the field is absent, which says *nobody said where to look*.
+     *
+     * Return a string or an integer (carried as its decimal string); anything
+     * else, a blank string, or a throw, leaves the code absent. **A throw never
+     * reaches the call**: a code is a detail on an answer the status already gave,
+     * and a reader choking on an HTML error page must not turn an explicit `401`
+     * into an unclassified failure.
+     */
+    providerCodeFrom?: (response: TransportResponse) => string | number | null | undefined;
 };
 type ConnectorRequest = {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -1108,7 +1141,13 @@ declare class ConnectorError extends Error {
      * failure must not be assumed safe.
      */
     readonly kind: FailureKind;
-    constructor(message: string, ctx: ConnectorErrorContext);
+    /**
+     * `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: string, ctx: ConnectorErrorContext, options?: ErrorOptions);
     /**
      * Safe to retry **without knowing anything about the connector**.
      *
@@ -1141,7 +1180,7 @@ declare class ConnectorRateLimited extends ConnectorError {
     readonly retryAfter?: number;
     constructor(message: string, ctx: ConnectorErrorContext & {
         retryAfter?: number;
-    });
+    }, options?: ErrorOptions);
     get classified(): Classified;
 }
 /**

package/dist/index.d.ts

@@ -346,6 +346,19 @@ type DeliveryOutcome<T> = {
     gaveUp?: string;
     /** The classification of the last failure, so a host can route on it. */
     kind?: FailureKind;
+    /**
+     * The last failure **as it was thrown** — absent when the call worked.
+     *
+     * `kind` and `gaveUp` are what `deliver()` concluded; this is what it
+     * concluded it FROM. Until 0.5.0 an outcome carried only the conclusions, so
+     * everything the error knew beyond them — the HTTP status, the provider's own
+     * code, the class it was raised as — stopped here, and every failed
+     * `callConnector` reached its host with none of it. See `failureFrom()` in
+     * `client.ts`.
+     *
+     * `unknown`, because `send` may throw anything.
+     */
+    error?: unknown;
 };
 /**
  * The message a person reads when an ambiguous failure could not be retried.
@@ -774,6 +787,26 @@ type ServiceDescriptor = {
     faker: ConnectorFaker;
     /** Header the provider uses for idempotency, when it has one. */
     idempotencyHeader?: string;
+    /**
+     * Where this provider puts its OWN error code on a failed response, when it
+     * publishes one — read only for a status of 400 or above, and carried as
+     * `error.providerCode`.
+     *
+     * **Declared per service, never guessed.** The shapes do not agree, and the
+     * near-misses are the dangerous part: Bluesky's `error` is a code
+     * (`"AuthenticationRequired"`), Mastodon's `error` is a sentence
+     * (`"The access token is invalid"`), Discord's code is a number under `code`,
+     * and some providers use a header. A generic reader would publish Mastodon's
+     * sentence as a code — the plausible answer that is wrong. With no
+     * declaration the field is absent, which says *nobody said where to look*.
+     *
+     * Return a string or an integer (carried as its decimal string); anything
+     * else, a blank string, or a throw, leaves the code absent. **A throw never
+     * reaches the call**: a code is a detail on an answer the status already gave,
+     * and a reader choking on an HTML error page must not turn an explicit `401`
+     * into an unclassified failure.
+     */
+    providerCodeFrom?: (response: TransportResponse) => string | number | null | undefined;
 };
 type ConnectorRequest = {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -1108,7 +1141,13 @@ declare class ConnectorError extends Error {
      * failure must not be assumed safe.
      */
     readonly kind: FailureKind;
-    constructor(message: string, ctx: ConnectorErrorContext);
+    /**
+     * `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: string, ctx: ConnectorErrorContext, options?: ErrorOptions);
     /**
      * Safe to retry **without knowing anything about the connector**.
      *
@@ -1141,7 +1180,7 @@ declare class ConnectorRateLimited extends ConnectorError {
     readonly retryAfter?: number;
     constructor(message: string, ctx: ConnectorErrorContext & {
         retryAfter?: number;
-    });
+    }, options?: ErrorOptions);
     get classified(): Classified;
 }
 /**

package/dist/index.js

@@ -137,7 +137,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) {
@@ -146,7 +147,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);
@@ -184,8 +186,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;
@@ -217,8 +225,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() {
@@ -265,7 +273,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);
@@ -496,7 +504,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,
@@ -515,12 +529,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) {
@@ -601,6 +642,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;