@hodeinavarro/odoo-rpc-ts 0.2.0

package/src/testing/fakeTransport.ts

@@ -0,0 +1,84 @@
+import { Effect, Layer, Ref } from "effect";
+import {
+  type CallKwParams,
+  Transport,
+  type TransportCallError,
+  type TransportDialect,
+} from "../transport.ts";
+
+/**
+ * A single scripted method. Receives the full {@link CallKwParams} of the
+ * `call_kw` — `args`, `kwargs`, and the browse `ids` faithfully, because the
+ * seam is the contract, not a projection of it — and returns either a bare value
+ * (wrapped in `Effect.succeed`) or an `Effect`; the latter lets a handler script
+ * a typed transport failure.
+ */
+export type FakeHandler = (
+  params: CallKwParams,
+) => Effect.Effect<unknown, TransportCallError> | unknown;
+
+/**
+ * Scripted responses keyed by `model` then `method`. Anything not scripted is a
+ * test misconfiguration — see the dispatch note in {@link make}.
+ */
+export type FakeHandlers = {
+  readonly [model: string]: {
+    readonly [method: string]: FakeHandler;
+  };
+};
+
+/** A `FakeTransport` layer paired with the log of every call it received. */
+export interface FakeTransport {
+  readonly layer: Layer.Layer<Transport>;
+  /**
+   * Every `call_kw` this transport handled, in order, for assertions. Populated
+   * before the handler runs, so a failing handler still records its call.
+   */
+  readonly callLog: Ref.Ref<ReadonlyArray<CallKwParams>>;
+}
+
+const isEffect = (
+  value: Effect.Effect<unknown, TransportCallError> | unknown,
+): value is Effect.Effect<unknown, TransportCallError> => Effect.isEffect(value);
+
+/**
+ * Build a deterministic, network-free {@link Transport} from scripted handlers.
+ *
+ * GOTCHA: an unhandled model/method is a defect in the test, not a runtime
+ * condition the code under test could ever encounter — so it is an `Effect.die`
+ * (with a precise locator), never a value in the typed failure channel. Tests
+ * that mean to exercise a transport failure must script it explicitly.
+ */
+export const make = (
+  handlers: FakeHandlers,
+  options?: { readonly dialect?: TransportDialect },
+): FakeTransport => {
+  const callLog = Ref.makeUnsafe<ReadonlyArray<CallKwParams>>([]);
+
+  const layer = Layer.succeed(Transport, {
+    dialect: options?.dialect ?? "execute-kw",
+    callKw: (params: CallKwParams) =>
+      Effect.gen(function* () {
+        const handler = handlers[params.model]?.[params.method];
+        if (handler === undefined) {
+          // Every real Odoo server answers the seeded default layer's
+          // res.users.context_get, so the fake does too — WITHOUT logging it
+          // (it is ambient plumbing, and logging it would shift positional
+          // log assertions). Script res.users.context_get to observe/override.
+          if (params.model === "res.users" && params.method === "context_get") {
+            return {};
+          }
+          yield* Ref.update(callLog, (log) => [...log, params]);
+          return yield* Effect.die(
+            `FakeTransport: no handler for ${params.model}.${params.method}`,
+          );
+        }
+        yield* Ref.update(callLog, (log) => [...log, params]);
+
+        const result = handler(params);
+        return isEffect(result) ? yield* result : result;
+      }),
+  });
+
+  return { layer, callLog };
+};

package/src/testing/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @hodeinavarro/odoo-rpc-ts/testing — deterministic test doubles.
+ *
+ * `FakeTransport` is a scripted, network-free {@link Transport} implementation
+ * (AGENTS.md § Testing export). Compose its `.layer` under the service you want
+ * to exercise and assert against its `.callLog`.
+ */
+
+export { make, type FakeHandler, type FakeHandlers, type FakeTransport } from "./fakeTransport.ts";

package/src/transport.ts

@@ -0,0 +1,72 @@
+import { Context, type Effect } from "effect";
+import type { OdooAuthenticationError } from "./errors/auth.ts";
+import type { ProtocolUnsupportedError } from "./errors/protocol.ts";
+import type { SchemaDriftError } from "./errors/schema.ts";
+import type { OdooServerFault } from "./errors/server.ts";
+import type { SessionExpiredError } from "./errors/session.ts";
+import type { OdooTransportError } from "./errors/transport.ts";
+
+/**
+ * Parameters for a single `call_kw`-shaped round trip. Deliberately mirrors
+ * Odoo's `execute_kw(model, method, args, kwargs)`.
+ */
+export interface CallKwParams {
+  readonly model: string;
+  readonly method: string;
+  readonly args: ReadonlyArray<unknown>;
+  readonly kwargs: Record<string, unknown>;
+  /**
+   * The browse target — the record ids the method operates on.
+   *
+   * GOTCHA: this is protocol-agnostic on purpose. JSON-2 sends it as its special
+   * `ids` body key; the execute_kw-family transports (web, `/jsonrpc`) prepend it
+   * as the first positional argument. Callers set `ids` instead of hand-placing
+   * it in `args`, so the same call works over every seam.
+   */
+  readonly ids?: ReadonlyArray<number>;
+}
+
+/**
+ * The complete typed failure channel of a transport round trip. Every seam
+ * (web, JSON-RPC, JSON-2) maps its wire faults into exactly this union at its
+ * choke point, so application code sees one shape regardless of protocol.
+ */
+export type TransportCallError =
+  | OdooTransportError
+  | SessionExpiredError
+  | SchemaDriftError
+  | OdooAuthenticationError
+  | ProtocolUnsupportedError
+  | OdooServerFault;
+
+/**
+ * How a transport encodes calls on the wire. High-level ops that know a
+ * method's Python semantics branch on this — a transport itself never reorders
+ * args. The one live case: `create` vals MUST be positional over the
+ * execute_kw family (Odoo's `call_kw` reads `args[0]` unconditionally, 16–19)
+ * but keyword-only (`vals_list`) over JSON-2.
+ */
+export type TransportDialect = "execute-kw" | "json2";
+
+/**
+ * The one seam every protocol implements. `JsonRpcTransport`, `Json2Transport`,
+ * and the cookie-session `WebTransport` all provide this tag; application code
+ * depends only on it and stays protocol-agnostic.
+ */
+export class Transport extends Context.Service<
+  Transport,
+  {
+    /** The wire dialect — see {@link TransportDialect}. */
+    readonly dialect: TransportDialect;
+
+    /**
+     * Execute one `call_kw`-shaped round trip and return the raw, still-undecoded
+     * result (callers decode through `effect/Schema` at their boundary).
+     *
+     * GOTCHA: the JSON-2 API (`/json/2/<model>/<method>`) is keyword-only — it
+     * cannot take positional `args`. A `Json2Transport` will reject any call
+     * where `args` is non-empty; put everything in `kwargs` when targeting it.
+     */
+    readonly callKw: (params: CallKwParams) => Effect.Effect<unknown, TransportCallError>;
+  }
+>()("odoo-rpc-ts/Transport") {}

package/src/transports/json2.ts

@@ -0,0 +1,303 @@
+import { type Config, Effect, Layer, Option, Redacted, Schema } from "effect";
+import { OdooConfig } from "../config.ts";
+import type { OdooConfig as OdooConfigType } from "../config.ts";
+import { OdooAuthenticationError } from "../errors/auth.ts";
+import { type FaultCallSite, mapServerFault, type RawServerFault } from "../errors/mapFault.ts";
+import { ProtocolUnsupportedError } from "../errors/protocol.ts";
+import { SchemaDriftError } from "../errors/schema.ts";
+import {
+  OdooAccessError,
+  OdooLockError,
+  OdooMissingError,
+  OdooServerError,
+  type OdooServerFault,
+  OdooUserError,
+} from "../errors/server.ts";
+import { OdooTransportError, type RequestInfo } from "../errors/transport.ts";
+import {
+  HttpClient,
+  type HttpClientErrorType,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "../internal/platform.ts";
+import { type CallKwParams, Transport } from "../transport.ts";
+import { ServerVersionInfo } from "../version.ts";
+
+/**
+ * Odoo's `/json/2/<model>/<method>` API (Odoo 19+): a keyword-only, bearer-auth
+ * JSON route that returns the raw method result with no JSON-RPC envelope. This
+ * module is one of the three seams behind the {@link Transport} tag.
+ */
+
+/** Strip any trailing slashes so path segments join cleanly onto a base URL. */
+const baseUrl = (url: URL): string => url.href.replace(/\/+$/u, "");
+
+/** Sanitized request snapshot — never carries the bearer header or body. */
+const requestInfo = (url: string, method: string): RequestInfo => ({ method, url });
+
+const toTransportError =
+  (request: RequestInfo) =>
+  (cause: HttpClientErrorType): OdooTransportError =>
+    OdooTransportError.fromHttpClientError(request, cause);
+
+/**
+ * The `serialize_exception` payload Odoo returns in an error body. Everything is
+ * optional: a bare HTTP failure (proxy 502, gateway timeout) may have no JSON
+ * body at all, in which case we synthesize a fault from the status alone.
+ */
+const SerializeException = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  message: Schema.optional(Schema.String),
+  arguments: Schema.optional(Schema.Array(Schema.Unknown)),
+  context: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  debug: Schema.optional(Schema.String),
+});
+type SerializeException = typeof SerializeException.Type;
+
+const emptyException: SerializeException = {};
+
+/**
+ * Build a {@link RawServerFault} from a decoded exception body and the call
+ * site, honouring `exactOptionalPropertyTypes` (optional keys are attached only
+ * when present, never as explicit `undefined`).
+ */
+const rawFault = (
+  exc: SerializeException,
+  status: number,
+  site: FaultCallSite,
+): RawServerFault & FaultCallSite => ({
+  name: exc.name ?? `http.${status}`,
+  message: exc.message ?? "",
+  arguments: exc.arguments ?? [],
+  context: exc.context ?? {},
+  ...(exc.debug !== undefined ? { debug: exc.debug } : {}),
+  ...(site.model !== undefined ? { model: site.model } : {}),
+  ...(site.method !== undefined ? { method: site.method } : {}),
+});
+
+/** Status → concrete server-fault constructor, for the no-`name` fallback path. */
+const byStatus: Record<number, new (fields: RawServerFault & FaultCallSite) => OdooServerFault> = {
+  403: OdooAccessError,
+  404: OdooMissingError,
+  409: OdooLockError,
+  422: OdooUserError,
+};
+
+/**
+ * The single error-mapping choke point for JSON-2. A non-2xx response becomes
+ * exactly one tagged error:
+ *
+ * - `400` / `415` are transport-shaped (malformed request / wrong media type),
+ *   so they map to {@link OdooTransportError} with sanitized response-error
+ *   metadata.
+ * - Any body with a Python `name` goes through {@link mapServerFault} (shared
+ *   with the other transports), so `AccessDenied` correctly becomes an auth
+ *   error and known exception names get their subtype.
+ * - Otherwise we fall back on the HTTP status, synthesizing a fault named
+ *   `http.<status>` so nothing is silently dropped.
+ */
+const mapJson2Fault = (
+  response: HttpClientResponse.HttpClientResponse,
+  request: RequestInfo,
+  site: FaultCallSite,
+): Effect.Effect<never, OdooTransportError | OdooAuthenticationError | OdooServerFault> =>
+  Effect.gen(function* () {
+    const status = response.status;
+
+    if (status === 400 || status === 415) {
+      // `filterStatusOk` manufactures a response error from the non-ok status
+      // without reading the body; the public error retains only safe metadata.
+      const cause = yield* Effect.flip(HttpClientResponse.filterStatusOk(response)).pipe(
+        Effect.orDie,
+      );
+      return yield* Effect.fail(OdooTransportError.fromHttpClientError(request, cause));
+    }
+
+    // A non-JSON or shape-drifted error body falls back to an empty exception,
+    // which routes to status-based mapping below.
+    const exc = yield* response.json.pipe(
+      Effect.flatMap(Schema.decodeUnknownEffect(SerializeException)),
+      Effect.orElseSucceed(() => emptyException),
+    );
+    const raw = rawFault(exc, status, site);
+
+    // GOTCHA: 401 is checked BEFORE the body name. Odoo 19 serializes a bad
+    // bearer key as werkzeug.exceptions.Unauthorized — an unmapped name that
+    // would otherwise fall through to OdooServerError instead of auth.
+    if (status === 401) {
+      return yield* Effect.fail(
+        new OdooAuthenticationError({
+          reason: "api-key-expired-or-invalid",
+          message: raw.message || "JSON-2 rejected the API key (HTTP 401).",
+        }),
+      );
+    }
+
+    if (exc.name !== undefined) {
+      return yield* Effect.fail(mapServerFault(raw, site));
+    }
+
+    const Ctor = byStatus[status] ?? OdooServerError;
+    return yield* Effect.fail(new Ctor(raw));
+  });
+
+/**
+ * Build a {@link Transport} bound to the JSON-2 route for a given config.
+ *
+ * GOTCHA: JSON-2 is bearer-only. If the config carries `Password` credentials
+ * there is no API key to send, so construction FAILS in the typed channel with
+ * {@link OdooAuthenticationError} rather than silently degrading — this is a
+ * `Layer` build failure, surfaced eagerly so a misconfigured client never issues
+ * an unauthenticated request.
+ */
+export const make = (
+  config: OdooConfigType,
+): Effect.Effect<typeof Transport.Service, OdooAuthenticationError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (config.credentials._tag !== "ApiKey") {
+      return yield* Effect.fail(
+        new OdooAuthenticationError({
+          reason: "invalid-credentials",
+          message:
+            "JSON-2 transport is bearer-only and requires ApiKey credentials; " +
+            "got Password. Provide ODOO_API_KEY.",
+        }),
+      );
+    }
+
+    const apiKey = config.credentials.apiKey;
+    const client = yield* HttpClient.HttpClient;
+    const base = baseUrl(config.url);
+
+    const callKw = (params: CallKwParams): Effect.Effect<unknown, TransportCallErrorLocal> => {
+      const site: FaultCallSite = { model: params.model, method: params.method };
+
+      const run = Effect.gen(function* () {
+        // JSON-2 cannot carry positional args; reordering silently would corrupt
+        // the call, so reject loudly and name the offending method.
+        if (params.args.length > 0) {
+          return yield* Effect.fail(
+            new ProtocolUnsupportedError({
+              protocol: "json-2",
+              serverVersion: "19+",
+              message:
+                `JSON-2 is keyword-only: "${params.model}.${params.method}" was called with ` +
+                `${params.args.length} positional argument(s); move them into kwargs.`,
+            }),
+          );
+        }
+
+        const url = `${base}/json/2/${params.model}/${params.method}`;
+        const info = requestInfo(url, "POST");
+
+        // Keyword-only route: the browse target rides as the dedicated `ids` body
+        // key (see CallKwParams.ids), never as positional args.
+        const body = params.ids ? { ...params.kwargs, ids: params.ids } : params.kwargs;
+
+        // Redacted is unwrapped ONLY here, at the wire boundary.
+        const request = HttpClientRequest.post(url).pipe(
+          HttpClientRequest.setHeaders({
+            Authorization: `Bearer ${Redacted.value(apiKey)}`,
+            "X-Odoo-Database": config.db,
+            "Content-Type": "application/json",
+          }),
+          HttpClientRequest.bodyJsonUnsafe(body),
+        );
+
+        const response = yield* client
+          .execute(request)
+          .pipe(Effect.mapError(toTransportError(info)));
+
+        if (response.status >= 200 && response.status < 300) {
+          // Raw method result, no envelope; callers decode at their own boundary.
+          return yield* response.json.pipe(Effect.mapError(toTransportError(info)));
+        }
+
+        return yield* mapJson2Fault(response, info, site);
+      });
+
+      // Span carries only the coordinates — never args, kwargs, or the API key.
+      return run.pipe(
+        Effect.withSpan("odoo.json2", {
+          attributes: { model: params.model, method: params.method },
+        }),
+      );
+    };
+
+    return { dialect: "json2" as const, callKw };
+  });
+
+/** The concrete subset of the transport failure channel JSON-2 produces. */
+type TransportCallErrorLocal =
+  | OdooTransportError
+  | OdooAuthenticationError
+  | ProtocolUnsupportedError
+  | OdooServerFault;
+
+/** Wire a JSON-2 {@link Transport} from an explicit config. */
+export const layer = (
+  config: OdooConfigType,
+): Layer.Layer<Transport, OdooAuthenticationError, HttpClient.HttpClient> =>
+  Layer.effect(Transport, make(config));
+
+/** Wire a JSON-2 {@link Transport}, reading {@link OdooConfig} from the environment. */
+export const layerConfig: Layer.Layer<
+  Transport,
+  OdooAuthenticationError | Config.ConfigError,
+  HttpClient.HttpClient
+> = Layer.effect(Transport, Effect.flatMap(OdooConfig, make));
+
+/**
+ * The `/json/version` probe result: the server's version string and its raw
+ * `version_info` tuple. Decoded at the boundary; drift raises
+ * {@link SchemaDriftError}.
+ */
+export const Json2Version = Schema.Struct({
+  version: Schema.String,
+  version_info: ServerVersionInfo,
+});
+export type Json2Version = typeof Json2Version.Type;
+
+/**
+ * Probe `GET {url}/json/version` to detect JSON-2 support.
+ *
+ * Returns `Option.some(version)` on a 200, and `Option.none()` on a 404 — a 404
+ * is the documented "this server predates Odoo 19 (no JSON-2)" signal, not an
+ * error. Any other non-2xx is a real {@link OdooTransportError}; a 200 body that
+ * fails to decode is a {@link SchemaDriftError}.
+ */
+export const probeJson2Version = (
+  config: OdooConfigType,
+): Effect.Effect<
+  Option.Option<Json2Version>,
+  OdooTransportError | SchemaDriftError,
+  HttpClient.HttpClient
+> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const url = `${baseUrl(config.url)}/json/version`;
+    const info = requestInfo(url, "GET");
+
+    const response = yield* client
+      .execute(HttpClientRequest.get(url))
+      .pipe(Effect.mapError(toTransportError(info)));
+
+    const status = response.status;
+    if (status === 404) {
+      return Option.none();
+    }
+    if (status < 200 || status >= 300) {
+      const cause = yield* Effect.flip(HttpClientResponse.filterStatusOk(response)).pipe(
+        Effect.orDie,
+      );
+      return yield* Effect.fail(OdooTransportError.fromHttpClientError(info, cause));
+    }
+
+    const payload = yield* response.json.pipe(Effect.mapError(toTransportError(info)));
+    const decoded = yield* Schema.decodeUnknownEffect(Json2Version)(payload).pipe(
+      Effect.mapError(
+        (cause) => new SchemaDriftError({ context: "odoo.json2.version", payload, cause }),
+      ),
+    );
+    return Option.some(decoded);
+  });

package/src/transports/jsonrpc.ts

@@ -0,0 +1,218 @@
+import { Config, Effect, Layer, Redacted, Ref, Schema } from "effect";
+import { OdooConfig, type OdooCredentials } from "../config.ts";
+import { OdooAuthenticationError } from "../errors/auth.ts";
+import type { FaultCallSite } from "../errors/mapFault.ts";
+import { SchemaDriftError } from "../errors/schema.ts";
+import type { OdooServerFault } from "../errors/server.ts";
+import type { SessionExpiredError } from "../errors/session.ts";
+import { OdooTransportError } from "../errors/transport.ts";
+import { HttpClient, HttpClientRequest } from "../internal/platform.ts";
+import * as SingleFlight from "../internal/singleFlight.ts";
+import { buildRequest, JsonRpcResponse, mapJsonRpcError } from "../protocol/jsonrpc.ts";
+import { type CallKwParams, Transport, type TransportCallError } from "../transport.ts";
+import { CommonVersionResponse } from "../version.ts";
+
+/** The by-name params of a `/jsonrpc` call: `{service, method, args}`. */
+interface JsonRpcCallParams {
+  readonly service: string;
+  readonly method: string;
+  readonly args: ReadonlyArray<unknown>;
+}
+
+/** The failure channel a single round trip can produce (a subset of `TransportCallError`). */
+type RoundTripError =
+  | OdooTransportError
+  | SchemaDriftError
+  | SessionExpiredError
+  | OdooServerFault
+  | OdooAuthenticationError;
+
+/** Join the configured base URL with the `/jsonrpc` path, tolerating a trailing slash. */
+const jsonRpcEndpoint = (url: URL): string => `${url.href.replace(/\/+$/, "")}/jsonrpc`;
+
+const extractCredentials = (
+  credentials: OdooCredentials,
+): {
+  readonly username: string;
+  readonly secret: Redacted.Redacted<string>;
+  readonly isPassword: boolean;
+} =>
+  credentials._tag === "ApiKey"
+    ? { username: credentials.username, secret: credentials.apiKey, isPassword: false }
+    : { username: credentials.username, secret: credentials.password, isPassword: true };
+
+/**
+ * One JSON-RPC round trip: build the envelope, POST it, decode the response, and
+ * either return the raw `result` or map the fault into our union.
+ *
+ * GOTCHA: never put `args`/`kwargs`/the secret into the span attributes — only
+ * the model and method (or service/method) are safe to record.
+ */
+const roundTrip = (
+  client: HttpClient.HttpClient,
+  endpoint: string,
+  id: number,
+  params: JsonRpcCallParams,
+  attributes: Record<string, string>,
+  site: FaultCallSite,
+): Effect.Effect<unknown, RoundTripError> =>
+  Effect.gen(function* () {
+    // v4 rename: bodyUnsafeJson → bodyJsonUnsafe.
+    const request = HttpClientRequest.post(endpoint).pipe(
+      HttpClientRequest.setHeader("Content-Type", "application/json"),
+      HttpClientRequest.bodyJsonUnsafe(buildRequest(params, id)),
+    );
+
+    // HttpClientError covers both connection failures and a non-JSON body.
+    const payload: unknown = yield* client.execute(request).pipe(
+      Effect.flatMap((response) => response.json),
+      Effect.mapError((cause) =>
+        OdooTransportError.fromHttpClientError({ method: "POST", url: endpoint }, cause),
+      ),
+    );
+
+    const decoded = yield* Schema.decodeUnknownEffect(JsonRpcResponse)(payload).pipe(
+      Effect.mapError(
+        (cause) => new SchemaDriftError({ context: "odoo.jsonrpc response", payload, cause }),
+      ),
+    );
+
+    if ("error" in decoded) {
+      return yield* Effect.fail(mapJsonRpcError(decoded.error, site));
+    }
+    return decoded.result;
+  }).pipe(Effect.withSpan("odoo.jsonrpc", { attributes }));
+
+/**
+ * Build a `JsonRpcTransport` service value against a fully-resolved config.
+ *
+ * `uid` is resolved lazily on the first `callKw` via `common.authenticate`, then
+ * success-only single-flight cached (a failed authenticate caches nothing, so
+ * the next call retries — never `Effect.cached`).
+ *
+ * Requires an `HttpClient` in context; the caller provides the platform layer.
+ */
+export const make = (
+  config: OdooConfig,
+): Effect.Effect<typeof Transport.Service, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const idRef = yield* Ref.make(0);
+    const endpoint = jsonRpcEndpoint(config.url);
+    const { username, secret, isPassword } = extractCredentials(config.credentials);
+    const db = config.db;
+
+    const nextId = Ref.updateAndGet(idRef, (n) => n + 1);
+
+    const authenticate: Effect.Effect<number, RoundTripError> = Effect.gen(function* () {
+      const id = yield* nextId;
+      const result = yield* roundTrip(
+        client,
+        endpoint,
+        id,
+        {
+          service: "common",
+          method: "authenticate",
+          args: [db, username, Redacted.value(secret), {}],
+        },
+        {},
+        {},
+      );
+      if (typeof result === "number" && result > 0) {
+        return result;
+      }
+      // authenticate returned `false` (or a null uid): credentials rejected.
+      return yield* Effect.fail(
+        new OdooAuthenticationError({
+          reason: "invalid-credentials",
+          message: isPassword
+            ? "Odoo rejected the login. If this account has TOTP/2FA enabled, its password cannot be used over RPC — supply an API key as the secret instead."
+            : "Odoo rejected the provided credentials.",
+        }),
+      );
+    });
+
+    const uid = yield* SingleFlight.make(authenticate);
+
+    const callKw = (params: CallKwParams): Effect.Effect<unknown, TransportCallError> =>
+      Effect.gen(function* () {
+        const resolvedUid = yield* uid.get;
+        const id = yield* nextId;
+        // execute_kw-family route: an explicit `ids` browse target rides as the
+        // first positional argument (see CallKwParams.ids).
+        const args = params.ids ? [params.ids, ...params.args] : params.args;
+        return yield* roundTrip(
+          client,
+          endpoint,
+          id,
+          {
+            service: "object",
+            method: "execute_kw",
+            args: [
+              db,
+              resolvedUid,
+              Redacted.value(secret),
+              params.model,
+              params.method,
+              args,
+              params.kwargs,
+            ],
+          },
+          { model: params.model, method: params.method },
+          { model: params.model, method: params.method },
+        );
+      }).pipe(
+        // Self-healing: an auth fault means the cached uid/credential pairing is
+        // no longer valid server-side (key revoked-then-restored, credentials
+        // out of sync, ...). Drop the cache so the next call re-authenticates
+        // instead of staying wedged until the layer is rebuilt — symmetric with
+        // CookieSession.invalidate.
+        Effect.tapError((error) =>
+          error._tag === "OdooAuthenticationError" ? uid.invalidate : Effect.void,
+        ),
+      );
+
+    return { dialect: "execute-kw" as const, callKw };
+  });
+
+/**
+ * `JsonRpcTransport` as a `Layer`, wired against an explicit config. Never
+ * fails to build (`E = never`); the config is already resolved. Requires an
+ * `HttpClient` from the platform layer the consumer provides.
+ */
+export const layer = (config: OdooConfig): Layer.Layer<Transport, never, HttpClient.HttpClient> =>
+  Layer.effect(Transport, make(config));
+
+/**
+ * `JsonRpcTransport` as a `Layer` that reads {@link OdooConfig} from the ambient
+ * `ConfigProvider`. Fails with `ConfigError` if required values are missing.
+ */
+export const layerConfig: Layer.Layer<Transport, Config.ConfigError, HttpClient.HttpClient> =
+  Layer.effect(Transport, Effect.flatMap(OdooConfig, make));
+
+/**
+ * The `common.version` probe, decoded into {@link CommonVersionResponse}. Shared
+ * with the `VersionResolver` implementation so version resolution and the
+ * transport agree on one wire path. Requires an `HttpClient` in context.
+ */
+export const makeVersion = (
+  config: OdooConfig,
+): Effect.Effect<CommonVersionResponse, RoundTripError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const endpoint = jsonRpcEndpoint(config.url);
+    const raw = yield* roundTrip(
+      client,
+      endpoint,
+      1,
+      { service: "common", method: "version", args: [] },
+      {},
+      {},
+    );
+    return yield* Schema.decodeUnknownEffect(CommonVersionResponse)(raw).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SchemaDriftError({ context: "odoo.jsonrpc common.version", payload: raw, cause }),
+      ),
+    );
+  });