feat(fetch-client): add @zenstackhq/fetch-client package

A simple fetch-based, non-reactive client library that consumes the
RPC-style auto CRUD API.

- Per-model CRUD operations (`findUnique`, `findMany`, `create`, etc.)
  derived from the ORM's `AllModelOperations`, with slicing applied via
  a key-filter mapped type that preserves per-call generic narrowing.
- `findUniqueOrThrow` / `findFirstOrThrow` raise a typed `CrudError`
  with `code: CrudErrorCode.NotFound` and the offending model name.
- Sequential transactions via `client.\$transaction([...])` accepting an
  array of typed `{ model, op, args }` operations; result tuple is
  typed per-position via `TransactionResults`.
- Custom procedures exposed under `client.\$procs` with `query` /
  `mutate` based on the procedure shape.
- Endpoint is required and validated as a fully qualified URL.
- Threads `ExtQueryArgs` and `ExtResult` through model ops and
  transactions so plugin-extended query args / result fields are
  reflected in user-facing types.

Refactors:
- Move `TransactionOperation` / `TransactionResults` types and the
  `CUSTOM_PROC_ROUTE_NAME` / `TRANSACTION_ROUTE_PREFIX` constants into
  `@zenstackhq/client-helpers` so both clients can share them.
- Move the `DEFAULT_QUERY_ENDPOINT` constant to tanstack-query (where
  it belongs).

Tests: 47 runtime tests + 13 type-level tests covering CRUD ops, HTTP
methods, SuperJSON serialization, error handling, transactions, slicing,
ExtQueryArgs, and ExtResult propagation. Test schemas use real ZModel
files generated via the existing `scripts/test-generate.ts`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ymc9

packages/clients/client-helpers/src/constants.ts

@@ -1,4 +1,9 @@
 /**
- * The default query endpoint.
+ * Route segment used for custom procedures.
  */
-export const DEFAULT_QUERY_ENDPOINT = '/api/model';
+export const CUSTOM_PROC_ROUTE_NAME = '$procs';
+
+/**
+ * Route prefix used for transactions.
+ */
+export const TRANSACTION_ROUTE_PREFIX = '$transaction';

packages/clients/client-helpers/src/index.ts

@@ -7,4 +7,5 @@ export * from './nested-read-visitor';
 export * from './nested-write-visitor';
 export * from './optimistic';
 export * from './query-analysis';
+export * from './transaction';
 export * from './types';

packages/clients/client-helpers/src/transaction.ts

@@ -0,0 +1,70 @@
+import type {
+    CoreCrudOperations,
+    CrudArgsMap,
+    CrudReturnMap,
+    ExtQueryArgsBase,
+    ExtResultBase,
+    GetSlicedOperations,
+    ModelAllowsCreate,
+    OperationsRequiringCreate,
+    QueryOptions,
+} from '@zenstackhq/orm';
+import type { GetModels, SchemaDef } from '@zenstackhq/schema';
+
+/**
+ * Operations available in a sequential transaction.
+ */
+type AllowedTransactionOps<
+    Schema extends SchemaDef,
+    Model extends GetModels<Schema>,
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+> =
+    ModelAllowsCreate<Schema, Model> extends true
+        ? GetSlicedOperations<Schema, Model, Options> & CoreCrudOperations
+        : Exclude<GetSlicedOperations<Schema, Model, Options> & CoreCrudOperations, OperationsRequiringCreate>;
+
+/**
+ * Represents a single operation to execute within a sequential transaction.
+ *
+ * The `model`, `op`, and `args` fields are correlated: `op` is constrained to
+ * the CRUD operations available on `model` (respecting `Options['slicing']`), and
+ * `args` is typed accordingly.
+ */
+export type TransactionOperation<
+    Schema extends SchemaDef,
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtQueryArgs extends ExtQueryArgsBase = {},
+    ExtResult extends ExtResultBase<Schema> = {},
+> = {
+    [Model in GetModels<Schema>]: {
+        [Op in AllowedTransactionOps<Schema, Model, Options>]: {} extends CrudArgsMap<
+            Schema,
+            Model,
+            Options,
+            ExtQueryArgs,
+            ExtResult
+        >[Op]
+            ? { model: Model; op: Op; args?: CrudArgsMap<Schema, Model, Options, ExtQueryArgs, ExtResult>[Op] }
+            : { model: Model; op: Op; args: CrudArgsMap<Schema, Model, Options, ExtQueryArgs, ExtResult>[Op] };
+    }[AllowedTransactionOps<Schema, Model, Options>];
+}[GetModels<Schema>];
+
+/**
+ * Maps each operation in a transaction tuple to its precise result type, preserving
+ * per-position typing.
+ */
+export type TransactionResults<
+    Schema extends SchemaDef,
+    Ops extends readonly TransactionOperation<Schema, any, any, any>[],
+    Options extends QueryOptions<Schema> = QueryOptions<Schema>,
+    ExtResult extends ExtResultBase<Schema> = {},
+> = {
+    [K in keyof Ops]: Ops[K] extends { model: infer M; op: infer O; args?: infer A }
+        ? M extends GetModels<Schema>
+            ? O extends keyof CrudReturnMap<Schema, M, A, Options, ExtResult>
+                ? CrudReturnMap<Schema, M, A, Options, ExtResult>[O]
+                : never
+            : never
+        : never;
+};
+

packages/clients/fetch-client/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@zenstackhq/fetch-client",
+    "displayName": "ZenStack Fetch Client",
+    "description": "Simple fetch-based client for consuming ZenStack's RPC-style CRUD API",
+    "version": "3.6.4",
+    "type": "module",
+    "author": {
+        "name": "ZenStack Team",
+        "email": "contact@zenstack.dev"
+    },
+    "homepage": "https://zenstack.dev",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/zenstackhq/zenstack"
+    },
+    "license": "MIT",
+    "scripts": {
+        "build": "tsc --noEmit && tsdown && pnpm test:generate && pnpm test:typecheck",
+        "watch": "tsdown --watch",
+        "lint": "eslint src --ext ts",
+        "test": "vitest run",
+        "test:generate": "tsx ../../../scripts/test-generate.ts test --lite-only",
+        "test:typecheck": "tsc --noEmit --project tsconfig.test.json",
+        "pack": "pnpm pack"
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "default": "./dist/index.mjs"
+        }
+    },
+    "dependencies": {
+        "@zenstackhq/client-helpers": "workspace:*",
+        "@zenstackhq/common-helpers": "workspace:*",
+        "@zenstackhq/orm": "workspace:*",
+        "@zenstackhq/schema": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/node": "catalog:",
+        "@zenstackhq/cli": "workspace:*",
+        "@zenstackhq/eslint-config": "workspace:*",
+        "@zenstackhq/tsdown-config": "workspace:*",
+        "@zenstackhq/typescript-config": "workspace:*",
+        "@zenstackhq/vitest-config": "workspace:*",
+        "decimal.js": "catalog:"
+    },
+    "funding": "https://github.com/sponsors/zenstackhq"
+}