@hodeinavarro/odoo-rpc-ts 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hodei Navarro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,401 @@
+# @hodeinavarro/odoo-rpc-ts
+
+Effect-native, strongly-typed Odoo RPC client for TypeScript. **Odoo 16–19**,
+three wire protocols behind one seam — JSON-RPC, the new JSON-2 API (19+),
+and the cookie-session web route — with a tagged-error taxonomy you can
+`catchTag` instead of parsing messages.
+
+> **Status:** public and pre-1.0. Releases are published to the public npm
+> registry with provenance.
+
+## Scope
+
+This package owns generic Odoo transport, authentication/session, schema
+decoding, typed records, connection profiles, and a small set of reusable
+services. It does not own application-specific models, UI, persistence,
+workflow policy, or automatic protocol selection. XML-RPC and generated
+per-model clients are deliberately out of scope.
+
+Install it from the public npm registry with:
+
+```
+pnpm add @hodeinavarro/odoo-rpc-ts effect@4.0.0-beta.93
+pnpm add @effect/platform-node@4.0.0-beta.93   # or run in the browser with FetchHttpClient
+```
+
+Effect 4 is in beta and moves between betas — pin it **exact** (no caret) and
+upgrade deliberately.
+
+## Quick start
+
+Set `ODOO_URL`, `ODOO_DB`, `ODOO_USERNAME`, and `ODOO_API_KEY` (or
+`ODOO_PASSWORD`), then:
+
+```ts
+import { Effect, Layer, Schema } from "effect";
+import { NodeHttpClient } from "@effect/platform-node";
+import { JsonRpcTransport, OdooClient, OdooClientLive, RpcLive } from "@hodeinavarro/odoo-rpc-ts";
+
+// One layer graph: client → rpc → transport → your HTTP runtime.
+const OdooLive = OdooClientLive.layer.pipe(
+  Layer.provideMerge(RpcLive.layer),
+  Layer.provide(JsonRpcTransport.layerConfig),
+  Layer.provide(NodeHttpClient.layerUndici),
+);
+
+// Rows decode through a schema — drift fails loudly, never a silent cast.
+const Partner = Schema.Struct({
+  id: Schema.Number,
+  name: Schema.String,
+  email: Schema.Union([Schema.String, Schema.Literal(false)]), // Odoo sends false, not null
+});
+
+const companies = Effect.gen(function* () {
+  const odoo = yield* OdooClient;
+  return yield* odoo.searchRead(
+    "res.partner",
+    { domain: [["is_company", "=", true]], fields: ["id", "name", "email"], limit: 10 },
+    Partner,
+  );
+});
+
+await companies.pipe(Effect.provide(OdooLive), Effect.runPromise);
+```
+
+`OdooClient` gives you `searchRead`, `search`, `read`, `create`, `write`,
+`unlink`, `fieldsGet`, `searchCount`, `readGroup`, `nameSearch`, `ref`
+(resolve an XML id to `[model, id]`), and a generic `call` escape hatch —
+every op works over every transport. `Rpc.callKw` sits underneath for
+anything else. `RpcLive.layer` seeds the user's server-side context
+(`lang`, `tz` — via `res.users.context_get`, lazily on the first call) as
+the base tier of every call, so translated fields come back in the user's
+language; use `RpcLive.layerWith()` to opt out of seeding.
+
+## Everyday workflows
+
+**Find or create:**
+
+```ts
+const findOrCreatePartner = (email: string, name: string) =>
+  Effect.gen(function* () {
+    const odoo = yield* OdooClient;
+    const existing = yield* odoo.search("res.partner", {
+      domain: [["email", "=", email]],
+      limit: 1,
+    });
+    if (existing.length > 0) return existing[0]!;
+    const [id] = yield* odoo.create("res.partner", { name, email });
+    return id!;
+  });
+```
+
+**Bulk update with domain combinators** (`AND` / `OR` / `NOT`):
+
+```ts
+import { AND, OR } from "@hodeinavarro/odoo-rpc-ts";
+
+const archiveStaleLeads = Effect.gen(function* () {
+  const odoo = yield* OdooClient;
+  const stale = yield* odoo.search("crm.lead", {
+    domain: AND(
+      [["active", "=", true]],
+      OR([["probability", "=", 0]], [["write_date", "<", "2025-01-01"]]),
+    ),
+  });
+  if (stale.length === 0) return 0;
+  yield* odoo.write("crm.lead", stale, { active: false });
+  return stale.length;
+});
+```
+
+**Paginate a big model:**
+
+```ts
+const allPartnerIds = Effect.gen(function* () {
+  const odoo = yield* OdooClient;
+  const out: number[] = [];
+  for (let offset = 0; ; offset += 500) {
+    const page = yield* odoo.search("res.partner", { limit: 500, offset });
+    out.push(...page);
+    if (page.length < 500) return out;
+  }
+});
+```
+
+## Typed records and relations
+
+Two per-protocol tiers — dialects of the same design, not competitors. Both
+make N+1 storms structurally impossible, and every RPC stays visible. The
+**spec tier** speaks the `specification` protocol Odoo grew in 17; the
+**classic tier** speaks the classic `[id, name]`-pair protocol every supported
+version (16+) understands. Pick by the oldest server you must reach.
+
+**Spec tier — declared prefetch** (Odoo 17+ `specification` protocol) —
+declare the graph, get ONE `web_search_read`:
+
+```ts
+import { defineRecord, Many2One, OdooClient, OdooDateTime } from "@hodeinavarro/odoo-rpc-ts"
+import { Schema } from "effect"
+
+const Company = defineRecord("res.company", { name: Schema.String })
+const Partner = defineRecord("res.partner", {
+  name: Schema.String,
+  create_date: OdooDateTime,            // parsed as UTC, never localized
+  company_id: Many2One(Company),        // row.company_id?.name — already fetched
+})
+
+const rows = Effect.gen(function* () {
+  const odoo = yield* OdooClient
+  return yield* odoo.searchTyped(Partner, { domain: [["is_company", "=", true]], limit: 10 })
+})
+```
+
+The version gate is explicit: the spec tier's relations REQUIRE Odoo 17+.
+Provide a `VersionResolver` layer and the gate holds automatically — a
+declared relation on Odoo 16 fails with `ProtocolUnsupportedError` before any
+round trip, while relation-free records degrade to plain `search_read`.
+`saveTyped` (17+) writes and returns the fresh nested snapshot in one call.
+For anything that must also run on 16, use the classic tier below.
+
+**Classic tier — explicit traversal** (all versions, 16+) — rows keep the
+classic `[id, name]` refs; batch the hop when you need it, exactly one deduped
+`read`:
+
+```ts
+import { Many2OneRefOrNull, OdooClient } from "@hodeinavarro/odoo-rpc-ts"
+
+const PartnerRow = Schema.Struct({
+  id: Schema.Number,
+  name: Schema.String,
+  company_id: Many2OneRefOrNull,        // Odoo's [id, name] pair; false -> null
+})
+const CompanyRow = Schema.Struct({ id: Schema.Number, name: Schema.String })
+
+const pairs = Effect.gen(function* () {
+  const odoo = yield* OdooClient
+  const rows = yield* odoo.searchRecordsTyped("res.partner", {}, PartnerRow)
+  return yield* rows.joinRelated("company_id", "res.company", CompanyRow) // ONE read
+})
+```
+
+## x2many writes without magic tuples
+
+```ts
+import { Command } from "@hodeinavarro/odoo-rpc-ts"
+
+yield* odoo.write("res.partner", [companyId], {
+  child_ids: [Command.create({ name: "New contact" }), Command.link(existingId)],
+})
+```
+
+## Services: databases, reports, profiles
+
+```ts
+import { DbService, ReportService } from "@hodeinavarro/odoo-rpc-ts"
+
+// database administration (master-password gated; Node-oriented)
+const names = yield* DbService.listDatabases(url)
+yield* DbService.duplicate(url, master, "prod", "staging")
+
+// report downloads over the cookie session — works on ALL of 16-19
+const pdf = yield* ReportService.download(session, {
+  reportName: "base.report_irmodeloverview",
+  ids: [modelId],
+})
+```
+
+Connection profiles never serialize secrets: `ProfileData` holds the metadata,
+secrets cross only as `Redacted` through a `SecretStore` you implement (OS
+keyring in Node, IndexedDB in the browser); in-memory layers ship for tests.
+Besides api-key/password presets, `saveSessionProfile(name, url, sessionId)`
+stores a harvested `session_id` cookie (the TOTP/SSO flow — no credentials
+exist); `loadProfile` returns a tagged union, and its `"session"` arm feeds
+`CookieSessionLive.fromExisting` directly instead of fabricating a config.
+
+## Bring your own HTTP layer
+
+The library depends only on the abstract `HttpClient` tag — timeouts, proxies,
+custom CAs, and retry policy are yours:
+
+```ts
+import { FetchHttpClient, HttpClient } from "effect/unstable/http"
+import { Layer } from "effect"
+
+const TunedHttp = Layer.effect(
+  HttpClient.HttpClient,
+  Effect.map(HttpClient.HttpClient, (client) => client.pipe(HttpClient.retryTransient({ times: 3 }))),
+).pipe(Layer.provide(FetchHttpClient.layer))
+```
+
+## Errors are a typed API
+
+Every failure is a tagged error carrying the raw fault, the Python exception
+name, and the call site — normalized identically across all three protocols:
+
+```ts
+const created = Effect.gen(function* () {
+  const odoo = yield* OdooClient;
+  return yield* odoo.create("res.partner", { name: "Ada" });
+}).pipe(
+  Effect.catchTags({
+    OdooValidationError: (e) => Effect.die(`rejected by a constraint: ${e.message}`),
+    OdooAccessError: () => Effect.succeed([]), // degrade gracefully
+    OdooAuthenticationError: (e) => Effect.die(e.reason), // "invalid-credentials" | "mfa-pending" | …
+  }),
+);
+```
+
+The full union: `OdooTransportError` · `OdooAuthenticationError` ·
+`SessionExpiredError` · `SchemaDriftError` · `ProtocolUnsupportedError` ·
+`OdooServerError` (+ `OdooAccessError`, `OdooValidationError`,
+`OdooMissingError`, `OdooUserError`, `OdooLockError`). Unknown server faults
+are preserved on `OdooServerError` with the raw name — never swallowed.
+`OdooTransportError` retains only a sanitized `{ method, url }` request,
+failure `kind`, safe message, and optional HTTP status; it never exposes the
+platform request, response, headers, body, or cause.
+
+## Pick your transport
+
+Same application code, different layer — always your explicit choice:
+
+```ts
+// Server-to-server, stateless: /jsonrpc + execute_kw (Odoo 16–19)
+Layer.provide(JsonRpcTransport.layerConfig);
+
+// Odoo 19+: /json/2, bearer API key, real HTTP status codes
+Layer.provide(Json2Transport.layerConfig);
+
+// Browser/long-lived: cookie session over /web/dataset/call_kw
+Layer.provide(WebTransport.layerConfig).pipe(Layer.provideMerge(CookieSessionLive.layerConfig));
+```
+
+Cookie sessions expire; recovery is opt-in, never magic:
+
+```ts
+import { CookieSession, retryOnSessionExpired } from "@hodeinavarro/odoo-rpc-ts";
+
+const resilientCount = Effect.gen(function* () {
+  const session = yield* CookieSession;
+  const odoo = yield* OdooClient;
+  return yield* retryOnSessionExpired(odoo.searchCount("res.partner", []), session);
+});
+```
+
+Already hold a `session_id` minted elsewhere — e.g. harvested from an
+embedded browser window after the user completed the real `/web/login` page
+(the only stock flow for TOTP/SSO accounts)? Adopt it directly; the client
+never holds credentials:
+
+```ts
+import { Redacted } from "effect";
+import { CookieSessionLive, WebTransport } from "@hodeinavarro/odoo-rpc-ts";
+
+const url = new URL("https://erp.example.com");
+
+const HarvestedOdoo = OdooClientLive.layer.pipe(
+  Layer.provideMerge(RpcLive.layer),
+  Layer.provide(WebTransport.layer({ url })), // no credentials needed
+  Layer.provide(
+    CookieSessionLive.layerFromExisting({
+      url,
+      sessionId: Redacted.make(harvestedCookieValue),
+      // Optional renew hook: mint a fresh cookie after an invalidate (e.g.
+      // reopen the login window). Without it the session cannot recover —
+      // once the server kills it, calls (and the one relogin attempted by
+      // retryOnSessionExpired) fail with SessionExpiredError, and your shell
+      // constructs a new session from a fresh cookie.
+      // renew: driveLoginWindow,
+    }),
+  ),
+  Layer.provide(NodeHttpClient.layerUndici),
+);
+```
+
+The injected session hydrates honestly on first use via
+`POST /web/session/get_session_info`, so `login` still yields the real
+`uid`/context/version — and a dead cookie surfaces immediately as
+`SessionExpiredError`.
+
+Notes: API keys work as the password on every route (and are _required_ for
+accounts with 2FA). JSON-2 is bearer-only and keyword-only — the client
+handles the encoding differences for you via the transport's `dialect`.
+
+## Testing without a server
+
+`@hodeinavarro/odoo-rpc-ts/testing` ships a deterministic `FakeTransport` with
+a call log:
+
+```ts
+import * as FakeTransport from "@hodeinavarro/odoo-rpc-ts/testing";
+
+const fake = FakeTransport.make({
+  "res.partner": {
+    search_read: () => [{ id: 1, name: "Alice", email: "alice@example.com" }],
+    create: (params) => (params.args[0] as unknown[]).map((_, i) => 100 + i),
+  },
+});
+
+const TestLayer = OdooClientLive.layer.pipe(
+  Layer.provideMerge(RpcLive.layer),
+  Layer.provide(fake.layer),
+);
+```
+
+Config is `effect/Config`, so tests can inject values without touching env:
+
+```ts
+import { ConfigProvider } from "effect";
+
+const TestConfig = ConfigProvider.layer(
+  ConfigProvider.fromEnv({
+    env: {
+      ODOO_URL: "https://mycompany.odoo.com",
+      ODOO_DB: "mycompany",
+      ODOO_USERNAME: "integration@mycompany.com",
+      ODOO_API_KEY: "…",
+    },
+  }),
+);
+```
+
+Want the real thing? `pnpm harness up 16.0` (or 17/18/19) boots a disposable
+seeded Odoo in Docker and `pnpm test:integration` runs the live suite against
+it — see [harness/README.md](harness/README.md).
+
+## Support matrix
+
+|                            | 16.0 | 17.0 | 18.0 | 19.0                    |
+| -------------------------- | ---- | ---- | ---- | ----------------------- |
+| JSON-RPC `/jsonrpc`        | ✓    | ✓    | ✓    | ✓ (deprecated upstream) |
+| Web session + `call_kw`    | ✓    | ✓    | ✓    | ✓                       |
+| JSON-2 `/json/2` (bearer)  | –    | –    | –    | ✓                       |
+| API key auth (as password) | ✓    | ✓    | ✓    | ✓                       |
+
+XML-RPC is deliberately out of scope — JSON-RPC reaches the same services on
+every supported version with strictly richer errors.
+
+## Design, in one paragraph
+
+Everything returns `Effect<A, OdooError, R>` — nothing throws. Services are
+`Context.Service`s wired with `Layer`s; the HTTP runtime is yours (`effect` —
+v4, incl. `effect/unstable/http` — is the only peer dependency, so it runs
+wherever Effect does, browser included). Responses are schema-decoded at the boundary
+(`SchemaDriftError` on drift), secrets stay `Redacted`, TLS is never
+disabled, and no URL/db/credential is ever assumed. The wire behavior was
+mapped from pinned Odoo 16–19 source snapshots and exercised against disposable
+instances. See the reproducible
+[protocol verification record](docs/protocol-verification.md) for the exact
+upstream revisions and source paths; architectural decisions live in
+[AGENTS.md](AGENTS.md).
+
+Every example in this README is compile-checked in CI
+([test/readme-snippets.test-d.ts](test/readme-snippets.test-d.ts)).
+
+## Status
+
+🚧 Pre-1.0. Core is implemented, the unit suite covers the shared API, and CI
+runs the integration suite against Odoo 16, 17, 18, and 19. The API may still
+move while Effect 4 remains in beta.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the local gates and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.

package/dist/client.d.ts

@@ -0,0 +1,184 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import type { Domain } from "./domain.js";
+import { type HasId, type RecordSpec, type TypedRecordSet } from "./records/index.js";
+import { type OdooContext, Rpc } from "./rpc.js";
+import type { TransportCallError } from "./transport.js";
+/** A decoded Odoo record with unmodeled field values. */
+export type OdooRecord = {
+    readonly [field: string]: unknown;
+};
+/** `fields_get` metadata: field name → its attribute dict. */
+export type FieldsMetadata = {
+    readonly [field: string]: OdooRecord;
+};
+/** Options for {@link OdooClient.call} — the undecoded model-method escape hatch. */
+export interface CallOptions {
+    readonly ids?: ReadonlyArray<number>;
+    readonly context?: OdooContext;
+    readonly kwargs?: Record<string, unknown>;
+}
+/** Arguments for `read_group` (all Python-stable parameter names, 16–19). */
+export interface ReadGroupOptions {
+    readonly domain: Domain;
+    readonly fields: ReadonlyArray<string>;
+    readonly groupby: ReadonlyArray<string>;
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly orderby?: string;
+    readonly lazy?: boolean;
+    readonly context?: OdooContext;
+}
+/** Arguments for `name_search`. `args` is the optional search domain. */
+export interface NameSearchOptions {
+    readonly name?: string;
+    readonly args?: Domain;
+    readonly operator?: string;
+    readonly limit?: number;
+    readonly context?: OdooContext;
+}
+/** Options shared by the record-listing ops. `context` merges via {@link Rpc}. */
+export interface SearchOptions {
+    readonly domain?: Domain;
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly order?: string;
+    readonly context?: OdooContext;
+}
+export interface SearchReadOptions extends SearchOptions {
+    readonly fields?: ReadonlyArray<string>;
+}
+/**
+ * Options for the declared-prefetch typed reads ({@link OdooClient.searchTyped}).
+ * `serverMajor` is the explicit version-gate override used when NO
+ * {@link VersionResolver} is in scope: it decides whether the `specification`
+ * path is taken (>= 17) or, for a relation-free spec, degrades to `search_read`
+ * (< 17). When a `VersionResolver` IS provided it always wins and `serverMajor`
+ * is ignored.
+ */
+export interface TypedOptions extends SearchOptions {
+    readonly serverMajor?: number;
+}
+/** Options for {@link OdooClient.readTyped}/`saveTyped` — context + the same
+ * explicit `serverMajor` gate override as {@link TypedOptions}. */
+export interface TypedReadOptions {
+    readonly context?: OdooContext;
+    readonly serverMajor?: number;
+}
+declare const OdooClient_base: Context.ServiceClass<OdooClient, "odoo-rpc-ts/OdooClient", {
+    /**
+     * `search_read(domain, fields, offset, limit, order)` — search and read in
+     * one round trip. Rows decode through `schema` (default: unknown record).
+     */
+    readonly searchRead: <A = OdooRecord, I = A>(model: string, options?: SearchReadOptions, schema?: Schema.Codec<A, I>) => Effect.Effect<ReadonlyArray<A>, TransportCallError>;
+    /**
+     * `search_read`, decoding rows through `schema`, into a {@link TypedRecordSet}
+     * — an immutable snapshot bound to `(rpc, model)` with explicit, batched
+     * relation traversal (`fetchRelated`/`joinRelated`). The schema MUST decode
+     * an `id: number` on every row (`A extends { id: number }`); that id keys all
+     * downstream joins. This is the classic-tier ("explicit traversal",
+     * `[id, name]`-pair protocol, works on 16+) entry
+     * point — one `search_read` here, then one `read` per relation you traverse.
+     */
+    readonly searchRecordsTyped: <A extends HasId, I = A>(model: string, options: SearchReadOptions | undefined, schema: Schema.Codec<A, I>) => Effect.Effect<TypedRecordSet<A>, TransportCallError>;
+    /**
+     * Spec-tier typed search (declared prefetch, 17+ `specification`
+     * protocol). Compiles `record`'s field
+     * graph into ONE `web_search_read` `specification` call and strict-decodes
+     * the nested payload — a declared many2one comes back as a `{ id, ... }` dict
+     * (or `null`), an x2many as a nested list — with NO per-relation round trip.
+     *
+     * VERSION GATE (before any round trip). If a {@link VersionResolver} is in
+     * scope it decides; else `options.serverMajor` does; else the spec path is
+     * assumed (17+). A declared relation on a < 17 server fails with
+     * {@link ProtocolUnsupportedError}; a relation-free declared model degrades to
+     * a plain `search_read` (one trip, identical decode).
+     */
+    readonly searchTyped: <A extends HasId, I = A>(record: RecordSpec<A, I>, options?: TypedOptions) => Effect.Effect<ReadonlyArray<A>, TransportCallError>;
+    /**
+     * Declared-prefetch typed read by ids via `web_read` (17+). Same nested
+     * decode and version gate as {@link searchTyped}; degrades to plain `read`
+     * for a relation-free spec on < 17.
+     */
+    readonly readTyped: <A extends HasId, I = A>(record: RecordSpec<A, I>, ids: ReadonlyArray<number>, options?: TypedReadOptions) => Effect.Effect<ReadonlyArray<A>, TransportCallError>;
+    /**
+     * Write `values` to `ids` and return the FRESH nested snapshot via
+     * `web_save` (17+ ONLY — no degrade, even for a relation-free spec). One
+     * explicit call: it writes, then re-reads through `record`'s compiled
+     * `specification`. On < 17 fails with {@link ProtocolUnsupportedError}.
+     */
+    readonly saveTyped: <A extends HasId, I = A>(record: RecordSpec<A, I>, ids: ReadonlyArray<number>, values: OdooRecord, options?: TypedReadOptions) => Effect.Effect<ReadonlyArray<A>, TransportCallError>;
+    /** `search(domain, offset, limit, order)` — matching record ids. */
+    readonly search: (model: string, options?: SearchOptions) => Effect.Effect<ReadonlyArray<number>, TransportCallError>;
+    /** `read(ids, fields)` — read fields of the given records. */
+    readonly read: (model: string, ids: ReadonlyArray<number>, fields?: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<OdooRecord>, TransportCallError>;
+    /**
+     * `create(vals_list)` — create one or many records, always returning the new
+     * ids as an array (even for a single dict, which is normalized to a
+     * one-element list). Odoo 16–19 `model_create_multi` returns a list of ids
+     * for a list input, so the return contract is uniformly {@link ReadonlyArray}.
+     */
+    readonly create: (model: string, values: OdooRecord | ReadonlyArray<OdooRecord>) => Effect.Effect<ReadonlyArray<number>, TransportCallError>;
+    /** `write(ids, values)` — update records; Odoo returns `true`. */
+    readonly write: (model: string, ids: ReadonlyArray<number>, values: OdooRecord) => Effect.Effect<true, TransportCallError>;
+    /** `unlink(ids)` — delete records; Odoo returns `true`. */
+    readonly unlink: (model: string, ids: ReadonlyArray<number>) => Effect.Effect<true, TransportCallError>;
+    /** `fields_get(attributes=...)` — field metadata keyed by field name. */
+    readonly fieldsGet: (model: string, options?: {
+        readonly attributes?: ReadonlyArray<string>;
+    }) => Effect.Effect<FieldsMetadata, TransportCallError>;
+    /** `search_count(domain)` — number of records matching the domain. */
+    readonly searchCount: (model: string, domain: Domain) => Effect.Effect<number, TransportCallError>;
+    /**
+     * Resolve an external identifier (`module.name`) to its `(model, id)` pair,
+     * via `ir.model.data.check_object_reference`.
+     *
+     * We always use `check_object_reference` (present since Odoo 15) rather than
+     * branching to the legacy `xmlid_to_res_model_res_id` — this library
+     * supports 16–19 only, so the legacy branch is dead weight. A missing xml_id
+     * (the server raises a `ValueError`, mapped to `OdooServerError`) or an
+     * xml_id that resolves but is not visible to the caller (`[model, false]`)
+     * both fail with {@link OdooMissingError} naming the xml_id.
+     */
+    readonly ref: (xmlId: string) => Effect.Effect<readonly [model: string, id: number], TransportCallError>;
+    /**
+     * Escape hatch: call any `model.method` and return its raw, UNDECODED result.
+     * The browse `ids`, `context`, and `kwargs` ride the {@link Rpc} seam; no
+     * schema is applied, so the caller owns validating the shape. Prefer the
+     * typed ops above where one exists.
+     */
+    readonly call: (model: string, method: string, options?: CallOptions) => Effect.Effect<unknown, TransportCallError>;
+    /**
+     * `read_group(domain, fields, groupby, offset, limit, orderby, lazy)` —
+     * aggregate records into groups. Rows decode as unknown records (group keys,
+     * aggregates, and `__count`/`__domain` are model-dependent).
+     */
+    readonly readGroup: (model: string, options: ReadGroupOptions) => Effect.Effect<ReadonlyArray<OdooRecord>, TransportCallError>;
+    /**
+     * `name_search(name, domain, operator, limit)` → `(id, display_name)` pairs.
+     *
+     * WIRE FACT: the second parameter was renamed `args` → `domain` in Odoo 19.
+     * Over the execute_kw family we pass all four POSITIONALLY (position is
+     * stable across 16–19); over JSON-2 (19+) we pass them by MODERN name
+     * (`name`, `domain`, `operator`, `limit`).
+     */
+    readonly nameSearch: (model: string, options?: NameSearchOptions) => Effect.Effect<ReadonlyArray<readonly [number, string]>, TransportCallError>;
+    /**
+     * `name_get()` → `(id, display_name)` pairs for the given ids.
+     *
+     * GOTCHA: `name_get` was REMOVED server-side in Odoo 17+. We call it as-is
+     * with no polyfill; on 17+ it fails as a server fault. Use {@link nameSearch}
+     * or read `display_name` instead on modern servers.
+     */
+    readonly nameGet: (model: string, ids: ReadonlyArray<number>) => Effect.Effect<ReadonlyArray<readonly [number, string]>, TransportCallError>;
+}>;
+/**
+ * Hand-typed, boundary-decoded high-level Odoo operations over {@link Rpc}.
+ * Every result is decoded through `effect/Schema`; a wire-shape mismatch fails
+ * with {@link SchemaDriftError} carrying the raw payload, never a silent cast.
+ */
+export declare class OdooClient extends OdooClient_base {
+}
+/** The {@link OdooClient} layer over an {@link Rpc} service. */
+export declare const layer: Layer.Layer<OdooClient, never, Rpc>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}