@podosoft/podokit-api-client 0.8.4 → 0.9.0

package/README.md

@@ -6,8 +6,9 @@ through this single entry point — never with a raw `fetch`.
 - `client.auth` — the [better-auth](https://better-auth.com) client (email/password,
   sessions, the `signupApproved` user field, and the admin plugin: `listUsers`,
   `updateUser`, `banUser`, `setRole`, `listUserSessions`, …).
-- `client.get/post/put/patch/del` — the app's JSON REST endpoints, parsing the
-  standard error envelope and throwing `ApiError` on failure.
+- `client.get/post/put/patch/del` — the app's REST endpoints, parsing the
+  standard error envelope and throwing `ApiError` on failure. Bodies are JSON,
+  except `FormData` and binary bodies, which are sent as they are.
 - `client.postForm` — multipart uploads with the browser-managed boundary and the
   same credentials and error handling.
 
@@ -29,6 +30,40 @@ form.set("file", imageFile);
 await api.postForm("/account/profile-image", form);
 ```
 
+## Binary bodies and request options
+
+`post`, `put`, and `patch` send a `Blob` (or `File`), an `ArrayBuffer`, a typed
+array such as `Uint8Array`, or a `ReadableStream` as the raw request body.
+Every call takes optional request options as its last argument:
+
+| Option | Purpose |
+| --- | --- |
+| `contentType` | Content type of the body. Binary bodies default to the Blob's type, else `application/octet-stream`; JSON bodies to `application/json`. |
+| `headers` | Additional headers, such as `content-range` or an idempotency key. |
+| `signal` | An `AbortSignal` that cancels the request. |
+
+```ts
+// Upload a file in 8 MiB chunks, one request per chunk
+const chunkSize = 8 * 1024 * 1024;
+for (let part = 0; part * chunkSize < file.size; part++) {
+  const chunk = file.slice(part * chunkSize, (part + 1) * chunkSize);
+  await api.put(`/uploads/${id}/parts/${part + 1}`, chunk, {
+    contentType: "application/octet-stream",
+    signal: controller.signal,
+  });
+}
+```
+
+A `ReadableStream` body is sent with `duplex: "half"`. Browsers stream request
+bodies only over HTTP/2 or later, and not every browser supports them, so send
+`Blob` slices from the browser and keep streams for server-side code. The SvelteKit
+`/api` proxy and the API each enforce their own request size limits.
+
+`ApiError.retryAfterSeconds` holds the `Retry-After` delay of a failed response,
+such as `429 RATE_LIMIT_EXCEEDED` or `503`, when the server sends one. Apps that
+called `fetch` directly to send binary chunks or to read `Retry-After` can use
+these instead.
+
 ## Options
 
 | Option | Default | Purpose |
@@ -40,6 +75,8 @@ await api.postForm("/account/profile-image", form);
 | `credentials` | `include` | Send cookies with requests. |
 
 Errors are thrown as `ApiError` (`code`, `message`, `statusCode`, `details`).
+A response without the JSON error envelope, such as a gateway's HTML error page,
+becomes an `ApiError` with code `HTTP_ERROR` and the response status.
 `PUBLIC_SIGNUP_DISABLED` and `SIGNUP_APPROVAL_REQUIRED` are re-exported for
 provider-independent registration-policy handling.
 The profile-image policy, response type, and stable validation error codes are

package/dist/index.d.ts

@@ -27,7 +27,28 @@ export declare class ApiError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly details?: unknown;
-    constructor(code: string, message: string, statusCode: number, details?: unknown);
+    /** Seconds to wait before retrying, from a `Retry-After` header (for example on 429 or 503). */
+    readonly retryAfterSeconds?: number;
+    constructor(code: string, message: string, statusCode: number, details?: unknown, retryAfterSeconds?: number);
+}
+/**
+ * A request body sent as is rather than as JSON: a `Blob` or `File`, bytes, or
+ * a stream. Send large files as a `Blob` (or `blob.slice()` chunks); a stream
+ * body needs a server and browser that support streaming uploads.
+ */
+export type BinaryBody = Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array>;
+/** Per-request options for {@link ApiClient} calls. */
+export interface RequestOptions {
+    /**
+     * Content type of the body. Binary bodies default to the Blob's own type,
+     * else `application/octet-stream`; JSON bodies to `application/json`.
+     * Ignored for `FormData`, whose boundary the runtime sets.
+     */
+    contentType?: string;
+    /** Additional request headers, such as `content-range` for a chunk. */
+    headers?: Record<string, string>;
+    /** Cancels the request, for example when the user abandons an upload. */
+    signal?: AbortSignal;
 }
 /**
  * Create a typed API client. Every frontend talks to the PodoKit backend
@@ -35,8 +56,10 @@ export declare class ApiError extends Error {
  *
  * - `client.auth` is the better-auth client (email/password, sessions, and the
  *   admin plugin: `client.auth.admin.listUsers()`, `banUser`, `setRole`, ...).
- * - `client.get/post/put/patch/del` call the app's JSON REST endpoints and parse
- *   the standard error envelope, throwing {@link ApiError} on failure.
+ * - `client.get/post/put/patch/del` call the app's REST endpoints and parse
+ *   the standard error envelope, throwing {@link ApiError} on failure. Bodies
+ *   are sent as JSON, except `FormData` (multipart, with the runtime's
+ *   boundary) and {@link BinaryBody} values, which are sent as they are.
  * - `client.postForm` sends multipart `FormData` without overriding the browser's
  *   boundary-aware content type.
  */
@@ -2675,7 +2698,17 @@ export declare function createApiClient(options?: ApiClientOptions): {
                                     expiresAt: Date;
                                     token: string;
                                     ipAddress?: string | null | undefined;
-                                    userAgent?: string | null | undefined;
+                                    userAgent
+                                    /**
+                                     * Content type of the body. Binary bodies default to the Blob's own type,
+                                     * else `application/octet-stream`; JSON bodies to `application/json`.
+                                     * Ignored for `FormData`, whose boundary the runtime sets.
+                                     */
+                                    ? /**
+                                     * Content type of the body. Binary bodies default to the Blob's own type,
+                                     * else `application/octet-stream`; JSON bodies to `application/json`.
+                                     * Ignored for `FormData`, whose boundary the runtime sets.
+                                     */: string | null | undefined;
                                 };
                                 user: Record<string, any> & {
                                     id: string;
@@ -5318,13 +5351,13 @@ export declare function createApiClient(options?: ApiClientOptions): {
         };
     }>>;
     /** Low-level typed request against the app's REST API. */
-    request: <T>(method: string, path: string, body?: unknown) => Promise<T>;
-    get: <T>(path: string) => Promise<T>;
-    post: <T>(path: string, body?: unknown) => Promise<T>;
-    put: <T>(path: string, body?: unknown) => Promise<T>;
-    patch: <T>(path: string, body?: unknown) => Promise<T>;
-    del: <T>(path: string) => Promise<T>;
-    postForm: <T>(path: string, body: FormData) => Promise<T>;
+    request: <T>(method: string, path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    get: <T>(path: string, options?: RequestOptions) => Promise<T>;
+    post: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    put: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    patch: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    del: <T>(path: string, options?: RequestOptions) => Promise<T>;
+    postForm: <T>(path: string, body: FormData, options?: RequestOptions) => Promise<T>;
 };
 /** The client returned by {@link createApiClient}. */
 export type ApiClient = ReturnType<typeof createApiClient>;

package/dist/index.js

@@ -9,23 +9,73 @@ export class ApiError extends Error {
     code;
     statusCode;
     details;
-    constructor(code, message, statusCode, details) {
+    /** Seconds to wait before retrying, from a `Retry-After` header (for example on 429 or 503). */
+    retryAfterSeconds;
+    constructor(code, message, statusCode, details, retryAfterSeconds) {
         super(message);
         this.name = "ApiError";
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/** Reads `Retry-After` as delay seconds or an HTTP date. */
+function retryAfterSeconds(response) {
+    const value = response.headers.get("retry-after")?.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, Math.ceil((date - Date.now()) / 1000));
+}
+/** An error body as JSON, or undefined when a proxy or server answered with text or HTML. */
+function errorBody(text) {
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
     }
 }
 function toApiError(data, response) {
+    const retryAfter = retryAfterSeconds(response);
     if (data && typeof data === "object" && "error" in data) {
         const error = data.error;
         if (error && typeof error === "object") {
             const record = error;
-            return new ApiError(typeof record.code === "string" ? record.code : "HTTP_ERROR", typeof record.message === "string" ? record.message : response.statusText, typeof record.statusCode === "number" ? record.statusCode : response.status, record.details);
+            return new ApiError(typeof record.code === "string" ? record.code : "HTTP_ERROR", typeof record.message === "string" ? record.message : response.statusText, typeof record.statusCode === "number" ? record.statusCode : response.status, record.details, retryAfter);
         }
     }
-    return new ApiError("HTTP_ERROR", response.statusText || "Request failed", response.status);
+    return new ApiError("HTTP_ERROR", response.statusText || "Request failed", response.status, undefined, retryAfter);
+}
+function isBinaryBody(body) {
+    return ((typeof Blob !== "undefined" && body instanceof Blob) ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
+function requestInit(method, credentials, body, options) {
+    const headers = { ...options.headers };
+    const init = { method, credentials, ...(options.signal ? { signal: options.signal } : {}) };
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        init.body = body;
+    }
+    else if (isBinaryBody(body)) {
+        headers["content-type"] =
+            options.contentType ?? (body instanceof Blob && body.type ? body.type : "application/octet-stream");
+        init.body = body;
+        if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream)
+            init.duplex = "half";
+    }
+    else if (body !== undefined) {
+        headers["content-type"] = options.contentType ?? "application/json";
+        init.body = JSON.stringify(body);
+    }
+    if (Object.keys(headers).length > 0)
+        init.headers = headers;
+    return init;
 }
 /**
  * Create a typed API client. Every frontend talks to the PodoKit backend
@@ -33,8 +83,10 @@ function toApiError(data, response) {
  *
  * - `client.auth` is the better-auth client (email/password, sessions, and the
  *   admin plugin: `client.auth.admin.listUsers()`, `banUser`, `setRole`, ...).
- * - `client.get/post/put/patch/del` call the app's JSON REST endpoints and parse
- *   the standard error envelope, throwing {@link ApiError} on failure.
+ * - `client.get/post/put/patch/del` call the app's REST endpoints and parse
+ *   the standard error envelope, throwing {@link ApiError} on failure. Bodies
+ *   are sent as JSON, except `FormData` (multipart, with the runtime's
+ *   boundary) and {@link BinaryBody} values, which are sent as they are.
  * - `client.postForm` sends multipart `FormData` without overriding the browser's
  *   boundary-aware content type.
  */
@@ -79,32 +131,13 @@ export function createApiClient(options = {}) {
         authClient ??= makeAuthClient();
         return authClient;
     }
-    async function request(method, path, body) {
-        const response = await doFetch(`${baseUrl}${apiBasePath}${path}`, {
-            method,
-            credentials,
-            headers: body === undefined ? undefined : { "content-type": "application/json" },
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
-        const text = await response.text();
-        const data = text ? JSON.parse(text) : undefined;
-        if (!response.ok) {
-            throw toApiError(data, response);
-        }
-        return data;
-    }
-    async function formRequest(method, path, body) {
-        const response = await doFetch(`${baseUrl}${apiBasePath}${path}`, {
-            method,
-            credentials,
-            body,
-        });
+    async function request(method, path, body, options = {}) {
+        const response = await doFetch(`${baseUrl}${apiBasePath}${path}`, requestInit(method, credentials, body, options));
         const text = await response.text();
-        const data = text ? JSON.parse(text) : undefined;
         if (!response.ok) {
-            throw toApiError(data, response);
+            throw toApiError(errorBody(text), response);
         }
-        return data;
+        return (text ? JSON.parse(text) : undefined);
     }
     return {
         /** The better-auth client (auth + admin plugin), created on first access. */
@@ -113,11 +146,11 @@ export function createApiClient(options = {}) {
         },
         /** Low-level typed request against the app's REST API. */
         request,
-        get: (path) => request("GET", path),
-        post: (path, body) => request("POST", path, body),
-        put: (path, body) => request("PUT", path, body),
-        patch: (path, body) => request("PATCH", path, body),
-        del: (path) => request("DELETE", path),
-        postForm: (path, body) => formRequest("POST", path, body),
+        get: (path, options) => request("GET", path, undefined, options),
+        post: (path, body, options) => request("POST", path, body, options),
+        put: (path, body, options) => request("PUT", path, body, options),
+        patch: (path, body, options) => request("PATCH", path, body, options),
+        del: (path, options) => request("DELETE", path, undefined, options),
+        postForm: (path, body, options) => request("POST", path, body, options),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit-api-client",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Typed API client for PodoKit backends: better-auth (auth + admin) plus a standard error-envelope request layer.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.4.0",
+    "@podosoft/podokit-contracts": "^0.5.0",
     "better-auth": "^1.7.7",
     "@better-auth/api-key": "^1.7.7",
     "@better-auth/passkey": "^1.7.7"