@hodeinavarro/odoo-rpc-ts 0.2.0

package/src/errors/transport.ts

@@ -0,0 +1,74 @@
+import { Data } from "effect";
+import type { HttpClientErrorType } from "../internal/platform.ts";
+
+/** The stable platform failure distinction, without the unsafe platform error. */
+export type TransportErrorKind = HttpClientErrorType["reason"]["_tag"];
+
+/**
+ * Sanitized snapshot of the outbound request, safe to log and to attach to
+ * errors. The URL has no userinfo, query, or fragment. Never carries auth
+ * headers, cookies, or the request body — those may hold `session_id`, API
+ * keys, or passwords.
+ */
+export interface RequestInfo {
+  readonly method: string;
+  readonly url: string;
+}
+
+const sanitizeUrl = (raw: string): string => {
+  try {
+    const url = new URL(raw);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.href;
+  } catch {
+    return "<invalid-url>";
+  }
+};
+
+/**
+ * The network / HTTP layer failed: DNS, TLS, connection reset, non-decodable
+ * response, timeout. Carries only primitive metadata copied from the platform
+ * error. It never retains the `HttpClientError`, its request, response, cause,
+ * headers, or body.
+ *
+ * A transport failure proves only that *something* failed at the wire — it
+ * says nothing about Odoo's application state. Never infer success/idempotency
+ * from it; probe actual state before any resume.
+ */
+export class OdooTransportError extends Data.TaggedError("OdooTransportError")<{
+  readonly request: RequestInfo;
+  readonly kind: TransportErrorKind;
+  readonly message: string;
+  readonly status?: number;
+}> {
+  constructor(fields: {
+    readonly request: RequestInfo;
+    readonly kind: TransportErrorKind;
+    readonly status?: number;
+  }) {
+    const request = {
+      method: fields.request.method,
+      url: sanitizeUrl(fields.request.url),
+    };
+    const suffix = fields.status === undefined ? "" : ` (HTTP ${fields.status})`;
+    super({
+      request,
+      kind: fields.kind,
+      message: `${fields.kind} during ${request.method} ${request.url}${suffix}`,
+      ...(fields.status !== undefined ? { status: fields.status } : {}),
+    });
+  }
+
+  /** Copy safe diagnostics out of an Effect HTTP error, then discard it. */
+  static fromHttpClientError(request: RequestInfo, error: HttpClientErrorType): OdooTransportError {
+    const status = error.response?.status;
+    return new OdooTransportError({
+      request,
+      kind: error.reason._tag,
+      ...(status !== undefined ? { status } : {}),
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,152 @@
+/**
+ * @hodeinavarro/odoo-rpc-ts — public surface.
+ *
+ * A modern, Effect-native, strongly-typed Odoo RPC client: the shared
+ * contracts (errors, the `Transport` seam, config, domains, version
+ * resolution), the three transports, the session/auth services, and the
+ * high-level `OdooClient`. The `FakeTransport` testing double ships from the
+ * separate `@hodeinavarro/odoo-rpc-ts/testing` entry point.
+ */
+
+// Error taxonomy + the fault mapper.
+export * from "./errors/index.ts";
+
+// The one transport seam and its call shape.
+export { Transport, type CallKwParams, type TransportCallError } from "./transport.ts";
+
+// Configuration.
+export { OdooConfig, type OdooCredentials } from "./config.ts";
+
+// Search-domain types and combinators.
+export {
+  AND,
+  OR,
+  NOT,
+  normalizeDomain,
+  type Domain,
+  type DomainItem,
+  type DomainLeaf,
+  type DomainOperator,
+} from "./domain.ts";
+
+// Version resolution and WIRE-capability derivation (the app layer owns
+// product capabilities — see WireCapabilities).
+export {
+  VersionResolver,
+  CommonVersionResponse,
+  ServerVersionInfo,
+  parseVersionInfo,
+  deriveWireCapabilities,
+  type OdooVersion,
+  type WireCapabilities,
+  type ResolvedVersion,
+} from "./version.ts";
+export * as VersionResolverLive from "./version-live.ts";
+
+// The call_kw choke point (context merge) and the high-level client.
+export { Rpc, GlobalContext, type OdooContext, type GlobalContextProvider } from "./rpc.ts";
+export * as RpcLive from "./rpc.ts";
+export {
+  OdooClient,
+  type OdooRecord,
+  type FieldsMetadata,
+  type SearchOptions,
+  type SearchReadOptions,
+  type CallOptions,
+  type ReadGroupOptions,
+  type NameSearchOptions,
+  type TypedOptions,
+  type TypedReadOptions,
+} from "./client.ts";
+export * as OdooClientLive from "./client.ts";
+
+// Typed records — two per-protocol tiers, not competitors. The CLASSIC tier
+// (explicit traversal: Many2OneRef*, TypedRecordSet) speaks the classic
+// `[id, name]`-pair protocol and works on 16+; the SPEC tier (declared
+// prefetch: defineRecord/Many2One/One2Many + the pure specification compiler)
+// speaks the 17+ `specification` protocol. Relation/temporal decode
+// vocabulary is shared.
+export {
+  // Relation & temporal decode schemas (classic-tier row declarations).
+  Many2OneRef,
+  Many2OneRefFromWire,
+  Many2OneRefOrNull,
+  Many2OneRefValue,
+  OdooDate,
+  OdooDateOrNull,
+  OdooDateTime,
+  OdooDateTimeOrNull,
+  // Pure join helpers + the classic-tier explicit-traversal snapshot.
+  collectRefIds,
+  makeRelatedMap,
+  makeTypedRecordSet,
+  refId,
+  type HasId,
+  type Many2OneRefField,
+  type RefOrId,
+  type RelatedMap,
+  type TypedRecordSet,
+  // Spec-tier model declaration + compilation (17+ `specification` protocol).
+  defineRecord,
+  Many2One,
+  One2Many,
+  compileSpecification,
+  hasRelations,
+  EmptyRecordSpecError,
+  RecordSpecCycleError,
+  type FieldInput,
+  type FieldMeta,
+  type Many2OneDecl,
+  type One2ManyDecl,
+  type RecordSpec,
+  type RowEncoded,
+  type RowType,
+} from "./records/index.ts";
+
+// Transports — one Layer per protocol, all implementing the Transport tag.
+export * as JsonRpcTransport from "./transports/jsonrpc.ts";
+export * as Json2Transport from "./transports/json2.ts";
+export * as WebTransport from "./transports/web.ts";
+
+// Cookie session + opt-in session-expiry recovery.
+export {
+  CookieSession,
+  type CookieSessionService,
+  type CookieLoginError,
+  type ExistingSessionOptions,
+  type OdooSessionInfo,
+  type RawHttpOptions,
+} from "./session/cookie.ts";
+export * as CookieSessionLive from "./session/cookie.ts";
+export { retryOnSessionExpired } from "./combinators/retryOnSessionExpired.ts";
+
+// Typed x2many write commands.
+export {
+  Command,
+  type CommandTuple,
+  type X2ManyCommands,
+} from "./commands.ts";
+
+// Database administration (master-password gated; Node-oriented buffers).
+export * as DbService from "./services/db.ts";
+export type { CreateOptions, DuplicateOptions, RestoreOptions } from "./services/db.ts";
+
+// Report downloads over a cookie session.
+export { ReportService, type ReportAction, type DownloadOptions } from "./services/report.ts";
+
+// Named connection profiles — secrets never serialize; storage is yours.
+export {
+  Profiles,
+  SecretStore,
+  ProfileStorage,
+  InMemorySecretStore,
+  InMemoryProfileStorage,
+  ProfileStoreError,
+  ProfileSecretMissingError,
+  type ProfileData,
+  type CredentialProfileData,
+  type SessionProfileData,
+  type LoadedProfile,
+  type ProfileProtocol,
+} from "./profiles.ts";
+export * as ProfilesLive from "./profiles.ts";

package/src/internal/platform.ts

@@ -0,0 +1,22 @@
+/**
+ * The single funnel for everything we consume from the platform HTTP layer.
+ *
+ * Every other module in this package imports platform values and types
+ * from HERE — never directly from `effect/unstable/http`. This kept the
+ * blast radius of the platform v4 move (v3 `@effect/platform` →
+ * `effect/unstable/http`) to exactly this file, and documents the exact
+ * platform surface the client depends on.
+ */
+
+export {
+  Cookies,
+  FetchHttpClient,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/unstable/http";
+
+// Type-only alias for the transport error channel of `HttpClient`, kept
+// here so error modules can name it without reaching into the namespace.
+export type { HttpClientError as HttpClientErrorType } from "effect/unstable/http/HttpClientError";

package/src/internal/singleFlight.ts

@@ -0,0 +1,80 @@
+import { Effect, Option, Ref, Semaphore } from "effect";
+
+/** A memoized `get` whose underlying `acquire` runs at most once on success. */
+export interface SingleFlight<A, E, R> {
+  /**
+   * Return the cached value, or acquire it. Concurrent callers race a single
+   * permit so `acquire` runs once; a failure caches nothing, so the next call
+   * retries. This is the success-only single-flight AGENTS.md mandates in place
+   * of `Effect.cached` (which would also memoize failures).
+   */
+  readonly get: Effect.Effect<A, E, R>;
+  /**
+   * Drop the cached value so the next `get` re-acquires.
+   *
+   * GOTCHA: an acquire already in flight when `invalidate` runs will complete
+   * and be returned to ITS caller, but is NOT cached — a generation counter
+   * guards the write, so a stale result can never resurrect the cache.
+   */
+  readonly invalidate: Effect.Effect<void>;
+  /** The current cached value, without triggering an acquire. */
+  readonly peek: Effect.Effect<Option.Option<A>>;
+}
+
+interface State<A> {
+  readonly generation: number;
+  readonly value: Option.Option<A>;
+}
+
+/**
+ * Build a success-only single-flight cache around `acquire`.
+ *
+ * Invariant (AGENTS.md): only successful results are cached. A failed `acquire`
+ * leaves the cache empty so callers can retry — never `Effect.cached`.
+ */
+export const make = <A, E, R>(
+  acquire: Effect.Effect<A, E, R>,
+): Effect.Effect<SingleFlight<A, E, R>, never, never> =>
+  Effect.gen(function* () {
+    const ref = yield* Ref.make<State<A>>({ generation: 0, value: Option.none() });
+    const semaphore = yield* Semaphore.make(1);
+
+    const get: Effect.Effect<A, E, R> = Effect.gen(function* () {
+      // Fast path: already cached, no lock needed.
+      const cached = yield* Ref.get(ref);
+      if (Option.isSome(cached.value)) {
+        return cached.value.value;
+      }
+
+      // Slow path: serialize acquisition behind the single permit.
+      return yield* semaphore.withPermits(1)(
+        Effect.gen(function* () {
+          // Double-check: a racing caller may have filled the cache while we
+          // waited for the permit.
+          const state = yield* Ref.get(ref);
+          if (Option.isSome(state.value)) {
+            return state.value.value;
+          }
+
+          const startGeneration = state.generation;
+          const value = yield* acquire;
+          // Cache only if no invalidate happened while we were acquiring.
+          yield* Ref.update(ref, (current) =>
+            current.generation === startGeneration
+              ? { generation: current.generation, value: Option.some(value) }
+              : current,
+          );
+          return value;
+        }),
+      );
+    });
+
+    const invalidate = Ref.update(ref, (current) => ({
+      generation: current.generation + 1,
+      value: Option.none<A>(),
+    }));
+
+    const peek = Ref.get(ref).pipe(Effect.map((state) => state.value));
+
+    return { get, invalidate, peek };
+  });