Client SDK

import { createClient } from "questpie/client";

import type { AppConfig } from "#questpie"; // generated by `questpie generate`

export const client = createClient<AppConfig>({
  // required, origin of your app's API
  baseURL:
    typeof window !== "undefined"
      ? window.location.origin
      : process.env.APP_URL || "http://localhost:3000",
  basePath: "/api", // must match your server handler's basePath
});

import { client } from "@/lib/client.js";

// List, returns a paginated envelope, not a bare array.
const { docs, totalDocs } = await client.collections.posts.find({
  where: { published: true },
  orderBy: { createdAt: "desc" },
  limit: 10,
});

// Read one by id (optimized to GET /api/posts/:id).
const post = await client.collections.posts.findOne({ where: { id } });

// Create, `data` is typed from the collection's insert shape.
const created = await client.collections.posts.create({
  title: "Hello",
  slug: "hello",
  published: true,
});

export type QuestpieClientConfig = {
  baseURL: string; // required, e.g. "http://localhost:3000"
  basePath?: string; // default "/", "/api" for fullstack apps
  fetch?: typeof fetch; // default globalThis.fetch
  headers?: Record<string, string>; // default headers on every request
  useSuperJSON?: boolean; // default true
};

{
  collections; // typed CRUD per collection
  globals;     // typed get/update per global
  routes;      // typed callers for your custom routes
  search;      // search + reindex
  realtime;    // low-level SSE stream API
  setLocale; getLocale; getBasePath; // locale + base-path helpers
}

// find, paginated. Returns { docs, totalDocs, totalPages, page, hasNextPage, ... }.
const result = await client.collections.posts.find({
  where: { published: true, author: { is: { role: "editor" } } },
  with: { author: true }, // hydrate the relation
  orderBy: { createdAt: "desc" },
  limit: 20,
  offset: 0,
});

// findOne, first match or null. Optimized: a where of ONLY { id } hits GET /:id.
const post = await client.collections.posts.findOne({ where: { id } });
const bySlug = await client.collections.posts.findOne({ where: { slug: "hello" } });

// count, bare number (the { count } envelope is unwrapped for you).
const total = await client.collections.posts.count({ where: { published: true } });

// await client.collections.posts.find({ limit: 2 })
{
  "docs": [ { "id": "01J…", "title": "Hello", "published": true }, { "id": "01J…", "title": "World", "published": false } ],
  "totalDocs": 2,
  "limit": 2,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

// create(data, options?), `data` is the collection's insert shape; supports nested relations.
const created = await client.collections.posts.create({
  title: "Hello",
  slug: "hello",
  published: true,
  author: { connect: { id: authorId } }, // belongsTo: raw id OR { connect: { id } }
  tags: { create: [{ name: "intro" }] }, // hasMany / M:N: connect | create | connectOrCreate | set
});

// updateById({ id, data }, options?), by id on the client. `update` is the alias.
const updated = await client.collections.posts.updateById({
  id: created.id,
  data: { published: false },
});

// deleteById({ id }), soft if softDelete is enabled. Returns { success }.
await client.collections.posts.deleteById({ id: created.id });

// restoreById({ id }), only on softDelete collections.
await client.collections.posts.restoreById({ id: created.id });

// updateMany({ where, data }), one `data` applied to every matching row. Returns the written rows.
const winners = await client.collections.posts.updateMany({
  where: { published: false },
  data: { published: true },
});

// updateBatch({ updates }), distinct data per row, all in one transaction.
await client.collections.posts.updateBatch({
  updates: [
    { id: a, data: { title: "A" } },
    { id: b, data: { title: "B" } },
  ],
});

// deleteMany({ where }), bulk delete by filter. Returns { success, count }.
const { count } = await client.collections.posts.deleteMany({
  where: { published: false },
});

// findVersions({ id, limit?, offset? }), history rows tagged with version metadata.
const versions = await client.collections.posts.findVersions({ id, limit: 10 });
// each row: { ...row, versionId, versionNumber, versionOperation, versionUserId, versionCreatedAt }

// revertToVersion({ id, version? | versionId? }), restore an old version.
await client.collections.posts.revertToVersion({ id, version: 3 });

// transitionStage({ id, stage, scheduledAt? }), move workflow stage (no data mutation).
await client.collections.posts.transitionStage({ id, stage: "published" });

// upload(file, options?), multipart POST to /:collection/upload.
const asset = await client.collections.media.upload(file, {
  onProgress: (pct) => setProgress(pct), // 0-100
  signal: controller.signal, // abort to cancel
  path: "uploads/2026", // optional destination folder
});
console.log(asset.url);

// uploadMany(files, options?), sequential; onProgress reports OVERALL batch progress.
const assets = await client.collections.media.uploadMany(files, {
  onProgress: (overall, fileIndex) => setProgress(overall),
});

const meta = await client.collections.posts.meta(); // title field, timestamps, localized fields
const schema = await client.collections.posts.schema(); // fields, relations, access (for current user), validation JSON Schema

// get(options?), read the singleton. Supports `with`, `columns`, `locale`, `localeFallback`, `stage`.
const settings = await client.globals.settings.get({ with: { logo: true } });

// update(data, options?), FIRST arg is the DATA object (no { id, data } wrapper).
const next = await client.globals.settings.update(
  { siteName: "QUESTPIE", logo: { connect: { id: assetId } } },
  { with: { logo: true } }, // options is the SECOND arg → query string
);

// routes/admin/stats.ts  →  client.routes.admin.stats(input)
const stats = await client.routes.admin.stats({ period: "week" });
//    ^? typed from the route's input/output schema

// Calling at any depth sends POST {basePath}/admin/stats with a JSON body.

// routes/admin/stats.ts exporting `stats:GET`  →  client.routes.admin.stats.get(input)
const stats = await client.routes.admin.stats.get({ period: "week" });
// GET serializes `input` into the query string; POST/PUT/PATCH/DELETE send it as a JSON body.

// The full URL string is available without calling:
const url = client.routes.admin.stats.url; // "http://localhost:3000/api/admin/stats"

const results = await client.search.search({
  query: "questpie", // required
  collections: ["posts", "pages"], // optional, restrict scope
  mode: "hybrid", // "lexical" | "semantic" | "hybrid"
  limit: 20,
  highlights: true,
  facets: [{ field: "tags", limit: 10, sortBy: "count" }],
});

// results.docs: each is the full record + { _collection, _search: { score, highlights, indexedTitle } }
// results.total, results.facets?

// Force a rebuild of a collection's index.
await client.search.reindex("posts");

// live(options, onSnapshot, opts?), callback form. Returns an unsubscribe function.
const unsubscribe = client.collections.posts.live(
  { where: { published: true }, orderBy: { createdAt: "desc" }, limit: 20 },
  (snapshot) => {
    // snapshot is the SAME shape as find() → { docs, totalDocs, ... }
    setPosts(snapshot.docs);
  },
  {
    signal: controller.signal, // optional, unsubscribes on abort
    onError: (err) => console.error("realtime dropped", err), // optional, SSE failure
  },
);

// Later:
unsubscribe();

// liveIter(options?, opts?), async-generator form, for workers / agents / tests.
for await (const snapshot of client.collections.posts.liveIter(
  { where: { published: true } },
  { signal: controller.signal }, // only `signal`, no onError
)) {
  console.log(snapshot.totalDocs);
}

const unsubscribe = client.globals.settings.live({}, (snapshot) => {
  setSettings(snapshot);
});

import { buildCollectionTopic, buildGlobalTopic } from "questpie/client";

const topic = buildCollectionTopic("posts", { where: { published: true }, limit: 20 });

// subscribe<TData>(topic, callback, signal?, customId?, onError?) → unsubscribe
const unsubscribe = client.realtime.subscribe(topic, (data) => {
  // `data` is untyped here (TData defaults to unknown), the wrappers add the types
});

// stream<TData>(topic, signal?, customId?) → AsyncGenerator
for await (const snap of client.realtime.stream(topic)) { /* ... */ }

client.realtime.destroy(); // tear down the multiplexer (re-creates lazily on next use)

client.setLocale("de"); // all subsequent requests send accept-language: de
client.getLocale(); // "de"
client.getBasePath(); // "/api"  ("" when basePath is "/")

client.setLocale(); // pass nothing to clear the locale header

import { QuestpieClientError } from "questpie/client";

try {
  await client.collections.posts.create({ title: "" /* missing slug */ });
} catch (err) {
  if (err instanceof QuestpieClientError) {
    err.status; // 400
    if (err.isCode("VALIDATION_ERROR")) {
      err.getFieldErrorsMap(); // { slug: ["Required"] }
      err.getFieldError("slug"); // { path: "slug", message: "Required" }
    }
  }
}

import { questpieNextRouteHandlers } from "@questpie/next";
import { app } from "#questpie";

// All verbs share one handler.
export const { GET, POST, PATCH, DELETE, PUT, OPTIONS, HEAD } =
  questpieNextRouteHandlers(app, { basePath: "/api" });

import { Hono } from "hono";
import { questpieHono } from "@questpie/hono/server";
import { app } from "#questpie";

const server = new Hono();
server.route("/", questpieHono(app, { basePath: "/api" }));

export default server;

import { Elysia } from "elysia";
import { questpieElysia } from "@questpie/elysia/server";
import { app } from "#questpie";

const server = new Elysia()
  .use(questpieElysia(app, { basePath: "/api" }));

export default server;

import {
  createClient,
  QuestpieClientError,
  UploadError,
  type QuestpieClientConfig,
  type QuestpieClient,
  type SearchOptions,
  type SearchResponse,
  type LiveQueryOptions,
  type LiveSubscribeOptions,
  // result + query types (shared with the server), for tooling like TanStack Query:
  type Where,
  type With,
  type OrderBy,
  type FindManyOptions,
  type ApplyQuery,
  type FindResult,
  type PaginatedResult,
  // realtime value + type exports:
  buildCollectionTopic,
  buildGlobalTopic,
  type RealtimeAPI,
  type TopicConfig,
} from "questpie/client";

import { client } from "@/lib/client.js";

type PostsFindResult = Awaited<ReturnType<typeof client.collections.posts.find>>;
type Post = PostsFindResult["docs"][number];
type AppClient = typeof client; // hand the whole client to helpers