Fix v3 import reliability and add group roles and cover images

.vcr/registry-test.json

@@ -223,7 +223,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/blocks",
-      "requestBody": "{\"value\":\"Integration test content\",\"channel_ids\":[4484793]}",
+      "requestBody": "{\"value\":\"Integration test content\",\"channels\":[{\"id\":4484793}]}",
       "status": 201,
       "statusText": "Created",
       "headers": {
@@ -730,7 +730,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/connections",
-      "requestBody": "{\"connectable_id\":41232438,\"channel_ids\":[\"cli-connect-target-_icsu6cvkta\"],\"connectable_type\":\"Block\"}",
+      "requestBody": "{\"connectable_id\":41232438,\"connectable_type\":\"Block\",\"channels\":[{\"id\":\"cli-connect-target-_icsu6cvkta\"}]}",
       "status": 201,
       "statusText": "Created",
       "headers": {
@@ -1296,7 +1296,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/blocks",
-      "requestBody": "{\"value\":\"Block one\",\"channel_ids\":[4484795]}",
+      "requestBody": "{\"value\":\"Block one\",\"channels\":[{\"id\":4484795}]}",
       "status": 201,
       "statusText": "Created",
       "headers": {
@@ -1369,7 +1369,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/blocks",
-      "requestBody": "{\"value\":\"Block two\",\"channel_ids\":[4484795]}",
+      "requestBody": "{\"value\":\"Block two\",\"channels\":[{\"id\":4484795}]}",
       "status": 201,
       "statusText": "Created",
       "headers": {
@@ -1798,7 +1798,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/blocks",
-      "requestBody": "{\"value\":\"Content with metadata\",\"channel_ids\":[4484796],\"title\":\"My Title\",\"description\":\"My Desc\"}",
+      "requestBody": "{\"value\":\"Content with metadata\",\"channels\":[{\"id\":4484796}],\"title\":\"My Title\",\"description\":\"My Desc\"}",
       "status": 201,
       "statusText": "Created",
       "headers": {
@@ -1871,7 +1871,7 @@
     {
       "method": "POST",
       "url": "https://staging-api.are.na/v3/blocks",
-      "requestBody": "{\"value\":\"https://example.com\",\"channel_ids\":[4484796]}",
+      "requestBody": "{\"value\":\"https://example.com\",\"channels\":[{\"id\":4484796}]}",
       "status": 201,
       "statusText": "Created",
       "headers": {

package.json

@@ -25,7 +25,7 @@
     "generate": "openapi-typescript https://api.are.na/v3/openapi -o src/api/schema.d.ts",
     "typecheck": "tsc --noEmit",
     "lint": "npm run typecheck",
-    "test": "tsx --test src/**/*.test.ts",
+    "test": "node --import tsx --test src/*.test.ts src/*/*.test.ts",
     "check": "npm run lint && npm run test && npm run build",
     "format": "prettier --write .",
     "format:check": "prettier --check .",

src/api/client.test.ts

@@ -0,0 +1,106 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { ArenaError, client } from "./client";
+import { formatJsonError } from "../lib/exit-codes";
+
+// Exercise the middleware with real Response objects and no network or cassette.
+process.env.ARENA_VCR_MODE = "off";
+
+for (const { body, status, message } of [
+  {
+    body: {
+      error: "Bad Request",
+      details: { message: "No more than 50 blocks permitted" },
+    },
+    status: 400,
+    message: "No more than 50 blocks permitted",
+  },
+  {
+    body: {
+      error: "Unprocessable Entity",
+      details: { errors: ["Title is required", "Value is invalid"] },
+    },
+    status: 422,
+    message: "Title is required; Value is invalid",
+  },
+  {
+    body: {
+      details: { errors: { title: ["is required"], value: "is invalid" } },
+    },
+    status: 422,
+    message: "title: is required; value: is invalid",
+  },
+  {
+    body: { error: { message: "Write budget exhausted" } },
+    status: 429,
+    message: "Write budget exhausted",
+  },
+  { body: { error: "Forbidden" }, status: 403, message: "Forbidden" },
+]) {
+  test(`API errors retain details: ${message}`, async (t) => {
+    t.mock.method(globalThis, "fetch", async () =>
+      Response.json(body, { status }),
+    );
+    await assert.rejects(client.GET("/v3/ping"), (error: unknown) => {
+      assert.ok(error instanceof ArenaError);
+      assert.equal(error.status, status);
+      assert.equal(error.message, message);
+      assert.equal(formatJsonError(error).error, message);
+      return true;
+    });
+  });
+}
+
+for (const { headers, retryAfter, expectedDelay, expectedReset } of [
+  {
+    headers: { "Retry-After": "60", "X-RateLimit-Reset": "1700000060" },
+    retryAfter: 5,
+    expectedDelay: 60_000,
+    expectedReset: 1700000060000,
+  },
+  {
+    headers: { "Retry-After": "Tue, 14 Nov 2023 22:14:20 GMT" },
+    retryAfter: 5,
+    expectedDelay: 60_000,
+  },
+  { headers: {}, retryAfter: 30, expectedDelay: 30_000 },
+  {
+    headers: { "X-RateLimit-Reset": "1700000060" },
+    expectedReset: 1700000060000,
+  },
+  { headers: { "Retry-After": "invalid" }, retryAfter: -1 },
+]) {
+  test(`rate-limit timing: ${JSON.stringify({ headers, retryAfter })}`, async (t) => {
+    t.mock.method(Date, "now", () => 1700000000000);
+    t.mock.method(globalThis, "fetch", async () =>
+      Response.json(
+        { error: { message: "Rate limited", retry_after: retryAfter } },
+        {
+          status: 429,
+          headers: { ...headers, "X-RateLimit-Bucket": "write-hour" },
+        },
+      ),
+    );
+    await assert.rejects(client.GET("/v3/ping"), (error: unknown) => {
+      assert.ok(error instanceof ArenaError);
+      assert.equal(error.rateLimit?.retryAfterMs, expectedDelay);
+      assert.equal(error.rateLimit?.resetAtMs, expectedReset);
+      assert.equal(error.rateLimit?.bucket, "write-hour");
+      assert.equal(formatJsonError(error).retry_after_ms, expectedDelay);
+      return true;
+    });
+  });
+}
+
+test("non-JSON errors retain the HTTP fallback", async (t) => {
+  t.mock.method(
+    globalThis,
+    "fetch",
+    async () =>
+      new Response("unavailable", {
+        status: 502,
+        statusText: "Bad Gateway",
+      }),
+  );
+  await assert.rejects(client.GET("/v3/ping"), /Bad Gateway/);
+});

src/api/client.ts

@@ -10,10 +10,29 @@ loadEnv();
 
 export class ArenaError extends Error {
   status: number;
-  constructor(message: string, status: number) {
+  rateLimit?: {
+    retryAfterMs?: number;
+    resetAtMs?: number;
+    limit?: string;
+    remaining?: string;
+    tier?: string;
+    window?: string;
+    bucket?: string;
+    cost?: string;
+    policy?: string;
+  };
+
+  constructor(
+    message: string,
+    status: number,
+    options: {
+      rateLimit?: ArenaError["rateLimit"];
+    } = {},
+  ) {
     super(message);
     this.name = "ArenaError";
     this.status = status;
+    this.rateLimit = options.rateLimit;
   }
 }
 
@@ -22,20 +41,120 @@ export async function getData<T>(request: Promise<{ data?: T }>): Promise<T> {
   return response.data!;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatValidationErrors(errors: unknown): string | undefined {
+  if (Array.isArray(errors)) {
+    const messages = errors
+      .map((error) => {
+        if (typeof error === "string") return error;
+        if (isRecord(error) && typeof error["message"] === "string") {
+          return error["message"];
+        }
+        return undefined;
+      })
+      .filter((message): message is string => Boolean(message));
+    return messages.length > 0 ? messages.join("; ") : undefined;
+  }
+
+  if (!isRecord(errors)) return undefined;
+
+  const messages = Object.entries(errors)
+    .map(([key, value]) => {
+      if (typeof value === "string") return `${key}: ${value}`;
+      if (Array.isArray(value)) return `${key}: ${value.join(", ")}`;
+      if (isRecord(value) && typeof value["message"] === "string") {
+        return `${key}: ${value["message"]}`;
+      }
+      return undefined;
+    })
+    .filter((message): message is string => Boolean(message));
+
+  return messages.length > 0 ? messages.join("; ") : undefined;
+}
+
 function toArenaMessage(body: unknown, fallback: string): string {
-  if (typeof body !== "object" || body === null) {
-    return fallback;
+  if (!isRecord(body)) return fallback;
+
+  const messages: string[] = [];
+  const details = body["details"];
+  if (isRecord(details)) {
+    if (typeof details["message"] === "string") {
+      messages.push(details["message"]);
+    }
+    const validation = formatValidationErrors(details["errors"]);
+    if (validation) messages.push(validation);
+  }
+
+  const error = body["error"];
+  if (isRecord(error) && typeof error["message"] === "string") {
+    messages.push(error["message"]);
   }
-  const errorBody = body as {
-    error?: unknown;
-    details?: {
-      message?: unknown;
-    };
+
+  if (typeof body["message"] === "string") {
+    messages.push(body["message"]);
+  }
+
+  const unique = [...new Set(messages.filter(Boolean))];
+  if (unique.length > 0) return unique.join("; ");
+  return typeof error === "string" && error ? error : fallback;
+}
+
+function retryAfterHeaderMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+
+  const timestamp = Date.parse(value);
+  if (!Number.isNaN(timestamp)) return Math.max(0, timestamp - Date.now());
+  return undefined;
+}
+
+function unixTimestampHeaderMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) return undefined;
+  return seconds * 1000;
+}
+
+function numericBodyRetryAfterMs(body: unknown): number | undefined {
+  if (!isRecord(body) || !isRecord(body["error"])) return undefined;
+  const retryAfter = body["error"]["retry_after"];
+  if (
+    typeof retryAfter !== "number" ||
+    !Number.isFinite(retryAfter) ||
+    retryAfter < 0
+  )
+    return undefined;
+  return retryAfter * 1000;
+}
+
+function rateLimitFromResponse(
+  response: Response,
+  body: unknown,
+): ArenaError["rateLimit"] {
+  if (response.status !== 429) return undefined;
+
+  const retryAfterMs =
+    retryAfterHeaderMs(response.headers.get("Retry-After")) ??
+    numericBodyRetryAfterMs(body);
+  const resetAtMs = unixTimestampHeaderMs(
+    response.headers.get("X-RateLimit-Reset"),
+  );
+
+  return {
+    retryAfterMs,
+    resetAtMs,
+    limit: response.headers.get("X-RateLimit-Limit") ?? undefined,
+    remaining: response.headers.get("X-RateLimit-Remaining") ?? undefined,
+    tier: response.headers.get("X-RateLimit-Tier") ?? undefined,
+    window: response.headers.get("X-RateLimit-Window") ?? undefined,
+    bucket: response.headers.get("X-RateLimit-Bucket") ?? undefined,
+    cost: response.headers.get("X-RateLimit-Cost") ?? undefined,
+    policy: response.headers.get("X-RateLimit-Policy") ?? undefined,
   };
-  if (typeof errorBody.error === "string") return errorBody.error;
-  if (typeof errorBody.details?.message === "string")
-    return errorBody.details.message;
-  return fallback;
 }
 
 const baseUrlMiddleware: Middleware = {
@@ -75,9 +194,13 @@ const errorMiddleware: Middleware = {
         .clone()
         .json()
         .catch(() => null);
+      const rateLimit = rateLimitFromResponse(response, body);
       throw new ArenaError(
         toArenaMessage(body, response.statusText),
         response.status,
+        {
+          rateLimit,
+        },
       );
     }
     return response;