@atscript/db-client 0.1.58 → 0.1.60

package/dist/index.cjs

@@ -22,7 +22,7 @@ var ClientError = class extends Error {
 * `name === 'ActionDisabledError'`. The transport / status / base body are
 * identical to a generic `ClientError`; this subclass adds typed accessors
 * so consumers can write `catch (e) { if (e instanceof ActionDisabledError) … }`
-* to access `action` / `pk` / `pks` without indexing into `body`.
+* to access `action` / `id` / `ids` without indexing into `body`.
 */
 var ActionDisabledError = class extends ClientError {
 	name = "ActionDisabledError";
@@ -31,12 +31,12 @@ var ActionDisabledError = class extends ClientError {
 		return this.body.action;
 	}
 	/** Present only for `'row'`-level rejections. */
-	get pk() {
-		return this.body.pk;
+	get id() {
+		return this.body.id;
 	}
-	/** Present only for `'rows'`-level rejections (full list of failing PKs). */
-	get pks() {
-		return this.body.pks;
+	/** Present only for `'rows'`-level rejections (full list of failing IDs). */
+	get ids() {
+		return this.body.ids;
 	}
 };
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
@@ -101,6 +101,9 @@ var Client = class {
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
+	*
+	* The response type narrows by the literal `$with` array in `query` —
+	* relations not listed in `$with` are stripped from the row type.
 	*/
 	async query(query) {
 		return this._get("query", query);
@@ -122,6 +125,9 @@ var Client = class {
 	}
 	/**
 	* `GET /pages` — paginated query with typed filter and relations.
+	*
+	* Response rows narrow by the literal `$with` array — same algebra as
+	* {@link query}.
 	*/
 	async pages(query, page = 1, size = 10) {
 		return this._get("pages", {
@@ -136,7 +142,8 @@ var Client = class {
 	/**
 	* `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
 	*
-	* Returns `null` on 404.
+	* Returns `null` on 404. Response narrows by the literal `$with` array in
+	* `query.controls` — same algebra as {@link query}.
 	*/
 	async one(id, query) {
 		const controlStr = query?.controls ? (0, _uniqu_url_builder.buildUrl)({ controls: query.controls }) : "";
@@ -187,33 +194,45 @@ var Client = class {
 	* Invoke a declared action by name. Resolves the action descriptor from the
 	* cached `/meta` response, then dispatches based on `processor`:
 	*
-	* - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+	* - `'backend'` → POST the identifier as a JSON body to the action's path
 	*   and return the parsed server response. The HTTP method is always POST.
 	* - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
-	*   PK (URL-encoded; composite PKs are URL-encoded per field and joined
-	*   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
-	*   verbatim. The default navigator (browser only) calls
-	*   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
-	*   integrate with a SPA router.
+	*   identifier values, walking `meta.preferredId` field order (each value
+	*   URL-encoded, compound IDs joined with `/`); for `level: 'rows'` or
+	*   `'table'`, navigate to `value` verbatim. The default navigator (browser
+	*   only) calls `window.location.assign(url)`. Provide
+	*   `ClientOptions.navigate` to integrate with a SPA router.
 	* - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
 	*   are the application's responsibility, not the client's.
 	*
 	* Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
 	*
-	* For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
-	* for a `'rows'` action it is wrapped into a single-element array — the
-	* server-side `@DbActionPKs()` resolver requires an array body.
+	* **Identifier shape (server contract).** `id` is always an object (single)
+	* or array of objects (multi) — never a scalar. Each object's field set
+	* must exactly match one legitimate identification on the table (PK or any
+	* `@db.index.unique` group). Even single-field PK tables send `{ id: 'abc' }`,
+	* not `'abc'`. `level: 'table'` actions take no identifier (`undefined`).
+	*
+	* The TypeScript signature widens to `Partial<Own<T>>` because the server's
+	* exact-match validation cannot be expressed at the type level. Mismatched
+	* field sets produce HTTP 400; obvious type errors (scalars, `null`) are
+	* caught at compile time when `T` is typed.
+	*
+	* @typeParam R Caller-asserted return shape from the action handler. The
+	*              server returns whatever the handler emits (commonly
+	*              `{ message?: string, ... }`); the client cannot validate.
 	*/
-	async action(name, pk) {
-		const action = (await this.meta()).actions.find((a) => a.name === name);
+	async action(name, id) {
+		const meta = await this.meta();
+		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
 		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
 		if (action.processor === "navigate") {
-			const url = this._interpolateNavigateUrl(action, pk);
+			const url = this._interpolateNavigateUrl(action, id, meta.preferredId);
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, pk);
+		const body = this._buildActionBody(action, id);
 		return this._postAction(action, body);
 	}
 	/**
@@ -233,16 +252,21 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
-	_buildActionBody(action, pk) {
+	_buildActionBody(action, id) {
 		if (action.level === "table") return void 0;
-		if (action.level !== "rows") return pk;
-		if (Array.isArray(pk)) return pk;
-		return pk === void 0 ? [] : [pk];
+		if (action.level === "rows") {
+			if (id === void 0) return [];
+			if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
+			return id;
+		}
+		if (id !== null && typeof id === "object" && !Array.isArray(id)) return id;
+		throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
 	}
-	_interpolateNavigateUrl(action, pk) {
+	_interpolateNavigateUrl(action, id, preferredId) {
 		if (action.level !== "row") return action.value;
-		if (pk === void 0) return action.value;
-		return action.value.replace(/\$1/g, encodeNavigatePk(pk));
+		if (id === void 0) return action.value;
+		if (id === null || typeof id !== "object" || Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): row-level navigate actions require an identifier object; received ${describeShape(id)}.`);
+		return action.value.replace(/\$1/g, encodeNavigateId(id, preferredId));
 	}
 	async _dispatchNavigate(action, url) {
 		if (this._navigate) {
@@ -326,14 +350,39 @@ var Client = class {
 	}
 };
 /**
-* Encode a row PK for substitution into a `processor: 'navigate'` URL template.
-* Scalars are URL-encoded directly; composite PK objects have each value
-* URL-encoded and joined with `/` in object-key order (which mirrors
-* `primaryKeys` for the table).
+* Render a single identifier field for substitution into a navigate-URL
+* template or human-readable string. `null` / `undefined` collapse to `""`
+* (NOT the literal `"undefined"` / `"null"` that `String()` would produce).
+*/
+function formatIdentifierField(v) {
+	if (v === null || v === void 0) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+	return JSON.stringify(v);
+}
+/**
+* Render a row identifier as a `/`-joined string in `preferredId`
+* declaration order — NOT object-key insertion order (which is unstable
+* across callers). Raw form, no URL-encoding; for prompt text, error
+* messages, log lines, etc.
+*/
+function formatIdentifier(id, preferredId) {
+	if (id === void 0) return "";
+	return preferredId.map((f) => formatIdentifierField(id[f])).join("/");
+}
+/**
+* URL-encoded form of `formatIdentifier` — for `processor: 'navigate'`
+* `$1` substitution. Each field is `encodeURIComponent`'d, then joined
+* with a literal `/`. Missing fields render as empty segments (e.g.
+* `acme//jane`), not the literal `"undefined"`.
 */
-function encodeNavigatePk(pk) {
-	if (pk === null || pk === void 0) return "";
-	return (typeof pk === "object" ? Object.values(pk) : [pk]).map((v) => encodeURIComponent(String(v))).join("/");
+function encodeNavigateId(id, preferredId) {
+	return preferredId.map((f) => encodeURIComponent(formatIdentifierField(id[f]))).join("/");
+}
+function describeShape(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
 }
 //#endregion
 exports.ActionDisabledError = ActionDisabledError;
@@ -341,3 +390,6 @@ exports.ActionNotFoundError = ActionNotFoundError;
 exports.ActionUnsupportedError = ActionUnsupportedError;
 exports.Client = Client;
 exports.ClientError = ClientError;
+exports.encodeNavigateId = encodeNavigateId;
+exports.formatIdentifier = formatIdentifier;
+exports.formatIdentifierField = formatIdentifierField;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-DNm9kCoq.cjs";
+import { C as TDbInsertManyResult, D as Uniquery, E as TypedWithRelation, O as UniqueryControls, S as TDbDeleteResult, T as TDbUpdateResult, _ as OwnOf, b as SearchIndexInfo, c as AtscriptClientShape, d as DataOf, f as FieldMeta, g as NavOf, h as MetaResponse, i as ValidatorMode, l as ClientOptions, m as IdOf, n as ClientValidator, o as AggregateQuery, p as FilterExpr, s as AggregateResult, t as ClientValidationError, u as ClientResponse, v as PageResult, w as TDbInsertResult, x as ServerError, y as RelationInfo } from "./validator-BminFmAf.cjs";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
@@ -8,6 +8,7 @@ type Own<T> = OwnOf<T>;
 type Nav<T> = NavOf<T>;
 type Data<T> = DataOf<T>;
 type Id<T> = IdOf<T>;
+type Response<T, Q> = ClientResponse<T, Q>;
 /**
  * HTTP client for moost-db REST endpoints.
  *
@@ -29,7 +30,7 @@ type Id<T> = IdOf<T>;
  * const page = await users.pages({ filter: { active: true } }, 1, 20)
  * ```
  */
-declare class Client<T = Record<string, unknown>> {
+declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private readonly _path;
   private readonly _baseUrl;
   private readonly _fetch;
@@ -40,8 +41,11 @@ declare class Client<T = Record<string, unknown>> {
   constructor(path: string, opts?: ClientOptions);
   /**
    * `GET /query` — query records with typed filter, sort, select, and relations.
+   *
+   * The response type narrows by the literal `$with` array in `query` —
+   * relations not listed in `$with` are stripped from the row type.
    */
-  query(query?: Uniquery$1<Own<T>, Nav<T>>): Promise<Data<T>[]>;
+  query<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q): Promise<Response<T, Q>[]>;
   /**
    * `GET /query` with `$count: true` — returns record count.
    */
@@ -57,16 +61,22 @@ declare class Client<T = Record<string, unknown>> {
   })[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
   /**
    * `GET /pages` — paginated query with typed filter and relations.
+   *
+   * Response rows narrow by the literal `$with` array — same algebra as
+   * {@link query}.
    */
-  pages(query?: Uniquery$1<Own<T>, Nav<T>>, page?: number, size?: number): Promise<PageResult<Data<T>>>;
+  pages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q>>>;
   /**
    * `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
    *
-   * Returns `null` on 404.
+   * Returns `null` on 404. Response narrows by the literal `$with` array in
+   * `query.controls` — same algebra as {@link query}.
    */
-  one(id: Id<T>, query?: {
+  one<Q extends {
+    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
+  } = {
     controls?: UniqueryControls$1<Own<T>, Nav<T>>;
-  }): Promise<Data<T> | null>;
+  }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
   /**
    * `POST /` — insert one record.
    */
@@ -95,24 +105,35 @@ declare class Client<T = Record<string, unknown>> {
    * Invoke a declared action by name. Resolves the action descriptor from the
    * cached `/meta` response, then dispatches based on `processor`:
    *
-   * - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+   * - `'backend'` → POST the identifier as a JSON body to the action's path
    *   and return the parsed server response. The HTTP method is always POST.
    * - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
-   *   PK (URL-encoded; composite PKs are URL-encoded per field and joined
-   *   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
-   *   verbatim. The default navigator (browser only) calls
-   *   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
-   *   integrate with a SPA router.
+   *   identifier values, walking `meta.preferredId` field order (each value
+   *   URL-encoded, compound IDs joined with `/`); for `level: 'rows'` or
+   *   `'table'`, navigate to `value` verbatim. The default navigator (browser
+   *   only) calls `window.location.assign(url)`. Provide
+   *   `ClientOptions.navigate` to integrate with a SPA router.
    * - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
    *   are the application's responsibility, not the client's.
    *
    * Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
    *
-   * For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
-   * for a `'rows'` action it is wrapped into a single-element array — the
-   * server-side `@DbActionPKs()` resolver requires an array body.
+   * **Identifier shape (server contract).** `id` is always an object (single)
+   * or array of objects (multi) — never a scalar. Each object's field set
+   * must exactly match one legitimate identification on the table (PK or any
+   * `@db.index.unique` group). Even single-field PK tables send `{ id: 'abc' }`,
+   * not `'abc'`. `level: 'table'` actions take no identifier (`undefined`).
+   *
+   * The TypeScript signature widens to `Partial<Own<T>>` because the server's
+   * exact-match validation cannot be expressed at the type level. Mismatched
+   * field sets produce HTTP 400; obvious type errors (scalars, `null`) are
+   * caught at compile time when `T` is typed.
+   *
+   * @typeParam R Caller-asserted return shape from the action handler. The
+   *              server returns whatever the handler emits (commonly
+   *              `{ message?: string, ... }`); the client cannot validate.
    */
-  action(name: string, pk?: unknown): Promise<unknown>;
+  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[]): Promise<R>;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
@@ -132,6 +153,26 @@ declare class Client<T = Record<string, unknown>> {
   private _buildInit;
   private _send;
 }
+/**
+ * Render a single identifier field for substitution into a navigate-URL
+ * template or human-readable string. `null` / `undefined` collapse to `""`
+ * (NOT the literal `"undefined"` / `"null"` that `String()` would produce).
+ */
+declare function formatIdentifierField(v: unknown): string;
+/**
+ * Render a row identifier as a `/`-joined string in `preferredId`
+ * declaration order — NOT object-key insertion order (which is unstable
+ * across callers). Raw form, no URL-encoding; for prompt text, error
+ * messages, log lines, etc.
+ */
+declare function formatIdentifier(id: Record<string, unknown> | undefined, preferredId: readonly string[]): string;
+/**
+ * URL-encoded form of `formatIdentifier` — for `processor: 'navigate'`
+ * `$1` substitution. Each field is `encodeURIComponent`'d, then joined
+ * with a literal `/`. Missing fields render as empty segments (e.g.
+ * `acme//jane`), not the literal `"undefined"`.
+ */
+declare function encodeNavigateId(id: Record<string, unknown>, preferredId: readonly string[]): string;
 //#endregion
 //#region src/client-error.d.ts
 /**
@@ -159,31 +200,31 @@ declare class ClientError extends Error {
 /**
  * Wire-body shape for `ActionDisabledError` responses (HTTP 409). Extends
  * the base `ServerError` envelope with a `name` discriminator, the action
- * name, and the offending PK(s). The bridge between `@atscript/moost-db`'s
+ * name, and the offending identifier(s). The bridge between `@atscript/moost-db`'s
  * server-side error and this typed client-side subclass is the wire JSON
  * body — neither package depends on the other.
  */
 interface ActionDisabledErrorBody extends ServerError {
   name: "ActionDisabledError";
   action: string;
-  pk?: unknown;
-  pks?: unknown[];
+  id?: Record<string, unknown>;
+  ids?: Record<string, unknown>[];
 }
 /**
  * Typed marker thrown by `Client._send` when the server response body's
  * `name === 'ActionDisabledError'`. The transport / status / base body are
  * identical to a generic `ClientError`; this subclass adds typed accessors
  * so consumers can write `catch (e) { if (e instanceof ActionDisabledError) … }`
- * to access `action` / `pk` / `pks` without indexing into `body`.
+ * to access `action` / `id` / `ids` without indexing into `body`.
  */
 declare class ActionDisabledError extends ClientError {
   name: string;
   /** The `@DbAction` name that rejected the request. */
   get action(): string;
   /** Present only for `'row'`-level rejections. */
-  get pk(): unknown;
-  /** Present only for `'rows'`-level rejections (full list of failing PKs). */
-  get pks(): unknown[] | undefined;
+  get id(): Record<string, unknown> | undefined;
+  /** Present only for `'rows'`-level rejections (full list of failing IDs). */
+  get ids(): Record<string, unknown>[] | undefined;
 }
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
 declare class ActionNotFoundError extends Error {
@@ -204,4 +245,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-DfNMCEKa.mjs";
+import { C as TDbInsertManyResult, D as Uniquery, E as TypedWithRelation, O as UniqueryControls, S as TDbDeleteResult, T as TDbUpdateResult, _ as OwnOf, b as SearchIndexInfo, c as AtscriptClientShape, d as DataOf, f as FieldMeta, g as NavOf, h as MetaResponse, i as ValidatorMode, l as ClientOptions, m as IdOf, n as ClientValidator, o as AggregateQuery, p as FilterExpr, s as AggregateResult, t as ClientValidationError, u as ClientResponse, v as PageResult, w as TDbInsertResult, x as ServerError, y as RelationInfo } from "./validator-DkIQ_0Lc.mjs";
 import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
@@ -8,6 +8,7 @@ type Own<T> = OwnOf<T>;
 type Nav<T> = NavOf<T>;
 type Data<T> = DataOf<T>;
 type Id<T> = IdOf<T>;
+type Response<T, Q> = ClientResponse<T, Q>;
 /**
  * HTTP client for moost-db REST endpoints.
  *
@@ -29,7 +30,7 @@ type Id<T> = IdOf<T>;
  * const page = await users.pages({ filter: { active: true } }, 1, 20)
  * ```
  */
-declare class Client<T = Record<string, unknown>> {
+declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private readonly _path;
   private readonly _baseUrl;
   private readonly _fetch;
@@ -40,8 +41,11 @@ declare class Client<T = Record<string, unknown>> {
   constructor(path: string, opts?: ClientOptions);
   /**
    * `GET /query` — query records with typed filter, sort, select, and relations.
+   *
+   * The response type narrows by the literal `$with` array in `query` —
+   * relations not listed in `$with` are stripped from the row type.
    */
-  query(query?: Uniquery$1<Own<T>, Nav<T>>): Promise<Data<T>[]>;
+  query<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q): Promise<Response<T, Q>[]>;
   /**
    * `GET /query` with `$count: true` — returns record count.
    */
@@ -57,16 +61,22 @@ declare class Client<T = Record<string, unknown>> {
   })[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
   /**
    * `GET /pages` — paginated query with typed filter and relations.
+   *
+   * Response rows narrow by the literal `$with` array — same algebra as
+   * {@link query}.
    */
-  pages(query?: Uniquery$1<Own<T>, Nav<T>>, page?: number, size?: number): Promise<PageResult<Data<T>>>;
+  pages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q>>>;
   /**
    * `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
    *
-   * Returns `null` on 404.
+   * Returns `null` on 404. Response narrows by the literal `$with` array in
+   * `query.controls` — same algebra as {@link query}.
    */
-  one(id: Id<T>, query?: {
+  one<Q extends {
+    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
+  } = {
     controls?: UniqueryControls$1<Own<T>, Nav<T>>;
-  }): Promise<Data<T> | null>;
+  }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
   /**
    * `POST /` — insert one record.
    */
@@ -95,24 +105,35 @@ declare class Client<T = Record<string, unknown>> {
    * Invoke a declared action by name. Resolves the action descriptor from the
    * cached `/meta` response, then dispatches based on `processor`:
    *
-   * - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+   * - `'backend'` → POST the identifier as a JSON body to the action's path
    *   and return the parsed server response. The HTTP method is always POST.
    * - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
-   *   PK (URL-encoded; composite PKs are URL-encoded per field and joined
-   *   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
-   *   verbatim. The default navigator (browser only) calls
-   *   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
-   *   integrate with a SPA router.
+   *   identifier values, walking `meta.preferredId` field order (each value
+   *   URL-encoded, compound IDs joined with `/`); for `level: 'rows'` or
+   *   `'table'`, navigate to `value` verbatim. The default navigator (browser
+   *   only) calls `window.location.assign(url)`. Provide
+   *   `ClientOptions.navigate` to integrate with a SPA router.
    * - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
    *   are the application's responsibility, not the client's.
    *
    * Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
    *
-   * For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
-   * for a `'rows'` action it is wrapped into a single-element array — the
-   * server-side `@DbActionPKs()` resolver requires an array body.
+   * **Identifier shape (server contract).** `id` is always an object (single)
+   * or array of objects (multi) — never a scalar. Each object's field set
+   * must exactly match one legitimate identification on the table (PK or any
+   * `@db.index.unique` group). Even single-field PK tables send `{ id: 'abc' }`,
+   * not `'abc'`. `level: 'table'` actions take no identifier (`undefined`).
+   *
+   * The TypeScript signature widens to `Partial<Own<T>>` because the server's
+   * exact-match validation cannot be expressed at the type level. Mismatched
+   * field sets produce HTTP 400; obvious type errors (scalars, `null`) are
+   * caught at compile time when `T` is typed.
+   *
+   * @typeParam R Caller-asserted return shape from the action handler. The
+   *              server returns whatever the handler emits (commonly
+   *              `{ message?: string, ... }`); the client cannot validate.
    */
-  action(name: string, pk?: unknown): Promise<unknown>;
+  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[]): Promise<R>;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
@@ -132,6 +153,26 @@ declare class Client<T = Record<string, unknown>> {
   private _buildInit;
   private _send;
 }
+/**
+ * Render a single identifier field for substitution into a navigate-URL
+ * template or human-readable string. `null` / `undefined` collapse to `""`
+ * (NOT the literal `"undefined"` / `"null"` that `String()` would produce).
+ */
+declare function formatIdentifierField(v: unknown): string;
+/**
+ * Render a row identifier as a `/`-joined string in `preferredId`
+ * declaration order — NOT object-key insertion order (which is unstable
+ * across callers). Raw form, no URL-encoding; for prompt text, error
+ * messages, log lines, etc.
+ */
+declare function formatIdentifier(id: Record<string, unknown> | undefined, preferredId: readonly string[]): string;
+/**
+ * URL-encoded form of `formatIdentifier` — for `processor: 'navigate'`
+ * `$1` substitution. Each field is `encodeURIComponent`'d, then joined
+ * with a literal `/`. Missing fields render as empty segments (e.g.
+ * `acme//jane`), not the literal `"undefined"`.
+ */
+declare function encodeNavigateId(id: Record<string, unknown>, preferredId: readonly string[]): string;
 //#endregion
 //#region src/client-error.d.ts
 /**
@@ -159,31 +200,31 @@ declare class ClientError extends Error {
 /**
  * Wire-body shape for `ActionDisabledError` responses (HTTP 409). Extends
  * the base `ServerError` envelope with a `name` discriminator, the action
- * name, and the offending PK(s). The bridge between `@atscript/moost-db`'s
+ * name, and the offending identifier(s). The bridge between `@atscript/moost-db`'s
  * server-side error and this typed client-side subclass is the wire JSON
  * body — neither package depends on the other.
  */
 interface ActionDisabledErrorBody extends ServerError {
   name: "ActionDisabledError";
   action: string;
-  pk?: unknown;
-  pks?: unknown[];
+  id?: Record<string, unknown>;
+  ids?: Record<string, unknown>[];
 }
 /**
  * Typed marker thrown by `Client._send` when the server response body's
  * `name === 'ActionDisabledError'`. The transport / status / base body are
  * identical to a generic `ClientError`; this subclass adds typed accessors
  * so consumers can write `catch (e) { if (e instanceof ActionDisabledError) … }`
- * to access `action` / `pk` / `pks` without indexing into `body`.
+ * to access `action` / `id` / `ids` without indexing into `body`.
  */
 declare class ActionDisabledError extends ClientError {
   name: string;
   /** The `@DbAction` name that rejected the request. */
   get action(): string;
   /** Present only for `'row'`-level rejections. */
-  get pk(): unknown;
-  /** Present only for `'rows'`-level rejections (full list of failing PKs). */
-  get pks(): unknown[] | undefined;
+  get id(): Record<string, unknown> | undefined;
+  /** Present only for `'rows'`-level rejections (full list of failing IDs). */
+  get ids(): Record<string, unknown>[] | undefined;
 }
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
 declare class ActionNotFoundError extends Error {
@@ -204,4 +245,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/index.mjs

@@ -21,7 +21,7 @@ var ClientError = class extends Error {
 * `name === 'ActionDisabledError'`. The transport / status / base body are
 * identical to a generic `ClientError`; this subclass adds typed accessors
 * so consumers can write `catch (e) { if (e instanceof ActionDisabledError) … }`
-* to access `action` / `pk` / `pks` without indexing into `body`.
+* to access `action` / `id` / `ids` without indexing into `body`.
 */
 var ActionDisabledError = class extends ClientError {
 	name = "ActionDisabledError";
@@ -30,12 +30,12 @@ var ActionDisabledError = class extends ClientError {
 		return this.body.action;
 	}
 	/** Present only for `'row'`-level rejections. */
-	get pk() {
-		return this.body.pk;
+	get id() {
+		return this.body.id;
 	}
-	/** Present only for `'rows'`-level rejections (full list of failing PKs). */
-	get pks() {
-		return this.body.pks;
+	/** Present only for `'rows'`-level rejections (full list of failing IDs). */
+	get ids() {
+		return this.body.ids;
 	}
 };
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
@@ -100,6 +100,9 @@ var Client = class {
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
+	*
+	* The response type narrows by the literal `$with` array in `query` —
+	* relations not listed in `$with` are stripped from the row type.
 	*/
 	async query(query) {
 		return this._get("query", query);
@@ -121,6 +124,9 @@ var Client = class {
 	}
 	/**
 	* `GET /pages` — paginated query with typed filter and relations.
+	*
+	* Response rows narrow by the literal `$with` array — same algebra as
+	* {@link query}.
 	*/
 	async pages(query, page = 1, size = 10) {
 		return this._get("pages", {
@@ -135,7 +141,8 @@ var Client = class {
 	/**
 	* `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
 	*
-	* Returns `null` on 404.
+	* Returns `null` on 404. Response narrows by the literal `$with` array in
+	* `query.controls` — same algebra as {@link query}.
 	*/
 	async one(id, query) {
 		const controlStr = query?.controls ? buildUrl({ controls: query.controls }) : "";
@@ -186,33 +193,45 @@ var Client = class {
 	* Invoke a declared action by name. Resolves the action descriptor from the
 	* cached `/meta` response, then dispatches based on `processor`:
 	*
-	* - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+	* - `'backend'` → POST the identifier as a JSON body to the action's path
 	*   and return the parsed server response. The HTTP method is always POST.
 	* - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
-	*   PK (URL-encoded; composite PKs are URL-encoded per field and joined
-	*   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
-	*   verbatim. The default navigator (browser only) calls
-	*   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
-	*   integrate with a SPA router.
+	*   identifier values, walking `meta.preferredId` field order (each value
+	*   URL-encoded, compound IDs joined with `/`); for `level: 'rows'` or
+	*   `'table'`, navigate to `value` verbatim. The default navigator (browser
+	*   only) calls `window.location.assign(url)`. Provide
+	*   `ClientOptions.navigate` to integrate with a SPA router.
 	* - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
 	*   are the application's responsibility, not the client's.
 	*
 	* Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
 	*
-	* For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
-	* for a `'rows'` action it is wrapped into a single-element array — the
-	* server-side `@DbActionPKs()` resolver requires an array body.
+	* **Identifier shape (server contract).** `id` is always an object (single)
+	* or array of objects (multi) — never a scalar. Each object's field set
+	* must exactly match one legitimate identification on the table (PK or any
+	* `@db.index.unique` group). Even single-field PK tables send `{ id: 'abc' }`,
+	* not `'abc'`. `level: 'table'` actions take no identifier (`undefined`).
+	*
+	* The TypeScript signature widens to `Partial<Own<T>>` because the server's
+	* exact-match validation cannot be expressed at the type level. Mismatched
+	* field sets produce HTTP 400; obvious type errors (scalars, `null`) are
+	* caught at compile time when `T` is typed.
+	*
+	* @typeParam R Caller-asserted return shape from the action handler. The
+	*              server returns whatever the handler emits (commonly
+	*              `{ message?: string, ... }`); the client cannot validate.
 	*/
-	async action(name, pk) {
-		const action = (await this.meta()).actions.find((a) => a.name === name);
+	async action(name, id) {
+		const meta = await this.meta();
+		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
 		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
 		if (action.processor === "navigate") {
-			const url = this._interpolateNavigateUrl(action, pk);
+			const url = this._interpolateNavigateUrl(action, id, meta.preferredId);
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, pk);
+		const body = this._buildActionBody(action, id);
 		return this._postAction(action, body);
 	}
 	/**
@@ -232,16 +251,21 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
-	_buildActionBody(action, pk) {
+	_buildActionBody(action, id) {
 		if (action.level === "table") return void 0;
-		if (action.level !== "rows") return pk;
-		if (Array.isArray(pk)) return pk;
-		return pk === void 0 ? [] : [pk];
+		if (action.level === "rows") {
+			if (id === void 0) return [];
+			if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
+			return id;
+		}
+		if (id !== null && typeof id === "object" && !Array.isArray(id)) return id;
+		throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
 	}
-	_interpolateNavigateUrl(action, pk) {
+	_interpolateNavigateUrl(action, id, preferredId) {
 		if (action.level !== "row") return action.value;
-		if (pk === void 0) return action.value;
-		return action.value.replace(/\$1/g, encodeNavigatePk(pk));
+		if (id === void 0) return action.value;
+		if (id === null || typeof id !== "object" || Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): row-level navigate actions require an identifier object; received ${describeShape(id)}.`);
+		return action.value.replace(/\$1/g, encodeNavigateId(id, preferredId));
 	}
 	async _dispatchNavigate(action, url) {
 		if (this._navigate) {
@@ -325,14 +349,39 @@ var Client = class {
 	}
 };
 /**
-* Encode a row PK for substitution into a `processor: 'navigate'` URL template.
-* Scalars are URL-encoded directly; composite PK objects have each value
-* URL-encoded and joined with `/` in object-key order (which mirrors
-* `primaryKeys` for the table).
+* Render a single identifier field for substitution into a navigate-URL
+* template or human-readable string. `null` / `undefined` collapse to `""`
+* (NOT the literal `"undefined"` / `"null"` that `String()` would produce).
+*/
+function formatIdentifierField(v) {
+	if (v === null || v === void 0) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+	return JSON.stringify(v);
+}
+/**
+* Render a row identifier as a `/`-joined string in `preferredId`
+* declaration order — NOT object-key insertion order (which is unstable
+* across callers). Raw form, no URL-encoding; for prompt text, error
+* messages, log lines, etc.
+*/
+function formatIdentifier(id, preferredId) {
+	if (id === void 0) return "";
+	return preferredId.map((f) => formatIdentifierField(id[f])).join("/");
+}
+/**
+* URL-encoded form of `formatIdentifier` — for `processor: 'navigate'`
+* `$1` substitution. Each field is `encodeURIComponent`'d, then joined
+* with a literal `/`. Missing fields render as empty segments (e.g.
+* `acme//jane`), not the literal `"undefined"`.
 */
-function encodeNavigatePk(pk) {
-	if (pk === null || pk === void 0) return "";
-	return (typeof pk === "object" ? Object.values(pk) : [pk]).map((v) => encodeURIComponent(String(v))).join("/");
+function encodeNavigateId(id, preferredId) {
+	return preferredId.map((f) => encodeURIComponent(formatIdentifierField(id[f]))).join("/");
+}
+function describeShape(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
 }
 //#endregion
-export { ActionDisabledError, ActionNotFoundError, ActionUnsupportedError, Client, ClientError };
+export { ActionDisabledError, ActionNotFoundError, ActionUnsupportedError, Client, ClientError, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/{validator-DNm9kCoq.d.cts → validator-BminFmAf.d.cts}

@@ -1,5 +1,5 @@
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
+import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 
@@ -59,6 +59,21 @@ interface ServerError {
     details?: unknown[];
   }>;
 }
+/**
+ * Minimal brand shape every `Client<T>` generic must satisfy. All fields are
+ * optional — plain interfaces and `Record<string, unknown>` satisfy this
+ * constraint, so `new Client('/path')` (no generic) keeps working with
+ * `unknown` / `Record<string, unknown>` fallbacks. Atscript-generated types
+ * fill these brand fields and unlock per-method inference.
+ */
+type AtscriptClientShape = {
+  __pk?: unknown;
+  __ownProps?: Record<string, unknown>;
+  __navProps?: Record<string, unknown>;
+  type?: {
+    __dataType?: unknown;
+  };
+};
 /** Extract the data type from an Atscript annotated type `T`. */
 type DataOf<T> = T extends {
   type: {
@@ -77,6 +92,22 @@ type NavOf<T> = T extends {
 type IdOf<T> = T extends {
   __pk: infer PK;
 } ? PK : unknown;
+/**
+ * Narrow a read-method response type by the literal `$with` array in the
+ * query, mirroring the backend's `DbResponse<Data, Nav, Q>` algebra. Nav
+ * properties are stripped by default and re-added only for relations the
+ * caller listed in `$with`. When `T` carries no nav-prop brand, `DbResponse`
+ * short-circuits to the data type. `$actions` is always optional — the
+ * server emits it only when the request set `?$actions=true`.
+ */
+type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
+  /**
+   * Server-evaluated per-row availability for `'row'` and `'rows'`-level
+   * actions. Each entry is the `name` of an action that is NOT disabled for
+   * this row.
+   */
+  $actions?: string[];
+};
 //#endregion
 //#region src/validator.d.ts
 /**
@@ -125,4 +156,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse): ClientValidator;
 //#endregion
-export { TDbUpdateResult$1 as C, UniqueryControls$1 as E, TDbInsertResult$1 as S, Uniquery$1 as T, RelationInfo as _, createClientValidator as a, TDbDeleteResult$1 as b, ClientOptions as c, FilterExpr as d, IdOf as f, PageResult as g, OwnOf as h, ValidatorMode$1 as i, DataOf as l, NavOf as m, ClientValidator as n, AggregateQuery$1 as o, MetaResponse as p, DbValidationContext as r, AggregateResult$1 as s, ClientValidationError as t, FieldMeta as u, SearchIndexInfo as v, TypedWithRelation as w, TDbInsertManyResult$1 as x, ServerError as y };
+export { TDbInsertManyResult$1 as C, Uniquery$1 as D, TypedWithRelation as E, UniqueryControls$1 as O, TDbDeleteResult$1 as S, TDbUpdateResult$1 as T, OwnOf as _, createClientValidator as a, SearchIndexInfo as b, AtscriptClientShape as c, DataOf as d, FieldMeta as f, NavOf as g, MetaResponse as h, ValidatorMode$1 as i, ClientOptions as l, IdOf as m, ClientValidator as n, AggregateQuery$1 as o, FilterExpr as p, DbValidationContext as r, AggregateResult$1 as s, ClientValidationError as t, ClientResponse as u, PageResult as v, TDbInsertResult$1 as w, ServerError as x, RelationInfo as y };

package/dist/{validator-DfNMCEKa.d.mts → validator-DkIQ_0Lc.d.mts}

@@ -1,7 +1,7 @@
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
+import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 
 //#region src/types.d.ts
 /** Options for creating a Client instance. */
@@ -59,6 +59,21 @@ interface ServerError {
     details?: unknown[];
   }>;
 }
+/**
+ * Minimal brand shape every `Client<T>` generic must satisfy. All fields are
+ * optional — plain interfaces and `Record<string, unknown>` satisfy this
+ * constraint, so `new Client('/path')` (no generic) keeps working with
+ * `unknown` / `Record<string, unknown>` fallbacks. Atscript-generated types
+ * fill these brand fields and unlock per-method inference.
+ */
+type AtscriptClientShape = {
+  __pk?: unknown;
+  __ownProps?: Record<string, unknown>;
+  __navProps?: Record<string, unknown>;
+  type?: {
+    __dataType?: unknown;
+  };
+};
 /** Extract the data type from an Atscript annotated type `T`. */
 type DataOf<T> = T extends {
   type: {
@@ -77,6 +92,22 @@ type NavOf<T> = T extends {
 type IdOf<T> = T extends {
   __pk: infer PK;
 } ? PK : unknown;
+/**
+ * Narrow a read-method response type by the literal `$with` array in the
+ * query, mirroring the backend's `DbResponse<Data, Nav, Q>` algebra. Nav
+ * properties are stripped by default and re-added only for relations the
+ * caller listed in `$with`. When `T` carries no nav-prop brand, `DbResponse`
+ * short-circuits to the data type. `$actions` is always optional — the
+ * server emits it only when the request set `?$actions=true`.
+ */
+type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
+  /**
+   * Server-evaluated per-row availability for `'row'` and `'rows'`-level
+   * actions. Each entry is the `name` of an action that is NOT disabled for
+   * this row.
+   */
+  $actions?: string[];
+};
 //#endregion
 //#region src/validator.d.ts
 /**
@@ -125,4 +156,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse): ClientValidator;
 //#endregion
-export { TDbUpdateResult$1 as C, UniqueryControls$1 as E, TDbInsertResult$1 as S, Uniquery$1 as T, RelationInfo as _, createClientValidator as a, TDbDeleteResult$1 as b, ClientOptions as c, FilterExpr as d, IdOf as f, PageResult as g, OwnOf as h, ValidatorMode$1 as i, DataOf as l, NavOf as m, ClientValidator as n, AggregateQuery$1 as o, MetaResponse as p, DbValidationContext as r, AggregateResult$1 as s, ClientValidationError as t, FieldMeta as u, SearchIndexInfo as v, TypedWithRelation as w, TDbInsertManyResult$1 as x, ServerError as y };
+export { TDbInsertManyResult$1 as C, Uniquery$1 as D, TypedWithRelation as E, UniqueryControls$1 as O, TDbDeleteResult$1 as S, TDbUpdateResult$1 as T, OwnOf as _, createClientValidator as a, SearchIndexInfo as b, AtscriptClientShape as c, DataOf as d, FieldMeta as f, NavOf as g, MetaResponse as h, ValidatorMode$1 as i, ClientOptions as l, IdOf as m, ClientValidator as n, AggregateQuery$1 as o, FilterExpr as p, DbValidationContext as r, AggregateResult$1 as s, ClientValidationError as t, ClientResponse as u, PageResult as v, TDbInsertResult$1 as w, ServerError as x, RelationInfo as y };

package/dist/validator.d.cts

@@ -1,2 +1,2 @@
-import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DNm9kCoq.cjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-BminFmAf.cjs";
 export { ClientValidationError, ClientValidator, DbValidationContext, ValidatorMode, createClientValidator };

package/dist/validator.d.mts

@@ -1,2 +1,2 @@
-import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DfNMCEKa.mjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DkIQ_0Lc.mjs";
 export { ClientValidationError, ClientValidator, DbValidationContext, ValidatorMode, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -50,7 +50,7 @@
     "@atscript/typescript": "^0.1.50",
     "@uniqu/core": "^0.1.5",
     "unplugin-atscript": "^0.1.50",
-    "@atscript/db": "0.1.58"
+    "@atscript/db": "0.1.60"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",