@classytic/arc-next 0.4.1 → 0.6.0

package/dist/upload.js

@@ -0,0 +1,346 @@
+import { ArcApiError, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
+import { getToastHandler } from "./mutation.js";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+
+//#region src/upload.ts
+/**
+* XHR-based upload with real progress events.
+*
+* `fetch()` has no upload-progress API across browsers — Chrome 105+ supports
+* `ReadableStream` request bodies, but Safari and Firefox don't ship the stream
+* fetch+request body combination consumers need. This module solves that with
+* `XMLHttpRequest`, which gives universal `xhr.upload.onprogress` support.
+*
+* Two surfaces:
+*   1. `uploadWithProgress()` — plain Promise-returning function. Works in any
+*      JS context (React, Node-with-XHR-shim, tests).
+*   2. `useUploadWithProgress()` — TanStack-Query-flavored React hook. Tracks
+*      progress as React state alongside the standard mutation lifecycle
+*      (loading, error, data, reset, cancel) and integrates with the SDK's
+*      toast handler + query invalidation.
+*
+* Both reuse arc-next's auth pipeline (`getClientAuthContext`), the shared
+* `ArcApiError` envelope (top-level `code` + `details.code` slots), and the
+* same `Authorization` / `x-organization-id` / `x-arc-scope` /
+* `Idempotency-Key` header conventions as the fetch path. SDK behavior (auth,
+* errors, elevated requests, ArcApiError messages) stays consistent across
+* both upload variants.
+*
+* ─── Divergence from the fetch path ──────────────────────────────────────
+*
+* Two `ClientConfig` surfaces deliberately do NOT propagate to uploads:
+*
+* 1. **`retry`** — uploads do not auto-retry. Re-uploading a multi-MB body
+*    after a transient 5xx is rarely what consumers want (re-encoding cost,
+*    duplicate-write risk on non-idempotent endpoints, bandwidth burn). If
+*    you need at-most-once semantics, set `idempotencyKey` and let the
+*    backend dedupe; if you need at-least-once, wrap the call site with
+*    your own retry policy where you control file streaming.
+*
+* 2. **`beforeRequest` / `afterResponse`** — interceptors are tied to
+*    `executeRequest` (the fetch path) and DO NOT fire on XHR uploads.
+*    Trace headers, correlation IDs, and latency loggers configured via
+*    `configureClient({ beforeRequest, afterResponse })` will be missing
+*    on upload requests. To attach trace/correlation headers per-upload,
+*    pass them through the `headers` option on `uploadWithProgress` (or
+*    the `headers` factory on `useUploadWithProgress`):
+*
+*        const traceId = crypto.randomUUID();
+*        await uploadWithProgress({
+*          url, formData,
+*          headers: { 'x-correlation-id': traceId },
+*        });
+*        log.info({ traceId, uploadKind: 'media' });
+*
+*    This is documented behavior, not a bug — bridging XHR's progress events
+*    into the fetch interceptor pipeline would either require duplicating
+*    every interceptor for both transports or giving up the upload-progress
+*    contract. Future versions may expose dedicated `beforeUpload` /
+*    `afterUpload` hooks if a strong use case emerges.
+*/
+/**
+* Upload a `FormData` payload via XHR with native progress events.
+*
+* Returns a Promise that resolves with the parsed response body
+* (`responseType: 'json'` by default — pass `'text'` or `'blob'` to opt out).
+* Rejects with {@link ArcApiError} on non-2xx, with abort errors when the
+* provided signal fires, or `Error` on transport failure (network down, CORS).
+*
+* Reuses {@link getClientAuthContext} so the global `configureAuth()` token /
+* orgId — and per-client overrides via `client?.auth` — flow through. Sets
+* `withCredentials = true` automatically for `authMode: 'cookie'`.
+*
+* @example
+* const result = await uploadWithProgress<{ url: string }>({
+*   url: '/api/v1/media/upload',
+*   formData,
+*   onProgress: ({ percent }) => setUiProgress(percent),
+* });
+*/
+function uploadWithProgress(options) {
+	const { url, formData, method = "POST", onProgress, signal, client, headers: extraHeaders, elevated, idempotencyKey, responseType = "json" } = options;
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(abortReason(signal));
+			return;
+		}
+		const xhr = new XMLHttpRequest();
+		const fullUrl = resolveUrl(url, client);
+		xhr.open(method, fullUrl, true);
+		xhr.responseType = responseType === "blob" ? "blob" : "";
+		const authMode = client?.config?.authMode ?? getAuthMode();
+		if (authMode === "cookie") xhr.withCredentials = true;
+		const authCtx = getClientAuthContext(client);
+		const token = options.token !== void 0 ? options.token : authCtx.token;
+		const orgId = options.organizationId !== void 0 ? options.organizationId : authCtx.organizationId;
+		const builtHeaders = {};
+		if (token) {
+			if (authMode === "header") {
+				const headerName = client?.auth?.headerName ?? "x-api-key";
+				builtHeaders[headerName] = token;
+			} else if (authMode !== "cookie") builtHeaders["Authorization"] = `Bearer ${token}`;
+		}
+		if (orgId) builtHeaders["x-organization-id"] = orgId;
+		if (elevated ?? client?.config?.elevated) builtHeaders["x-arc-scope"] = "platform";
+		if (idempotencyKey) builtHeaders["Idempotency-Key"] = idempotencyKey;
+		if (client?.config?.apiVersion) builtHeaders["Accept-Version"] = client.config.apiVersion;
+		if (client?.config?.internalApiKey) builtHeaders["x-internal-api-key"] = client.config.internalApiKey;
+		Object.assign(builtHeaders, client?.config?.defaultHeaders ?? {});
+		Object.assign(builtHeaders, extraHeaders ?? {});
+		for (const [name, value] of Object.entries(builtHeaders)) {
+			if (name.toLowerCase() === "content-type") continue;
+			xhr.setRequestHeader(name, value);
+		}
+		if (onProgress) xhr.upload.onprogress = (event) => {
+			const lengthComputable = event.lengthComputable;
+			const total = lengthComputable ? event.total : 0;
+			const loaded = event.loaded;
+			onProgress({
+				percent: lengthComputable && total > 0 ? Math.min(100, Math.round(loaded / total * 100)) : 0,
+				loaded,
+				total,
+				lengthComputable
+			});
+		};
+		let abortListener = null;
+		if (signal) {
+			abortListener = () => {
+				try {
+					xhr.abort();
+				} catch {}
+				reject(abortReason(signal));
+			};
+			signal.addEventListener("abort", abortListener, { once: true });
+		}
+		xhr.onload = () => {
+			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+			const status = xhr.status;
+			const statusText = xhr.statusText || statusTextFromCode(status);
+			if (status === 0) {
+				reject(/* @__PURE__ */ new Error(`Network error during upload to ${fullUrl}`));
+				return;
+			}
+			const body = parseResponseBody(xhr, responseType);
+			if (status >= 200 && status < 300) {
+				resolve(body);
+				return;
+			}
+			reject(new ArcApiError(extractErrorMessage(body, statusText), {
+				status,
+				statusText,
+				json: body,
+				endpoint: url,
+				method
+			}));
+		};
+		xhr.onerror = () => {
+			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+			reject(/* @__PURE__ */ new Error(`Network error during upload to ${fullUrl}`));
+		};
+		xhr.ontimeout = () => {
+			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+			reject(/* @__PURE__ */ new Error(`Upload timed out: ${fullUrl}`));
+		};
+		xhr.send(formData);
+	});
+}
+/**
+* React hook that wraps {@link uploadWithProgress} with TanStack-Query-style
+* mutation ergonomics. Progress lives in React state — every progress tick
+* re-renders the consumer so binding `progress.percent` to a `<ProgressBar>`
+* "just works" with no extra plumbing.
+*
+* @example
+* const { upload, progress, isUploading, cancel, error } = useUploadWithProgress<
+*   { url: string }[],
+*   { files: File[]; folder?: string }
+* >({
+*   url: '/api/v1/media/upload-multiple',
+*   buildFormData: ({ files, folder }) => {
+*     const fd = new FormData();
+*     if (folder) fd.append('folder', folder);
+*     files.forEach((f) => fd.append('files[]', f));
+*     return fd;
+*   },
+*   invalidateQueries: [mediaKeys.lists()],
+*   messages: { success: 'Uploaded', error: 'Upload failed' },
+* });
+*
+* <ProgressBar value={progress?.percent ?? 0} />
+* <button onClick={() => upload({ files })}>Upload</button>
+* {isUploading && <button onClick={cancel}>Cancel</button>}
+*/
+function useUploadWithProgress(options) {
+	const queryClient = useQueryClient();
+	const [progress, setProgress] = useState(null);
+	const [isUploading, setIsUploading] = useState(false);
+	const [data, setData] = useState(null);
+	const [error, setError] = useState(null);
+	const [isSuccess, setIsSuccess] = useState(false);
+	const optsRef = useRef(options);
+	optsRef.current = options;
+	const abortRef = useRef(null);
+	const reset = useCallback(() => {
+		setProgress(null);
+		setIsUploading(false);
+		setData(null);
+		setError(null);
+		setIsSuccess(false);
+	}, []);
+	const cancel = useCallback(() => {
+		abortRef.current?.abort();
+	}, []);
+	return {
+		upload: useCallback(async (vars) => {
+			const opts = optsRef.current;
+			const url = typeof opts.url === "function" ? opts.url(vars) : opts.url;
+			const formData = opts.buildFormData(vars);
+			const headers = typeof opts.headers === "function" ? opts.headers(vars) : opts.headers;
+			const elevated = typeof opts.elevated === "function" ? opts.elevated(vars) : opts.elevated;
+			const idempotencyKey = typeof opts.idempotencyKey === "function" ? opts.idempotencyKey(vars) : opts.idempotencyKey;
+			abortRef.current?.abort();
+			const controller = new AbortController();
+			abortRef.current = controller;
+			setError(null);
+			setIsSuccess(false);
+			setIsUploading(true);
+			setProgress({
+				percent: 0,
+				loaded: 0,
+				total: 0,
+				lengthComputable: false
+			});
+			try {
+				const result = await uploadWithProgress({
+					url,
+					formData,
+					method: opts.method,
+					client: opts.client,
+					headers,
+					elevated,
+					idempotencyKey,
+					responseType: opts.responseType,
+					signal: controller.signal,
+					onProgress: (p) => {
+						setProgress(p);
+						opts.onProgress?.(p, vars);
+					}
+				});
+				if (abortRef.current === controller) {
+					setData(result);
+					setIsSuccess(true);
+					setIsUploading(false);
+				}
+				if (opts.invalidateQueries?.length) for (const key of opts.invalidateQueries) queryClient.invalidateQueries({ queryKey: key });
+				const successMsg = opts.messages?.success;
+				if (successMsg) {
+					const text = typeof successMsg === "function" ? successMsg(result, vars) : successMsg;
+					(opts.toastHandler ?? getToastHandler()).success(text);
+				}
+				opts.onSuccess?.(result, vars);
+				opts.onSettled?.(result, null, vars);
+				return result;
+			} catch (err) {
+				const e = err instanceof Error ? err : new Error(String(err));
+				if (abortRef.current === controller) {
+					setError(e);
+					setIsSuccess(false);
+					setIsUploading(false);
+				}
+				const errorMsg = opts.messages?.error;
+				if (errorMsg) {
+					const text = typeof errorMsg === "function" ? errorMsg(e, vars) : errorMsg;
+					(opts.toastHandler ?? getToastHandler()).error(text);
+				}
+				opts.onError?.(e, vars);
+				opts.onSettled?.(void 0, e, vars);
+				throw e;
+			} finally {
+				if (abortRef.current === controller) abortRef.current = null;
+			}
+		}, [queryClient]),
+		progress,
+		isUploading,
+		isPending: isUploading,
+		data,
+		error,
+		isSuccess,
+		isError: error !== null,
+		cancel,
+		reset
+	};
+}
+/**
+* Resolve a possibly-relative URL against the configured base. Mirrors
+* `executeRequest` so the SDK presents a consistent URL contract regardless
+* of transport.
+*/
+function resolveUrl(url, client) {
+	if (/^https?:\/\//i.test(url)) return url;
+	const base = client?.config?.baseUrl ?? getBaseUrl();
+	if (!base) return url;
+	if (base.endsWith("/") && url.startsWith("/")) return base + url.slice(1);
+	if (!base.endsWith("/") && !url.startsWith("/")) return `${base}/${url}`;
+	return base + url;
+}
+/**
+* Parse XHR response body. Returns the raw value the caller asked for —
+* `'json'` parses (and falls back to text on parse failure); `'text'` returns
+* the string as-is; `'blob'` returns the binary directly.
+*/
+function parseResponseBody(xhr, kind) {
+	if (kind === "blob") return xhr.response;
+	const raw = xhr.responseText;
+	if (kind === "text") return raw;
+	if (!raw) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return { rawBody: raw };
+	}
+}
+function extractErrorMessage(body, fallback) {
+	if (body && typeof body === "object") {
+		const obj = body;
+		if (typeof obj.error === "string" && obj.error) return obj.error;
+		if (typeof obj.message === "string" && obj.message) return obj.message;
+	}
+	return fallback;
+}
+function abortReason(signal) {
+	const reason = signal.reason;
+	if (reason !== void 0) return reason;
+	if (typeof DOMException !== "undefined") return new DOMException("The operation was aborted.", "AbortError");
+	const err = /* @__PURE__ */ new Error("The operation was aborted.");
+	err.name = "AbortError";
+	return err;
+}
+function statusTextFromCode(code) {
+	if (code >= 500) return "Internal Server Error";
+	if (code >= 400) return "Request Error";
+	return "OK";
+}
+
+//#endregion
+export { uploadWithProgress, useUploadWithProgress };

package/dist/ws.d.ts

@@ -0,0 +1,167 @@
+import { QueryKey } from "@tanstack/react-query";
+
+//#region src/ws.d.ts
+/**
+ * Inbound message shape from Arc's `websocketPlugin` broadcasts.
+ *
+ * Arc auto-broadcasts CRUD events for resources listed in
+ * `websocketPlugin({ resources: [...] })` as:
+ *   `{ type: '<resource>.<op>', data: { resource, operation, data: doc, timestamp }, meta }`
+ *
+ * Custom messages from your handlers can have any shape — typed as `unknown` data.
+ */
+interface ArcWsMessage<TData = unknown> {
+  type: string;
+  data?: TData;
+  meta?: Record<string, unknown>;
+}
+/**
+ * Subscribe-frame shape Arc's `websocketPlugin` accepts.
+ * Wire format (per backend tests): `{ type: 'subscribe', resource: '<resource>' }`.
+ * Backend also accepts `channel` as alias.
+ */
+interface ArcSubscribeFrame {
+  type: 'subscribe' | 'unsubscribe';
+  resource?: string;
+  channel?: string;
+  /** Free-form additional fields the backend may use (token, filters, etc.). */
+  [key: string]: unknown;
+}
+interface ConnectWsOptions<TData = unknown> {
+  /** Full ws/wss URL. When set, overrides `path` and `baseUrl`. */
+  url?: string;
+  /** WS path relative to baseUrl (default: `/ws`). Auto-converts http(s)→ws(s). */
+  path?: string;
+  /**
+   * Resources to subscribe to on connect — sends `{type:'subscribe', resource: <name>}`
+   * for each. Auto-resubscribes after reconnect.
+   */
+  subscribe?: string[];
+  /**
+   * Message types to listen for. When omitted, all messages reach `onMessage`.
+   * Pattern matches the type prefix when ending with a dot
+   * (e.g. `'todo.'` matches `'todo.created'`), otherwise exact match.
+   */
+  patterns?: string[];
+  /** Callback per inbound message (after pattern filtering). */
+  onMessage?: (message: ArcWsMessage<TData>) => void;
+  /** Connection-state callback. */
+  onConnectionChange?: (connected: boolean) => void;
+  /** Reconnect delay in ms. Default: 3000 (capped at 30000 with backoff). */
+  reconnectDelay?: number;
+  /** Max reconnect attempts. Default: Infinity. */
+  maxReconnectAttempts?: number;
+  /**
+   * Application-level heartbeat interval in ms. When > 0, sends `{type:'ping'}`
+   * every N ms so the backend can detect dead clients. Default: 0 (disabled).
+   */
+  heartbeatInterval?: number;
+  /** WebSocket subprotocols (some auth schemes pass tokens here). */
+  protocols?: string | string[];
+}
+/** Per-type listener handle returned by {@link ConnectWsHandle.on}. Call to remove. */
+type WsOffHandle = () => void;
+/**
+ * Imperative handle returned by {@link connectWs}. Stable across reconnects.
+ *
+ * Use `on(eventType, handler)` to register an additional per-type listener
+ * alongside the global `onMessage` callback. Returns an unsubscribe function.
+ */
+interface ConnectWsHandle<TData = unknown> {
+  /** True when the WS is OPEN. */
+  isConnected: () => boolean;
+  /** Send any JSON-serializable payload. Returns false if not connected. */
+  send: (payload: unknown) => boolean;
+  /** Subscribe to a resource. Persists across reconnects. */
+  subscribe: (resource: string) => void;
+  /** Unsubscribe from a resource. */
+  unsubscribe: (resource: string) => void;
+  /**
+   * Listen for messages whose type matches `eventType` exactly. Use `'*'` for
+   * a catch-all listener. Returns an unsubscribe function.
+   */
+  on: (eventType: string, handler: (message: ArcWsMessage<TData>) => void) => WsOffHandle;
+  /** Close manually (no auto-reconnect after this). */
+  close: () => void;
+  /** Reopen after a manual close. */
+  reconnect: () => void;
+}
+interface WebSocketOptions<TData = unknown> extends ConnectWsOptions<TData> {
+  /** Query keys to invalidate when any matching message is received. */
+  invalidateQueries?: QueryKey[];
+  /** Whether the socket is active. Default: true. */
+  enabled?: boolean;
+  /**
+   * Whether to track `lastMessage` in React state. Default: true.
+   *
+   * Set to `false` for high-volume streams (chat, telemetry) where the consumer
+   * uses `onMessage` for fire-and-forget handling and never reads
+   * `result.lastMessage`. Each inbound frame skips a `setState` call,
+   * eliminating per-message re-renders.
+   */
+  trackLastMessage?: boolean;
+  /**
+   * Whether to track `messageCount` in React state. Default: true.
+   *
+   * Same trade-off as `trackLastMessage`: skip the counter `setState` for
+   * high-volume streams that don't read it.
+   */
+  trackMessageCount?: boolean;
+}
+interface WebSocketResult<TData = unknown> {
+  isConnected: boolean;
+  lastMessage: ArcWsMessage<TData> | null;
+  messageCount: number;
+  send: (payload: unknown) => boolean;
+  subscribe: (resource: string) => void;
+  unsubscribe: (resource: string) => void;
+  close: () => void;
+  reconnect: () => void;
+}
+/**
+ * Build an authenticated WebSocket URL using the global client + auth singletons.
+ *
+ * Thin alias for {@link import('./client.js').buildStreamUrl} with the WS
+ * protocol — rewrites `http(s)://` → `ws(s)://` and attaches the same auth
+ * params SSE uses, so the two transports stay in lock-step.
+ *
+ * @example
+ * const socket = new WebSocket(buildWsUrl('/ws'));
+ */
+declare function buildWsUrl(path?: string, params?: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * Connect to an Arc WebSocket channel from any JS context (React, Node, Bun, tests).
+ * Pure function — no React hook required. Returns a handle with `send()`,
+ * `subscribe()`, `on()`, `close()`, `reconnect()`, `isConnected()`.
+ *
+ * Reconnect uses exponential backoff (×1.5 per attempt, capped at 30s).
+ * Subscriptions persist across reconnect.
+ *
+ * @example
+ * const ws = connectWs<CrudEvent<Todo>>({
+ *   subscribe: ['todo'],
+ *   onMessage: (m) => console.log(m.type, m.data),
+ * });
+ *
+ * const off = ws.on('todo.created', (m) => console.log('new todo:', m.data));
+ * // ...later
+ * off();
+ * ws.close();
+ */
+declare function connectWs<TData = unknown>(options?: ConnectWsOptions<TData>): ConnectWsHandle<TData>;
+/**
+ * Connect to an Arc WebSocket channel with auto-reconnect, subscription
+ * persistence, and TanStack Query invalidation on inbound messages.
+ *
+ * Internally delegates to {@link connectWs} — for non-React contexts (Node,
+ * tests, plain JS) call that directly.
+ *
+ * @example
+ * const { isConnected, lastMessage } = useWebSocket<CrudEvent<Todo>>({
+ *   subscribe: ['todo'],
+ *   invalidateQueries: [todoKeys.lists()],
+ * });
+ */
+declare function useWebSocket<TData = unknown>(options: WebSocketOptions<TData>): WebSocketResult<TData>;
+//#endregion
+export { ArcSubscribeFrame, ArcWsMessage, ConnectWsHandle, ConnectWsOptions, WebSocketOptions, WebSocketResult, WsOffHandle, buildWsUrl, connectWs, useWebSocket };