@multiplatform.one/frappe 6.0.0

package/src/core/http.ts

@@ -0,0 +1,324 @@
+import { getCookie, setCookie, deleteCookie } from "@multiplatform.one/platform";
+import { isBrowser } from "../util";
+import { FrappeError, HttpMethod } from "./types";
+import type { AuthConfig, RetryConfig } from "./types";
+
+export { getCookie, setCookie, deleteCookie };
+
+const defaultRetryConfig: RetryConfig = {
+  baseDelayMs: 250,
+  exponentialBackoff: true,
+  maxDelayMs: 5000,
+  maxRetries: 3,
+  retryOnNetworkError: true,
+  retryStatusCodes: [408, 429, 500, 502, 503, 504],
+};
+export type RequestBody = BodyInit | Record<string, unknown> | unknown[] | ArrayBufferView;
+
+export interface HttpResponse<T> {
+  _res: Response;
+  headers: Headers;
+  payload: T;
+  status: number;
+}
+
+export class HttpClient {
+  private readonly retryConfig: RetryConfig;
+  // Language preference for Accept-Language header (used in SSR / React Native)
+  private _language?: string;
+
+  constructor(
+    private readonly baseURL: string,
+    private auth?: AuthConfig,
+    retryConfig?: RetryConfig,
+  ) {
+    this.retryConfig = { ...defaultRetryConfig, ...retryConfig };
+  }
+
+  /** Set language preference for Accept-Language header on all requests. */
+  setLanguage(lang: string) {
+    this._language = lang;
+  }
+
+  /** Get resolved language: explicit > cookie > undefined. */
+  getLanguage(): string | undefined {
+    if (this._language) return this._language;
+    if (isBrowser()) return getCookie("preferred_language") || undefined;
+    return undefined;
+  }
+
+  /** Sync language preference to Frappe user profile (authenticated users). */
+  async syncUserLanguage(lang: string, user?: string): Promise<void> {
+    this._language = lang;
+    await this.post("/api/method/frappe.client.set_value", {
+      doctype: "User",
+      name: user ?? "currentuser",
+      fieldname: "language",
+      value: lang,
+    });
+  }
+
+  private async getAuthHeaders(): Promise<Record<string, string>> {
+    if (!this.auth?.useToken) return {};
+    const raw = typeof this.auth.token === "function" ? await this.auth.token() : this.auth?.token;
+    if (!raw) return {};
+    const scheme = this.auth?.type === "token" ? "token" : "Bearer";
+    return { Authorization: `${scheme} ${raw}` };
+  }
+
+  private shouldRetryError(err: unknown, attempt: number): boolean {
+    if (this.retryConfig.shouldRetry) {
+      return this.retryConfig.shouldRetry(err, attempt);
+    }
+    if (attempt >= Number(this.retryConfig.maxRetries)) return false;
+    if (!(err instanceof Error && "status" in err)) {
+      return Boolean(this.retryConfig.retryOnNetworkError);
+    }
+    if (err && typeof err === "object" && "status" in err) {
+      const statusCode = (err as { status: unknown }).status;
+      if (typeof statusCode === "number") {
+        return Boolean(this.retryConfig.retryStatusCodes?.includes(statusCode));
+      }
+    }
+    return false;
+  }
+
+  private getRetryDelay(attempt: number) {
+    if (!this.retryConfig.exponentialBackoff) {
+      return Number(this.retryConfig.baseDelayMs ?? 0);
+    }
+    const delay = Number(this.retryConfig.baseDelayMs ?? 0) * 2 ** attempt;
+    return Math.min(delay, Number(this.retryConfig.maxDelayMs ?? 0));
+  }
+
+  async request<T>(
+    method: HttpMethod,
+    path: string,
+    request: {
+      body?: RequestBody;
+      headers?: Record<string, string>;
+    },
+  ): Promise<HttpResponse<T>> {
+    const url = new URL(path, this.baseURL).toString();
+    let body: BodyInit;
+    const headers = new Headers(request?.headers);
+    let contentType = headers.get("Content-Type");
+    if (
+      headers.get("Content-Type")?.includes("multipart/form-data") ||
+      (typeof FormData !== "undefined" && request?.body instanceof FormData)
+    ) {
+      contentType = "multipart/form-data";
+    } else if (
+      headers.get("Content-Type")?.includes("application/x-www-form-urlencoded") ||
+      (typeof URLSearchParams !== "undefined" && request?.body instanceof URLSearchParams)
+    ) {
+      contentType = "application/x-www-form-urlencoded";
+    }
+    if (request?.body) {
+      if (
+        !(
+          request?.body instanceof ArrayBuffer ||
+          request?.body instanceof Blob ||
+          request?.body instanceof FormData ||
+          request?.body instanceof ReadableStream ||
+          request?.body instanceof URLSearchParams ||
+          ArrayBuffer.isView(request.body)
+        )
+      ) {
+        if (contentType === "multipart/form-data") {
+          const formData = new FormData();
+          for (const [key, value] of Object.entries(request.body)) {
+            if (typeof value === "string" || value instanceof Blob) {
+              formData.append(key, value);
+            }
+          }
+          body = formData;
+          headers.set("Content-Type", "multipart/form-data");
+        } else if (contentType === "application/x-www-form-urlencoded") {
+          const searchParams = new URLSearchParams();
+          for (const [key, value] of Object.entries(request.body)) {
+            if (typeof value === "string") {
+              searchParams.append(key, value);
+            }
+          }
+          body = searchParams.toString();
+          headers.set("Content-Type", "application/x-www-form-urlencoded");
+        } else if (typeof request.body === "object") {
+          body = JSON.stringify(request.body);
+          headers.set("Content-Type", "application/json");
+        } else {
+          body = request.body as unknown as BodyInit;
+        }
+      } else {
+        body = request.body as unknown as BodyInit;
+      }
+    }
+    const authHeaders = await this.getAuthHeaders();
+    for (const [key, value] of Object.entries(authHeaders)) {
+      headers.set(key, value);
+    }
+    // SSR / Node.js: forward cookies explicitly (browser cookie jar is
+    // unavailable on the server).
+    if (!isBrowser()) {
+      // Use explicit auth cookie if provided, otherwise use SSR cookies
+      if (this.auth?.cookie) {
+        headers.set("Cookie", this.auth.cookie);
+      } else if (ssrCookies && ssrCookies.size > 0) {
+        // Build cookie string from SSR cookie storage
+        const cookieStr = Array.from(ssrCookies.entries())
+          .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+          .join("; ");
+        if (cookieStr) headers.set("Cookie", cookieStr);
+      }
+    }
+    // Inject Accept-Language header from language preference or cookie
+    const lang = this.getLanguage();
+    if (lang && !headers.has("Accept-Language")) {
+      headers.set("Accept-Language", lang);
+    }
+    if (!this.auth?.useToken && isBrowser() && method !== HttpMethod.Get) {
+      const csrf =
+        getCookie("frappe-csrf-token") || getCookie("csrf_token") || globalThis.frappe?.csrf_token;
+      if (csrf) headers.set("X-Frappe-CSRF-Token", csrf);
+    }
+    const makeRequest = (): Promise<Response> => {
+      return fetch(url, {
+        method,
+        headers,
+        credentials: this.auth?.useToken ? "omit" : "include",
+        body,
+      });
+    };
+    let lastError: unknown;
+    let attempt = 0;
+    while (attempt <= Number(this.retryConfig.maxRetries ?? 0)) {
+      try {
+        const res = await makeRequest();
+        if (!res.ok) {
+          const contentType = res.headers.get("content-type");
+          const payload = contentType?.includes("application/json")
+            ? await res.json()
+            : await res.text();
+          const message =
+            (payload && (payload.message || payload.exc || payload._server_messages)) ||
+            res.statusText;
+          const err = new FrappeError(message, res.status, payload);
+          if (this.shouldRetryError(err, attempt)) {
+            lastError = err;
+            attempt++;
+            if (attempt <= Number(this.retryConfig.maxRetries ?? 0)) {
+              await new Promise((resolve) => setTimeout(resolve, this.getRetryDelay(attempt - 1)));
+              continue;
+            }
+          }
+          throw err;
+        }
+        const contentType = res.headers.get("Content-Type");
+        const payload = contentType?.includes("application/json")
+          ? await res.json()
+          : await res.text();
+        return {
+          headers: res.headers,
+          payload,
+          status: res.status,
+          _res: res,
+        };
+      } catch (err) {
+        if (this.shouldRetryError(err, attempt)) {
+          lastError = err;
+          attempt++;
+          if (attempt <= Number(this.retryConfig.maxRetries ?? 0)) {
+            await new Promise((resolve) => setTimeout(resolve, this.getRetryDelay(attempt - 1)));
+            continue;
+          }
+        }
+        throw err;
+      }
+    }
+    throw lastError;
+  }
+
+  get<T>(path: string, params?: Record<string, unknown>, headers?: Record<string, string>) {
+    const qs = params ? `?${new URLSearchParams(normalizeParams(params)).toString()}` : "";
+    return this.request<T>(HttpMethod.Get, `${path}${qs}`, { headers });
+  }
+
+  post<T>(path: string, body?: RequestBody, headers?: Record<string, string>) {
+    return this.request<T>(HttpMethod.Post, path, { headers, body });
+  }
+
+  put<T>(path: string, body?: RequestBody, headers?: Record<string, string>) {
+    return this.request<T>(HttpMethod.Put, path, { headers, body });
+  }
+
+  delete<T>(path: string, body?: RequestBody, headers?: Record<string, string>) {
+    return this.request<T>(HttpMethod.Delete, path, { headers, body });
+  }
+
+  head(path: string, params?: Record<string, unknown>, headers?: Record<string, string>) {
+    const qs = params ? `?${new URLSearchParams(normalizeParams(params)).toString()}` : "";
+    return this.request<void>(HttpMethod.Head, `${path}${qs}`, { headers });
+  }
+
+  getAuthConfig(): AuthConfig {
+    return this.auth || {};
+  }
+
+  updateAuth(auth: AuthConfig) {
+    this.auth = auth;
+  }
+}
+
+function normalizeParams(params: Record<string, unknown>): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      normalized[key] = typeof value === "string" ? value : JSON.stringify(value);
+    }
+  }
+  return normalized;
+}
+
+/** SSR cookie storage for non-browser environments */
+let ssrCookies: Map<string, string> | null = null;
+
+/**
+ * Set cookies for SSR/Node environments where document.cookie is unavailable.
+ * Pass a cookie header string (e.g., from incoming request).
+ */
+export function setSSRCookies(cookieHeader: string | undefined): void {
+  if (isBrowser()) return;
+
+  ssrCookies = new Map();
+  if (!cookieHeader) return;
+
+  const cookies = cookieHeader.split("; ");
+  for (const cookie of cookies) {
+    const eqIndex = cookie.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const name = cookie.slice(0, eqIndex).trim();
+    const value = cookie.slice(eqIndex + 1);
+
+    if (!name) continue;
+
+    try {
+      ssrCookies.set(name, decodeURIComponent(value));
+    } catch {
+      ssrCookies.set(name, value);
+    }
+  }
+}
+
+/**
+ * Clear SSR cookies (call at end of request lifecycle).
+ */
+export function clearSSRCookies(): void {
+  ssrCookies = null;
+}
+
+/**
+ * Invalidate the cookie cache. No-op — retained for backwards compatibility.
+ * Cookie reads now delegate directly to the platform abstraction.
+ */
+export function invalidateCookieCache(): void {}

package/src/core/types.ts

@@ -0,0 +1,85 @@
+import type { OrderBy } from "../sync/types";
+
+export enum AuthType {
+  Bearer = "Bearer",
+  Token = "token",
+}
+
+export interface AuthConfig {
+  /**
+   * Raw cookie string to attach to every request (used in SSR / Node.js
+   * where the browser cookie jar is not available).
+   *
+   * Example: `"sid=abc123; system_user=yes"`
+   */
+  cookie?: string;
+  sessionId?: string | (() => string | Promise<string>);
+  token?: string | (() => string | Promise<string>);
+  type?: AuthType;
+  useToken?: boolean;
+}
+
+export interface RetryConfig {
+  baseDelayMs?: number;
+  exponentialBackoff?: boolean;
+  maxDelayMs?: number;
+  maxRetries?: number;
+  retryOnNetworkError?: boolean;
+  retryStatusCodes?: number[];
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+
+export type CustomEndpoints = {
+  createDoc?: string;
+  deleteDoc?: string;
+  backfill?: string;
+  updateDoc?: string;
+  /** Cursor-based pagination endpoint (frappe_live.api.get_list_with_cursor) */
+  getListWithCursor?: string;
+  /** Batch mutations endpoint (frappe_live.api.batch_mutations) */
+  batchMutations?: string;
+  /** CDC list_since endpoint (frappe_live.api.list_since) */
+  listSince?: string;
+};
+
+/**
+ * Configuration for frappe_live extension endpoints
+ */
+export interface FrappeLiveConfig {
+  /** Custom Frappe app name for extension endpoints (default: 'frappe_live') */
+  appName?: string;
+  /** Custom endpoints to override default frappe_live endpoints */
+  customEndpoints?: CustomEndpoints;
+}
+
+export enum HttpMethod {
+  Delete = "DELETE",
+  Get = "GET",
+  Head = "HEAD",
+  Post = "POST",
+  Put = "PUT",
+}
+
+export class FrappeError extends Error {
+  public readonly status: number;
+  public readonly data?: unknown;
+  constructor(message: string, status: number, data?: unknown) {
+    super(message);
+    this.name = "FrappeError";
+    this.status = status;
+    this.data = data;
+    Object.setPrototypeOf(this, FrappeError.prototype);
+  }
+}
+
+export interface ListOptions {
+  asDict?: boolean;
+  cursor?: string;
+  fields?: readonly string[];
+  filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+  groupBy?: string;
+  limit?: number;
+  limitStart?: number;
+  orFilters?: Array<[string, string, unknown]>;
+  orderBy?: OrderBy;
+}