@oxy-hq/sdk 2.12.0 → 2.16.0

package/dist/{function-context-D8eyZuw_.d.mts → function-context-BNpL5bFb.d.mts}

@@ -3,12 +3,27 @@
 /**
  * The request passed as the first argument to a function's default export.
  *
- * The host hands the isolate the raw request body as a string (see
- * `req_json` in `runtime.rs`); parse it yourself, e.g.
- * `JSON.parse(req.body || "{}")`. This is intentionally *not* a full Web
- * `Request` — there is no `.json()` / headers object in v1.
+ * The host builds this as `{ method, headers, body }` (`req_json` in
+ * `runtime.rs`). It is intentionally *not* a full Web `Request`: the body
+ * arrives as a string, so parse it yourself — `JSON.parse(req.body || "{}")`
+ * — and there is no `.json()`, no `url`, and no `Headers` object.
  */
 interface OxyFunctionRequest {
+  /**
+   * HTTP method of the triggering request, upper-case (`"POST"`, `"GET"`).
+   * A scheduled or Airway run has no real request and reports `"POST"`.
+   */
+  method: string;
+  /**
+   * The headers the function is allowed to see, keyed by **lower-case** name.
+   *
+   * The host drops everything that is not on its passthrough list and not
+   * `x-*`, plus its own `x-oxy-*` prefix and a blocked list; a header sent
+   * twice collapses to its **first** value, and one whose bytes are not UTF-8
+   * is dropped rather than lossily decoded. A scheduled or Airway run has no
+   * headers, so this is `{}` — never absent.
+   */
+  headers: Record<string, string>;
   /** Raw request body as received (JSON string for a JSON POST). */
   body: string;
 }
@@ -191,6 +206,12 @@ type OxyFetchInit = RequestInit & {
  * `query` does not, because that allowlist is about modifying a project's
  * warehouse, and a `postgres_managed` database resolves the read-only analyst
  * for every caller regardless.
+ *
+ * **Shape: the customer's warehouse — read it, don't write it.** Writes to a
+ * customer warehouse (anything but `airhouse` / `airhouse_managed`) are refused
+ * unless the function names the database in `customerWarehouseWrites` with a
+ * reason. Facts your app records go to `ctx.airhouse`, records it edits to
+ * `ctx.oltp`, files to `ctx.storage`.
  */
 interface OxyWarehouseApi {
   /**
@@ -206,11 +227,21 @@ interface OxyWarehouseApi {
   }>;
   insert(database: string, table: string, rows: OxyFunctionRow[]): Promise<unknown>;
   exec(database: string, sql: string): Promise<unknown>;
+  /**
+   * Insert rows, updating any whose `conflictColumns` already exist.
+   *
+   * Compiles to `INSERT … ON CONFLICT … DO UPDATE`, which only Postgres and
+   * DuckDB parse, and which needs a primary key or unique constraint on
+   * `conflictColumns`. On any other warehouse — ClickHouse, Snowflake, BigQuery,
+   * MySQL — the call is refused by name before anything is sent; use `exec` with
+   * that warehouse's own upsert statement instead. Airhouse (DuckLake) tables
+   * carry no such constraint, so there the engine refuses it.
+   */
   upsert(database: string, table: string, rows: OxyFunctionRow[], conflictColumns: string[]): Promise<unknown>;
 }
 /**
- * The handle `ctx.tx` passes to your callback — a pinned connection with an
- * open transaction.
+ * The handle `ctx.tx` and `ctx.oltp.tx` pass to your callback — a pinned
+ * connection with an open transaction.
  *
  * Both methods take **bound parameters** (`$1`, `$2`, …). Never build SQL by
  * concatenating request data: `ctx.warehouse.exec` takes a bare string, but a
@@ -227,6 +258,11 @@ interface OxyTransaction {
   exec(sql: string, params?: unknown[]): Promise<number>;
 }
 /**
+ * **Shape: records your app edits** — current state that needs constraints or
+ * transactions: a booking, a shift assignment, a template, a count. What
+ * happened (history that will not change) goes to `ctx.airhouse`; bytes go to
+ * `ctx.storage`.
+ *
  * `ctx.oltp` — read and WRITE the app's OWN per-org OLTP schema (`app_<writer>`)
  * on the managed Postgres tenant, and nothing else.
  *
@@ -253,8 +289,9 @@ interface OxyTransaction {
  * handshake, and a wake-up if the compute was idle) and its own transaction, so
  * a per-row loop pays that per row. Prefer one statement over many — a
  * multi-row `INSERT`, an `INSERT … SELECT`, or `INSERT … RETURNING` to avoid a
- * follow-up read — and reach for `ctx.oltp` a handful of times per request, not
- * in a hot loop.
+ * follow-up read — or run several inside one `ctx.oltp.tx`, which holds a single
+ * connection. Reach for `ctx.oltp` a handful of times per request, not in a hot
+ * loop.
  *
  * ```ts
  * const [row] = await ctx.oltp.query(
@@ -268,11 +305,147 @@ interface OxyOltpApi {
   query(sql: string, params?: unknown[]): Promise<OxyFunctionRow[]>;
   /** Run a statement for its effect; resolves to the number of rows affected. */
   exec(sql: string, params?: unknown[]): Promise<number>;
+  /**
+   * Run several statements as one transaction on one connection: commits when
+   * `fn` resolves, rolls back when it throws, and rethrows your error. The same
+   * handle and rules as `ctx.tx` — let a failed statement's error propagate —
+   * without naming a database: the app's own store is implicit.
+   *
+   * ```ts
+   * await ctx.oltp.tx(async (tx) => {
+   *   await tx.exec("UPDATE shifts SET status = 'closed' WHERE id = $1", [shiftId]);
+   *   await tx.exec("INSERT INTO shift_notes (shift_id, body) VALUES ($1, $2)", [shiftId, note]);
+   * });
+   * ```
+   */
+  tx<T>(fn: (tx: OxyTransaction) => Promise<T> | T): Promise<T>;
+}
+/**
+ * **Shape: facts — what happened, which will not change**: an order, a completed
+ * checklist, a delivery, a reading. `ctx.airhouse` appends them to your app's own
+ * schema in the workspace's Airhouse, where the analytics agent, semantic views
+ * and other apps read them as history. Records your app edits in place belong in
+ * `ctx.oltp`; files in `ctx.storage`.
+ *
+ * Gated by the fail-closed `airhouse` manifest capability (`"airhouse": {
+ * "enabled": true }`), a pure gate: the schema is `app_<writer>`, derived from
+ * the app's slug (`store-ops` → `app_store_ops`) and exposed as `schema`. Writes
+ * run **as the app**, whoever invoked the function — a schedule, a webhook and a
+ * click write the same way.
+ *
+ * Every statement is checked before it is sent. Reads may name any schema;
+ * writes must target `<schema>.<table>`; `exec` runs no DDL — declare tables in
+ * `airhouseMigrations` files, which run once at publish. One statement per call.
+ *
+ * Airhouse is DuckLake: **no primary keys, UNIQUE, indexes or foreign keys**, and
+ * no bound parameters. Give every fact the id its source assigned and a
+ * `recorded_at`, append a correction as a new fact instead of updating, and keep
+ * one row per id when reading — a retried function can append twice:
+ *
+ * ```ts
+ * await ctx.airhouse.append("checklist_completions", [
+ *   { completion_id: id, store_guid: store, recorded_at: new Date().toISOString() },
+ * ]);
+ *
+ * const { rows } = await ctx.airhouse.query(`
+ *   SELECT * FROM ${ctx.airhouse.schema}.checklist_completions
+ *   QUALIFY row_number() OVER (PARTITION BY completion_id ORDER BY recorded_at DESC) = 1
+ * `);
+ * ```
+ */
+interface OxyAirhouseApi {
+  /** `app_<writer>` when the function declares the capability, else `null`. */
+  readonly schema: string | null;
+  /** Read, from any schema. Capped like `ctx.warehouse.query`; `truncated` says the cap cut rows. */
+  query(sql: string): Promise<{
+    rows: OxyFunctionRow[];
+    truncated: boolean;
+  }>;
+  /**
+   * Append rows to `<schema>.<table>`. Pass the bare table name; every row must
+   * carry the first row's columns. Values are sent as literals, safely quoted.
+   * Resolves to the number of rows sent.
+   */
+  append(table: string, rows: OxyFunctionRow[]): Promise<number>;
+  /**
+   * One write statement against your own schema: a `DELETE` for retention or
+   * erasure, an `INSERT … SELECT` deriving facts from other facts. Nothing is
+   * bound, so never interpolate request data here — that is what `append` is for.
+   */
+  exec(sql: string): Promise<void>;
 }
-/** `ctx.secrets` — write app-scoped secrets (gated by the `secrets.write` capability). */
+/**
+ * `ctx.secrets` — write app-scoped secrets (gated by the `secrets.write` capability).
+ *
+ * **Credentials only — not state.** A secret is for a value you authenticate
+ * with, like a rotated token. A cursor, a counter or a JSON blob that changes
+ * between runs is a record: keep it in `ctx.oltp`.
+ */
 interface OxySecretsApi {
   set(key: string, value: string): Promise<void>;
 }
+/**
+ * `ctx.crypto` — HMAC signing and verification, and a constant-time compare.
+ * **Synchronous**: pure CPU inside the isolate, so these skip the host-call
+ * channel and there is nothing to `await`. Mirrors `crypto` in `__buildCtx`
+ * (`runtime.rs`); the three members here are the three the host binds.
+ *
+ * `key` and `data` are read as UTF-8 — every webhook scheme in the wild signs a
+ * UTF-8 base string with a UTF-8 secret (GitHub the body, Slack `v0:ts:body`,
+ * Stripe `ts.body`) — so there is deliberately no per-argument encoding knob.
+ *
+ * Who controls an input decides what its absence does. An unset or empty `key`,
+ * or an unknown `algorithm` / `encoding`, is the author's mistake and **throws**.
+ * A `signature` that is absent or will not decode is the caller's, and returns
+ * **`false`** — throwing would turn a forged request into a 500. Both sides of
+ * `timingSafeEqual` are symmetric, so an absent or empty side is `false` and
+ * never a throw: with the secret unset, every request is rejected.
+ */
+interface OxyCryptoApi {
+  /**
+   * The digest of `data` under `key`, as a string in `encoding`. For signing an
+   * **outbound** request; `verifyHmac` is the inverse direction.
+   */
+  hmac(input: OxyHmacInput): string;
+  /**
+   * Whether `signature` is the digest of `data` under `key`, compared in
+   * constant time. Strip the provider's prefix first (`sha256=`, `v0=`) and
+   * pass the bare digest — prefix formats are per-provider. A header the caller
+   * omitted can be passed as-is: absent is `false`, not a throw.
+   */
+  verifyHmac(input: OxyVerifyHmacInput): boolean;
+  /**
+   * Constant-time equality for a plain shared secret where there is no HMAC.
+   * Use it, not `===`, for any secret comparison: `===` short-circuits at the
+   * first differing byte and leaks the secret one byte at a time to anyone who
+   * can time the endpoint. `false` when either side is absent or empty.
+   */
+  timingSafeEqual(a: string | null | undefined, b: string | null | undefined): boolean;
+}
+/** The inputs `ctx.crypto.hmac` and `ctx.crypto.verifyHmac` share. */
+interface OxyHmacInput {
+  /** `"sha256"` (default) or `"sha512"`. Anything else throws. */
+  algorithm?: "sha256" | "sha512";
+  /**
+   * The secret, from configuration (`ctx.env.…`), never from the request.
+   * Required and non-empty: an absent one throws rather than signing with `""`
+   * or the literal `"undefined"` — keys an attacker guesses as easily as you do.
+   */
+  key: string;
+  /** The base string to sign — for a webhook, the body or `v0:{ts}:{body}`. */
+  data: string;
+  /** How the digest is written (`hmac`) or read (`verifyHmac`): `"hex"` (default) or `"base64"`. */
+  encoding?: "hex" | "base64";
+}
+/** `ctx.crypto.verifyHmac`'s input: {@link OxyHmacInput} plus the signature to check. */
+interface OxyVerifyHmacInput extends OxyHmacInput {
+  /**
+   * The bare digest the caller sent, provider prefix (`sha256=`, `v0=`) already
+   * stripped. Attacker-controlled, so a header the caller omitted may be passed
+   * as-is: absent, or not decodable in `encoding`, is `false`, never a throw.
+   */
+  signature: string | null | undefined;
+}
 /** `ctx.semantic` — airlayer-compiled semantic queries (inherits the pre-agg fast path). */
 interface OxySemanticApi {
   /**
@@ -544,7 +717,10 @@ interface OxyStorageApi {
   delete(keyOrKeys: string | string[]): Promise<{
     deleted: number;
   }>;
-  /** Server-side copy within the app's silo (requires `storage.write`). */
+  /**
+   * Server-side copy within the app's silo (requires `storage.read` **and**
+   * `storage.write`: it reads the source and writes the destination).
+   */
   copy(fromKey: string, toPathname: string, opts?: {
     allowOverwrite?: boolean;
   }): Promise<StoragePutResult>;
@@ -589,7 +765,8 @@ interface OxyOrgAssignment {
 /**
  * The data-plane context passed as the second argument to a function's default
  * export. Mirrors the host-assembled `ctx` (`__buildCtx` in `runtime.rs`);
- * every member is a host-provided async function bridged to a Rust backend.
+ * every member is a host-provided async function bridged to a Rust backend,
+ * except `crypto`, which is synchronous (pure CPU inside the isolate).
  */
 interface OxyFunctionContext {
   /** Invoking user (route) or system identity (schedule/airway). */
@@ -655,8 +832,22 @@ interface OxyFunctionContext {
   env: Record<string, string>;
   /** Structured per-invocation logging (captured + surfaced with the response). */
   log(...args: unknown[]): void;
-  /** Read-only SQL (SELECT/WITH only), function-scoped row cap. Resolves to the rows. */
-  query(sql: string): Promise<OxyFunctionRow[]>;
+  /**
+   * HMAC sign / verify and a constant-time compare. Synchronous — no `await`.
+   * See {@link OxyCryptoApi}.
+   */
+  crypto: OxyCryptoApi;
+  /**
+   * Read-only SQL (`SELECT` / `WITH` only) against the app's default database,
+   * capped at the function row limit. Resolves to `{ rows, truncated }` — the
+   * shape the host sends (`host.rs` `query`), the same as `ctx.warehouse.query`;
+   * `truncated` says the cap cut rows. Destructure it:
+   * `const { rows } = await ctx.query(sql)`.
+   */
+  query(sql: string): Promise<{
+    rows: OxyFunctionRow[];
+    truncated: boolean;
+  }>;
   /** Read-only SQL with a higher row cap, yielded to the caller in batches. */
   queryStream(sql: string, opts?: {
     batchSize?: number;
@@ -675,7 +866,11 @@ interface OxyFunctionContext {
    *
    * `database` must be in this function's manifest `destinations` — a
    * transaction is a write, and the same fail-closed allowlist applies. Postgres
-   * only; other backends reject `ctx.tx` rather than faking it.
+   * only; other backends reject `ctx.tx` rather than faking it. A customer
+   * warehouse is refused unless named in `customerWarehouseWrites`; for the app's
+   * own OLTP store use `ctx.oltp.tx`, which needs no destination. A transaction
+   * counts as a write even when your callback only reads — `begin` cannot know —
+   * so for reads alone use `ctx.warehouse.query`.
    *
    * **Do not catch a failed statement and return normally.** A statement the
    * server rejects aborts the whole transaction, and `COMMIT` on an aborted
@@ -701,20 +896,28 @@ interface OxyFunctionContext {
    */
   tx<T>(database: string, fn: (tx: OxyTransaction) => Promise<T> | T): Promise<T>;
   /**
-   * Read/write the app's OWN per-org OLTP schema (derived from its slug). The
-   * write half `ctx.warehouse` cannot give an app on a managed database. Gated
-   * by the fail-closed `oltp` manifest capability (`{ enabled: true }`). See
-   * {@link OxyOltpApi}.
+   * **Records your app edits.** Read/write the app's OWN per-org OLTP schema
+   * (derived from its slug), with `ctx.oltp.tx` for several statements at once.
+   * Gated by the fail-closed `oltp` manifest capability (`{ enabled: true }`).
+   * See {@link OxyOltpApi}.
    */
   oltp: OxyOltpApi;
+  /**
+   * **Facts: what happened.** Append-only history in the app's own Airhouse
+   * schema, written as the app. Gated by the fail-closed `airhouse` manifest
+   * capability (`{ enabled: true }`). See {@link OxyAirhouseApi}.
+   */
+  airhouse: OxyAirhouseApi;
+  /** Credentials the app rotates — not a state store. See {@link OxySecretsApi}. */
   secrets: OxySecretsApi;
   semantic: OxySemanticApi;
   airway: OxyAirwayApi;
   email: OxyEmailApi;
+  /** **Files: bytes.** The app's private storage silo. See {@link OxyStorageApi}. */
   storage: OxyStorageApi;
 }
 /** Signature of a function's default export: `export default async (req, ctx) => Response`. */
 type OxyFunctionHandler = (req: OxyFunctionRequest, ctx: OxyFunctionContext) => Promise<Response> | Response;
 //#endregion
-export { StorageDownloadUrl as C, StoragePutResult as D, StoragePutOptions as E, StorageUploadUrl as O, OxyWarehouseApi as S, StorageObject as T, OxyReach as _, OxyEmailApi as a, OxyStorageApi as b, OxyFunctionHandler as c, OxyFunctionUser as d, OxyIdentityKind as f, OxyOrgTeam as g, OxyOrgPlace as h, OxyAirwayApi as i, StorageUploadUrlInput as k, OxyFunctionRequest as l, OxyOrgAssignment as m, EmailSendInput as n, OxyFetchResult as o, OxyOltpApi as p, EmailSendResult as r, OxyFunctionContext as s, EmailAttachment as t, OxyFunctionRow as u, OxySecretsApi as v, StorageListPage as w, OxyTransaction as x, OxySemanticApi as y };
-//# sourceMappingURL=function-context-D8eyZuw_.d.mts.map
+export { StoragePutOptions as A, OxyStorageApi as C, StorageDownloadUrl as D, OxyWarehouseApi as E, StorageUploadUrl as M, StorageUploadUrlInput as N, StorageListPage as O, OxySemanticApi as S, OxyVerifyHmacInput as T, OxyOrgAssignment as _, OxyAirwayApi as a, OxyReach as b, OxyFetchResult as c, OxyFunctionRequest as d, OxyFunctionRow as f, OxyOltpApi as g, OxyIdentityKind as h, OxyAirhouseApi as i, StoragePutResult as j, StorageObject as k, OxyFunctionContext as l, OxyHmacInput as m, EmailSendInput as n, OxyCryptoApi as o, OxyFunctionUser as p, EmailSendResult as r, OxyEmailApi as s, EmailAttachment as t, OxyFunctionHandler as u, OxyOrgPlace as v, OxyTransaction as w, OxySecretsApi as x, OxyOrgTeam as y };
+//# sourceMappingURL=function-context-BNpL5bFb.d.mts.map

package/dist/function-context-BNpL5bFb.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-context-BNpL5bFb.d.mts","names":[],"sources":["../src/custom-app/function-context.ts"],"mappings":"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"}

package/dist/index.cjs

@@ -1,8 +1,9 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_react = require('./react-DcT-mUPj.cjs');
+const require_rolldown_runtime = require('./rolldown-runtime-KC0qvQup.cjs');
+const require_react = require('./react-Dvkv2deI.cjs');
 let react = require("react");
-react = require_react.__toESM(react, 1);
+react = require_rolldown_runtime.__toESM(react, 1);
 
 //#region src/anomalies.ts
 /** Which buckets a write may touch when the caller didn't say. Live statuses
@@ -318,7 +319,7 @@ function useMetricTreeEndpoint(key, run, enabled) {
 	const [data, setData] = react.useState(null);
 	const [loading, setLoading] = react.useState(enabled && key !== null);
 	const [error, setError] = react.useState(null);
-	const [_nonce, setNonce] = react.useState(0);
+	const [nonce, setNonce] = react.useState(0);
 	const runRef = react.useRef(run);
 	runRef.current = run;
 	react.useEffect(() => {
@@ -336,15 +337,18 @@ function useMetricTreeEndpoint(key, run, enabled) {
 			setLoading(false);
 		}).catch((err) => {
 			if (cancelled) return;
-			if (err instanceof DOMException && err.name === "AbortError") return;
-			setError(err instanceof Error ? err : new Error(String(err)));
+			setError(require_react.asReportableError(err));
 			setLoading(false);
 		});
 		return () => {
 			cancelled = true;
 			ctrl.abort();
 		};
-	}, [key, enabled]);
+	}, [
+		key,
+		enabled,
+		nonce
+	]);
 	return {
 		data,
 		loading,
@@ -563,7 +567,7 @@ function useWorldModelGraph(opts = {}) {
 	const [data, setData] = react.useState(null);
 	const [loading, setLoading] = react.useState(enabled && !!projectId);
 	const [error, setError] = react.useState(null);
-	const [_nonce, setNonce] = react.useState(0);
+	const [nonce, setNonce] = react.useState(0);
 	react.useEffect(() => {
 		if (!enabled || !projectId) {
 			setLoading(false);
@@ -585,8 +589,7 @@ function useWorldModelGraph(opts = {}) {
 			setLoading(false);
 		}).catch((err) => {
 			if (cancelled) return;
-			if (err instanceof DOMException && err.name === "AbortError") return;
-			setError(err instanceof Error ? err : new Error(String(err)));
+			setError(require_react.asReportableError(err));
 			setLoading(false);
 		});
 		return () => {
@@ -596,7 +599,8 @@ function useWorldModelGraph(opts = {}) {
 	}, [
 		enabled,
 		projectId,
-		fetcher
+		fetcher,
+		nonce
 	]);
 	return {
 		data,
@@ -617,7 +621,7 @@ function useWorldModelInstances(entityId, opts = {}) {
 	const [data, setData] = react.useState(null);
 	const [loading, setLoading] = react.useState(enabled && !!projectId && !!entityId);
 	const [error, setError] = react.useState(null);
-	const [_nonce, setNonce] = react.useState(0);
+	const [nonce, setNonce] = react.useState(0);
 	react.useEffect(() => {
 		if (!enabled || !projectId || !entityId) {
 			setLoading(false);
@@ -646,8 +650,7 @@ function useWorldModelInstances(entityId, opts = {}) {
 			setLoading(false);
 		}).catch((err) => {
 			if (cancelled) return;
-			if (err instanceof DOMException && err.name === "AbortError") return;
-			setError(err instanceof Error ? err : new Error(String(err)));
+			setError(require_react.asReportableError(err));
 			setLoading(false);
 		});
 		return () => {
@@ -662,7 +665,8 @@ function useWorldModelInstances(entityId, opts = {}) {
 		limit,
 		fetcher,
 		scope,
-		appId
+		appId,
+		nonce
 	]);
 	return {
 		data,
@@ -740,8 +744,7 @@ function useMeasureBreakdown(entityId, keyValue, measure) {
 			if (!cancelled) setLoading(false);
 		}).catch((err) => {
 			if (cancelled) return;
-			if (err instanceof DOMException && err.name === "AbortError") return;
-			setError(err instanceof Error ? err : new Error(String(err)));
+			setError(require_react.asReportableError(err));
 			setLoading(false);
 		});
 		return () => {
@@ -1086,6 +1089,66 @@ var MetricTreeClient = class {
 	}
 };
 
+//#endregion
+//#region src/peerCohort.ts
+/**
+* Client for the `/semantic/cohort` endpoint. Surfaces airlayer's peer-cohort
+* benchmarking — comparing an entity's subjects against their declared peers
+* on a measure, with exclusions explained rather than silently dropped.
+*
+* Construction is internal to {@link OxyClient} — call `client.peerCohort`
+* to access an instance rather than building one yourself.
+*
+* @example
+* ```typescript
+* const client = await OxyClient.create({ projectId: "...", apiKey: "..." });
+* const result = await client.peerCohort.resolve({
+*   entity: "restaurant_id",
+*   measure: "orders.net_revenue",
+*   time_dimension: "orders.order_date",
+*   period: ["2025-09-01", "2025-09-30"],
+* });
+* for (const excluded of result.excluded) {
+*   console.warn(excluded.key, excluded.reason);
+* }
+* ```
+*/
+var PeerCohortClient = class {
+	constructor(config, request) {
+		this.config = config;
+		this.request = request;
+	}
+	path(suffix) {
+		return `/${this.config.projectId}${suffix}`;
+	}
+	buildQuery(extra = {}) {
+		const params = { ...extra };
+		if (this.config.branch) params.branch = this.config.branch;
+		const qs = new URLSearchParams(params).toString();
+		return qs ? `?${qs}` : "";
+	}
+	/**
+	* Resolve a subject's peer cohort and every peer's comparison against it.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.peerCohort.resolve({
+	*   entity: "restaurant_id",
+	*   measure: "orders.net_revenue",
+	*   time_dimension: "orders.order_date",
+	*   period: ["2025-09-01", "2025-09-30"],
+	* });
+	* ```
+	*/
+	async resolve(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/semantic/cohort${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
+		});
+	}
+};
+
 //#endregion
 exports.AnomaliesClient = AnomaliesClient;
 exports.MetricTreeClient = MetricTreeClient;
@@ -1093,6 +1156,7 @@ exports.OxyAnswer = require_react.OxyAnswer;
 exports.OxyApiError = require_react.OxyApiError;
 exports.OxyAppProvider = require_react.OxyAppProvider;
 exports.OxyChat = require_react.OxyChat;
+exports.PeerCohortClient = PeerCohortClient;
 exports.WorldModelScopeUnsupportedError = WorldModelScopeUnsupportedError;
 exports._resetCustomAppManifestCacheForTest = require_react._resetCustomAppManifestCacheForTest;
 exports.apiErrorFromResponse = require_react.apiErrorFromResponse;