@particle-academy/fancy-connector-core 0.3.1 → 0.5.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;
 }
 /**
@@ -1305,6 +1344,17 @@ type IdempotencyOptions = {
     now?: Date;
     /** For the error message when a key cannot be made safe. */
     context?: Partial<ConnectorErrorContext>;
+    /**
+     * The PROVIDER'S own limit, when it declares one — `idempotencyMaxLength` in
+     * the connector index. Omitted uses {@link MAX_IDEMPOTENCY_KEY_LENGTH}, which
+     * is the catalogue CEILING rather than any one provider's limit.
+     *
+     * Discord's `discord_message` declares 25, and for years only the ceiling was
+     * applied — so a legitimate engine-derived key came back at 29 characters and
+     * the connector's own validation refused it, failing the run at a node the
+     * host had no way to fix.
+     */
+    maxLength?: number | null;
 };
 /**
  * The idempotency key for this execution of this node, or `null`.

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;
 }
 /**
@@ -1305,6 +1344,17 @@ type IdempotencyOptions = {
     now?: Date;
     /** For the error message when a key cannot be made safe. */
     context?: Partial<ConnectorErrorContext>;
+    /**
+     * The PROVIDER'S own limit, when it declares one — `idempotencyMaxLength` in
+     * the connector index. Omitted uses {@link MAX_IDEMPOTENCY_KEY_LENGTH}, which
+     * is the catalogue CEILING rather than any one provider's limit.
+     *
+     * Discord's `discord_message` declares 25, and for years only the ceiling was
+     * applied — so a legitimate engine-derived key came back at 29 characters and
+     * the connector's own validation refused it, failing the run at a node the
+     * host had no way to fix.
+     */
+    maxLength?: number | null;
 };
 /**
  * The idempotency key for this execution of this node, or `null`.

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;
@@ -829,7 +881,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(
@@ -841,13 +893,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) {