Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

68.1 KB
Raw Blame
import type { ImportMemosInput, ImportMemosResponse } from "@edgeever/shared/note-import/types";
import type { NotebookUpdateInput } from "@edgeever/shared";
import {
  parsePreparedAiGeneration,
  streamDirectAiGeneration,
} from "./ai-direct-stream";
import { throwIfAborted } from "./abort-signal";

import { createPluginCapabilities } from './plugin-capabilities';
import type {
  CompanionMemory,
  CompanionDiscoverySettings,
  CompanionDiscoverySettingsInput,
  CompanionDiscoveryItem,
  CompanionAction,
  CompanionTurn,
  CompanionTurnInput,
  CompanionTurnResume,
  CompanionEvent,
  CompanionToolExecuteResult,
  ApiToken,
  AuthSession,
  LoginInput,
  LoginDeviceSession,
  InstanceUser,
  CreatedApiToken,
  JsonBackupMemo,
  JsonBackupNotebook,
  JsonBackupAiPrompt,
  JsonBackupRevision,
  MemoDetail,
  MemoEditSession,
  MemoRevision,
  MemoSummary,
  MemoShare,
  NotebookShare,
  PublicNotebookShare,
  NotebookSiteUpdate,
  NotebookSiteSearchResult,
  NotebookSiteExclusions,
  NotebookSiteContents,
  MemoNotebookSite,
  NotebookSiteMemoPreview,
  ManagedMemoShare,
  PublicTableForm,
  TableFormSettings,
  TableFormUpdateInput,
  MemoTemplate,
  ScheduledTask,
  ScheduledTaskRun,
  WorkspaceExtension,
  WorkspaceExtensionUpsertInput,
  Notebook,
  Resource,
  ResourceListItem,
  ResourceStorageSummary,
  ObjectStorageSettings,
  AccountNoteProse,
  NoteProsePatch,
  PublicMemoShare,
  TagSummary,
  TiptapDoc,
  AiSettings,
  AiTranscriptionSettings,
  AiProvider,
  AiTranscriptionStandard,
  AiPromptTemplate,
  AiPromptTemplateCreateInput,
  AiPromptTemplateUpdateInput,
  AiStreamEvent,
  AiGenerateInput,
  InfographicAgentEvent,
  InfographicAgentRequest,
  AiTagSuggestionsRequestInput,
  SyncBootstrapResponse,
  SyncChange,
  SyncChangesResponse,
  DeploymentMetadata,
  PluginAiGenerateRequest,
  PluginPublicFetchRequest,
  PluginPublicFetchResponse,
} from "@edgeever/shared";

export const MAX_SINGLE_REQUEST_UPLOAD_BYTES = 5 * 1024 * 1024;

export type EdgeEverClientRequestContext = {
  path: string;
  token?: string;
};

export type EdgeEverClientOptions = {
  baseUrl?: string | (() => string);
  token?: string | null | (() => string | null | undefined);
  fetch?: typeof fetch;
  /** @deprecated All AI generation now uses client-direct transport. */
  directAiGeneration?: boolean;
  /** @deprecated Use allowAiServerFallback for browser transports. */
  tryDirectAiGeneration?: boolean;
  /** Web only: retry initial network/CORS failures through the instance. */
  allowAiServerFallback?: boolean;
  /** Used only for the model provider request; defaults to `fetch`. */
  providerFetch?: typeof fetch;
  beforeRequest?: (context: EdgeEverClientRequestContext) => void | Promise<void>;
  shouldAttachToken?: (path: string) => boolean;
  onUnauthorized?: (context: EdgeEverClientRequestContext) => void | Promise<void>;
};

export type MultipartResourceUploadSource = {
  filename: string;
  mimeType: string;
  byteSize: number;
  readPart: (start: number, end: number) => Promise<Blob | Uint8Array<ArrayBuffer>>;
  /** Importers use this to distinguish an uncertain commit from a failed part. */
  onBeforeComplete?: () => void | Promise<void>;
  onPartUploaded?: (byteSize: number) => void;
};

export type InstanceHealth = {
  ok: true;
  name: string;
  runtime?: string | null;
  containerImageSource?: "official-ghcr" | "official-cn-mirror" | "custom" | "unknown" | string | null;
  authMode?: string | null;
  build?: string | null;
  deployment?: DeploymentMetadata | null;
  deploymentVersionCreatedAt?: string | null;
  /** Self-hosted images only: when the container image was built. */
  buildCreatedAt?: string | null;
  /** Self-hosted images only: how the container image was built, not how it was deployed. */
  buildProvenance?: DeploymentMetadata | null;
  migration?: string | null;
  storage?: {
    database?: "d1" | "sqlite" | string | null;
    resources?: "r2" | "filesystem" | "s3" | string | null;
  } | null;
  objectStorageProvider?: "builtin" | "s3" | "unknown" | string | null;
};

export type InstanceRelease = {
  version: string;
  changes: Record<string, readonly string[]>;
};

export type MemoFilterMode = "all" | "tagged" | "untagged" | "pinned";
export type MemoSortMode = "updated-desc" | "created-desc" | "title-asc" | "title-desc";

export type ListNotebooksResponse = {
  notebooks: Notebook[];
};

export type ListMemosResponse = {
  memos: MemoSummary[];
  totalCount?: number;
  nextCursor: string | null;
};

export type ListMemoRevisionsResponse = {
  revisions: MemoRevision[];
};

export type ListResourcesResponse = {
  resources: ResourceListItem[];
  summary: ResourceStorageSummary;
};

export type ListTagsResponse = {
  tags: TagSummary[];
};

export type ListApiTokensResponse = {
  apiTokens: ApiToken[];
  availableScopes: string[];
};

export type InstanceStorageUsageResponse = {
  summary: ResourceStorageSummary;
  users: { userId: string; summary: ResourceStorageSummary }[];
};

export type ListUsersResponse = {
  users: InstanceUser[];
};

export type UserResponse = {
  user: InstanceUser;
};

export type ListLoginDeviceSessionsResponse = {
  sessions: LoginDeviceSession[];
};

export type ObjectStorageSettingsResponse = {
  settings: ObjectStorageSettings;
  externalSettings?: ObjectStorageSettings | null;
};

export type MemoResponse = {
  memo: MemoDetail;
};

export type ListTemplatesResponse = {
  templates: MemoTemplate[];
};

export type TemplateResponse = {
  template: MemoTemplate;
};

export type ListScheduledTasksResponse = {
  tasks: ScheduledTask[];
};

export type ListWorkspaceExtensionsResponse = {
  extensions: WorkspaceExtension[];
};

export type WorkspaceExtensionResponse = {
  extension: WorkspaceExtension;
};

export type ScheduledTaskResponse = {
  task: ScheduledTask;
};

export type ScheduledTaskRunResponse = {
  run: ScheduledTaskRun;
};

export type ScheduledTaskRunsResponse = {
  runs: ScheduledTaskRun[];
  totalCount: number;
  nextOffset: number | null;
};

export type ScheduledTaskRunHistoryItem = ScheduledTaskRun & {
  taskName: string;
  pluginId: string;
  ownerPluginId: string | null;
  pluginScheduleKey: string | null;
};

export type ScheduledTaskRunHistoryResponse = {
  runs: ScheduledTaskRunHistoryItem[];
  totalCount: number;
  nextOffset: number | null;
};

export type MemoShareResponse = {
  share: MemoShare | null;
};

export type ListMemoSharesResponse = {
  shares: ManagedMemoShare[];
  nextOffset: number | null;
};

export type PublicMemoShareResponse = {
  share: PublicMemoShare;
};

export type NotebookResponse = {
  notebook: Notebook;
};

export type ResourceResponse = {
  resource: Resource;
};

export type ResourceUploadResponse = {
  upload: {
    id: string;
    resourceId: string;
    partSize: number;
    partCount: number;
    byteSize: number;
    expiresAt: string;
  };
};

export type MarkdownExportPage = {
  memos: MemoDetail[];
  resources: Resource[];
  totalCount?: number;
  nextOffset: number | null;
  nextCursor?: string | null;
};

export type JsonBackupPage = MarkdownExportPage & {
  revisions: JsonBackupRevision[];
};

export type AiProviderCreatePayload = {
  provider: AiProvider;
  displayName: string;
  baseUrl: string;
  apiKey: string;
  isEnabled: boolean;
  initialModelId?: string;
};

export type AiProviderUpdatePayload = {
  provider: AiProvider;
  displayName: string;
  baseUrl: string;
  apiKey?: string;
  isEnabled: boolean;
};

export type AiTranscriptionProviderCreatePayload = {
  provider: AiTranscriptionStandard;
  displayName: string;
  baseUrl: string;
  apiKey: string;
  isEnabled: boolean;
  initialModelId?: string;
};

export type AiTranscriptionProviderUpdatePayload = {
  provider: AiTranscriptionStandard;
  displayName: string;
  baseUrl: string;
  apiKey?: string;
  isEnabled: boolean;
};

/** @deprecated Use SyncBootstrapResponse; kept for mobile source compatibility. */
export type MobileSyncBootstrapPage = SyncBootstrapResponse;

/** @deprecated Use SyncChange; kept for mobile source compatibility. */
export type MobileSyncChange = SyncChange;

/** @deprecated Use SyncChangesResponse; kept for mobile source compatibility. */
export type MobileSyncChangesPage = SyncChangesResponse;

export class ApiRequestError extends Error {
  status: number;
  code?: string;
  details?: unknown;
  responseDiagnostics?: ApiResponseDiagnostics;

  constructor(
    message: string,
    status: number,
    code?: string,
    details?: unknown,
    responseDiagnostics?: ApiResponseDiagnostics,
  ) {
    super(message);
    this.name = "ApiRequestError";
    this.status = status;
    this.code = code;
    this.details = details;
    this.responseDiagnostics = responseDiagnostics;
  }
}

export type ApiResponseDiagnostics = {
  cloudflareMitigated: boolean;
  isEdgeEverApiError: boolean;
  rayId?: string;
};

export type { SyncBootstrapResponse, SyncChangesResponse };

export const createEdgeEverClient = (options: EdgeEverClientOptions = {}) => {
  const getFetch = () => options.fetch ?? globalThis.fetch;
  const providerFetch = (): typeof fetch => async (url, init) => {
    const directFetch = options.providerFetch ?? getFetch();
    if (!options.allowAiServerFallback) return directFetch(url, { ...init, credentials: "omit", redirect: "error" });
    const { fetchAiWithServerFallback } = await import("./ai-provider-relay");
    return fetchAiWithServerFallback(url, init, directFetch, async target => {
      const { response } = await send("/api/v1/ai/provider-relay", {
        method: "POST",
        headers: {
          "Content-Type": "application/octet-stream",
          "x-edgeever-ai-target": target.url,
          "x-edgeever-ai-method": target.method,
          "x-edgeever-ai-headers": JSON.stringify(Object.fromEntries(target.headers)),
        },
        body: target.method === "GET" ? undefined : await target.arrayBuffer(),
        signal: target.signal,
      });
      return response;
    });
  };
  const getBaseUrl = () => normalizeBaseUrl(
    typeof options.baseUrl === "function" ? options.baseUrl() : options.baseUrl,
  );
  const getToken = () => {
    const token = typeof options.token === "function" ? options.token() : options.token;
    return token || undefined;
  };

  const send = async (
    path: string,
    init?: RequestInit,
    requestOptions?: { attachToken?: boolean; setJsonContentType?: boolean },
  ) => {
    const token = getToken();
    const context: EdgeEverClientRequestContext = { path, ...(token ? { token } : {}) };
    await options.beforeRequest?.(context);

    const headers = new Headers(init?.headers);
    const attachToken = requestOptions?.attachToken
      ?? options.shouldAttachToken?.(path)
      ?? true;

    if (token && attachToken && !headers.has("Authorization")) {
      headers.set("Authorization", `Bearer ${token}`);
    }

    if (
      requestOptions?.setJsonContentType !== false
      && !(init?.body instanceof FormData)
      && !headers.has("Content-Type")
    ) {
      headers.set("Content-Type", "application/json");
    }

    const requestUrl = isAbsoluteHttpUrl(path) ? path : `${getBaseUrl()}${path}`;
    const response = await getFetch()(requestUrl, {
      credentials: "include",
      ...init,
      headers,
    });

    return { context, response };
  };

  const throwRequestError = async (
    context: EdgeEverClientRequestContext,
    response: Response,
    fallbackMessage = "Request failed",
  ): Promise<never> => {
    const body = await response.json().catch(() => null);
    const rayId = response.headers.get("cf-ray")?.trim();
    const error =
      body && typeof body === "object" && "error" in body
        ? (body as { error?: { code?: string; message?: string; details?: unknown } }).error
        : undefined;
    const responseDiagnostics: ApiResponseDiagnostics = {
      cloudflareMitigated: response.headers.get("cf-mitigated") === "challenge",
      isEdgeEverApiError: Boolean(error && typeof error === "object"),
      ...(rayId ? { rayId } : {}),
    };

    if (response.status === 401) {
      void options.onUnauthorized?.(context);
    }

    throw new ApiRequestError(
      error?.message || response.statusText || fallbackMessage,
      response.status,
      error?.code,
      error?.details,
      responseDiagnostics,
    );
  };

  const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
    const { context, response } = await send(path, init);

    if (!response.ok) {
      await throwRequestError(context, response);
    }

    return response.json() as Promise<T>;
  };

  const requestPluginPublic = async (input: PluginPublicFetchRequest, signal?: AbortSignal): Promise<PluginPublicFetchResponse> => {
    const { context, response } = await send("/api/v1/plugins/network/fetch", {
      method: "POST",
      body: JSON.stringify(input),
      signal,
    });
    const upstreamStatus = response.headers.get("x-edgeever-upstream-status");
    if (!response.ok || !upstreamStatus) await throwRequestError(context, response, "Public network request failed");
    const status = Number(upstreamStatus);
    if (!Number.isInteger(status) || status < 100 || status > 599) throw new Error("Invalid public network response status");
    const headers: Record<string, string> = {};
    for (const [key, value] of response.headers) {
      const prefix = "x-edgeever-upstream-header-";
      if (key.startsWith(prefix)) headers[key.slice(prefix.length)] = value;
    }
    return {
      url: input.url,
      status,
      statusText: decodeURIComponent(response.headers.get("x-edgeever-upstream-status-text") ?? ""),
      headers,
      body: await response.arrayBuffer(),
    };
  };

  const requestResourceResponse = async (path: string, init?: RequestInit) => {
    const isAbsolute = isAbsoluteHttpUrl(path);
    const { context, response } = await send(path, init, {
      attachToken: !isAbsolute,
      setJsonContentType: false,
    });
    if (!response.ok) await throwRequestError(context, response, "Resource download failed");
    return response;
  };

  const requestBlob = async (path: string) => (await requestResourceResponse(path)).blob();

  const requestArrayBuffer = async (path: string) => {
    const { context, response } = await send(path, undefined, { setJsonContentType: false });
    if (!response.ok) await throwRequestError(context, response, "Binary download failed");
    return response.arrayBuffer();
  };

  const uploadMemoResourceParts = async (memoId: string, source: MultipartResourceUploadSource) => {
    const filename = source.filename.trim() || "attachment";
    const mimeType = source.mimeType || "application/octet-stream";
    const { upload } = await request<ResourceUploadResponse>(
      `/api/v1/memos/${encodeURIComponent(memoId)}/resource-uploads`,
      {
        method: "POST",
        body: JSON.stringify({ filename, mimeType, byteSize: source.byteSize }),
      },
    );

    try {
      for (let partNumber = 1; partNumber <= upload.partCount; partNumber += 1) {
        const start = (partNumber - 1) * upload.partSize;
        const chunk = await source.readPart(start, Math.min(start + upload.partSize, source.byteSize));
        let attempt = 0;
        while (true) {
          try {
            await request<{ part: { partNumber: number; byteSize: number } }>(
              `/api/v1/resource-uploads/${encodeURIComponent(upload.id)}/parts/${partNumber}`,
              {
                method: "PUT",
                headers: { "Content-Type": "application/octet-stream" },
                body: chunk,
              },
            );
            source.onPartUploaded?.(Math.min(partNumber * upload.partSize, source.byteSize));
            break;
          } catch (error) {
            attempt += 1;
            const retryable = !(error instanceof ApiRequestError)
              || error.status === 408
              || error.status === 429
              || error.status >= 500;
            if (!retryable || attempt >= 3) throw error;
            await new Promise((resolve) => setTimeout(resolve, attempt * 250));
          }
        }
      }
      await source.onBeforeComplete?.();
      return await request<ResourceResponse>(
        `/api/v1/resource-uploads/${encodeURIComponent(upload.id)}/complete`,
        { method: "POST", body: JSON.stringify({}) },
      );
    } catch (error) {
      await request<{ ok: true }>(`/api/v1/resource-uploads/${encodeURIComponent(upload.id)}`, {
        method: "DELETE",
      }).catch(() => undefined);
      throw error;
    }
  };

  const uploadMemoResourceMultipart = (memoId: string, file: Blob) =>
    uploadMemoResourceParts(memoId, {
      filename: "name" in file && typeof file.name === "string" && file.name.trim()
        ? file.name
        : "attachment",
      mimeType: file.type || "application/octet-stream",
      byteSize: file.size,
      readPart: async (start, end) => file.slice(start, end),
    });

  const createResourceMultipartSink = (upload: ResourceUploadResponse["upload"]) => {
    let partNumber = 1;
    let bufferedBytes = 0;
    let receivedBytes = 0;
    let chunks: ArrayBuffer[] = [];
    let closed = false;

    const abort = async () => {
      if (closed) return;
      closed = true;
      chunks = [];
      bufferedBytes = 0;
      await request<{ ok: true }>(`/api/v1/resource-uploads/${encodeURIComponent(upload.id)}`, {
        method: "DELETE",
      }).catch(() => undefined);
    };

    const sendPart = async () => {
      if (bufferedBytes === 0) return;
      const body = new Blob(chunks, { type: "application/octet-stream" });
      const currentPart = partNumber;
      chunks = [];
      bufferedBytes = 0;
      let attempt = 0;
      while (true) {
        try {
          await request<{ part: { partNumber: number; byteSize: number } }>(
            `/api/v1/resource-uploads/${encodeURIComponent(upload.id)}/parts/${currentPart}`,
            {
              method: "PUT",
              headers: { "Content-Type": "application/octet-stream" },
              body,
            },
          );
          partNumber += 1;
          return;
        } catch (error) {
          attempt += 1;
          const retryable = !(error instanceof ApiRequestError)
            || error.status === 408
            || error.status === 429
            || error.status >= 500;
          if (!retryable || attempt >= 3) throw error;
          await new Promise((resolve) => setTimeout(resolve, attempt * 250));
        }
      }
    };

    return {
      write: async (chunk: Uint8Array) => {
        if (closed) throw new Error("Resource restore upload is closed");
        let offset = 0;
        while (offset < chunk.byteLength) {
          const available = upload.partSize - bufferedBytes;
          const length = Math.min(available, chunk.byteLength - offset);
          const copy = new Uint8Array(length);
          copy.set(chunk.subarray(offset, offset + length));
          chunks.push(copy.buffer);
          bufferedBytes += length;
          receivedBytes += length;
          offset += length;
          if (bufferedBytes === upload.partSize) await sendPart();
        }
      },
      close: async () => {
        if (closed) throw new Error("Resource restore upload is closed");
        if (receivedBytes !== upload.byteSize) {
          await abort();
          throw new Error(`Resource restore size mismatch: expected ${upload.byteSize}, received ${receivedBytes}`);
        }
        try {
          await sendPart();
          const result = await request<ResourceResponse>(
            `/api/v1/resource-uploads/${encodeURIComponent(upload.id)}/complete`,
            { method: "POST", body: JSON.stringify({}) },
          );
          closed = true;
          return result;
        } catch (error) {
          await abort();
          throw error;
        }
      },
      abort,
    };
  };

  const createJsonResourceRestoreSink = async (
    resourceId: string,
    metadata: JsonBackupMemo["resources"][number],
  ) => {
    const { upload } = await request<ResourceUploadResponse>(
      `/api/v1/restores/json/resources/${encodeURIComponent(resourceId)}/uploads`,
      { method: "POST", body: JSON.stringify(metadata) },
    );
    return createResourceMultipartSink(upload);
  };

  const runPreparedCompanion = async (
    prepared: import("@edgeever/shared").CompanionPreparedTurn,
    streamOptions: { signal?: AbortSignal; onEvent: (event: CompanionEvent) => void },
  ) => {
    const { streamDirectCompanion } = await import("./companion-direct-stream");
    const turnId = prepared.turn.id;
    await streamDirectCompanion(prepared, {
      fetch: providerFetch(),
      signal: streamOptions.signal,
      onEvent: streamOptions.onEvent,
      executeTool: (body) => request<CompanionToolExecuteResult>(
        `/api/v1/companion/turns/${encodeURIComponent(turnId)}/tools`,
        { method: "POST", body: JSON.stringify(body), signal: streamOptions.signal },
      ),
      checkpoint: (body) => request(
        `/api/v1/companion/turns/${encodeURIComponent(turnId)}/checkpoint`,
        { method: "POST", body: JSON.stringify(body), signal: streamOptions.signal },
      ),
      complete: (body) => request<{ turn: CompanionTurn }>(
        `/api/v1/companion/turns/${encodeURIComponent(turnId)}/complete`,
        { method: "POST", body: JSON.stringify(body), signal: streamOptions.signal },
      ),
    });
  };

  const directAiUnavailable = () => new ApiRequestError(
    "This instance does not support direct AI preparation. Update the instance before using AI.",
    409,
    "ai_direct_unavailable",
  );

  const runCompanionDirect = async (
    preparePath: string,
    payload: unknown,
    streamOptions: { signal?: AbortSignal; onEvent: (event: CompanionEvent) => void },
  ) => {
    throwIfAborted(streamOptions.signal);
    const { context, response } = await send(preparePath, {
      method: "POST", body: JSON.stringify(payload), signal: streamOptions.signal,
    });
    if (response.status === 404 || response.status === 410) throw directAiUnavailable();
    if (!response.ok) await throwRequestError(context, response);
    const { parsePreparedCompanion } = await import("./companion-direct-stream");
    const prepared = parsePreparedCompanion(await response.json());
    if (!prepared) throw new ApiRequestError("The companion prepare response is invalid", 502, "companion_failed");
    await runPreparedCompanion(prepared, streamOptions);
  };

  const runDirectAi = async <T, P>(args: {
    signal?: AbortSignal;
    prepare: () => Promise<P | null>;
    run: (prepared: P) => Promise<T>;
  }): Promise<T> => {
    throwIfAborted(args.signal);
    const prepared = await args.prepare();
    if (prepared == null) throw directAiUnavailable();
    throwIfAborted(args.signal);
    return args.run(prepared);
  };

  const pluginCapabilities = createPluginCapabilities(request, requestPluginPublic);

  return {
    fetchAiProvider: providerFetch(),
    getInstanceHealth: () => request<InstanceHealth>("/api/health"),
    ...pluginCapabilities,
    pluginAi: {
      status: pluginCapabilities.pluginAi.status,
      generate: async (input: PluginAiGenerateRequest & { signal?: AbortSignal }) => {
        const { signal, ...payload } = input;
        return runDirectAi({
          signal,
          prepare: async () => {
            const { context, response } = await send("/api/v1/plugins/ai/generate/prepare", {
              method: "POST", body: JSON.stringify(payload), signal,
            });
            if (response.ok) {
              const { parsePreparedAiText } = await import("./ai-direct-generate");
              const prepared = parsePreparedAiText(await response.json());
              if (!prepared) throw new ApiRequestError("The AI prepare response is invalid", 502, "plugin_ai_failed");
              return prepared;
            }
            if (response.status !== 404) await throwRequestError(context, response);
            return null;
          },
          run: async (prepared) => {
            const { generateDirectAiText } = await import("./ai-direct-generate");
            return { text: await generateDirectAiText(prepared, { fetch: providerFetch(), signal }) };
          },
        });
      },
    },

    getInstanceRelease: () => request<InstanceRelease>("/api/release"),

    getSession: () => request<AuthSession>("/api/v1/auth/session"),

    getPublicNotebookShare: (token: string) =>
      request<{ share: PublicNotebookShare }>(`/api/public/notebook-shares/${encodeURIComponent(token)}`),
    resolveNotebookSite: (slug: string) => request<{ token: string }>(`/api/public/notebook-sites/${encodeURIComponent(slug)}/resolve`),
    searchPublicNotebook: (token: string, input: { q?: string; tag?: string; cursor?: string | null }) => {
      const params = new URLSearchParams();
      if (input.q) params.set("q", input.q);
      if (input.tag) params.set("tag", input.tag);
      if (input.cursor) params.set("cursor", input.cursor);
      return request<NotebookSiteSearchResult>(`/api/public/notebook-shares/${encodeURIComponent(token)}/search?${params}`);
    },
    previewPublicNotebookMemo: (token: string, memoId: string) => request<{ memo: NotebookSiteMemoPreview }>(`/api/public/notebook-shares/${encodeURIComponent(token)}/memos/${encodeURIComponent(memoId)}/preview`),
    updateNotebookSite: (id: string, input: NotebookSiteUpdate) => request<{ share: NotebookShare }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share/site`, { method: "PATCH", body: JSON.stringify(input) }),
    getMemoNotebookSites: (memoId: string) => request<{ sites: MemoNotebookSite[] }>(`/api/v1/memos/${encodeURIComponent(memoId)}/notebook-sites`),
    listNotebookSiteMemos: (id: string, input: { q?: string; visibility?: "all" | "public" | "excluded"; cursor?: string | null; limit?: number }) => {
      const params = new URLSearchParams();
      if (input.q) params.set("q", input.q);
      if (input.visibility) params.set("visibility", input.visibility);
      if (input.cursor) params.set("cursor", input.cursor);
      if (input.limit !== undefined) params.set("limit", String(input.limit));
      return request<NotebookSiteContents>(`/api/v1/notebooks/${encodeURIComponent(id)}/share/memos?${params}`);
    },
    listNotebookSiteExclusions: (id: string, cursor?: string | null) => request<NotebookSiteExclusions>(`/api/v1/notebooks/${encodeURIComponent(id)}/share/excluded-memos${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`),
    setNotebookSiteExclusion: (id: string, memoId: string, excluded: boolean) => request<{ memoId: string; excluded: boolean }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share/memos/${encodeURIComponent(memoId)}`, { method: "PATCH", body: JSON.stringify({ excluded }) }),
    getPublicNotebookMemo: (token: string, memoId: string) =>
      request<{ share: PublicMemoShare; memoUrls: Record<string, string> }>(`/api/public/notebook-shares/${encodeURIComponent(token)}/memos/${encodeURIComponent(memoId)}`),
    unlockPublicNotebookShare: (token: string, password: string) =>
      request<{ ok: true }>(`/api/public/notebook-shares/${encodeURIComponent(token)}/unlock`, { method: "POST", body: JSON.stringify({ password }) }),
    updateNotebookShare: (id: string, input: { passwordProtected: boolean }) =>
      request<{ share: NotebookShare }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share`, { method: "PATCH", body: JSON.stringify(input) }),
    listNotebookShares: () => request<{ shares: NotebookShare[] }>("/api/v1/notebook-shares"),
    getNotebookShare: (id: string) => request<{ share: NotebookShare | null }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share`),
    createNotebookShare: (id: string) => request<{ share: NotebookShare }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share`, { method: "POST" }),
    revokeNotebookShare: (id: string) => request<{ ok: true }>(`/api/v1/notebooks/${encodeURIComponent(id)}/share`, { method: "DELETE" }),

    getPublicMemoShare: (token: string) =>
      request<PublicMemoShareResponse>(`/api/public/shares/${encodeURIComponent(token)}`),

    updatePublishedNoteBodyFont: (bodyFont: PublicMemoShare["bodyFont"]) =>
      request<{ bodyFont: PublicMemoShare["bodyFont"] }>("/api/v1/me/note-body-font", {
        method: "PUT",
        body: JSON.stringify({ bodyFont }),
      }),

    getNoteProse: () => request<AccountNoteProse>("/api/v1/me/note-prose"),

    updateNoteProse: (patch: NoteProsePatch) =>
      request<AccountNoteProse>("/api/v1/me/note-prose", {
        method: "PUT",
        body: JSON.stringify(patch),
      }),

    unlockPublicMemoShare: (token: string, password: string) =>
      request<{ ok: true }>(`/api/public/shares/${encodeURIComponent(token)}/unlock`, {
        method: "POST",
        body: JSON.stringify({ password }),
      }),

    listLoginDeviceSessions: () =>
      request<ListLoginDeviceSessionsResponse>("/api/v1/auth/sessions"),

    revokeLoginDeviceSession: (sessionId: string) =>
      request<{ ok: true }>(`/api/v1/auth/sessions/${sessionId}`, { method: "DELETE" }),

    updateLoginDeviceSession: (sessionId: string, payload: { label: string | null }) =>
      request<{ ok: true }>(`/api/v1/auth/sessions/${sessionId}`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    revokeOtherLoginDeviceSessions: () =>
      request<{ ok: true }>("/api/v1/auth/sessions", { method: "DELETE" }),

    login: (payload: LoginInput) =>
      request<AuthSession>("/api/v1/auth/login", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    changePassword: (payload: { currentPassword: string; newPassword: string; confirmPassword: string }) =>
      request<{ ok: true }>("/api/v1/auth/change-password", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    getObjectStorageSettings: () =>
      request<ObjectStorageSettingsResponse>("/api/v1/instance/object-storage"),

    testObjectStorageConnection: (payload: {
      endpoint: string;
      region: string;
      bucket: string;
      accessKeyId: string;
      secretAccessKey?: string;
      forcePathStyle: boolean;
      objectPrefix: string;
    }) => request<{ ok: true }>("/api/v1/instance/object-storage/test", {
      method: "POST",
      body: JSON.stringify(payload),
    }),

    updateObjectStorageSettings: (payload:
      | { provider: "builtin" }
      | {
          provider: "s3";
          displayName: string;
          endpoint: string;
          region: string;
          bucket: string;
          accessKeyId: string;
          secretAccessKey?: string;
          forcePathStyle: boolean;
          objectPrefix: string;
        }) => request<ObjectStorageSettingsResponse>("/api/v1/instance/object-storage", {
      method: "PUT",
      body: JSON.stringify(payload),
    }),

    getAiSettings: (locale?: string) => {
      const search = locale ? `?locale=${encodeURIComponent(locale)}` : "";
      return request<AiSettings>(`/api/v1/ai/settings${search}`);
    },

    getAiTranscriptionSettings: () =>
      request<AiTranscriptionSettings>("/api/v1/ai/transcription-settings"),

    createAiTranscriptionProvider: (payload: AiTranscriptionProviderCreatePayload) =>
      request<AiTranscriptionSettings>("/api/v1/ai/transcription-providers", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    updateAiTranscriptionProvider: (providerId: string, payload: AiTranscriptionProviderUpdatePayload) =>
      request<AiTranscriptionSettings>(`/api/v1/ai/transcription-providers/${encodeURIComponent(providerId)}`, {
        method: "PUT",
        body: JSON.stringify(payload),
      }),

    deleteAiTranscriptionProvider: (providerId: string) =>
      request<AiTranscriptionSettings>(`/api/v1/ai/transcription-providers/${encodeURIComponent(providerId)}`, {
        method: "DELETE",
      }),

    addAiTranscriptionModel: (providerId: string, payload: { modelId: string; displayName?: string }) =>
      request<AiTranscriptionSettings>(`/api/v1/ai/transcription-providers/${encodeURIComponent(providerId)}/models`, {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    deleteAiTranscriptionModel: (providerId: string, modelConfigId: string) =>
      request<AiTranscriptionSettings>(
        `/api/v1/ai/transcription-providers/${encodeURIComponent(providerId)}/models/${encodeURIComponent(modelConfigId)}`,
        { method: "DELETE" },
      ),

    updateDefaultAiTranscriptionModel: (modelConfigId: string | null) =>
      request<AiTranscriptionSettings>("/api/v1/ai/transcription-default-model", {
        method: "PUT",
        body: JSON.stringify({ modelConfigId }),
      }),

    prepareNoteResourceTranscription: (memoId: string, resourceId: string, signal?: AbortSignal) =>
      request<{ baseUrl: string; modelId: string; apiKey: string; resourceId: string; filename: string }>(
        `/api/v1/memos/${encodeURIComponent(memoId)}/resources/${encodeURIComponent(resourceId)}/transcription-target`,
        { method: "POST", signal },
      ),

    getAiTranscriptionDirectCredential: (providerId: string, signal?: AbortSignal) =>
      request<{ apiKey: string }>(
        `/api/v1/ai/transcription-providers/${encodeURIComponent(providerId)}/direct-credential`,
        { method: "POST", signal },
      ),

    createAiProvider: (payload: AiProviderCreatePayload) =>
      request<AiSettings>("/api/v1/ai/providers", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    updateAiProvider: (providerConfigId: string, payload: AiProviderUpdatePayload) =>
      request<AiSettings>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}`, {
        method: "PUT",
        body: JSON.stringify(payload),
      }),

    deleteAiProvider: (providerConfigId: string) =>
      request<AiSettings>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}`, {
        method: "DELETE",
      }),

    testAiProvider: async (providerConfigId: string, payload: { modelId: string; provider?: AiProvider; baseUrl?: string; apiKey?: string }) => {
      const prepared = await request<import("@edgeever/shared").AiPreparedTextGeneration>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}/direct-credential`, { method: "POST", body: JSON.stringify(payload) });
      const { generateDirectAiText } = await import("./ai-direct-generate");
      const text = await generateDirectAiText({ ...prepared, system: "Follow the user instruction exactly.", prompt: "Reply with only: OK", maxOutputTokens: 16 }, { fetch: providerFetch(), signal: AbortSignal.timeout(20_000) });
      return { ok: true, response: text.trim() };
    },
    discoverAiProviderModels: async (providerConfigId: string) => {
      const prepared = await request<{ provider: AiProvider; baseUrl: string; apiKey: string }>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}/direct-credential`, { method: "POST", body: "{}" });
      const { discoverAiModels } = await import("./ai-provider-direct");
      return { models: await discoverAiModels(prepared, providerFetch()) };
    },

    addAiModel: (providerConfigId: string, payload: { modelId: string; displayName?: string }) =>
      request<AiSettings>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}/models`, {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    deleteAiModel: (providerConfigId: string, modelConfigId: string) =>
      request<AiSettings>(`/api/v1/ai/providers/${encodeURIComponent(providerConfigId)}/models/${encodeURIComponent(modelConfigId)}`, {
        method: "DELETE",
      }),

    updateDefaultAiModel: (modelConfigId: string | null) =>
      request<AiSettings>("/api/v1/ai/default-model", {
        method: "PUT",
        body: JSON.stringify({ modelConfigId }),
      }),

    listAiPrompts: (locale?: string) => {
      const search = locale ? `?locale=${encodeURIComponent(locale)}` : "";
      return request<{ prompts: AiPromptTemplate[] }>(`/api/v1/ai/prompts${search}`);
    },

    createAiPrompt: (payload: AiPromptTemplateCreateInput) =>
      request<{ prompt: AiPromptTemplate }>("/api/v1/ai/prompts", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    updateAiPrompt: (
      promptId: string,
      payload: AiPromptTemplateUpdateInput,
    ) =>
      request<{ prompt: AiPromptTemplate }>(`/api/v1/ai/prompts/${encodeURIComponent(promptId)}`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    deleteAiPrompt: (promptId: string) =>
      request<{ ok: true }>(`/api/v1/ai/prompts/${encodeURIComponent(promptId)}`, {
        method: "DELETE",
      }),

    restoreDefaultAiPrompts: (locale?: string) => {
      const search = locale ? `?locale=${encodeURIComponent(locale)}` : "";
      return request<{ prompts: AiPromptTemplate[]; restoredCount: number }>(`/api/v1/ai/prompts/restore-defaults${search}`, {
        method: "POST",
        body: JSON.stringify({}),
      });
    },

    suggestAiTags: (payload: AiTagSuggestionsRequestInput, signal?: AbortSignal) =>
      runDirectAi({
        signal,
        prepare: async () => {
          const { context, response } = await send("/api/v1/ai/tag-suggestions/prepare", {
            method: "POST", body: JSON.stringify(payload), signal,
          });
          if (response.ok) {
            const { parsePreparedTagSuggestions } = await import("./ai-direct-generate");
            const prepared = parsePreparedTagSuggestions(await response.json());
            if (!prepared) throw new ApiRequestError("The AI prepare response is invalid", 502, "ai_tag_suggestions_failed");
            return prepared;
          }
          if (response.status !== 404) await throwRequestError(context, response);
          return null;
        },
        run: async (prepared) => {
          const { generateDirectAiText, suggestionsFromDirectText } = await import("./ai-direct-generate");
          const text = await generateDirectAiText(prepared, { fetch: providerFetch(), signal });
          return { suggestions: suggestionsFromDirectText(text, prepared) };
        },
      }),

    listCompanionMemories: () => request<{ memories: CompanionMemory[] }>("/api/v1/companion/memories"),
    getCompanionDiscoverySettings: () => request<{ settings: CompanionDiscoverySettings }>("/api/v1/companion/discovery/settings"),
    saveCompanionDiscoverySettings: (input: CompanionDiscoverySettingsInput) => request<{ settings: CompanionDiscoverySettings }>("/api/v1/companion/discovery/settings", { method: "PUT", body: JSON.stringify(input) }),
    listCompanionDiscoveries: () => request<{ items: CompanionDiscoveryItem[] }>("/api/v1/companion/discovery"),
    checkCompanionDiscoveries: (locale: string, signal?: AbortSignal) =>
      runDirectAi({
        signal,
        prepare: async () => {
          const { context, response } = await send(
            `/api/v1/companion/discovery/check/prepare?locale=${encodeURIComponent(locale)}`,
            { method: "POST", body: "{}", signal },
          );
          if (response.ok) {
            const { parsePreparedDiscovery } = await import("./ai-direct-generate");
            const prepared = parsePreparedDiscovery(await response.json());
            if (!prepared) throw new ApiRequestError("The companion prepare response is invalid", 502, "companion_failed");
            return prepared;
          }
          if (response.status !== 404) await throwRequestError(context, response);
          return null;
        },
        run: async (prepared) => {
          if (prepared.quiet) return { items: prepared.items };
          const { generateDirectDiscoveryOutput } = await import("./ai-direct-generate");
          const output = await generateDirectDiscoveryOutput(prepared, { fetch: providerFetch(), signal });
          return request<{ items: CompanionDiscoveryItem[] }>("/api/v1/companion/discovery/check/complete", {
            method: "POST", body: JSON.stringify({ turnId: prepared.turnId, output }), signal,
          });
        },
      }),
    acknowledgeCompanionDiscovery: (id: string, dismiss = false) => request<{ ok: true }>(`/api/v1/companion/discovery/${encodeURIComponent(id)}/${dismiss ? "dismiss" : "seen"}`, { method: "POST", body: "{}" }),
    rememberCompanionDiscoveryFeedback: (id: string) => request<{ ok: true }>(`/api/v1/companion/discovery/${encodeURIComponent(id)}/feedback`, { method: "POST", body: "{}" }),
    listCompanionActions: () => request<{ actions: CompanionAction[] }>("/api/v1/companion/actions"),
    applyCompanionAction: (id: string) => request<{ action: CompanionAction }>(`/api/v1/companion/actions/${encodeURIComponent(id)}/apply`, { method: "POST", body: "{}" }),
    dismissCompanionAction: (id: string) => request<{ action: CompanionAction }>(`/api/v1/companion/actions/${encodeURIComponent(id)}/dismiss`, { method: "POST", body: "{}" }),
    saveCompanionMemory: (content: string, sourceTurnId?: string) => request<{ memory: CompanionMemory }>("/api/v1/companion/memories", {
      method: "POST", body: JSON.stringify({ content, sourceTurnId }),
    }),
    updateCompanionMemory: (memory: CompanionMemory, content: string) => request<{ memory: CompanionMemory }>(`/api/v1/companion/memories/${encodeURIComponent(memory.id)}`, {
      method: "PATCH", body: JSON.stringify({ content, version: memory.version }),
    }),
    forgetCompanionMemory: (memory: CompanionMemory) => request<{ ok: true }>(`/api/v1/companion/memories/${encodeURIComponent(memory.id)}?version=${memory.version}`, { method: "DELETE" }),
    listCompanionTurns: () => request<{ turns: CompanionTurn[] }>("/api/v1/companion/turns"),
    getCompanionTurn: (id: string) => request<{ turn: CompanionTurn }>(`/api/v1/companion/turns/${encodeURIComponent(id)}`),
    cancelCompanionTurn: (id: string) => request<{ ok: true }>(`/api/v1/companion/turns/${encodeURIComponent(id)}/cancel`, { method: "POST", body: "{}" }),
    resumeCompanionTurn: async (id: string, payload: CompanionTurnResume = {}, options: { signal?: AbortSignal; onEvent: (event: CompanionEvent) => void }) => {
      await runCompanionDirect(`/api/v1/companion/turns/${encodeURIComponent(id)}/resume/prepare`, payload, options);
    },
    clearCompanionHistory: () => request<{ ok: true }>("/api/v1/companion/history", { method: "DELETE" }),
    uploadCompanionAttachment: (attachment: { filename: string; mediaType: string; base64Data: string }) =>
      request<{ attachment: { id: string; filename: string; mediaType: string; byteLength: number; expiresAt: string } }>(
        "/api/v1/companion/attachments",
        { method: "POST", body: JSON.stringify(attachment) },
      ),
    exportCompanion: () => request<{ version: 2; controls: { useMemory: boolean; learningEnabled: boolean }; exportedAt: string; memories: CompanionMemory[]; turns: CompanionTurn[]; actions: CompanionAction[] }>("/api/v1/companion/export"),
    importCompanionMemories: (memories: { content: string; kind?: "explicit" | "inferred" }[], controls?: { useMemory: boolean; learningEnabled: boolean }) => request<{ memories: CompanionMemory[] }>("/api/v1/companion/import-memories", {
      method: "POST", body: JSON.stringify({ version: 2, memories, controls }),
    }),
    streamCompanion: async (payload: CompanionTurnInput, streamOptions: { signal?: AbortSignal; onEvent: (event: CompanionEvent) => void }) => {
      await runCompanionDirect("/api/v1/companion/turns/prepare", payload, streamOptions);
    },

    streamInfographicAgent: async (payload: InfographicAgentRequest, streamOptions: { signal?: AbortSignal; onEvent: (event: InfographicAgentEvent) => void }) => {
      const prepared = await request<import("@edgeever/shared").AiPreparedTextGeneration>("/api/v1/ai/infographic-agent/prepare", {
        method: "POST", body: JSON.stringify(payload), signal: streamOptions.signal,
      });
      const { runInfographicAgent } = await import("./infographic-direct");
      const { createClientAiModel } = await import("./ai-model");
      await runInfographicAgent({ input: payload, model: createClientAiModel({ ...prepared, fetch: providerFetch() }),
        signal: streamOptions.signal ?? new AbortController().signal, onEvent: streamOptions.onEvent });
    },

    streamAiGeneration: async (payload: AiGenerateInput, streamOptions: { signal?: AbortSignal; onEvent: (event: AiStreamEvent) => void }) => {
      throwIfAborted(streamOptions.signal);
      const { context, response } = await send("/api/v1/ai/generate/prepare", {
        method: "POST", body: JSON.stringify(payload), signal: streamOptions.signal,
      });
      if (response.status === 404 || response.status === 410) throw directAiUnavailable();
      if (!response.ok) await throwRequestError(context, response);
      const prepared = parsePreparedAiGeneration(await response.json());
      if (!prepared) throw new ApiRequestError("The AI prepare response is invalid", 502, "ai_generation_failed");
      await streamDirectAiGeneration(prepared, payload.attachments, { fetch: providerFetch(), ...streamOptions });
    },

    listUsers: () => request<ListUsersResponse>("/api/v1/users"),

    getInstanceStorageUsage: () => request<InstanceStorageUsageResponse>("/api/v1/instance/storage-usage"),

    createUser: (payload: { username: string; displayName?: string | null; password: string }) =>
      request<UserResponse>("/api/v1/users", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    updateUser: (userId: string, payload: { displayName?: string | null; password?: string; isDisabled?: boolean }) =>
      request<UserResponse>(`/api/v1/users/${userId}`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    logout: () =>
      request<{ ok: true }>("/api/v1/auth/logout", {
        method: "POST",
        body: JSON.stringify({}),
      }),

    listNotebooks: () => request<ListNotebooksResponse>("/api/v1/notebooks"),

    syncBootstrap: (params?: { afterId?: string | null; limit?: number }) => {
      const search = new URLSearchParams();
      if (params?.afterId) {
        search.set("afterId", params.afterId);
        search.set("includeMetadata", "0");
      }
      if (params?.limit) search.set("limit", String(params.limit));
      const suffix = search.toString() ? `?${search.toString()}` : "";
      return request<SyncBootstrapResponse>(`/api/v1/sync/bootstrap${suffix}`);
    },

    syncChanges: (params: { cursor: number; limit?: number }) => {
      const search = new URLSearchParams({ cursor: String(params.cursor) });
      if (params.limit) search.set("limit", String(params.limit));
      return request<SyncChangesResponse>(`/api/v1/sync/changes?${search.toString()}`);
    },

    getMobileSyncBootstrapPage: (afterId: string | null = null, limit = 100) => {
      const search = new URLSearchParams({ limit: String(limit) });
      if (afterId) {
        search.set("afterId", afterId);
        search.set("includeMetadata", "0");
      }
      return request<MobileSyncBootstrapPage>(`/api/v1/sync/bootstrap?${search.toString()}`);
    },

    getMobileSyncChanges: (cursor: number, limit = 100) =>
      request<MobileSyncChangesPage>(`/api/v1/sync/changes?cursor=${cursor}&limit=${limit}`),

    createNotebook: (payload: { name: string; parentId?: string | null }) =>
      request<NotebookResponse>("/api/v1/notebooks", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    updateNotebook: (notebookId: string, payload: NotebookUpdateInput) =>
      request<NotebookResponse>(`/api/v1/notebooks/${notebookId}`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    deleteNotebook: (notebookId: string) =>
      request<{ ok: true }>(`/api/v1/notebooks/${notebookId}`, {
        method: "DELETE",
      }),

    restoreNotebook: (notebookId: string) =>
      request<NotebookResponse>(`/api/v1/notebooks/${notebookId}/restore`, {
        method: "POST",
      }),

    listTags: () => request<ListTagsResponse>("/api/v1/tags"),

    renameTag: (tag: string, name: string) =>
      request<{ ok: true; updated: number }>(`/api/v1/tags/${encodeURIComponent(tag)}`, {
        method: "PATCH",
        body: JSON.stringify({ name }),
      }),

    deleteTag: (tag: string) =>
      request<{ ok: true; updated: number }>(`/api/v1/tags/${encodeURIComponent(tag)}`, {
        method: "DELETE",
      }),

    listApiTokens: () => request<ListApiTokensResponse>("/api/v1/api-tokens"),

    createApiToken: (payload: { name: string; scopes: string[]; expiresAt?: string | null }) =>
      request<CreatedApiToken>("/api/v1/api-tokens", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    revokeApiToken: (tokenId: string) =>
      request<{ ok: true }>(`/api/v1/api-tokens/${tokenId}`, {
        method: "DELETE",
      }),

    listMemos: (params: {
      notebookId?: string | null;
      includeTotal?: boolean;
      includeDescendants?: boolean;
      q?: string;
      tag?: string;
      trash?: boolean;
      sort?: MemoSortMode;
      filter?: MemoFilterMode;
      cursor?: string | null;
      limit?: number;
    }) => {
      const search = new URLSearchParams();

      if (params.notebookId) {
        search.set("notebookId", params.notebookId);
      }

      if (params.includeDescendants) {
        search.set("includeDescendants", "1");
      }

      if (params.q?.trim()) {
        search.set("q", params.q.trim());
      }

      if (params.tag?.trim()) {
        search.set("tag", params.tag.trim());
      }

      if (params.trash) {
        search.set("trash", "1");
      }

      if (params.sort) {
        search.set("sort", params.sort);
      }

      if (params.filter && params.filter !== "all") {
        search.set("filter", params.filter);
      }

      if (params.cursor) {
        search.set("cursor", params.cursor);
      }

      if (params.limit) {
        search.set("limit", String(params.limit));
      }

      if (params.includeTotal === false) search.set("includeTotal", "0");
      return request<ListMemosResponse>(`/api/v1/memos?${search.toString()}`);
    },

    getImportCapabilities: () => request<{ protocolVersion: number; maxBatchSize: number; formats: string[]; importContext: string; accountId: string | null }>("/api/v1/imports/capabilities"),

    importMemos: (payload: ImportMemosInput) => request<ImportMemosResponse>("/api/v1/imports/memos", { method: "POST", body: JSON.stringify(payload) }),

    createMemo: (payload: {
      notebookId: string;
      title?: string;
      contentJson?: TiptapDoc;
      contentMarkdown?: string;
      tags?: string[];
      createdAt?: string;
      updatedAt?: string;
    }) =>
      request<MemoResponse>("/api/v1/memos", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    listTemplates: () => request<ListTemplatesResponse>("/api/v1/templates"),

    createTemplate: (payload: {
      name: string;
      description?: string | null;
      memoId?: string;
      title?: string | null;
      contentMarkdown?: string;
      tags?: string[];
    }) => request<TemplateResponse>("/api/v1/templates", {
      method: "POST",
      body: JSON.stringify(payload),
    }),

    updateTemplate: (templateId: string, payload: {
      name?: string;
      description?: string | null;
      title?: string | null;
      contentMarkdown?: string;
      tags?: string[];
    }) => request<TemplateResponse>(`/api/v1/templates/${templateId}`, {
      method: "PATCH",
      body: JSON.stringify(payload),
    }),

    useTemplate: (templateId: string, notebookId: string, locale?: string) =>
      request<MemoResponse>(`/api/v1/templates/${templateId}/use`, {
        method: "POST",
        body: JSON.stringify(locale ? { notebookId, locale } : { notebookId }),
      }),

    deleteTemplate: (templateId: string) =>
      request<{ ok: true }>(`/api/v1/templates/${templateId}`, { method: "DELETE" }),

    listScheduledTasks: (executorDeviceId?: string) => {
      const search = new URLSearchParams();
      if (executorDeviceId) search.set("executorDeviceId", executorDeviceId);
      const suffix = search.size > 0 ? `?${search.toString()}` : "";
      return request<ListScheduledTasksResponse>(`/api/v1/scheduled-tasks${suffix}`);
    },

    listWorkspaceExtensions: () => request<ListWorkspaceExtensionsResponse>("/api/v1/workspace-extensions"),

    upsertWorkspaceExtension: (extensionId: string, payload: WorkspaceExtensionUpsertInput) =>
      request<WorkspaceExtensionResponse>(
        `/api/v1/workspace-extensions/${encodeURIComponent(extensionId)}`,
        { method: "PUT", body: JSON.stringify(payload) },
      ),

    deleteWorkspaceExtension: (extensionId: string) =>
      request<WorkspaceExtensionResponse>(
        `/api/v1/workspace-extensions/${encodeURIComponent(extensionId)}`,
        { method: "DELETE" },
      ),

    listScheduledTaskRunHistory: (offset = 0, limit = 50) => {
      const search = new URLSearchParams({ offset: String(offset), limit: String(limit) });
      return request<ScheduledTaskRunHistoryResponse>(`/api/v1/scheduled-task-runs?${search.toString()}`);
    },

    listPluginScheduledTasks: (pluginId: string) => request<ListScheduledTasksResponse>(
      `/api/v1/scheduled-tasks/plugin/${encodeURIComponent(pluginId)}`,
    ),

    upsertPluginScheduledTask: (payload: {
      pluginId: string;
      scheduleKey: string;
      name: string;
      commandId: string;
      cronExpression: string;
      timezone: string;
      executorDeviceId: string;
      missedRunPolicy?: "run-once" | "skip";
      isEnabled?: boolean;
    }) => request<ScheduledTaskResponse>("/api/v1/scheduled-tasks/plugin-upsert", {
      method: "POST",
      body: JSON.stringify(payload),
    }),

    deletePluginScheduledTask: (pluginId: string, scheduleKey: string) => request<{ ok: true }>(
      `/api/v1/scheduled-tasks/plugin/${encodeURIComponent(pluginId)}/${encodeURIComponent(scheduleKey)}`,
      { method: "DELETE" },
    ),

    createScheduledTask: (payload: {
      name: string;
      taskType: "plugin-command";
      taskPayload: { pluginId: string; commandId: string };
      cronExpression: string;
      timezone: string;
      executorDeviceId: string;
      missedRunPolicy?: "run-once" | "skip";
      isEnabled?: boolean;
    }) => request<ScheduledTaskResponse>("/api/v1/scheduled-tasks", {
      method: "POST",
      body: JSON.stringify(payload),
    }),

    updateScheduledTask: (taskId: string, payload: {
      name?: string;
      taskPayload?: { pluginId: string; commandId: string };
      cronExpression?: string;
      timezone?: string;
      executorDeviceId?: string;
      missedRunPolicy?: "run-once" | "skip";
      isEnabled?: boolean;
    }) => request<ScheduledTaskResponse>(`/api/v1/scheduled-tasks/${encodeURIComponent(taskId)}`, {
      method: "PATCH",
      body: JSON.stringify(payload),
    }),

    deleteScheduledTask: (taskId: string) => request<{ ok: true }>(
      `/api/v1/scheduled-tasks/${encodeURIComponent(taskId)}`,
      { method: "DELETE" },
    ),

    listScheduledTaskRuns: (taskId: string, offset = 0, limit = 50) => {
      const search = new URLSearchParams({ offset: String(offset), limit: String(limit) });
      return request<ScheduledTaskRunsResponse>(
        `/api/v1/scheduled-tasks/${encodeURIComponent(taskId)}/runs?${search.toString()}`,
      );
    },

    claimScheduledTaskRun: (taskId: string, payload: {
      scheduledFor: string;
      executorDeviceId: string;
    }) => request<ScheduledTaskRunResponse>(
      `/api/v1/scheduled-tasks/${encodeURIComponent(taskId)}/runs/claim`,
      { method: "POST", body: JSON.stringify(payload) },
    ),

    finishScheduledTaskRun: (taskId: string, runId: string, payload: {
      executorDeviceId: string;
      status: "succeeded" | "failed";
      errorMessage?: string | null;
    }) => request<ScheduledTaskRunResponse>(
      `/api/v1/scheduled-tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/finish`,
      { method: "POST", body: JSON.stringify(payload) },
    ),

    moveMemos: (payload: { memoIds: string[]; notebookId: string }) =>
      request<{ ok: true; moved: number }>("/api/v1/memos/batch/move", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    deleteMemos: (payload: { memoIds: string[]; permanent?: boolean }) =>
      request<{ ok: true; deleted: number }>("/api/v1/memos/batch/delete", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    emptyTrash: () =>
      request<{ ok: true; deleted: number }>("/api/v1/memos/trash/empty", {
        method: "DELETE",
      }),

    getMemo: (memoId: string, options?: { includeDeleted?: boolean }) => {
      const search = new URLSearchParams();

      if (options?.includeDeleted) {
        search.set("includeDeleted", "1");
      }

      const suffix = search.toString() ? `?${search.toString()}` : "";
      return request<MemoResponse>(`/api/v1/memos/${memoId}${suffix}`);
    },

    getMemoShare: (memoId: string) =>
      request<MemoShareResponse>(`/api/v1/memos/${memoId}/share`),

    listMemoShares: (offset = 0, limit = 50) =>
      request<ListMemoSharesResponse>(`/api/v1/memo-shares?offset=${offset}&limit=${limit}`),

    createMemoShare: (memoId: string) =>
      request<{ share: MemoShare }>(`/api/v1/memos/${memoId}/share`, {
        method: "POST",
        body: JSON.stringify({}),
      }),

    updateMemoShare: (memoId: string, payload: { passwordProtected?: boolean; password?: string; slug?: string | null; showUpdatedAt?: boolean; showBranding?: boolean; expiresAt?: string | null }) =>
      request<{ share: MemoShare }>(`/api/v1/memos/${memoId}/share`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    getTableForm: (memoId: string) =>
      request<{ form: TableFormSettings | null }>(`/api/v1/memos/${encodeURIComponent(memoId)}/form`),

    updateTableForm: (memoId: string, payload: TableFormUpdateInput) =>
      request<{ form: TableFormSettings }>(`/api/v1/memos/${encodeURIComponent(memoId)}/form`, {
        method: "PUT",
        body: JSON.stringify(payload),
      }),

    getPublicTableForm: (token: string) =>
      request<{ form: PublicTableForm }>(`/api/public/forms/${encodeURIComponent(token)}`),

    unlockPublicTableForm: (token: string, password: string) =>
      request<{ ok: true }>(`/api/public/forms/${encodeURIComponent(token)}/unlock`, {
        method: "POST",
        body: JSON.stringify({ password }),
      }),

    submitPublicTableForm: (token: string, cells: Record<string, unknown>) =>
      request<{ ok: true }>(`/api/public/forms/${encodeURIComponent(token)}/submissions`, {
        method: "POST",
        body: JSON.stringify({ cells }),
      }),

    uploadPublicTableFormFile: (token: string, file: File) => {
      const form = new FormData();
      form.append("file", file, file.name || "attachment");
      return request<{ resource: { id: string; filename: string; mimeType: string; byteSize: number } }>(
        `/api/public/forms/${encodeURIComponent(token)}/resources`,
        { method: "POST", body: form },
      );
    },

    revokeMemoShare: (memoId: string) =>
      request<{ ok: true }>(`/api/v1/memos/${memoId}/share`, { method: "DELETE" }),

    createMemoEditSession: (memoId: string) =>
      request<{ editSession: MemoEditSession }>(`/api/v1/memos/${memoId}/edit-sessions`, {
        method: "POST",
        body: JSON.stringify({}),
      }),

    listMemoRevisions: (memoId: string) => request<ListMemoRevisionsResponse>(`/api/v1/memos/${memoId}/revisions`),

    restoreMemoRevision: (memoId: string, revisionId: string) =>
      request<MemoResponse>(`/api/v1/memos/${memoId}/revisions/${revisionId}/restore`, {
        method: "POST",
        body: JSON.stringify({}),
      }),

    listResources: () => request<ListResourcesResponse>("/api/v1/resources"),

    renameResource: (resourceId: string, filename: string) =>
      request<ResourceResponse>(`/api/v1/resources/${encodeURIComponent(resourceId)}`, {
        method: "PATCH",
        body: JSON.stringify({ filename }),
      }),

    updateResourceContent: (resourceId: string, file: Blob, expectedContentHash: string) => {
      const form = new FormData();
      form.append("file", file);
      form.append("expectedContentHash", expectedContentHash);
      form.append("mimeType", file.type || "application/octet-stream");
      if (file instanceof File) form.append("filename", file.name);
      return request<ResourceResponse>(`/api/v1/resources/${encodeURIComponent(resourceId)}/blob`, {
        method: "PUT",
        body: form,
      });
    },

    deleteResource: (resourceId: string) =>
      request<{ ok: true }>(`/api/v1/resources/${encodeURIComponent(resourceId)}`, {
        method: "DELETE",
      }),

    getMarkdownExportPage: (offset = 0, limit = 50, memoIds?: string[], cursor?: string) => {
      const search = new URLSearchParams({
        offset: String(offset),
        limit: String(limit),
      });
      if (memoIds && memoIds.length > 0) {
        search.set("ids", memoIds.join(","));
      }
      if (offset > 0) search.set("includeTotal", "0");
      if (cursor !== undefined) search.set("cursor", cursor);
      return request<MarkdownExportPage>(`/api/v1/exports/markdown?${search.toString()}`);
    },

    getJsonBackupPage: (offset = 0, limit = 25, cursor?: string) => {
      const search = new URLSearchParams({ offset: String(offset), limit: String(limit) });
      if (offset > 0) search.set("includeTotal", "0");
      if (cursor !== undefined) search.set("cursor", cursor);
      return request<JsonBackupPage>(`/api/v1/backups/json?${search}`);
    },

    restoreJsonNotebooks: (notebooks: JsonBackupNotebook[]) =>
      request<{ ok: true }>("/api/v1/restores/json/notebooks", {
        method: "POST",
        body: JSON.stringify({ notebooks }),
      }),

    restoreJsonMemos: (memos: JsonBackupMemo[]) =>
      request<{ ok: true }>("/api/v1/restores/json/memos", {
        method: "POST",
        body: JSON.stringify({ memos }),
      }),

    restoreJsonAiPrompts: (prompts: JsonBackupAiPrompt[]) =>
      request<{ ok: true }>("/api/v1/restores/json/ai-prompts", {
        method: "POST",
        body: JSON.stringify({ prompts }),
      }),

    createJsonResourceRestoreSink,

    restoreJsonResource: async (resourceId: string, metadata: JsonBackupMemo["resources"][number], file: Blob) => {
      const sink = await createJsonResourceRestoreSink(resourceId, metadata);
      const reader = file.stream().getReader();
      try {
        while (true) {
          const next = await reader.read();
          if (next.done) break;
          await sink.write(next.value);
        }
        await sink.close();
        return { ok: true as const };
      } catch (error) {
        await sink.abort();
        throw error;
      } finally {
        reader.releaseLock();
      }
    },

    getResourceResponse: (resourceUrl: string, init?: RequestInit) =>
      requestResourceResponse(resourceUrl, init),

    getResourceBlob: (resourceUrl: string) => requestBlob(resourceUrl),

    downloadGithubPluginAsset: (
      owner: string,
      repository: string,
      releaseTag: string,
      assetName: "manifest.json" | "main.js" | "styles.css",
    ) => requestArrayBuffer(
      `/api/v1/plugins/github/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/releases/${encodeURIComponent(releaseTag)}/assets/${encodeURIComponent(assetName)}`,
    ),

    downloadGithubPluginAssetById: (
      owner: string,
      repository: string,
      assetId: string,
      assetName: "manifest.json" | "main.js" | "styles.css",
    ) => requestArrayBuffer(
      `/api/v1/plugins/github/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/assets/${encodeURIComponent(assetId)}/${encodeURIComponent(assetName)}`,
    ),

    getGithubPluginRepositoryManifest: async (owner: string, repository: string) => {
      const path = `/api/v1/plugins/github/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/manifest`;
      const { context, response } = await send(path, undefined, { setJsonContentType: false });
      if (!response.ok) await throwRequestError(context, response, "GitHub plugin manifest request failed");
      return response.text();
    },

    getGithubPluginLatestManifest: async (owner: string, repository: string) => {
      const path = `/api/v1/plugins/github/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/latest-manifest`;
      const { context, response } = await send(path, undefined, { setJsonContentType: false });
      if (!response.ok) await throwRequestError(context, response, "GitHub plugin latest-release manifest request failed");
      return response.text();
    },

    getCommunityPluginRegistry: async () => {
      const { context, response } = await send("/api/v1/plugins/community-registry", undefined, { setJsonContentType: false });
      if (response.status === 404) return null;
      if (!response.ok) await throwRequestError(context, response, "Community registry request failed");
      return {
        bytes: await response.arrayBuffer(),
        signatureBase64: response.headers.get("x-edgeever-community-registry-signature") ?? "",
      };
    },

    getGithubPluginRelease: async (owner: string, repository: string, releaseTag: string) => {
      const path = `/api/v1/plugins/github/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/releases/tags/${encodeURIComponent(releaseTag)}`;
      const { context, response } = await send(path, undefined, { setJsonContentType: false });
      if (response.status === 404) return null;
      if (!response.ok) await throwRequestError(context, response, "GitHub plugin release request failed");
      return response.json() as Promise<{
        tag_name: string;
        draft: boolean;
        assets: Array<{
          id: number;
          name: string;
          size: number;
          url: string;
          browser_download_url: string;
          digest?: string;
        }>;
      }>;
    },

    uploadMemoResource: (memoId: string, file: Blob | FormData) => {
      // Small files do not benefit from an upload session's three round trips.
      // Keep large attachments on the bounded-memory, resumable path.
      if (!(file instanceof FormData) && file.size > MAX_SINGLE_REQUEST_UPLOAD_BYTES) {
        return uploadMemoResourceMultipart(memoId, file);
      }
      const form = file instanceof FormData ? file : new FormData();
      if (!(file instanceof FormData)) {
        const filename = "name" in file && typeof file.name === "string" && file.name.trim()
          ? file.name
          : "attachment";
        form.append("file", file, filename);
      }
      return request<ResourceResponse>(`/api/v1/memos/${encodeURIComponent(memoId)}/resources`, {
        method: "POST",
        body: form,
      });
    },

    claimPosterRender: () => request<{ job: null | { id: string; memoId: string; expectedRevision: number; templateId: string | null; claimToken: string; expiresAt: string } }>("/api/v1/poster-render/claim", { method: "POST", body: "{}" }),
    completePosterRender: (id: string, input: { claimToken: string; document?: import("@edgeever/shared").PosterDocument; errorCode?: "render_failed" | "revision_conflict" | "client_timeout" }) => request<{ job: { status: string } }>(`/api/v1/poster-render/${encodeURIComponent(id)}/complete`, { method: "POST", body: JSON.stringify(input) }),
    uploadMemoResourceParts,

    updateMemo: (
      memoId: string,
      payload: {
        expectedRevision?: number;
        expectedContentHash?: string;
        editSessionId?: string;
        notebookId?: string;
        title?: string;
        isPinned?: boolean;
        contentJson?: TiptapDoc;
        contentMarkdown?: string;
        tags?: string[];
        createdAt?: string;
        updatedAt?: string;
        allowDestructiveOverwrite?: boolean;
      }
    ) =>
      request<MemoResponse>(`/api/v1/memos/${memoId}`, {
        method: "PATCH",
        body: JSON.stringify(payload),
      }),

    deleteMemo: (memoId: string, options?: { permanent?: boolean }) => {
      const search = new URLSearchParams();

      if (options?.permanent) {
        search.set("permanent", "1");
      }

      const suffix = search.toString() ? `?${search.toString()}` : "";
      return request<{ ok: true }>(`/api/v1/memos/${memoId}${suffix}`, {
        method: "DELETE",
      });
    },

    restoreMemo: (memoId: string) =>
      request<MemoResponse>(`/api/v1/memos/${memoId}/restore`, {
        method: "POST",
        body: JSON.stringify({}),
      }),

    duplicateMemo: (memoId: string, payload: { notebookId?: string; title?: string } = {}) =>
      request<MemoResponse>(`/api/v1/memos/${encodeURIComponent(memoId)}/duplicate`, {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    mergeMemos: (payload: { memoIds: string[]; notebookId?: string; title?: string }) =>
      request<MemoResponse>("/api/v1/memos/merge", {
        method: "POST",
        body: JSON.stringify(payload),
      }),

    resetDemo: () =>
      request<{ success: true }>("/api/v1/demo/reset", {
        method: "POST",
      }),
  };
};

const normalizeBaseUrl = (value?: string) => {
  if (!value) {
    return "";
  }

  return value.replace(/\/+$/, "");
};

const isAbsoluteHttpUrl = (value: string) => /^https?:\/\//i.test(value);