@hodeinavarro/odoo-rpc-ts 0.2.0

package/src/transports/web.ts

@@ -0,0 +1,96 @@
+import { type Config, Effect, Layer, Schema } from "effect";
+import { OdooConfig } from "../config.ts";
+import { SchemaDriftError } from "../errors/schema.ts";
+import { OdooTransportError, type RequestInfo } from "../errors/transport.ts";
+import { HttpClientRequest } from "../internal/platform.ts";
+import { CookieSession } from "../session/cookie.ts";
+import { joinPath } from "../session/cookie.ts";
+import {
+  buildRequest,
+  JsonRpcResponse,
+  mapJsonRpcError,
+  nextRequestId,
+} from "../protocol/jsonrpc.ts";
+import { type CallKwParams, Transport, type TransportCallError } from "../transport.ts";
+
+/**
+ * Build the `WebTransport` implementation. Every `call_kw` first ensures a
+ * cookie session exists (via {@link CookieSession}) and then rides the shared,
+ * cookie-bound HttpClient so `session_id` — and any rotation — is always sent.
+ */
+export const make = (
+  // Only `url` is read: the transport never touches credentials, so an
+  // injected-cookie consumer (CookieSessionLive.fromExisting) can drive it
+  // without fabricating an OdooConfig. A full OdooConfig still satisfies this.
+  config: Pick<OdooConfig, "url">,
+): Effect.Effect<typeof Transport.Service, never, CookieSession> =>
+  Effect.gen(function* () {
+    const session = yield* CookieSession;
+    const callUrl = joinPath(config.url, "web/dataset/call_kw");
+    const request: RequestInfo = { method: "POST", url: callUrl };
+
+    const callKw = (params: CallKwParams): Effect.Effect<unknown, TransportCallError> =>
+      Effect.gen(function* () {
+        // Choke point: ensure the session before the call. A SessionExpiredError
+        // from here does NOT auto-relogin (see retryOnSessionExpired).
+        yield* session.login;
+
+        // 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;
+        const envelope = buildRequest(
+          {
+            model: params.model,
+            method: params.method,
+            args,
+            kwargs: params.kwargs,
+          },
+          nextRequestId(),
+        );
+
+        const response = yield* session.client
+          .execute(HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.post(callUrl), envelope))
+          .pipe(Effect.mapError((cause) => OdooTransportError.fromHttpClientError(request, cause)));
+
+        const body = yield* response.json.pipe(
+          Effect.mapError((cause) => OdooTransportError.fromHttpClientError(request, cause)),
+        );
+
+        const decoded = yield* Schema.decodeUnknownEffect(JsonRpcResponse)(body).pipe(
+          Effect.mapError(
+            (cause) =>
+              new SchemaDriftError({
+                context: "web/dataset/call_kw envelope",
+                payload: body,
+                cause,
+              }),
+          ),
+        );
+
+        if ("error" in decoded) {
+          // Single mapping choke point: code 100 → SessionExpiredError, else
+          // mapServerFault, with the call site threaded through.
+          return yield* Effect.fail(
+            mapJsonRpcError(decoded.error, { model: params.model, method: params.method }),
+          );
+        }
+
+        return decoded.result;
+      }).pipe(
+        // No args/secrets in span attributes — model + method only.
+        Effect.withSpan("odoo.web.call_kw", {
+          attributes: { model: params.model, method: params.method },
+        }),
+      );
+
+    return { dialect: "execute-kw" as const, callKw };
+  });
+
+/** Provide the web `Transport` from an already-resolved config. Requires `CookieSession`. */
+export const layer = (
+  config: Pick<OdooConfig, "url">,
+): Layer.Layer<Transport, never, CookieSession> => Layer.effect(Transport, make(config));
+
+/** Provide the web `Transport`, resolving `OdooConfig` from the environment. */
+export const layerConfig: Layer.Layer<Transport, Config.ConfigError, CookieSession> =
+  Layer.effect(Transport, Effect.flatMap(OdooConfig, make));

package/src/version-live.ts

@@ -0,0 +1,67 @@
+import { Effect, Layer } from "effect";
+import type { SchemaDriftError } from "./errors/schema.ts";
+import type { ProtocolUnsupportedError } from "./errors/protocol.ts";
+import type { OdooTransportError } from "./errors/transport.ts";
+import * as SingleFlight from "./internal/singleFlight.ts";
+import {
+  type CommonVersionResponse,
+  deriveWireCapabilities,
+  parseVersionInfo,
+  type ResolvedVersion,
+  type ServerVersionInfo,
+  VersionResolver,
+} from "./version.ts";
+
+/**
+ * The two version-probe shapes we accept, already boundary-decoded by whichever
+ * transport family issued the probe:
+ *
+ * - {@link CommonVersionResponse} — the `/jsonrpc` `common.version` response.
+ * - `{ version, version_info }` — the web `/web/webclient/version_info` shape.
+ *
+ * Both carry the `server_version_info` tuple under different keys; that tuple is
+ * all this resolver needs.
+ */
+export type VersionProbeResponse =
+  | CommonVersionResponse
+  | { readonly version: string; readonly version_info: ServerVersionInfo };
+
+/**
+ * The typed failures a transport-provided VERSION probe may surface. The
+ * `VersionProbe` prefix is deliberate: the bare word "probe" belongs to the
+ * application layer's product-capability probing (`fields_get` reachability);
+ * this package only ever probes the server version.
+ */
+export type VersionProbeError = OdooTransportError | SchemaDriftError | ProtocolUnsupportedError;
+
+const extractInfo = (response: VersionProbeResponse): ServerVersionInfo =>
+  "server_version_info" in response ? response.server_version_info : response.version_info;
+
+const resolveVersion = (response: VersionProbeResponse): ResolvedVersion => {
+  const version = parseVersionInfo(extractInfo(response));
+  return { version, capabilities: deriveWireCapabilities(version) };
+};
+
+/**
+ * Build a {@link VersionResolver} service from a transport-agnostic `probe`.
+ *
+ * The `Transport` seam only exposes `call_kw`, so version discovery lives with
+ * each transport family (which owns the right endpoint and decode). This
+ * resolver stays generic: hand it the decoded probe effect and it success-only
+ * single-flight caches the mapped {@link ResolvedVersion}.
+ */
+export const make = (
+  probe: Effect.Effect<VersionProbeResponse, VersionProbeError>,
+): Effect.Effect<typeof VersionResolver.Service, never> =>
+  Effect.gen(function* () {
+    const cache = yield* SingleFlight.make(Effect.map(probe, resolveVersion));
+    return { resolve: cache.get };
+  });
+
+/**
+ * The {@link VersionResolver} layer over a transport-provided `probe`. Transport
+ * packages construct the probe (endpoint + decode) and pass it here.
+ */
+export const layer = (
+  probe: Effect.Effect<VersionProbeResponse, VersionProbeError>,
+): Layer.Layer<VersionResolver> => Layer.effect(VersionResolver, make(probe));

package/src/version.ts

@@ -0,0 +1,102 @@
+import { Context, type Effect, Schema } from "effect";
+import type { ProtocolUnsupportedError } from "./errors/protocol.ts";
+import type { SchemaDriftError } from "./errors/schema.ts";
+import type { OdooTransportError } from "./errors/transport.ts";
+
+/**
+ * Odoo's `server_version_info`: `[major, minor, micro, releaselevel, serial]`,
+ * a heterogeneous tuple (numbers plus a string release level). Modeled
+ * leniently as a mixed array so a shape change on a future version surfaces as
+ * a decode drift rather than a silent truncation.
+ */
+export const ServerVersionInfo = Schema.Array(Schema.Union([Schema.Number, Schema.String]));
+export type ServerVersionInfo = typeof ServerVersionInfo.Type;
+
+/**
+ * The response of the `common.version` call (`/jsonrpc` service `common`,
+ * method `version`). Decoded at the boundary; drift raises `SchemaDriftError`.
+ */
+export const CommonVersionResponse = Schema.Struct({
+  server_version: Schema.String,
+  server_version_info: ServerVersionInfo,
+  server_serie: Schema.String,
+  protocol_version: Schema.Number,
+});
+export type CommonVersionResponse = typeof CommonVersionResponse.Type;
+
+/** A parsed, structured server version. */
+export interface OdooVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly micro: number;
+  readonly releaseLevel: string;
+  readonly serial: number;
+  readonly raw: ServerVersionInfo;
+}
+
+/**
+ * What a given server version can and cannot do, ON THE WIRE. This package
+ * owns WIRE capabilities derived from the server version; the application
+ * layer owns PRODUCT capabilities (derived from `fields_get` reachability,
+ * installed modules, …) — the bare words "capabilities"/"probe" belong to the
+ * app layer, hence the `Wire`/`VersionProbe` prefixes here.
+ */
+export interface WireCapabilities {
+  /** The JSON-2 `/json/2` bearer API exists (Odoo 19+). */
+  readonly supportsJson2: boolean;
+  /** `/jsonrpc` and `/xmlrpc` are deprecated upstream (Odoo 19+). */
+  readonly jsonRpcDeprecated: boolean;
+  /**
+   * `web_read`/`web_search_read`/`web_save` accept a nested `specification`
+   * kwarg (Odoo 17+). This gates the declared-prefetch typed record path
+   * (`searchTyped`/`readTyped`/`saveTyped`); on 16 the kwarg is rejected, so a
+   * relation-free declared model degrades to `search_read`/`read` and a declared
+   * relation fails with `ProtocolUnsupportedError` before any round trip.
+   */
+  readonly supportsWebReadSpec: boolean;
+}
+
+/** A resolved version together with its derived wire capabilities. */
+export interface ResolvedVersion {
+  readonly version: OdooVersion;
+  readonly capabilities: WireCapabilities;
+}
+
+const asNumber = (value: number | string | undefined): number =>
+  typeof value === "number" ? value : 0;
+
+/**
+ * Turn a raw `server_version_info` tuple into a structured {@link OdooVersion}.
+ * Missing trailing elements default to `0` / empty; the raw tuple is retained.
+ */
+export const parseVersionInfo = (raw: ServerVersionInfo): OdooVersion => ({
+  major: asNumber(raw[0]),
+  minor: asNumber(raw[1]),
+  micro: asNumber(raw[2]),
+  releaseLevel: typeof raw[3] === "string" ? raw[3] : "",
+  serial: asNumber(raw[4]),
+  raw,
+});
+
+/** Derive wire capabilities from a version. JSON-2 lands, and the legacy RPC
+ * routes are deprecated, at major 19. */
+export const deriveWireCapabilities = (version: OdooVersion): WireCapabilities => ({
+  supportsJson2: version.major >= 19,
+  jsonRpcDeprecated: version.major >= 19,
+  supportsWebReadSpec: version.major >= 17,
+});
+
+/**
+ * Resolves (and success-only caches) the server version behind whichever
+ * transport is provided. Implementation ships later; this is the seam so the
+ * client can gate protocol choices on capabilities.
+ */
+export class VersionResolver extends Context.Service<
+  VersionResolver,
+  {
+    readonly resolve: Effect.Effect<
+      ResolvedVersion,
+      OdooTransportError | SchemaDriftError | ProtocolUnsupportedError
+    >;
+  }
+>()("odoo-rpc-ts/VersionResolver") {}