Client API reference

@aventara/client is a development-time generator. It reads your deployment's client contract and writes a standalone typed client into your project; the generated client imports nothing from @aventara/client or @aventara/core at runtime. This page lists both halves: what you write (framework.client.ts, avclient) and what is generated. For a guided tour see Frontend client.

What @aventara/client exports

Only the generator's configuration helpers (used in framework.client.ts, never at runtime in your app):

// framework.client.ts
import { defineClientConfig, env } from "@aventara/client";

export default defineClientConfig({
  entrypoint: env("AVENTARA_API_URL"),   // or a literal: "https://api.example.com/api"
  generateAt: "./src/api",
});

AvClientConfigInput

The file is framework.client.ts. The generator loads it like prisma.config: .ts, .mts, .cts, .js, .mjs or .cjs, in ESM or CommonJS syntax (a framework.client.mts from 0.1.0-pilot.1 keeps working). With two of them present the generator refuses.

The .env cascade is read from the current directory before the config is evaluated, highest precedence first: the process environment, .env.<mode>.local, .env.<mode>, .env.local, .env. mode is NODE_ENV, or development. process.env is never written.

Errors, one sentence and exit code 1 (verified):

avclient: entrypoint must use http: or https:, not ftp:
avclient: entrypoint must not carry credentials: the platform's fetch refuses a URL that includes them, and the entrypoint is embedded in the generated client, which ships — authenticate through a custom fetch instead.
avclient: entrypoint reads AVENTARA_API_URL, which is not set in the process environment or in any of .env.development.local, .env.development, .env.local, .env (mode "development").
avclient: Could not fetch the ClientContract from http://localhost:3999/api/_contract: fetch failed (connect ECONNREFUSED 127.0.0.1:3999). Check that the deployment is running and that the entrypoint is its origin plus mount path.

The avclient command

avclient init [options]     Set up this frontend and generate.
avclient generate [--yes]   Fetch <entrypoint>/_contract and write AvClient.ts and generated/.
avclient --help             Print usage, exit 0.
avclient <command> --help   Print that command's usage, exit 0.
avclient --version, -v      Print the generator's version, exit 0.

Flags and exit codes are in the CLI reference. avclient generate asks the server conditionally (If-None-Match with the stored hash): on 304 and identical output it prints avclient: up to date: ... nothing was written. and exits 0.

The generated files

Written into generateAt:

Every file is TypeScript source. The files import each other the way the project's tsconfig.json says (extensionless, .js or .ts; see Client setup), and you import AvClient the same way (Importing the client).

Never edit them: output is deterministic (two runs over one contract write the same bytes) and replaced on every run. Commit the tree; regenerating needs a running server.

What AvClient.ts exports

AvClient

class AvClient {
  constructor(options?: AvClientOptions);
  readonly tx: /* deferred operations, only when transactions are interactive */;
  readonly transaction: /* only when transactions are interactive */;
  all(calls: { [key: string]: Promise<unknown> }, options?: { settle?: boolean; signal?: AbortSignal }): Promise</* one value per key */>;
  // plus one property per Resource:
  readonly [Resource]: { [family]: { [variant]: (args?, options?: AvCallOptions) => Promise<Result> } };
}

Only what the client contract advertises exists, in the type and at runtime: one property per Resource, one per family, one per advertised variant. A call is avClient.<Resource>.<family>.<variant>(args, options?).

all(calls, options?) awaits an object of calls (or avLazy thenables) together and resolves one typed value per key. Strict by default: the first failure rejects it and aborts its other calls. With settle: true each key is { status: "fulfilled", value } or { status: "rejected", reason }. Its signal aborts every call in it. See Several operations in one round trip.

A call runs when it is made, and the calls made in one tick go out as one POST /_all, except a call with headers, a requestId or grouping: false, a transaction, and a cached read, which goes out as a GET.

A Resource whose name collides with a client member (all, tx, transaction, then, constructor, names of Object.prototype) is reached as <name>Model, with one warning at generation; its wire name is unchanged.

A call resolves to the data (record, list, count; null for a first-style miss, A1001). Every other outcome throws.

Values are application values: bigint, Date, Uint8Array, the client's AvDecimal, and JSON as is. Arguments are encoded and results revived for you.

AvClientOptions

If no fetch is available a call throws No fetch is available here; pass one: new AvClient({ fetch }). Importing the client never fails.

const client = new AvClient({
  fetch: (input, init) =>
    fetch(input, { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` } }),
});

AvCallOptions

The last argument of every call. Never sent in the body.

await avClient.User.find.count({}, { requestId: "from-client-1", signal });

AvFetch

typeof globalThis.fetch when your TypeScript lib declares one (DOM, @types/node); otherwise a structural (url, init) => Promise<response> type. The platform fetch therefore needs no cast.

Transactions

When the contract advertises interactive transactions the client has tx and transaction; otherwise neither exists.

const user = avClient.tx.User.create.one({ data: { email: "tx@example.com" }, select: ["id"] });
const post = avClient.tx.Post.create.one({ data: { title: "from tx", authorId: user.$ref("id") } });
const [u, p] = await avClient.transaction([user, post]);

Refused before anything is sent: an undefined in a step's filter, unique selector or cursor (AvValidationError, A2004/V1001 at ["operations", i, "args", …]), the same handle twice (AvValidationError, A2004/V1001) and a $ref to a handle not in the list (A2007/V1010). A $ref can sit in a value, a relation identifier, a unique where, a cursor, a filter at any depth and nested writes (Transactions with $ref); a $ref to a step later in the list is A2007/V1016. More than maxTransactionOperations steps throws AvValidationError A2009/V1014. A builder (tx) never throws for an unreadable argument: transaction([...]) rejects with a TypeError that names where (Client errors). See Transactions.

Error classes

class AvError<C extends AvOperationErrorCode = AvOperationErrorCode> extends Error {
  readonly code: C;        // branch on this
  readonly cause: AvCause;   // { message, issues?, operation? }
}
class AvTransportError extends Error {
  readonly status: number | null;   // null: no response arrived
}
interface AvCause { readonly message: string; readonly issues?: readonly AvValidationIssue[]; readonly operation?: number }
interface AvValidationIssue {
  readonly path?: readonly (string | number)[]; readonly code: AvValidationCode; readonly message: string;
  readonly check?: string; readonly params?: Record<string, unknown>;   // a failed field validator
}

Each has name equal to its class name. When the contract carries field validators, every call and every transaction checks its values first and throws the AvValidationError the server would answer (A2004, the same issues), without sending anything. cause is rebuilt member by member from the envelope, so nothing the protocol does not define reaches it. AvTransportError carries no cause. Full table with fixes: Error codes.

Named types

For each Resource R, exported only when the operation it reads is advertised:

A name that would clash (a Resource UserWhere beside User) walks a rename ladder (User becomes UserModel), one warning each. For the sample schema: User, UserWhere, UserUniqueWhere, UserOrderBy, UserCreateData, UserUpdateData, UserSelect, UserInclude, and the same for Post and Category.

import avClient, { type User, type UserWhere } from "./api/AvClient";

const where: UserWhere = { email: { equals: "ada@example.com" } };
const users: readonly User[] = await avClient.User.find.many({ where });

List results are readonly arrays, so type them readonly User[].

Bound to a contract

A generated client is bound to the exact contract hash and protocol version it was generated from (both in generated/metadata.ts) and sends them on every request. A deployment whose contract differs answers A2005, thrown as AvContractMismatchError, including when the stale client calls an operation the server no longer advertises. Generate against the deployment the client will call, and regenerate when it changes. See Contract hash.

Verified behavior

Run against a live server: find.unique miss throws AvNotFoundError; find.first miss resolves null; an AbortSignal already aborted rejects with AbortError; a client with the wrong hash throws AvContractMismatchError; an unreachable server throws AvTransportError with status === null and the message The request for "User" find.many failed before any response arrived.; a 404 without an envelope throws AvTransportError with status === 404: The response to "User" find.many (HTTP 404) is not an Aventara response envelope.

In a CommonJS project, importing the default export (import avClient from) can resolve to the module object under some TypeScript runners. Use new AvClient() there, or a bundler/ESM setup.

See also

• Frontend client, CLI reference, Error codes
• Protocol API reference: the wire the client speaks.
• Guides: Authentication and guards, Request IDs and diagnostics, Transactions with $ref