@north-light/api 0.3.436 → 0.3.438

package/dist/core/io.d.ts

@@ -57,6 +57,8 @@ interface ErrorPayloadBase {
      *  of `received` on purpose: `received` names the caller's offending VALUE, and
      *  reporting an HTTP status there is a false claim about what was sent. */
     http_status?: number;
+    /** Seconds the provider asked the caller to wait before retrying (a rate limit). */
+    retry_after_s?: number;
     next: string;
 }
 export type ErrorPayload = ErrorPayloadBase & ({
@@ -109,7 +111,12 @@ export declare function diag(message: string): void;
  *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
  *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
  *      it before the re-plumb, preserving its SPECIFIC code + next.
- *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   3. A provider-origin refusal (`err.origin === 'provider'`) carries the
+ *      provider's own error in `details` (`{code,message,field?,next?,received?}`)
+ *      under the daemon's coarse `provider_*` code and the provider's HTTP
+ *      status. The provider's code, `next`, `field` and `Retry-After` reach the
+ *      caller unchanged; the status→code map would flatten them to `conflict`.
+ *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
 export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
 /** Terminal error handler. Command-level failures (bad input, not-found,

package/dist/core/io.js

@@ -209,6 +209,7 @@ function payloadOf(e) {
         received: d.received,
         field: d.field,
         ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
+        ...(typeof d.retry_after_s === 'number' ? { retry_after_s: d.retry_after_s } : {}),
     };
     return result === undefined
         ? { ...base, next }
@@ -274,7 +275,12 @@ const STATUS_TO_CLI_CODE = {
  *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
  *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
  *      it before the re-plumb, preserving its SPECIFIC code + next.
- *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   3. A provider-origin refusal (`err.origin === 'provider'`) carries the
+ *      provider's own error in `details` (`{code,message,field?,next?,received?}`)
+ *      under the daemon's coarse `provider_*` code and the provider's HTTP
+ *      status. The provider's code, `next`, `field` and `Retry-After` reach the
+ *      caller unchanged; the status→code map would flatten them to `conflict`.
+ *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
 export function apiErrorToCliError(err, next) {
     // A handover is NOT a down daemon: the successor is already up (the client
@@ -297,12 +303,23 @@ export function apiErrorToCliError(err, next) {
     }
     // A responding daemon can relay an unavailable provider or storage service.
     // HTTP 503 alone does not mean that crtrd is down.
+    const d = err.details;
+    const provider = providerSupplied(err, d);
     if (err.status === 503) {
-        return new CrtrError(err.code, err.message, ExitCode.NETWORK, {
-            next: next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
-        });
+        const code = provider.code ?? err.code;
+        const details = {
+            next: provider.next ?? next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
+        };
+        if (provider.code !== undefined) {
+            if (provider.field !== undefined)
+                details['field'] = provider.field;
+            if (provider.received !== undefined)
+                details['received'] = provider.received;
+            if (provider.retryAfterS !== undefined)
+                details['retry_after_s'] = provider.retryAfterS;
+        }
+        return new CrtrError(code, err.message, ExitCode.NETWORK, details);
     }
-    const d = err.details;
     // A `/v1` request validator reports each bad field in `details.violations`;
     // the message alone only says the request was invalid.
     const violations = Array.isArray(d?.violations)
@@ -312,14 +329,20 @@ export function apiErrorToCliError(err, next) {
     const payload = d && typeof d.error === 'string' && typeof d.message === 'string' && typeof d.next === 'string'
         ? d
         : {
-            error: STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            error: provider.code ?? STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            ...(provider.field !== undefined ? { field: provider.field } : {}),
+            ...(provider.received !== undefined ? { received: provider.received } : {}),
+            ...(provider.retryAfterS !== undefined ? { retry_after_s: provider.retryAfterS } : {}),
             message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message.trim() !== '' ? err.message : `request refused (HTTP ${err.status}, ${err.code}) with no message`,
-            next: next ??
-                (err.status >= 500
-                    ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
-                    : err.status === 404
-                        ? 'List nodes with `crtr node inspect list`.'
-                        : 'Inspect the error and adjust the call. See -h for the schema.'),
+            next: provider.next ??
+                next ??
+                (provider.retryAfterS !== undefined
+                    ? `Wait ${provider.retryAfterS}s, then retry; do not retry sooner.`
+                    : err.status >= 500
+                        ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
+                        : err.status === 404
+                            ? 'List nodes with `crtr node inspect list`.'
+                            : 'Inspect the error and adjust the call. See -h for the schema.'),
         };
     // Preserve the exit-code class the server leaf carried instead of collapsing
     // every non-503 to USAGE(2): a not-found (404 / `not_found`) surfaces exit 3
@@ -327,6 +350,33 @@ export function apiErrorToCliError(err, next) {
     // (memory/pkg/sys) still emit so the taxonomy stays uniform across the CLI.
     return new InputError(payload, exitForCliCode(payload.error, err.status));
 }
+/** What a provider put in its own error body, as the daemon relays it: the
+ *  provider's code (`details.code`; the envelope `code` is only the daemon's
+ *  coarse `provider_*` bucket), plus `next`, `field`, `received`, and the
+ *  `Retry-After` the daemon lifts into the envelope. Empty for any error that
+ *  did not originate at a provider, so non-provider status→code mapping is
+ *  untouched. A code that is not a snake_case identifier, or that came with no
+ *  provider HTTP status, is ignored. */
+function providerSupplied(err, d) {
+    if (err.origin !== 'provider' || d === undefined || d === null || typeof d !== 'object')
+        return {};
+    const out = {};
+    // `details.status` is the provider's own HTTP status; the runtime's transport
+    // diagnostics (`{status: null, code: 'timeout'}`) are not a provider's code.
+    if (typeof d.status === 'number' && typeof d.code === 'string' && /^[a-z][a-z0-9_]*$/.test(d.code))
+        out.code = d.code;
+    if (typeof d.next === 'string' && d.next.trim() !== '')
+        out.next = d.next;
+    if (typeof d.field === 'string' && d.field !== '')
+        out.field = d.field;
+    else if (err.param !== undefined)
+        out.field = err.param;
+    if (d.received !== undefined && d.received !== null)
+        out.received = d.received;
+    if (typeof err.retryAfterS === 'number')
+        out.retryAfterS = err.retryAfterS;
+    return out;
+}
 /** The `ExitCode` class a reconstructed API error should carry, keyed off the
  *  round-tripped CLI code (and the 404 status as the not-found signal — the
  *  server maps NOT_FOUND's exit class to status 404, but folds AMBIGUOUS and

package/dist/core/render.js

@@ -129,6 +129,8 @@ export function renderError(p) {
     // the value the caller supplied.
     if (p.http_status !== undefined)
         lines.push(`http status: ${p.http_status}`);
+    if (p.retry_after_s !== undefined)
+        lines.push(`retry after: ${p.retry_after_s}s`);
     if ('primaryCompleted' in p && p.primaryCompleted === true) {
         lines.push('primaryCompleted: true');
         lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.436",
+  "version": "0.3.438",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",