@hodeinavarro/odoo-rpc-ts 0.2.0

package/dist/profiles.js

@@ -0,0 +1,191 @@
+import { Context, Data, Effect, Layer, Option, Ref } from "effect";
+/**
+ * A profile's storage operation failed at the consumer-supplied backend (keyring
+ * denied, IndexedDB transaction aborted, file unwritable, …). Wraps the opaque
+ * platform `cause`; upper layers branch on `_tag`, never on the message. A store
+ * failure proves only that *that* operation failed — infer nothing about the
+ * other backend's state (see the removal ordering in {@link make}).
+ */
+export class ProfileStoreError extends Data.TaggedError("ProfileStoreError") {
+}
+/**
+ * A profile's metadata was found but its credential secret is not reachable
+ * through {@link SecretStore} (the secret was never stored, was removed out of
+ * band, or the named profile does not exist at all). Distinct from
+ * {@link ProfileStoreError}: the backend answered fine — the secret is simply
+ * absent, so the {@link OdooConfig} cannot be reconstructed.
+ */
+export class ProfileSecretMissingError extends Data.TaggedError("ProfileSecretMissingError") {
+}
+/**
+ * Consumer-implemented secret vault, keyed by an opaque `account` string. The
+ * platform-portable seam: an OS keyring in Node, IndexedDB + WebCrypto in a
+ * browser, a `Ref`-backed map in tests. Secrets cross this boundary only as
+ * `Redacted` — never a bare string — so they cannot leak into logs or JSON.
+ */
+export class SecretStore extends Context.Service()("odoo-rpc-ts/SecretStore") {
+}
+/**
+ * Consumer-implemented store for the secret-free {@link ProfileData} map, keyed
+ * by profile name. A JSON file on disk, `localStorage`, a config table — anything
+ * that round-trips a `Record<string, ProfileData>`. Never carries secrets.
+ */
+export class ProfileStorage extends Context.Service()("odoo-rpc-ts/ProfileStorage") {
+}
+/** The keyring account for a profile's secret. One secret per (name, kind). */
+const accountOf = (name, credentialKind) => `${name}:${credentialKind}`;
+const credentialKindOf = (c) => c._tag === "ApiKey" ? "api-key" : "password";
+const secretOf = (c) => c._tag === "ApiKey" ? c.apiKey : c.password;
+/** Rebuild the live {@link OdooConfig} from stored metadata + a resolved secret. */
+const reconstructConfig = (data, secret) => ({
+    url: new URL(data.url),
+    db: data.db,
+    credentials: data.credentialKind === "api-key"
+        ? { _tag: "ApiKey", username: data.username, apiKey: secret }
+        : { _tag: "Password", username: data.username, password: secret },
+});
+/**
+ * Named connection profiles over a {@link SecretStore} + {@link ProfileStorage}
+ * seam. The metadata (URL, db, username, protocol) is serializable and travels
+ * through `ProfileStorage`; the credential secret travels *only* through
+ * `SecretStore` as `Redacted`. Serializing what this service persists can never
+ * expose secret material.
+ */
+export class Profiles extends Context.Service()("odoo-rpc-ts/Profiles") {
+}
+/** Hand-written {@link Profiles} layer over the two storage seams. */
+export const layer = Layer.effect(Profiles, Effect.gen(function* () {
+    const secrets = yield* SecretStore;
+    const storage = yield* ProfileStorage;
+    /**
+     * Overwriting a profile with a DIFFERENT credentialKind must evict the
+     * superseded secret first, or it is orphaned in the keyring forever:
+     * removeProfile derives the account from the *current* metadata kind, so a
+     * password secret left behind by a password→session switch would be
+     * invisible and un-removable. Evict-before-write keeps the failure modes
+     * benign: if the subsequent new-secret write fails, the stored metadata
+     * still names the OLD kind whose secret is now gone — loadProfile then
+     * reports ProfileSecretMissingError rather than returning stale material.
+     */
+    const evictSuperseded = (name, newKind, existing) => {
+        const previous = existing[name];
+        return previous !== undefined && previous.credentialKind !== newKind
+            ? secrets.remove(accountOf(name, previous.credentialKind))
+            : Effect.void;
+    };
+    const saveProfile = (name, config, protocol) => Effect.gen(function* () {
+        const credentialKind = credentialKindOf(config.credentials);
+        const data = {
+            url: config.url.href,
+            db: config.db,
+            username: config.credentials.username,
+            credentialKind,
+            protocol,
+        };
+        const existing = yield* storage.load();
+        yield* evictSuperseded(name, credentialKind, existing);
+        // Secret before metadata: if metadata landed first and the secret write
+        // then failed, we'd persist a profile that can never be loaded.
+        yield* secrets.set(accountOf(name, credentialKind), secretOf(config.credentials));
+        yield* storage.save({ ...existing, [name]: data });
+    });
+    const saveSessionProfile = (name, url, sessionId) => Effect.gen(function* () {
+        const data = { url: url.href, credentialKind: "session", protocol: "web" };
+        const existing = yield* storage.load();
+        yield* evictSuperseded(name, "session", existing);
+        // Same ordering as saveProfile: secret (the cookie) before metadata.
+        yield* secrets.set(accountOf(name, "session"), sessionId);
+        yield* storage.save({ ...existing, [name]: data });
+    });
+    const loadProfile = (name) => Effect.gen(function* () {
+        const all = yield* storage.load();
+        const data = all[name];
+        if (data === undefined) {
+            // No metadata ⇒ no reachable secret either.
+            return yield* new ProfileSecretMissingError({ name, account: name });
+        }
+        // ProfileStorage is a consumer-supplied JSON round-trip — its output is
+        // NOT trusted. A corrupted/hand-edited record must fail in the typed
+        // channel (ProfileStoreError), never throw past it (new URL TypeError,
+        // or a credentials arm missing username/db sailing into OdooConfig).
+        const url = yield* Effect.try({
+            try: () => new URL(data.url),
+            catch: (cause) => new ProfileStoreError({ operation: "profile.decode", cause }),
+        });
+        if (data.credentialKind !== "session" &&
+            (typeof data.username !== "string" || typeof data.db !== "string")) {
+            return yield* new ProfileStoreError({
+                operation: "profile.decode",
+                cause: `stored profile "${name}" (${data.credentialKind}) lacks username/db`,
+            });
+        }
+        const account = accountOf(name, data.credentialKind);
+        const maybeSecret = yield* secrets.get(account);
+        if (Option.isNone(maybeSecret)) {
+            return yield* new ProfileSecretMissingError({ name, account });
+        }
+        if (data.credentialKind === "session") {
+            // NEVER fabricate an OdooConfig around a session cookie — there is
+            // no credential; the consumer feeds this to CookieSessionLive.fromExisting.
+            return {
+                _tag: "session",
+                url,
+                sessionId: maybeSecret.value,
+                protocol: data.protocol,
+            };
+        }
+        return {
+            _tag: "credentials",
+            config: reconstructConfig(data, maybeSecret.value),
+            protocol: data.protocol,
+        };
+    });
+    const listProfiles = () => storage.load();
+    const removeProfile = (name) => Effect.gen(function* () {
+        const all = yield* storage.load();
+        const data = all[name];
+        if (data === undefined) {
+            return; // Nothing to remove — idempotent.
+        }
+        // Ordering: remove the SECRET first, then the metadata. The dangerous
+        // half-state is an orphaned secret — a credential left in the keyring
+        // with no metadata pointing at it, invisible and un-removable. Deleting
+        // the secret first guarantees the credential is gone even if the
+        // subsequent metadata save fails. The reverse transient (metadata
+        // without a secret) is benign and self-heals: loadProfile reports
+        // ProfileSecretMissingError rather than handing back a broken config.
+        yield* secrets.remove(accountOf(name, data.credentialKind));
+        const { [name]: _removed, ...rest } = all;
+        yield* storage.save(rest);
+    });
+    return { saveProfile, saveSessionProfile, loadProfile, listProfiles, removeProfile };
+}));
+/**
+ * Ready-made, `Ref`-backed {@link SecretStore} for tests and single-process
+ * consumers. Each `.layer` build gets its own isolated map — no shared global
+ * state between tests.
+ */
+export const InMemorySecretStore = {
+    layer: Layer.effect(SecretStore, Effect.gen(function* () {
+        const store = yield* Ref.make({});
+        return {
+            get: (account) => Ref.get(store).pipe(Effect.map((s) => Option.fromNullishOr(s[account]))),
+            set: (account, secret) => Ref.update(store, (s) => ({ ...s, [account]: secret })),
+            remove: (account) => Ref.update(store, ({ [account]: _removed, ...rest }) => rest),
+        };
+    })),
+};
+/**
+ * Ready-made, `Ref`-backed {@link ProfileStorage} for tests and single-process
+ * consumers. Isolated per `.layer` build, like {@link InMemorySecretStore}.
+ */
+export const InMemoryProfileStorage = {
+    layer: Layer.effect(ProfileStorage, Effect.gen(function* () {
+        const store = yield* Ref.make({});
+        return {
+            load: () => Ref.get(store),
+            save: (profiles) => Ref.set(store, profiles),
+        };
+    })),
+};
+//# sourceMappingURL=profiles.js.map

package/dist/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAiB,GAAG,EAAE,MAAM,QAAQ,CAAC;AA6ClF;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAIzE;CAAG;AAEL;;;;;;GAMG;AACH,MAAM,OAAO,yBAA0B,SAAQ,IAAI,CAAC,WAAW,CAAC,2BAA2B,CAIzF;CAAG;AAEL;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,OAAO,CAAC,OAAO,EAY7C,CAAC,yBAAyB,CAAC;CAAG;AAEjC;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,OAAO,CAAC,OAAO,EAQhD,CAAC,4BAA4B,CAAC;CAAG;AAEpC,+EAA+E;AAC/E,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,cAA6C,EAAU,EAAE,CACxF,GAAG,IAAI,IAAI,cAAc,EAAE,CAAC;AAE9B,MAAM,gBAAgB,GAAG,CAAC,CAAkB,EAA2C,EAAE,CACvF,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;AAE/C,MAAM,QAAQ,GAAG,CAAC,CAAkB,EAA6B,EAAE,CACjE,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAE9C,oFAAoF;AACpF,MAAM,iBAAiB,GAAG,CACxB,IAA2B,EAC3B,MAAiC,EACrB,EAAE,CAAC,CAAC;IAChB,GAAG,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;IACtB,EAAE,EAAE,IAAI,CAAC,EAAE;IACX,WAAW,EACT,IAAI,CAAC,cAAc,KAAK,SAAS;QAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;QAC7D,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE;CACtE,CAAC,CAAC;AA0BH;;;;;;GAMG;AACH,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,OAAO,EAkD1C,CAAC,sBAAsB,CAAC;CAAG;AAE9B,sEAAsE;AACtE,MAAM,CAAC,MAAM,KAAK,GAA+D,KAAK,CAAC,MAAM,CAC3F,QAAQ,EACR,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,WAAW,CAAC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC;IAEtC;;;;;;;;;OASG;IACH,MAAM,eAAe,GAAG,CACtB,IAAY,EACZ,OAAsC,EACtC,QAAqC,EACG,EAAE;QAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,cAAc,KAAK,OAAO;YAClE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;YAC1D,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;IAClB,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAClB,IAAY,EACZ,MAAkB,EAClB,QAAyB,EACe,EAAE,CAC1C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,cAAc,GAAG,gBAAgB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAgB;YACxB,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI;YACpB,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ;YACrC,cAAc;YACd,QAAQ;SACT,CAAC;QACF,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;QACvD,wEAAwE;QACxE,gEAAgE;QAChE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;QAClF,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEL,MAAM,kBAAkB,GAAG,CACzB,IAAY,EACZ,GAAQ,EACR,SAAoC,EACI,EAAE,CAC1C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,IAAI,GAAgB,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACxF,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAClD,qEAAqE;QACrE,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC;QAC1D,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEL,MAAM,WAAW,GAAG,CAClB,IAAY,EACiE,EAAE,CAC/E,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,4CAA4C;YAC5C,OAAO,KAAK,CAAC,CAAC,IAAI,yBAAyB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,wEAAwE;QACxE,qEAAqE;QACrE,uEAAuE;QACvE,qEAAqE;QACrE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAC5B,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;YAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,iBAAiB,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;SAChF,CAAC,CAAC;QACH,IACE,IAAI,CAAC,cAAc,KAAK,SAAS;YACjC,CAAC,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,CAAC,EAClE,CAAC;YACD,OAAO,KAAK,CAAC,CAAC,IAAI,iBAAiB,CAAC;gBAClC,SAAS,EAAE,gBAAgB;gBAC3B,KAAK,EAAE,mBAAmB,IAAI,MAAM,IAAI,CAAC,cAAc,qBAAqB;aAC7E,CAAC,CAAC;QACL,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC,CAAC,IAAI,yBAAyB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACtC,mEAAmE;YACnE,4EAA4E;YAC5E,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,GAAG;gBACH,SAAS,EAAE,WAAW,CAAC,KAAK;gBAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACf,CAAC;QACb,CAAC;QACD,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC;YAClD,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACf,CAAC;IACb,CAAC,CAAC,CAAC;IAEL,MAAM,YAAY,GAAG,GAAkE,EAAE,CACvF,OAAO,CAAC,IAAI,EAAE,CAAC;IAEjB,MAAM,aAAa,GAAG,CAAC,IAAY,EAA0C,EAAE,CAC7E,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,kCAAkC;QAC5C,CAAC;QACD,sEAAsE;QACtE,sEAAsE;QACtE,wEAAwE;QACxE,iEAAiE;QACjE,kEAAkE;QAClE,kEAAkE;QAClE,sEAAsE;QACtE,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;QAC5D,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;QAC1C,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEL,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AACvF,CAAC,CAAC,CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,KAAK,EAAE,KAAK,CAAC,MAAM,CACjB,WAAW,EACX,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAA4C,EAAE,CAAC,CAAC;QAC7E,OAAO;YACL,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1F,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACjF,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC;SACnF,CAAC;IACJ,CAAC,CAAC,CACH;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,KAAK,EAAE,KAAK,CAAC,MAAM,CACjB,cAAc,EACd,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAA8B,EAAE,CAAC,CAAC;QAC/D,OAAO;YACL,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC;YAC1B,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC;SAC7C,CAAC;IACJ,CAAC,CAAC,CACH;CACO,CAAC"}

package/dist/protocol/jsonrpc.d.ts

@@ -0,0 +1,127 @@
+import { Schema } from "effect";
+import type { FaultCallSite } from "../errors/mapFault.js";
+import { type OdooServerFault } from "../errors/server.js";
+import type { OdooAuthenticationError } from "../errors/auth.js";
+import { SessionExpiredError } from "../errors/session.js";
+/**
+ * The JSON-RPC envelope shared by every route that speaks it (`/jsonrpc`,
+ * `/web/session/authenticate`, `/web/dataset/call_kw`). Deliberately
+ * transport-agnostic: `params` is opaque here so the same builder serves the
+ * `object`/`common` service calls and the web route's `{model, method, ...}`
+ * params alike.
+ *
+ * GOTCHA: Odoo ignores the JSON-RPC `method` member entirely — it dispatches on
+ * the URL and reads `params` by name. We still send the spec-mandated
+ * `"call"` so the envelope is valid JSON-RPC 2.0.
+ */
+export interface JsonRpcRequest<P> {
+    readonly jsonrpc: "2.0";
+    readonly method: "call";
+    readonly params: P;
+    readonly id: number;
+}
+/** Next distinct JSON-RPC request id (log-correlation only; see gotcha above). */
+export declare const nextRequestId: () => number;
+/** Build a JSON-RPC 2.0 request envelope around arbitrary by-name `params`. */
+export declare const buildRequest: <P>(params: P, id: number) => JsonRpcRequest<P>;
+/**
+ * The `error.data` payload. Odoo guarantees only `name` (the dotted Python
+ * exception class); every other field can be absent depending on the fault and
+ * the server's `dev_mode`. Decoded leniently, then normalized to
+ * ""/[]/{} before it reaches {@link mapServerFault}.
+ */
+export declare const JsonRpcErrorData: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly debug: Schema.optional<Schema.String>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly arguments: Schema.optional<Schema.$Array<Schema.Unknown>>;
+    readonly context: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+export type JsonRpcErrorData = typeof JsonRpcErrorData.Type;
+/** The `error` member of a JSON-RPC error response. `data` may be absent. */
+export declare const JsonRpcErrorPayload: Schema.Struct<{
+    readonly code: Schema.Number;
+    readonly message: Schema.String;
+    readonly data: Schema.optional<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly debug: Schema.optional<Schema.String>;
+        readonly message: Schema.optional<Schema.String>;
+        readonly arguments: Schema.optional<Schema.$Array<Schema.Unknown>>;
+        readonly context: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    }>>;
+}>;
+export type JsonRpcErrorPayload = typeof JsonRpcErrorPayload.Type;
+/** A JSON-RPC error response: `{jsonrpc, id?, error:{code, message, data?}}`. */
+export declare const JsonRpcErrorResponse: Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>>;
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Number;
+        readonly message: Schema.String;
+        readonly data: Schema.optional<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly debug: Schema.optional<Schema.String>;
+            readonly message: Schema.optional<Schema.String>;
+            readonly arguments: Schema.optional<Schema.$Array<Schema.Unknown>>;
+            readonly context: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+        }>>;
+    }>;
+}>;
+export type JsonRpcErrorResponse = typeof JsonRpcErrorResponse.Type;
+export declare const JsonRpcSuccessResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>>;
+    readonly result: Schema.Unknown;
+    readonly error: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>;
+    readonly result: Schema.withDecodingDefaultTypeKey<Schema.Unknown, never>;
+    readonly error: Schema.optionalKey<Schema.Never>;
+}>]>;
+export type JsonRpcSuccessResponse = typeof JsonRpcSuccessResponse.Type;
+/**
+ * A whole JSON-RPC response. The error branch is tried first so a fault is
+ * never mistaken for a `result: undefined` success. A body that is neither
+ * shape (e.g. a proxy's HTML error page decoded as garbage) fails to decode →
+ * the caller raises `SchemaDriftError`.
+ */
+export declare const JsonRpcResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>>;
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Number;
+        readonly message: Schema.String;
+        readonly data: Schema.optional<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly debug: Schema.optional<Schema.String>;
+            readonly message: Schema.optional<Schema.String>;
+            readonly arguments: Schema.optional<Schema.$Array<Schema.Unknown>>;
+            readonly context: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+        }>>;
+    }>;
+}>, Schema.Union<readonly [Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>>;
+    readonly result: Schema.Unknown;
+    readonly error: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly jsonrpc: Schema.Literal<"2.0">;
+    readonly id: Schema.Union<readonly [Schema.Number, Schema.String, Schema.Null]>;
+    readonly result: Schema.withDecodingDefaultTypeKey<Schema.Unknown, never>;
+    readonly error: Schema.optionalKey<Schema.Never>;
+}>]>]>;
+export type JsonRpcResponse = typeof JsonRpcResponse.Type;
+/**
+ * The single JSON-RPC fault choke point. Both `/jsonrpc` and the web route feed
+ * their decoded `error` payload through here so every fault normalizes into the
+ * same tagged union.
+ *
+ * - code `100` → {@link SessionExpiredError} (Odoo's `SessionExpiredException`).
+ * - code `404` → {@link OdooServerError} (NotFound; the `data.name` is often a
+ *   werkzeug class we do not map, so it lands on the base fault by design).
+ * - otherwise → {@link mapServerFault} on the normalized `data`; a missing
+ *   `data` becomes name `"unknown"`, which falls back to {@link OdooServerError}.
+ */
+export declare const mapJsonRpcError: (error: JsonRpcErrorPayload, site?: FaultCallSite) => SessionExpiredError | OdooServerFault | OdooAuthenticationError;
+//# sourceMappingURL=jsonrpc.d.ts.map

package/dist/protocol/jsonrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/protocol/jsonrpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAQD,kFAAkF;AAClF,eAAO,MAAM,aAAa,QAAO,MAAiC,CAAC;AAEnE,+EAA+E;AAC/E,eAAO,MAAM,YAAY,GAAI,CAAC,UAAU,CAAC,MAAM,MAAM,KAAG,cAAc,CAAC,CAAC,CAKtE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;EAM3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC;AAE5D,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB;;;;;;;;;;EAI9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAC;AAMlE,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;EAI/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAC;AAwBpE,eAAO,MAAM,sBAAsB;;;;;;;;;;IAGjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;MAA+D,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC;AAe1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,UACnB,mBAAmB,SACpB,aAAa,KAClB,mBAAmB,GAAG,eAAe,GAAG,uBAoB1C,CAAC"}

package/dist/protocol/jsonrpc.js

@@ -0,0 +1,117 @@
+import { Effect, Schema } from "effect";
+import { mapServerFault } from "../errors/mapFault.js";
+import { OdooServerError } from "../errors/server.js";
+import { SessionExpiredError } from "../errors/session.js";
+// GOTCHA: Odoo ignores the JSON-RPC `id` entirely — it never round-trips into
+// dispatch. This process-wide monotonic counter exists only to keep concurrent
+// requests distinguishable in logs/traces; module-level mutable state is
+// acceptable precisely because nothing correctness-bearing reads it back.
+let requestIdCounter = 0;
+/** Next distinct JSON-RPC request id (log-correlation only; see gotcha above). */
+export const nextRequestId = () => (requestIdCounter += 1);
+/** Build a JSON-RPC 2.0 request envelope around arbitrary by-name `params`. */
+export const buildRequest = (params, id) => ({
+    jsonrpc: "2.0",
+    method: "call",
+    params,
+    id,
+});
+/**
+ * The `error.data` payload. Odoo guarantees only `name` (the dotted Python
+ * exception class); every other field can be absent depending on the fault and
+ * the server's `dev_mode`. Decoded leniently, then normalized to
+ * ""/[]/{} before it reaches {@link mapServerFault}.
+ */
+export const JsonRpcErrorData = Schema.Struct({
+    name: Schema.String,
+    debug: 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)),
+});
+/** The `error` member of a JSON-RPC error response. `data` may be absent. */
+export const JsonRpcErrorPayload = Schema.Struct({
+    code: Schema.Number,
+    message: Schema.String,
+    data: Schema.optional(JsonRpcErrorData),
+});
+// `id` echoes what we sent, but a few Odoo error paths return `null` — accept
+// any of the JSON-RPC-legal id shapes rather than drift on the envelope.
+const JsonRpcId = Schema.Union([Schema.Number, Schema.String, Schema.Null]);
+/** A JSON-RPC error response: `{jsonrpc, id?, error:{code, message, data?}}`. */
+export const JsonRpcErrorResponse = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.optional(JsonRpcId),
+    error: JsonRpcErrorPayload,
+});
+/**
+ * A JSON-RPC success response: `{jsonrpc, id?, result?}` (result is opaque).
+ *
+ * Odoo 16 and 17 omit the member entirely when a Python method returns
+ * `None`. Decode that wire quirk to an explicit `undefined`, so consumers have
+ * one stable successful-response shape.
+ */
+const JsonRpcResultSuccessResponse = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.optional(JsonRpcId),
+    result: Schema.Unknown,
+    error: Schema.optionalKey(Schema.Never),
+});
+const JsonRpcVoidSuccessResponse = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: JsonRpcId,
+    result: Schema.Unknown.pipe(Schema.withDecodingDefaultTypeKey(Effect.void)),
+    // Declare this forbidden member so malformed error envelopes cannot fall
+    // through to the missing-result success shape in the union below.
+    error: Schema.optionalKey(Schema.Never),
+});
+export const JsonRpcSuccessResponse = Schema.Union([
+    JsonRpcResultSuccessResponse,
+    JsonRpcVoidSuccessResponse,
+]);
+/**
+ * A whole JSON-RPC response. The error branch is tried first so a fault is
+ * never mistaken for a `result: undefined` success. A body that is neither
+ * shape (e.g. a proxy's HTML error page decoded as garbage) fails to decode →
+ * the caller raises `SchemaDriftError`.
+ */
+export const JsonRpcResponse = Schema.Union([JsonRpcErrorResponse, JsonRpcSuccessResponse]);
+/** Normalize a lenient `error.data` (or its absence) into a {@link RawServerFault}. */
+const normalizeFault = (data, fallbackMessage) => ({
+    name: data?.name ?? "unknown",
+    message: data?.message ?? fallbackMessage,
+    arguments: data?.arguments ?? [],
+    context: data?.context ?? {},
+    // exactOptionalPropertyTypes: attach `debug` only when actually present.
+    ...(data?.debug !== undefined ? { debug: data.debug } : {}),
+});
+/**
+ * The single JSON-RPC fault choke point. Both `/jsonrpc` and the web route feed
+ * their decoded `error` payload through here so every fault normalizes into the
+ * same tagged union.
+ *
+ * - code `100` → {@link SessionExpiredError} (Odoo's `SessionExpiredException`).
+ * - code `404` → {@link OdooServerError} (NotFound; the `data.name` is often a
+ *   werkzeug class we do not map, so it lands on the base fault by design).
+ * - otherwise → {@link mapServerFault} on the normalized `data`; a missing
+ *   `data` becomes name `"unknown"`, which falls back to {@link OdooServerError}.
+ */
+export const mapJsonRpcError = (error, site = {}) => {
+    if (error.code === 100) {
+        return new SessionExpiredError({ message: error.message });
+    }
+    const raw = normalizeFault(error.data, error.message);
+    if (error.code === 404) {
+        return new OdooServerError({
+            name: raw.name,
+            message: raw.message,
+            arguments: raw.arguments,
+            context: raw.context,
+            ...(raw.debug !== undefined ? { debug: raw.debug } : {}),
+            ...(site.model !== undefined ? { model: site.model } : {}),
+            ...(site.method !== undefined ? { method: site.method } : {}),
+        });
+    }
+    return mapServerFault(raw, site);
+};
+//# sourceMappingURL=jsonrpc.js.map

package/dist/protocol/jsonrpc.js.map

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

package/dist/records/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed records — internal barrel for both per-protocol tiers of the records
+ * design: the CLASSIC tier (explicit traversal over the classic `[id, name]`
+ * pair protocol, 16+: relation/temporal decode schemas, pure join helpers,
+ * the `TypedRecordSet` snapshot) and the SPEC tier (declared prefetch over the
+ * 17+ `specification` protocol: `defineRecord` + the specification compiler).
+ * Re-exported to the public surface via `src/index.ts`.
+ */
+export { Many2OneRef, Many2OneRefFromWire, Many2OneRefOrNull, Many2OneRefValue, OdooDate, OdooDateOrNull, OdooDateTime, OdooDateTimeOrNull, } from "./relations.js";
+export { collectRefIds, makeRelatedMap, refId, type RefOrId, type RelatedMap, } from "./related.js";
+export { make as makeTypedRecordSet, type HasId, type Many2OneRefField, type TypedRecordSet, } from "./typed.js";
+export { defineRecord, Many2One, One2Many, type FieldInput, type FieldMeta, type Many2OneDecl, type One2ManyDecl, type RecordSpec, type RowEncoded, type RowType, } from "./recordModel.js";
+export { compileSpecification, EmptyRecordSpecError, hasRelations, RecordSpecCycleError, } from "./spec.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/records/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/records/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,EACL,KAAK,OAAO,EACZ,KAAK,UAAU,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,IAAI,IAAI,kBAAkB,EAC1B,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/records/index.js

@@ -0,0 +1,14 @@
+/**
+ * Typed records — internal barrel for both per-protocol tiers of the records
+ * design: the CLASSIC tier (explicit traversal over the classic `[id, name]`
+ * pair protocol, 16+: relation/temporal decode schemas, pure join helpers,
+ * the `TypedRecordSet` snapshot) and the SPEC tier (declared prefetch over the
+ * 17+ `specification` protocol: `defineRecord` + the specification compiler).
+ * Re-exported to the public surface via `src/index.ts`.
+ */
+export { Many2OneRef, Many2OneRefFromWire, Many2OneRefOrNull, Many2OneRefValue, OdooDate, OdooDateOrNull, OdooDateTime, OdooDateTimeOrNull, } from "./relations.js";
+export { collectRefIds, makeRelatedMap, refId, } from "./related.js";
+export { make as makeTypedRecordSet, } from "./typed.js";
+export { defineRecord, Many2One, One2Many, } from "./recordModel.js";
+export { compileSpecification, EmptyRecordSpecError, hasRelations, RecordSpecCycleError, } from "./spec.js";
+//# sourceMappingURL=index.js.map

package/dist/records/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/records/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,GAGN,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,IAAI,IAAI,kBAAkB,GAI3B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,QAAQ,GAQT,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/records/recordModel.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Declared record models — the SPEC tier of the records design ("declared
+ * prefetch" over the 17+ `specification` protocol; the classic tier in
+ * `typed.ts`/`related.ts` speaks the 16+ `[id, name]`-pair protocol instead).
+ * A `RecordSpec`
+ * declares a model's field graph with `effect/Schema`: scalars decode directly,
+ * relations declared with {@link Many2One}/{@link One2Many} carry a nested child
+ * `RecordSpec`. From one declaration we derive BOTH:
+ *
+ *   1. a row {@link RecordSpec.schema} that strict-decodes the NESTED wire shape
+ *      the 17+ `web_search_read`/`web_read` `specification` protocol returns
+ *      (a many2one as a `{ id, ...declared }` dict or `false`; an x2many as a
+ *      nested list), and
+ *   2. the field {@link RecordSpec.fields} metadata that {@link ./spec.ts} compiles
+ *      into that `specification` payload.
+ *
+ * No I/O lives here — this is pure declaration. The single round trip that turns
+ * a spec into rows is in `OdooClient.searchTyped`/`readTyped`/`saveTyped`.
+ *
+ * MANY2ONE VALUE SHAPE (decision, records design 2026-07-10). A declared
+ * many2one decodes to a FLAT struct `{ id, ...declaredChildFields } | null`, not
+ * a `{ id, value }` wrapper. In TS, `| null` already carries "is it set?", and a
+ * flat struct exposes `.id` and every declared child field as directly-typed
+ * properties (`company.name`) with no `__getattr__`-style proxy and no extra
+ * `.value` hop — strictly better inference and ergonomics than a wrapper. This
+ * deliberately diverges from the Python design's `.value` recommendation, which
+ * existed to model presence separately from the record; TS does not need it.
+ */
+import { Schema } from "effect";
+import type { HasId } from "./typed.js";
+/**
+ * Per-field compilation metadata: how {@link ./spec.ts} renders each field. The
+ * relation `child` is typed loosely (`RecordSpec<any, any>`) because `Schema` is
+ * invariant in its type parameter — a precisely-typed child spec is not
+ * assignable to a widened one, so the metadata graph is deliberately erased. The
+ * precise types live on {@link RecordSpec.schema} for decode; this metadata is
+ * only ever walked structurally by the pure compiler.
+ */
+export type FieldMeta = {
+    readonly kind: "scalar";
+} | {
+    readonly kind: "many2one";
+    readonly child: RecordSpec<any, any>;
+} | {
+    readonly kind: "one2many";
+    readonly child: RecordSpec<any, any>;
+    readonly limit: number | undefined;
+};
+/**
+ * A declared record model: its Odoo model name, the row decode `schema` (the
+ * whole nested graph), the per-field compilation `fields`, and whether it
+ * declares any relation (the version gate keys on this). Build one with
+ * {@link defineRecord}.
+ */
+export interface RecordSpec<A extends HasId, I = A> {
+    readonly model: string;
+    readonly schema: Schema.Codec<A, I>;
+    readonly fields: Readonly<Record<string, FieldMeta>>;
+    /** `true` iff at least one declared field is a many2one/one2many relation. */
+    readonly hasRelations: boolean;
+}
+/** A declared many2one relation field — nests a child {@link RecordSpec}. */
+export interface Many2OneDecl<A extends HasId, I> {
+    readonly _decl: "many2one";
+    readonly spec: RecordSpec<A, I>;
+}
+/** A declared one2many/many2many relation field — nests a child {@link RecordSpec}. */
+export interface One2ManyDecl<A extends HasId, I> {
+    readonly _decl: "one2many";
+    readonly spec: RecordSpec<A, I>;
+    readonly limit: number | undefined;
+}
+/**
+ * Declare a many2one field: `company_id: Many2One(Company)`. Decodes the nested
+ * `{ id, ...Company fields }` wire dict to `Company | null` (Odoo's `false`
+ * empty → `null`). Note it does NOT accept the classic `[id, name]` pair — under
+ * a `specification` the server returns a dict, so a leaked pair is drift, not a
+ * silent decode.
+ */
+export declare const Many2One: <A extends HasId, I>(spec: RecordSpec<A, I>) => Many2OneDecl<A, I>;
+/**
+ * Declare an x2many field: `child_ids: One2Many(Contact)` or
+ * `One2Many(Contact, { limit: 20 })`. Decodes the nested list to
+ * `ReadonlyArray<Contact>`; `limit`, when given, rides the compiled
+ * `specification` so the server bounds the co-recordset.
+ */
+export declare const One2Many: <A extends HasId, I>(spec: RecordSpec<A, I>, options?: {
+    readonly limit?: number;
+}) => One2ManyDecl<A, I>;
+/**
+ * A field of a {@link defineRecord} declaration: a scalar schema or a relation.
+ * The relation members are `any`-parameterized because `Schema` (inside the
+ * nested child spec) is invariant — a precisely-typed `Many2One(Company)` is not
+ * assignable to a widened `Many2OneDecl<HasId, unknown>`. Field-level types are
+ * recovered structurally by {@link FieldType}/{@link FieldEncoded} via `infer`.
+ */
+export type FieldInput = Schema.Top | Many2OneDecl<any, any> | One2ManyDecl<any, any>;
+/** The decoded (`Type`) value a declared field yields. */
+type FieldType<T> = T extends Many2OneDecl<infer A, infer _I> ? A | null : T extends One2ManyDecl<infer A, infer _I> ? ReadonlyArray<A> : T extends Schema.Top ? T["Type"] : never;
+/** The wire (`Encoded`) value a declared field maps from. */
+type FieldEncoded<T> = T extends Many2OneDecl<infer _A, infer I> ? I | false : T extends One2ManyDecl<infer _A, infer I> ? ReadonlyArray<I> : T extends Schema.Top ? T["Encoded"] : never;
+/** The decoded row type of a declaration `F` — always carries `id: number`. */
+export type RowType<F extends Record<string, FieldInput>> = {
+    readonly id: number;
+} & {
+    readonly [K in keyof F]: FieldType<F[K]>;
+};
+/** The wire row type of a declaration `F`. */
+export type RowEncoded<F extends Record<string, FieldInput>> = {
+    readonly id: number;
+} & {
+    readonly [K in keyof F]: FieldEncoded<F[K]>;
+};
+/**
+ * Build a {@link RecordSpec} from a model name and a field declaration. `id`
+ * (`Schema.Number`) is added automatically and always compiled into the
+ * `specification`, so every declared record and every relation subtree carries
+ * its id — the key downstream joins and re-reads rely on.
+ *
+ * ```ts
+ * const Company = defineRecord("res.company", { name: Schema.String });
+ * const Partner = defineRecord("res.partner", {
+ *   name: Schema.String,
+ *   company_id: Many2One(Company),
+ *   child_ids: One2Many(Partner_contact, { limit: 20 }),
+ * });
+ * ```
+ */
+export declare const defineRecord: <F extends Record<string, FieldInput>>(model: string, fields: F) => RecordSpec<RowType<F>, RowEncoded<F>>;
+export {};
+//# sourceMappingURL=recordModel.d.ts.map

package/dist/records/recordModel.d.ts.map

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