@godxjp/sdk 0.3.0 → 0.4.0

package/README.md

@@ -99,11 +99,20 @@ export const apiClient = createClient({
   // 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.
-  onUnauthorized: () => tokens.refresh(),
+  // `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`.
+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
 
@@ -129,10 +138,23 @@ createClient({
 });
 ```
 
+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);
 }
 
 /**
@@ -57,6 +64,14 @@ type DownloadResult = {
     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;
@@ -81,9 +96,22 @@ type ClientConfig = {
      * 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.
+     * 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.
      */
-    onUnauthorized?: () => Promise<boolean>;
+    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
@@ -115,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 DownloadOptions, type DownloadResult, 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,11 +3,19 @@ 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;
   }
 };
 
@@ -112,7 +120,10 @@ function send(url, init, onUploadProgress) {
     xhr.send(init.body ?? null);
   });
 }
-function unreachable(config) {
+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) {
@@ -122,7 +133,7 @@ async function read(response, as, config, signal) {
     if (signal?.aborted) {
       throw error;
     }
-    throw unreachable(config);
+    throw unreachable(config, error);
   }
 }
 async function exchange({ config, unauthorized }, method, path, body, { signal, query, onUploadProgress }, retried = false) {
@@ -142,10 +153,11 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
     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)}`,
+      url,
       {
         method,
         headers,
@@ -159,12 +171,12 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
     if (signal?.aborted) {
       throw error;
     }
-    throw unreachable(config);
+    throw unreachable(config, error);
   }
   if (response.status >= 200 && response.status < 300) {
     return response;
   }
-  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized()) {
+  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized({ method, url, headers: { ...headers } })) {
     return exchange(
       { config, unauthorized },
       method,
@@ -187,7 +199,8 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
   throw new ApiError(
     response.status,
     typeof bag.message === "string" && bag.message !== "" ? bag.message : config.messages?.(response.status) ?? "",
-    flattenErrors(bag.errors)
+    flattenErrors(bag.errors),
+    json
   );
 }
 async function request(client, method, path, body, options) {
@@ -206,7 +219,7 @@ function createClient(config) {
   let refreshing;
   const client = {
     config,
-    unauthorized: () => refreshing ??= (config.onUnauthorized?.() ?? Promise.resolve(false)).finally(() => {
+    unauthorized: (ctx) => refreshing ??= (config.onUnauthorized?.(ctx) ?? Promise.resolve(false)).finally(() => {
       refreshing = void 0;
     })
   };

package/package.json

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