@godxjp/sdk 0.2.0 → 0.4.0

package/README.md

@@ -83,6 +83,78 @@ Authentication is the session cookie, so a write sends the `XSRF-TOKEN` cookie b
 
 A cancellation stays an `AbortError` and is never converted to an `ApiError` — TanStack Query tells a cancelled query from a failed one by exactly that.
 
+### Other ways to authenticate
+
+Every option below is optional; left out, the client behaves exactly as described above.
+
+```ts
+export const apiClient = createClient({
+  baseUrl: "https://api.example.com/v1",
+  // Read before every request — and again before a retry — so a token
+  // refreshed a moment ago is the one that goes out. Wins over the defaults.
+  headers: async () => ({ Authorization: `Bearer ${await tokens.access()}` }),
+  // `fetch` credentials mode, `same-origin` by default. `include` also sets
+  // `withCredentials` on an upload that goes out over XHR.
+  credentials: "include",
+  // On a 401, before `signInUrl`: resolve `true` and the request is sent once
+  // more; resolve `false` and the 401 takes its usual course. Never more than
+  // one retry per request, and 401s that arrive together share one call.
+  // `ctx` is the request that was answered 401 — method, URL and the headers
+  // it was sent with — so a login that failed is not mistaken for an expired
+  // token.
+  onUnauthorized: ({ headers }) =>
+    headers.Authorization === undefined
+      ? Promise.resolve(false)
+      : tokens.refresh(),
+  // A request that never reached the server: `ApiError` with status 0 by
+  // default ("wrap"); "throw" rethrows fetch's own `TypeError`.
+  networkErrors: "throw",
+});
+```
+
+A request body is always JSON text or `FormData`, never a stream, so it can be sent a second time. A request cancelled while the token was refreshed stays an `AbortError`, whatever `networkErrors` says.
+
+### Downloading a file
+
+```ts
+const { blob, headers, status } = await apiClient.download("/exports", {
+  method: "POST", // "GET" unless given
+  body: { ids: [1, 2] },
+  query: { format: "csv" },
+});
+const disposition = headers.get("Content-Disposition");
+```
+
+Same headers, XSRF header, retry and errors as every other method: a 4xx, a 419 or an unreachable server is still an `ApiError`.
+
+### Error messages
+
+`ApiError.message` is the server's `message` when it sent a non-empty one. Otherwise it comes from `messages`, or is empty — the client has no language of its own, and never uses `statusText`, which HTTP/2 does not send.
+
+```ts
+createClient({
+  baseUrl: "/api",
+  messages: (status) => (status === 419 ? t("session.expired") : undefined),
+});
+```
+
+Everything else the server sent is on `ApiError.body` — the parsed JSON, or `undefined` when there was none, it was not JSON, or the server was never reached. Read an `error` code, a `message` that is not a string, or every message per field from there:
+
+```ts
+if (error instanceof ApiError) {
+  const { error: code, errors } = (error.body ?? {}) as {
+    error?: string;
+    errors?: Record<string, string[]>;
+  };
+}
+```
+
+An unreachable server (`status: 0`) keeps its built-in text, `Could not reach the server. Check your connection and try again.`, unless `messages(0)` answers one.
+
+**Changed in 0.3.0.** Before, a 419 always carried `Your session has expired. Reload the page and try again.` and a response without a message fell back to `statusText`. Both are now the server's message or empty. To keep the old 419 text, pass `messages: (status) => status === 419 ? "Your session has expired. Reload the page and try again." : undefined`.
+
+**Changed in 0.4.0.** Additions only; a client configured for 0.3.0 sends and throws exactly what it did. `ApiError` gains `body` (also on a `download()` failure). `onUnauthorized` now receives the request that was answered 401 (`{ method, url, headers }`); a function that takes no argument still works. `networkErrors: "throw"` rethrows `fetch`'s own error instead of `ApiError(0)` — including a response body that breaks off mid-way.
+
 ## `./realtime`
 
 ```ts

package/dist/laravel/index.d.ts

@@ -13,7 +13,14 @@ declare class ApiError extends Error {
     readonly status: number;
     /** Laravel's `{errors: {field: string[]}}`, first message per key; `{}` when absent. */
     readonly errors: Record<string, string>;
-    constructor(status: number, message: string, errors?: Record<string, string>);
+    /**
+     * The error response's body, parsed as JSON — everything `message` and
+     * `errors` leave out: an `error` code, a `message` that is not a string,
+     * every message per field. `undefined` when there was no body, it was not
+     * JSON, or the server was never reached.
+     */
+    readonly body: unknown;
+    constructor(status: number, message: string, errors?: Record<string, string>, body?: unknown);
 }
 
 /**
@@ -45,6 +52,26 @@ type WriteOptions = RequestOptions & {
      */
     onUploadProgress?: (percent: number) => void;
 };
+type DownloadOptions = RequestOptions & {
+    /** `GET` unless given. A `POST` carries the XSRF header like any write. */
+    method?: "GET" | "POST";
+    body?: Body;
+    query?: ApiQuery;
+};
+/** A binary response, with the headers a screen reads the file name from. */
+type DownloadResult = {
+    blob: Blob;
+    headers: Headers;
+    status: number;
+};
+/** The request a 401 answered, as `onUnauthorized` receives it. */
+type UnauthorizedContext = {
+    method: string;
+    /** The full URL, `baseUrl` and query string included. */
+    url: string;
+    /** Exactly the headers the request was sent with. */
+    headers: Record<string, string>;
+};
 type ClientConfig = {
     /** Prefixed to every path, e.g. `/api/app/v1`. */
     baseUrl: string;
@@ -53,6 +80,44 @@ type ClientConfig = {
      * Omitted for a public API whose visitor has nowhere to sign in.
      */
     signInUrl?: (returnTo: string) => string;
+    /**
+     * Extra headers, read again before EVERY request (and before a retry), so a
+     * bearer token refreshed a moment ago is the one that goes out. Applied
+     * after the defaults, so a header named here wins.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * `fetch` credentials mode; `same-origin` unless given. `include` is what a
+     * cross-origin API behind a cookie needs, and also turns on
+     * `withCredentials` for an upload that goes out over XHR.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Called on a 401 before `signInUrl`. Resolve `true` (a token was refreshed,
+     * say) and the request is sent once more, headers read afresh; resolve
+     * `false` and the 401 takes its usual course. A request is retried at most
+     * once, and 401s that arrive together share one call — made with the
+     * context of the request that started it.
+     *
+     * `ctx` describes the request that was answered 401, with the headers it
+     * was actually sent with — so a host can refresh only when that request
+     * carried a token.
+     */
+    onUnauthorized?: (ctx: UnauthorizedContext) => Promise<boolean>;
+    /**
+     * What a request that never reached the server throws. `wrap` (the
+     * default) turns it into `ApiError` with status `0`; `throw` rethrows what
+     * `fetch` threw (a `TypeError`), for a host that tells a network failure
+     * from an HTTP one by exactly that. A cancelled request is an `AbortError`
+     * either way.
+     */
+    networkErrors?: "wrap" | "throw";
+    /**
+     * The message for an `ApiError` whose response carried none — the client
+     * has no language of its own. Unset, or answering `undefined`, leaves
+     * `message` empty; status `0` then keeps its built-in text.
+     */
+    messages?: (status: number) => string | undefined;
 };
 type ApiClient = {
     get: <T>(path: string, options?: GetOptions) => Promise<T>;
@@ -60,8 +125,17 @@ type ApiClient = {
     put: <T>(path: string, body?: Body, options?: WriteOptions) => Promise<T>;
     patch: <T>(path: string, body?: Body, options?: WriteOptions) => Promise<T>;
     delete: <T>(path: string, options?: GetOptions) => Promise<T>;
+    /**
+     * The response as a `Blob` plus its headers, through the same error
+     * handling as every other method: a failure is still an `ApiError`.
+     */
+    download: (path: string, options?: DownloadOptions) => Promise<DownloadResult>;
 };
-/** `FormData` goes out as multipart untouched; anything else is JSON-encoded. */
+/**
+ * `FormData` goes out as multipart untouched; anything else is JSON-encoded.
+ * Either way the payload can be sent twice, which is what makes the retry
+ * after `onUnauthorized` safe — a stream body is never produced.
+ */
 type Body = FormData | object;
 /** Laravel reads `key[]=a&key[]=b` as an array and '1'/'0' as booleans. */
 declare function queryString(query: ApiQuery | undefined): string;
@@ -69,4 +143,4 @@ declare function queryString(query: ApiQuery | undefined): string;
 declare function flattenErrors(errors: unknown): Record<string, string>;
 declare function createClient(config: ClientConfig): ApiClient;
 
-export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type GetOptions, type WriteOptions, createClient, flattenErrors, queryString };
+export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type DownloadOptions, type DownloadResult, type GetOptions, type UnauthorizedContext, type WriteOptions, createClient, flattenErrors, queryString };

package/dist/laravel/index.js

@@ -3,16 +3,23 @@ var ApiError = class extends Error {
   status;
   /** Laravel's `{errors: {field: string[]}}`, first message per key; `{}` when absent. */
   errors;
-  constructor(status, message, errors = {}) {
+  /**
+   * The error response's body, parsed as JSON — everything `message` and
+   * `errors` leave out: an `error` code, a `message` that is not a string,
+   * every message per field. `undefined` when there was no body, it was not
+   * JSON, or the server was never reached.
+   */
+  body;
+  constructor(status, message, errors = {}, body) {
     super(message);
     this.name = "ApiError";
     this.status = status;
     this.errors = errors;
+    this.body = body;
   }
 };
 
 // src/laravel/api-client.ts
-var SESSION_EXPIRED = "Your session has expired. Reload the page and try again.";
 var UNREACHABLE = "Could not reach the server. Check your connection and try again.";
 var redirectingToSignIn = false;
 function readCookie(name) {
@@ -75,18 +82,13 @@ function redirectToSignIn(signInUrl) {
 }
 function send(url, init, onUploadProgress) {
   if (onUploadProgress === void 0) {
-    return fetch(url, { ...init, credentials: "same-origin" }).then(
-      async (response) => ({
-        status: response.status,
-        statusText: response.statusText,
-        text: await response.text()
-      })
-    );
+    return fetch(url, init);
   }
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     const abort = () => xhr.abort();
     xhr.open(init.method, url);
+    xhr.withCredentials = init.credentials === "include";
     for (const [name, value] of Object.entries(init.headers)) {
       xhr.setRequestHeader(name, value);
     }
@@ -97,11 +99,16 @@ function send(url, init, onUploadProgress) {
     };
     xhr.onload = () => {
       init.signal?.removeEventListener("abort", abort);
-      resolve({
-        status: xhr.status,
-        statusText: xhr.statusText,
-        text: xhr.responseText
-      });
+      const empty = xhr.responseText === "" || [204, 205, 304].includes(xhr.status);
+      try {
+        resolve(
+          new Response(empty ? null : xhr.responseText, {
+            status: xhr.status
+          })
+        );
+      } catch (error) {
+        reject(error);
+      }
     };
     xhr.onerror = () => reject(new TypeError("Network request failed"));
     xhr.onabort = () => reject(new DOMException("The request was aborted.", "AbortError"));
@@ -113,7 +120,23 @@ function send(url, init, onUploadProgress) {
     xhr.send(init.body ?? null);
   });
 }
-async function request(config, method, path, body, { signal, query, onUploadProgress }) {
+function unreachable(config, error) {
+  if (config.networkErrors === "throw") {
+    return error;
+  }
+  return new ApiError(0, config.messages?.(0) ?? UNREACHABLE);
+}
+async function read(response, as, config, signal) {
+  try {
+    return await response[as]();
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    throw unreachable(config, error);
+  }
+}
+async function exchange({ config, unauthorized }, method, path, body, { signal, query, onUploadProgress }, retried = false) {
   const headers = {
     Accept: "application/json",
     "X-Requested-With": "XMLHttpRequest"
@@ -129,51 +152,95 @@ async function request(config, method, path, body, { signal, query, onUploadProg
     headers["Content-Type"] = "application/json";
     payload = JSON.stringify(body);
   }
+  Object.assign(headers, await config.headers?.());
+  const url = `${config.baseUrl}${path}${queryString(query)}`;
   let response;
   try {
     response = await send(
-      `${config.baseUrl}${path}${queryString(query)}`,
-      { method, headers, body: payload, signal },
+      url,
+      {
+        method,
+        headers,
+        body: payload,
+        signal,
+        credentials: config.credentials ?? "same-origin"
+      },
       onUploadProgress
     );
   } catch (error) {
     if (signal?.aborted) {
       throw error;
     }
-    throw new ApiError(0, UNREACHABLE);
+    throw unreachable(config, error);
   }
-  if (response.status === 204) {
-    return void 0;
+  if (response.status >= 200 && response.status < 300) {
+    return response;
   }
+  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized({ method, url, headers: { ...headers } })) {
+    return exchange(
+      { config, unauthorized },
+      method,
+      path,
+      body,
+      { signal, query, onUploadProgress },
+      true
+    );
+  }
+  const text = await read(response, "text", config, signal);
   let json = void 0;
   try {
-    json = response.text === "" ? void 0 : JSON.parse(response.text);
+    json = text === "" ? void 0 : JSON.parse(text);
   } catch {
   }
-  if (response.status >= 200 && response.status < 300) {
-    return json;
-  }
   const bag = json ?? {};
   if (response.status === 401 && config.signInUrl !== void 0) {
     redirectToSignIn(config.signInUrl);
   }
-  if (response.status === 419) {
-    throw new ApiError(419, SESSION_EXPIRED);
-  }
   throw new ApiError(
     response.status,
-    typeof bag.message === "string" && bag.message !== "" ? bag.message : response.statusText,
-    flattenErrors(bag.errors)
+    typeof bag.message === "string" && bag.message !== "" ? bag.message : config.messages?.(response.status) ?? "",
+    flattenErrors(bag.errors),
+    json
   );
 }
+async function request(client, method, path, body, options) {
+  const response = await exchange(client, method, path, body, options);
+  if (response.status === 204) {
+    return void 0;
+  }
+  const text = await read(response, "text", client.config, options.signal);
+  try {
+    return text === "" ? void 0 : JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
 function createClient(config) {
+  let refreshing;
+  const client = {
+    config,
+    unauthorized: (ctx) => refreshing ??= (config.onUnauthorized?.(ctx) ?? Promise.resolve(false)).finally(() => {
+      refreshing = void 0;
+    })
+  };
   return {
-    get: (path, options = {}) => request(config, "GET", path, void 0, options),
-    post: (path, body, options = {}) => request(config, "POST", path, body, options),
-    put: (path, body, options = {}) => request(config, "PUT", path, body, options),
-    patch: (path, body, options = {}) => request(config, "PATCH", path, body, options),
+    get: (path, options = {}) => request(client, "GET", path, void 0, options),
+    post: (path, body, options = {}) => request(client, "POST", path, body, options),
+    put: (path, body, options = {}) => request(client, "PUT", path, body, options),
+    patch: (path, body, options = {}) => request(client, "PATCH", path, body, options),
     /** `query` for what identifies the targets (`?ids[]=1&ids[]=2`). */
-    delete: (path, options = {}) => request(config, "DELETE", path, void 0, options)
+    delete: (path, options = {}) => request(client, "DELETE", path, void 0, options),
+    download: async (path, { method = "GET", body, query, signal } = {}) => {
+      const response = await exchange(client, method, path, body, {
+        query,
+        signal
+      });
+      return {
+        blob: await read(response, "blob", config, signal),
+        headers: response.headers,
+        status: response.status
+      };
+    }
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@godxjp/sdk",
-    "version": "0.2.0",
+    "version": "0.4.0",
     "description": "GoDX JavaScript SDK \u2014 shared frontend infrastructure for GoDX products.",
     "license": "Apache-2.0",
     "type": "module",