@hodeinavarro/odoo-rpc-ts 0.2.0

package/src/records/typed.ts

@@ -0,0 +1,180 @@
+/**
+ * `TypedRecordSet` — an immutable, decoded snapshot of rows bound to its
+ * `(rpc, model)` origin, with explicit, batched relation traversal — the
+ * CLASSIC tier of the records design (the classic `[id, name]`-pair protocol,
+ * works on 16+; the spec tier in `recordModel.ts` needs 17+). Traversal is always ONE `read` per relation per
+ * recordset — never per row — so the N+1 storm is structurally impossible: there
+ * is no per-record fetch API to misuse. The snapshot is never mutated; a fetch
+ * produces a fresh {@link RelatedMap}, and the caller joins explicitly.
+ */
+import { Effect, Schema } from "effect";
+import { SchemaDriftError } from "../errors/schema.ts";
+import type { Rpc } from "../rpc.ts";
+import type { TransportCallError } from "../transport.ts";
+import { collectRefIds, makeRelatedMap, type RelatedMap } from "./related.ts";
+import type { Many2OneRefValue } from "./relations.ts";
+
+/** A decoded row must carry its `id` — every traversal and join keys on it. */
+export type HasId = { readonly id: number };
+
+/**
+ * The field names of `Row` whose decoded value is a many2one reference
+ * (`Many2OneRefValue | null`) — the only fields a relation can be traversed
+ * through. A compile-time constraint: passing any other key to
+ * {@link TypedRecordSet.fetchRelated}/`joinRelated` is a type error, not a
+ * runtime surprise.
+ */
+export type Many2OneRefField<Row> = {
+  readonly [K in keyof Row]: Row[K] extends Many2OneRefValue | null ? K : never;
+}[keyof Row];
+
+/**
+ * An immutable snapshot of typed rows with explicit relation traversal. Obtain
+ * one from `OdooClient.searchRecordsTyped`; it is bound to the `Rpc` seam and
+ * model it was read from so `fetchRelated` can batch a co-model `read`.
+ */
+export interface TypedRecordSet<Row extends HasId> extends Iterable<Row> {
+  /** The model these rows were read from. */
+  readonly model: string;
+  /** The decoded rows, in server order. Immutable. */
+  readonly rows: ReadonlyArray<Row>;
+  /** Each row's `id`, in row order. */
+  readonly ids: ReadonlyArray<number>;
+  /** The number of rows. */
+  readonly length: number;
+
+  /**
+   * Fetch the related records behind a many2one `field` in ONE batched `read`
+   * over the distinct, non-null ids across the whole snapshot, decoded through
+   * `schema`. Returns a {@link RelatedMap} keyed by related id — a fresh
+   * snapshot; the recordset is never back-filled.
+   *
+   * ZERO round trips when no row references a related record (all empty). The
+   * batched-single-read guarantee is the entire point of this API and is
+   * asserted in the tests, not merely documented.
+   */
+  readonly fetchRelated: <K extends Many2OneRefField<Row>, A extends HasId, I = A>(
+    field: K,
+    relatedModel: string,
+    schema: Schema.Codec<A, I>,
+    fields?: ReadonlyArray<string>,
+  ) => Effect.Effect<RelatedMap<A>, TransportCallError>;
+
+  /**
+   * Like {@link fetchRelated}, but returns each row paired with its joined
+   * related record (`null` when the many2one is empty or unresolved). One
+   * explicit, batched call — named to keep "this is a fetch" legible at the call
+   * site.
+   */
+  readonly joinRelated: <K extends Many2OneRefField<Row>, A extends HasId, I = A>(
+    field: K,
+    relatedModel: string,
+    schema: Schema.Codec<A, I>,
+    fields?: ReadonlyArray<string>,
+  ) => Effect.Effect<ReadonlyArray<readonly [Row, A | null]>, TransportCallError>;
+}
+
+/** The subset of the {@link Rpc} service {@link TypedRecordSet} depends on. */
+type RpcSeam = Pick<typeof Rpc.Service, "callKw">;
+
+/** Boundary decode: a related-`read` payload that fails the caller schema is drift. */
+const decodeRows =
+  <A, I>(schema: Schema.Codec<A, I>, context: string) =>
+  (raw: unknown): Effect.Effect<ReadonlyArray<A>, SchemaDriftError> =>
+    Schema.decodeUnknownEffect(Schema.Array(schema))(raw).pipe(
+      Effect.mapError((cause) => new SchemaDriftError({ context, payload: raw, cause })),
+    );
+
+/**
+ * Read a many2one field off a row as a traversable ref value, or fail the whole
+ * traversal as a defect. The type system already forbids non-ref fields; this
+ * guards the dynamic-misuse escape hatch (e.g. an `any`-typed field or a schema
+ * that decoded the wrong shape) — a `TypeError`-equivalent `Effect.die` with a
+ * precise locator, never a silent skip.
+ */
+const readRefField = <Row extends HasId>(
+  row: Row,
+  field: PropertyKey,
+  model: string,
+): Effect.Effect<Many2OneRefValue | null> => {
+  const value = (row as Record<PropertyKey, unknown>)[field];
+  if (value === null || value === undefined) {
+    return Effect.succeed(null);
+  }
+  if (typeof value === "object" && typeof (value as { id?: unknown }).id === "number") {
+    return Effect.succeed(value as Many2OneRefValue);
+  }
+  return Effect.die(
+    `TypedRecordSet(${model}).fetchRelated: field ${String(field)} of record ${row.id} is not a ` +
+      `many2one reference ({ id, name } | null); got ${typeof value}. Declare it with ` +
+      `Many2OneRefOrNull so traversal is type-safe.`,
+  );
+};
+
+/**
+ * Construct a {@link TypedRecordSet} over already-decoded rows. Internal: the
+ * public entry point is `OdooClient.searchRecordsTyped`, which owns the initial
+ * `search_read` decode and passes the resulting rows here.
+ */
+export const make = <Row extends HasId>(
+  rpc: RpcSeam,
+  model: string,
+  rows: ReadonlyArray<Row>,
+): TypedRecordSet<Row> => {
+  const ids = rows.map((row) => row.id);
+
+  const fetchRelated = <K extends Many2OneRefField<Row>, A extends HasId, I = A>(
+    field: K,
+    relatedModel: string,
+    schema: Schema.Codec<A, I>,
+    fields?: ReadonlyArray<string>,
+  ): Effect.Effect<RelatedMap<A>, TransportCallError> =>
+    // Validate every row's field up front (dynamic-misuse guard), then collect
+    // the distinct ids purely and issue AT MOST one read.
+    Effect.forEach(rows, (row) => readRefField(row, field, model)).pipe(
+      Effect.flatMap((refs) => {
+        const relatedIds = collectRefIds(refs, (ref) => ref);
+        if (relatedIds.length === 0) {
+          // No referenced records → no round trip. Asserted in the tests.
+          return Effect.succeed(makeRelatedMap<A>([]));
+        }
+        return rpc
+          .callKw(
+            relatedModel,
+            "read",
+            [],
+            fields === undefined ? {} : { fields },
+            { ids: relatedIds },
+          )
+          .pipe(
+            Effect.flatMap(decodeRows(schema, `${relatedModel}.read`)),
+            Effect.map((relatedRows) => makeRelatedMap(relatedRows)),
+          );
+      }),
+    );
+
+  const joinRelated = <K extends Many2OneRefField<Row>, A extends HasId, I = A>(
+    field: K,
+    relatedModel: string,
+    schema: Schema.Codec<A, I>,
+    fields?: ReadonlyArray<string>,
+  ): Effect.Effect<ReadonlyArray<readonly [Row, A | null]>, TransportCallError> =>
+    fetchRelated(field, relatedModel, schema, fields).pipe(
+      Effect.map((related) =>
+        rows.map(
+          (row) =>
+            [row, related.get((row as Record<PropertyKey, unknown>)[field] as never)] as const,
+        ),
+      ),
+    );
+
+  return {
+    model,
+    rows,
+    ids,
+    length: rows.length,
+    [Symbol.iterator]: () => rows[Symbol.iterator](),
+    fetchRelated,
+    joinRelated,
+  };
+};

package/src/rpc.ts

@@ -0,0 +1,219 @@
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { SchemaDriftError } from "./errors/schema.ts";
+import * as SingleFlight from "./internal/singleFlight.ts";
+import {
+  type CallKwParams,
+  Transport,
+  type TransportCallError,
+  type TransportDialect,
+} from "./transport.ts";
+
+/** An Odoo `context` dict: opaque keys, values we do not model. */
+export type OdooContext = Record<string, unknown>;
+
+/** A plain object (a mergeable context), excluding arrays and `null`. */
+const isPlainObject = (value: unknown): value is OdooContext =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Copy `kwargs` without its `context` key (never mutates the caller's object). */
+const omitContext = (kwargs: OdooContext): OdooContext => {
+  const { context: _context, ...rest } = kwargs;
+  return rest;
+};
+
+/**
+ * The session/base Odoo `context` — the innermost, lowest-precedence layer of
+ * the context merge (e.g. `uid`, `lang`, `tz` established at authentication).
+ *
+ * Provided by the auth/transport layer that owns the session; absent here it
+ * defaults to `{}`. It is read once, when the {@link Rpc} layer is built.
+ */
+export class GlobalContext extends Context.Service<
+  GlobalContext,
+  OdooContext
+>()("odoo-rpc-ts/GlobalContext") {}
+
+/**
+ * The `call_kw` choke point. Every high-level operation funnels through here so
+ * the Odoo `context` is merged in exactly one place, with a single, documented
+ * precedence (see {@link callKw}).
+ */
+export class Rpc extends Context.Service<
+  Rpc,
+  {
+    /** The underlying transport's wire dialect, for ops that must branch on it. */
+    readonly dialect: TransportDialect;
+    /**
+     * Execute one `call_kw`, merging the effective `context` and forwarding to
+     * the {@link Transport}. Caller inputs are never mutated — `args`, `kwargs`,
+     * and every context object are treated as read-only and copied.
+     *
+     * Context precedence (lowest → highest, later wins):
+     *   session/base ({@link GlobalContext}) < layer overrides
+     *     < `kwargs.context` < `options.context`.
+     *
+     * A `context` key inside `kwargs` is treated as a caller-level context (the
+     * ergonomic form `callKw(m, meth, [], { context })`), merged just below
+     * `options.context` and then stripped from `kwargs` so it never wires twice.
+     * If it is present but not a plain object it is a caller defect and fails
+     * with `Effect.die`.
+     */
+    readonly callKw: (
+      model: string,
+      method: string,
+      args: ReadonlyArray<unknown>,
+      kwargs?: OdooContext,
+      options?: { readonly context?: OdooContext; readonly ids?: ReadonlyArray<number> },
+    ) => Effect.Effect<unknown, TransportCallError>;
+  }
+>()("odoo-rpc-ts/Rpc") {}
+
+/**
+ * The provider seam for a lazily-seeded session/base context.
+ *
+ * A `Layer` resolves eagerly at build time, but the base tier must be lazy and
+ * retryable-on-failure (a transport error resolving it must surface as the
+ * failing call's error, never be baked in). So instead of a value provider we
+ * take an `Effect` that yields the base context; {@link buildRpc} runs it behind
+ * a success-only single-flight on the FIRST `callKw` (and retries on failure).
+ *
+ * Merge position: below the layer overrides, above the static {@link GlobalContext}
+ * tag (which, when both are present, seeds the innermost defaults).
+ */
+export type GlobalContextProvider = Effect.Effect<OdooContext, TransportCallError>;
+
+const ContextRecord = Schema.Record(Schema.String, Schema.Unknown);
+
+/**
+ * Decode a raw `res.users.context_get` result into an {@link OdooContext};
+ * drift (a non-object payload) fails as {@link SchemaDriftError}, which is part
+ * of {@link TransportCallError} and so propagates as the seeding call's error.
+ */
+const decodeContext = (raw: unknown): Effect.Effect<OdooContext, SchemaDriftError> =>
+  Schema.decodeUnknownEffect(ContextRecord)(raw).pipe(
+    Effect.mapError(
+      (cause) => new SchemaDriftError({ context: "res.users.context_get", payload: raw, cause }),
+    ),
+  );
+
+/**
+ * The shared {@link Rpc} service constructor. `provider`, when given, seeds the
+ * base tier lazily (single-flight on first call). The static {@link GlobalContext}
+ * tag is always read (defaulting to `{}`) and sits at the very bottom.
+ */
+const buildRpc = (
+  transport: typeof Transport.Service,
+  config: { readonly globalContext?: OdooContext } | undefined,
+  provider: GlobalContextProvider | undefined,
+): Effect.Effect<typeof Rpc.Service> =>
+  Effect.gen(function* () {
+    const staticBase = Option.getOrElse(
+      yield* Effect.serviceOption(GlobalContext),
+      (): OdooContext => ({}),
+    );
+    const layerOverrides = config?.globalContext ?? {};
+
+    // No provider: the base tier is the static tag value (today's behavior,
+    // resolved once at build). With a provider: resolve it lazily behind a
+    // success-only single-flight and layer it over the static base.
+    const resolveBase: Effect.Effect<OdooContext, TransportCallError> =
+      provider === undefined
+        ? Effect.succeed(staticBase)
+        : yield* SingleFlight.make(provider).pipe(
+            Effect.map((sf) =>
+              sf.get.pipe(Effect.map((seeded): OdooContext => ({ ...staticBase, ...seeded }))),
+            ),
+          );
+
+    const callKw = (
+      model: string,
+      method: string,
+      args: ReadonlyArray<unknown>,
+      kwargs?: OdooContext,
+      options?: { readonly context?: OdooContext; readonly ids?: ReadonlyArray<number> },
+    ): Effect.Effect<unknown, TransportCallError> => {
+      // Pull any caller-supplied `kwargs.context` out of the spread so it is
+      // merged at the caller tier (not silently clobbered) and never wired twice.
+      const hasKwargsContext = kwargs !== undefined && "context" in kwargs;
+      const kwargsContext = hasKwargsContext ? kwargs["context"] : undefined;
+      if (hasKwargsContext && !isPlainObject(kwargsContext)) {
+        return Effect.die(
+          `Rpc.callKw: kwargs.context for "${model}.${method}" must be a plain object, ` +
+            `got ${typeof kwargsContext}.`,
+        );
+      }
+      const restKwargs = hasKwargsContext ? omitContext(kwargs) : (kwargs ?? {});
+
+      return resolveBase.pipe(
+        Effect.flatMap((base) => {
+          const context: OdooContext = {
+            ...base,
+            ...layerOverrides,
+            ...(kwargsContext as OdooContext | undefined),
+            ...options?.context,
+          };
+          const params: CallKwParams = {
+            model,
+            method,
+            args,
+            kwargs: { ...restKwargs, context },
+            ...(options?.ids !== undefined ? { ids: options.ids } : {}),
+          };
+          return transport.callKw(params);
+        }),
+      );
+    };
+
+    return { dialect: transport.dialect, callKw };
+  });
+
+/**
+ * Build the {@link Rpc} layer over a {@link Transport}, optionally baking in
+ * layer-level `globalContext` overrides that sit above the session/base context
+ * but below any per-call context, and/or a {@link GlobalContextProvider} that
+ * lazily seeds the base tier on the first call.
+ */
+export const layerWith = (config?: {
+  readonly globalContext?: OdooContext;
+  readonly globalContextProvider?: GlobalContextProvider;
+}): Layer.Layer<Rpc, never, Transport> =>
+  Layer.effect(
+    Rpc,
+    Effect.gen(function* () {
+      const transport = yield* Transport;
+      return yield* buildRpc(transport, config, config?.globalContextProvider);
+    }),
+  );
+
+/**
+ * The {@link Rpc} layer with the base tier seeded from the ambient
+ * {@link Transport}'s server-side user context.
+ *
+ * Resolves `res.users.context_get` (an `@api.model` method — kwargs-only, so it
+ * works identically over `execute_kw` and the JSON-2 by-name dialect) exactly
+ * once, lazily on the first `callKw`, behind a success-only single-flight. A
+ * transport/decoding failure while seeding is NOT swallowed: it surfaces as that
+ * first call's error and the seed is retried on the next call.
+ */
+export const layerSeeded = (config?: {
+  readonly globalContext?: OdooContext;
+}): Layer.Layer<Rpc, never, Transport> =>
+  Layer.effect(
+    Rpc,
+    Effect.gen(function* () {
+      const transport = yield* Transport;
+      const provider: GlobalContextProvider = transport
+        .callKw({ model: "res.users", method: "context_get", args: [], kwargs: {} })
+        .pipe(Effect.flatMap(decodeContext));
+      return yield* buildRpc(transport, config, provider);
+    }),
+  );
+
+/**
+ * The default {@link Rpc} layer: base tier seeded from the server-side user
+ * context ({@link layerSeeded}), so translated fields (stage names, selection
+ * labels, …) come back in the user's language instead of the source terms —
+ * matching odoo-rpc-py's `seed_context=True` default. Opt out with
+ * {@link layerWith} (no provider) when calls must carry no ambient context.
+ */
+export const layer: Layer.Layer<Rpc, never, Transport> = layerSeeded();

package/src/services/db.ts

@@ -0,0 +1,282 @@
+/**
+ * `DbService` — the master-password-gated database-management endpoints exposed
+ * by Odoo's `db` service over `POST /jsonrpc` (`exp_list`, `exp_db_exist`,
+ * `exp_create_database`, `exp_drop`, `exp_duplicate_database`, `exp_dump`,
+ * `exp_restore`, `exp_change_admin_password`).
+ *
+ * Unlike the model-level `Transport`, this service is **database-less and
+ * credential-less**: it authenticates nothing and speaks to no database. The
+ * only secret is the per-call master password (Odoo's `admin_passwd`), taken as
+ * a `Redacted<string>` and unwrapped solely at the point the request body is
+ * built. There is therefore no `Transport` tag, no uid, and no session — every
+ * function takes the server `url: URL` explicitly and requires only an abstract
+ * `HttpClient`.
+ *
+ * A wrong master password surfaces as `odoo.exceptions.AccessDenied`, which the
+ * shared JSON-RPC choke point ({@link mapJsonRpcError}) maps to
+ * {@link OdooAuthenticationError} — same as any other auth rejection.
+ *
+ * NODE ORIENTATION: {@link dump} and {@link restore} carry the whole backup in
+ * memory as a `Uint8Array`. This is inherent to the wire contract — Odoo's
+ * `exp_dump` returns the archive base64-encoded inside the JSON-RPC `result`,
+ * and `exp_restore` takes it back the same way — so there is no streaming path
+ * to preserve. Fine for the CI/ops-sized databases this is meant for; not a
+ * mechanism for multi-gigabyte production dumps.
+ *
+ * Wire arities verified against `odoo/service/db.py` on 16.0 and 19.0 (stable
+ * 16–19). `dispatch` strips the leading master password for every `exp_*`
+ * method except the four unauthenticated ones (`list`, `db_exist`, `list_lang`,
+ * `server_version`); `exp_restore` has NO `neutralize` parameter on any version.
+ */
+import { Effect, Encoding, Redacted, Schema } from "effect";
+import type { FaultCallSite } from "../errors/mapFault.ts";
+import { SchemaDriftError } from "../errors/schema.ts";
+import type { OdooAuthenticationError } from "../errors/auth.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 {
+  buildRequest,
+  JsonRpcResponse,
+  mapJsonRpcError,
+  nextRequestId,
+} from "../protocol/jsonrpc.ts";
+
+/** The failure channel a single `db` round trip can produce. */
+type DbCallError =
+  | OdooTransportError
+  | SchemaDriftError
+  | SessionExpiredError
+  | OdooServerFault
+  | OdooAuthenticationError;
+
+/** Join the base URL with the `/jsonrpc` path, tolerating a trailing slash. */
+const jsonRpcEndpoint = (url: URL): string => `${url.href.replace(/\/+$/, "")}/jsonrpc`;
+
+/**
+ * One `db`-service round trip: build the `{service:"db", method, args}`
+ * envelope, POST it, decode the JSON-RPC response, and either return the raw
+ * `result` or map the fault through the shared choke point.
+ *
+ * GOTCHA: never record `args` on the span — the master password rides in
+ * position 0 for gated methods. Only the method name is safe.
+ */
+const dbCall = (
+  url: URL,
+  method: string,
+  args: ReadonlyArray<unknown>,
+): Effect.Effect<unknown, DbCallError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const endpoint = jsonRpcEndpoint(url);
+    const id = nextRequestId();
+    const site: FaultCallSite = { method: `db.${method}` };
+
+    const request = HttpClientRequest.post(endpoint).pipe(
+      HttpClientRequest.setHeader("Content-Type", "application/json"),
+      HttpClientRequest.bodyJsonUnsafe(buildRequest({ service: "db", method, args }, id)),
+    );
+
+    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.db response", payload, cause }),
+      ),
+    );
+
+    if ("error" in decoded) {
+      return yield* Effect.fail(mapJsonRpcError(decoded.error, site));
+    }
+    return decoded.result;
+  }).pipe(Effect.withSpan("odoo.db", { attributes: { "odoo.db.method": method } }));
+
+/** Decode a `db` result through `schema`, raising {@link SchemaDriftError} on drift. */
+const decodeResult = <A, I>(
+  schema: Schema.Codec<A, I>,
+  context: string,
+  result: unknown,
+): Effect.Effect<A, SchemaDriftError> =>
+  Schema.decodeUnknownEffect(schema)(result).pipe(
+    Effect.mapError((cause) => new SchemaDriftError({ context, payload: result, cause })),
+  );
+
+/**
+ * List the databases the server is willing to expose (honours `list_db` and any
+ * `dbfilter`). Unauthenticated — no master password required.
+ */
+export const listDatabases = (
+  url: URL,
+): Effect.Effect<ReadonlyArray<string>, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "list", []).pipe(
+    Effect.flatMap((result) =>
+      decodeResult(Schema.Array(Schema.String), "odoo.db exp_list", result),
+    ),
+  );
+
+/** Whether a database of the given name exists. Unauthenticated. */
+export const exists = (
+  url: URL,
+  name: string,
+): Effect.Effect<boolean, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "db_exist", [name]).pipe(
+    Effect.flatMap((result) => decodeResult(Schema.Boolean, "odoo.db exp_db_exist", result)),
+  );
+
+/** Options for {@link create}. `master` and `adminPassword` are the two secrets. */
+export interface CreateOptions {
+  readonly master: Redacted.Redacted<string>;
+  readonly name: string;
+  /** Install demo data. Defaults to `false`. */
+  readonly demo?: boolean;
+  /** Load language / locale (e.g. `"en_US"`). Defaults to `"en_US"`. */
+  readonly lang?: string;
+  /** Login of the initial admin user. Defaults to `"admin"`. */
+  readonly adminLogin?: string;
+  /** Password of the initial admin user. */
+  readonly adminPassword: Redacted.Redacted<string>;
+  /** ISO country code to seed localization (e.g. `"US"`). */
+  readonly countryCode?: string;
+  /** Company phone to seed. */
+  readonly phone?: string;
+}
+
+/**
+ * Create a fresh database and its initial admin user.
+ *
+ * Wire (after `dispatch` strips the master): `exp_create_database(db_name,
+ * demo, lang, user_password='admin', login='admin', country_code=None,
+ * phone=None)`.
+ */
+export const create = (
+  url: URL,
+  options: CreateOptions,
+): Effect.Effect<void, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "create_database", [
+    Redacted.value(options.master),
+    options.name,
+    options.demo ?? false,
+    options.lang ?? "en_US",
+    Redacted.value(options.adminPassword),
+    options.adminLogin ?? "admin",
+    options.countryCode ?? null,
+    options.phone ?? null,
+  ]).pipe(Effect.asVoid);
+
+/**
+ * Drop a database. Resolves to `true` when a database was actually dropped,
+ * `false` when none of that name existed.
+ */
+export const drop = (
+  url: URL,
+  master: Redacted.Redacted<string>,
+  name: string,
+): Effect.Effect<boolean, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "drop", [Redacted.value(master), name]).pipe(
+    Effect.flatMap((result) => decodeResult(Schema.Boolean, "odoo.db exp_drop", result)),
+  );
+
+/** Options for {@link duplicate}. */
+export interface DuplicateOptions {
+  /**
+   * Neutralize the copy (disable outgoing mail/crons/payment providers, …) so it
+   * is safe as a staging database. Maps to `neutralize_database`. Defaults to
+   * `false`.
+   */
+  readonly neutralize?: boolean;
+}
+
+/**
+ * Duplicate `source` into a new database `target`.
+ *
+ * Wire (after master strip): `exp_duplicate_database(db_original_name, db_name,
+ * neutralize_database=False)`.
+ */
+export const duplicate = (
+  url: URL,
+  master: Redacted.Redacted<string>,
+  source: string,
+  target: string,
+  options: DuplicateOptions = {},
+): Effect.Effect<void, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "duplicate_database", [
+    Redacted.value(master),
+    source,
+    target,
+    options.neutralize ?? false,
+  ]).pipe(Effect.asVoid);
+
+/**
+ * Dump a database into an in-memory archive.
+ *
+ * `format` is `"zip"` (default; includes the filestore) or `"dump"` (raw
+ * `pg_dump` custom format, database only). Odoo returns the archive
+ * base64-encoded inside the JSON-RPC `result`; we decode it to raw bytes.
+ */
+export const dump = (
+  url: URL,
+  master: Redacted.Redacted<string>,
+  name: string,
+  format: "zip" | "dump" = "zip",
+): Effect.Effect<Uint8Array, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "dump", [Redacted.value(master), name, format]).pipe(
+    // Odoo returns the archive base64-encoded in `result`; decode to raw bytes,
+    // any malformed base64 surfacing as SchemaDriftError like every other drift.
+    Effect.flatMap((result) =>
+      decodeResult(Schema.Uint8ArrayFromBase64, "odoo.db exp_dump", result),
+    ),
+  );
+
+/** Options for {@link restore}. */
+export interface RestoreOptions {
+  /**
+   * Restore as a *copy* — regenerate the database uuid and secret so it does not
+   * collide with the original in a mail/cron sense. Maps to `copy`. Defaults to
+   * `false`.
+   *
+   * NOTE: `exp_restore` has NO `neutralize` parameter on any supported version;
+   * there is deliberately no such option here.
+   */
+  readonly copy?: boolean;
+}
+
+/**
+ * Restore a previously {@link dump}ed archive under a new database `name`.
+ *
+ * The bytes are re-encoded to the base64 string `exp_restore` expects.
+ * Wire (after master strip): `exp_restore(db_name, data, copy=False)`.
+ */
+export const restore = (
+  url: URL,
+  master: Redacted.Redacted<string>,
+  name: string,
+  archive: Uint8Array,
+  options: RestoreOptions = {},
+): Effect.Effect<void, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "restore", [
+    Redacted.value(master),
+    name,
+    Encoding.encodeBase64(archive),
+    options.copy ?? false,
+  ]).pipe(Effect.asVoid);
+
+/**
+ * Change the server master password (`admin_passwd`). `master` is the current
+ * password; `next` becomes the new one.
+ *
+ * Wire (after master strip): `exp_change_admin_password(new_password)`.
+ */
+export const changeMasterPassword = (
+  url: URL,
+  master: Redacted.Redacted<string>,
+  next: Redacted.Redacted<string>,
+): Effect.Effect<void, DbCallError, HttpClient.HttpClient> =>
+  dbCall(url, "change_admin_password", [Redacted.value(master), Redacted.value(next)]).pipe(
+    Effect.asVoid,
+  );