@blokjs/api-call 0.6.20 → 0.6.21

package/dist/index.d.ts

@@ -37,15 +37,15 @@ declare const _default: import("@blokjs/runner").FunctionNode<z.ZodObject<{
     responseType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     url: string;
+    body: Record<string, unknown>;
     method: string;
     headers: Record<string, string>;
-    body: Record<string, unknown>;
     responseType: string;
 }, {
     url: string;
+    body?: Record<string, unknown> | undefined;
     method?: string | undefined;
     headers?: Record<string, string> | undefined;
-    body?: Record<string, unknown> | undefined;
     responseType?: string | undefined;
 }>, z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
 export default _default;

package/dist/test/util.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for runApiCall's HTTP-error handling — it must NOT discard the upstream
+ * status, body, or Retry-After header on a >=400 response.
+ */
+export {};

package/dist/test/util.test.js

@@ -0,0 +1,81 @@
+/**
+ * Tests for runApiCall's HTTP-error handling — it must NOT discard the upstream
+ * status, body, or Retry-After header on a >=400 response.
+ */
+import { GlobalError } from "@blokjs/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { runApiCall } from "../util";
+function mockFetchResponse(opts) {
+    const headers = new Headers(opts.headers ?? {});
+    return {
+        status: opts.status,
+        statusText: opts.statusText ?? "",
+        ok: opts.status < 400,
+        headers,
+        json: async () => opts.json,
+        text: async () => opts.body ?? "",
+    };
+}
+describe("runApiCall — HTTP error handling", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("throws a GlobalError carrying the upstream status code on >=400 (not a generic 500)", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => mockFetchResponse({
+            status: 429,
+            statusText: "Too Many Requests",
+            headers: { "content-type": "application/json", "retry-after": "30" },
+            json: { error: "rate_limited" },
+        })));
+        const err = await runApiCall("https://api.example.com/x", "GET", {}, {}, "json").catch((e) => e);
+        expect(err).toBeInstanceOf(GlobalError);
+        const ge = err;
+        expect(ge.context.code).toBe(429);
+        expect(ge.context.name).toBe("ApiCallError");
+        expect(ge.context.json).toMatchObject({
+            status: 429,
+            statusText: "Too Many Requests",
+            retryAfter: "30",
+            retryAfterSeconds: 30,
+            body: { error: "rate_limited" },
+        });
+    });
+    it("captures a text body and an HTTP-date Retry-After", async () => {
+        const future = new Date(Date.now() + 60_000).toUTCString();
+        vi.stubGlobal("fetch", vi.fn(async () => mockFetchResponse({
+            status: 503,
+            statusText: "Service Unavailable",
+            headers: { "content-type": "text/plain", "retry-after": future },
+            body: "down for maintenance",
+        })));
+        const err = (await runApiCall("https://api.example.com/y", "GET", {}, {}, "json").catch((e) => e));
+        expect(err.context.code).toBe(503);
+        const json = err.context.json;
+        expect(json.body).toBe("down for maintenance");
+        expect(typeof json.retryAfterSeconds).toBe("number");
+        expect(json.retryAfterSeconds).toBeGreaterThan(50);
+    });
+    it("omits retry fields when no Retry-After header is present", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => mockFetchResponse({
+            status: 404,
+            statusText: "Not Found",
+            headers: { "content-type": "application/json" },
+            json: { message: "missing" },
+        })));
+        const err = (await runApiCall("https://api.example.com/z", "GET", {}, {}, "json").catch((e) => e));
+        expect(err.context.code).toBe(404);
+        const json = err.context.json;
+        expect(json).not.toHaveProperty("retryAfter");
+        expect(json.body).toMatchObject({ message: "missing" });
+    });
+    it("returns the parsed JSON body on a 2xx response", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => mockFetchResponse({
+            status: 200,
+            headers: { "content-type": "application/json" },
+            json: { ok: true },
+        })));
+        const result = await runApiCall("https://api.example.com/ok", "GET", {}, {}, "json");
+        expect(result).toEqual({ ok: true });
+    });
+});
+//# sourceMappingURL=util.test.js.map

package/dist/test/util.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.test.js","sourceRoot":"","sources":["../../test/util.test.ts"],"names":[],"mappings":"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"}

package/dist/util.js

@@ -1,3 +1,19 @@
+import { GlobalError } from "@blokjs/shared";
+/**
+ * Parse a `Retry-After` header into seconds. The header is either a number of
+ * seconds (delta) or an HTTP-date; returns `undefined` when absent/unparseable.
+ */
+function parseRetryAfterSeconds(value) {
+    if (!value)
+        return undefined;
+    const asNumber = Number(value);
+    if (Number.isFinite(asNumber))
+        return Math.max(0, asNumber);
+    const asDate = Date.parse(value);
+    if (!Number.isNaN(asDate))
+        return Math.max(0, Math.round((asDate - Date.now()) / 1000));
+    return undefined;
+}
 export const runApiCall = async (url, method, headers, body, responseType) => {
     const options = {
         method,
@@ -10,7 +26,34 @@ export const runApiCall = async (url, method, headers, body, responseType) => {
         options.body = undefined;
     const response = await fetch(url, options);
     if (response.status >= 400 && response.ok === false) {
-        throw new Error(response.statusText);
+        // Don't discard the upstream signal. Capture the body and the rate-limit
+        // headers, and throw a GlobalError carrying the *upstream* status code so a
+        // 429/503 surfaces as a retryable 429/503 (not a generic 500) and callers
+        // (or a `tryCatch` arm) can honor `Retry-After` instead of hammering the
+        // provider. The framework preserves a thrown GlobalError's code verbatim.
+        const contentType = response.headers.get("content-type") ?? "";
+        let responseBody;
+        try {
+            responseBody = contentType.includes("application/json")
+                ? (await response.json())
+                : await response.text();
+        }
+        catch {
+            responseBody = undefined;
+        }
+        const retryAfterRaw = response.headers.get("retry-after");
+        const retryAfterSeconds = parseRetryAfterSeconds(retryAfterRaw);
+        const error = new GlobalError(`API call to ${url} failed: ${response.status} ${response.statusText || ""}`.trim());
+        error.setName("ApiCallError");
+        error.setCode(response.status);
+        error.setJson({
+            status: response.status,
+            statusText: response.statusText,
+            url,
+            ...(retryAfterRaw !== null ? { retryAfter: retryAfterRaw, retryAfterSeconds } : {}),
+            ...(responseBody !== undefined ? { body: responseBody } : {}),
+        });
+        throw error;
     }
     let parsedResponse;
     if (response.headers.get("content-type")?.includes("application/json")) {

package/dist/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../util.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC9B,GAAW,EACX,MAAc,EACd,OAAuB,EACvB,IAAoB,EACpB,YAAoB,EACe,EAAE;IACrC,MAAM,OAAO,GAMT;QACH,MAAM;QACN,OAAO;QACP,QAAQ,EAAE,QAAQ;QAClB,YAAY;QACZ,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC5D,CAAC;IAEF,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC;IAC/C,MAAM,QAAQ,GAAa,MAAM,KAAK,CAAC,GAAG,EAAE,OAAsB,CAAC,CAAC;IAEpE,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,cAAuC,CAAC;IAC5C,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACxE,cAAc,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;SAAM,CAAC;QACP,cAAc,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,OAAO,cAAc,CAAC;AACvB,CAAC,CAAC"}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/api-call",
-	"version": "0.6.20",
+	"version": "0.6.21",
 	"files": ["dist"],
 	"description": "Node module for making API calls",
 	"type": "module",
@@ -26,8 +26,8 @@
 		"vitest": "^4.0.18"
 	},
 	"dependencies": {
-		"@blokjs/runner": "^0.6.20",
-		"@blokjs/shared": "^0.6.20",
+		"@blokjs/runner": "^0.6.21",
+		"@blokjs/shared": "^0.6.21",
 		"lodash": "^4.17.21",
 		"zod": "^3.24.2"
 	},