@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/openSearch.d.ts

@@ -0,0 +1,234 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.openSearch` (OpenSearch): 4 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"opensearch_aggregate_opensearch_aggregate_post">;
+ *
+ * Reference with examples: openSearch.md
+ */
+/* eslint-disable */
+
+/** `g8.api.openSearch.<member>` -> the operationId it calls. */
+export interface OpenSearchMembers {
+  opensearchAggregate: "opensearch_aggregate_opensearch_aggregate_post";
+  opensearchCount: "opensearch_count_opensearch_count_post";
+  opensearchResolve: "opensearch_resolve_opensearch_resolve_post";
+  opensearchSearch: "opensearch_search_opensearch_search_post";
+}
+
+/** Input and output of every `g8.api.openSearch` operation, keyed by operationId. */
+export interface OpenSearchOperations {
+  /**
+   * POST /opensearch/aggregate
+   * Opensearch Aggregate
+   * tier: write · scope: search:write
+   */
+  opensearch_aggregate_opensearch_aggregate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OpenSearchAggregateRequest;
+  };
+    output: ApiResponse_OpenSearchAggregateResponse_;
+  };
+  /**
+   * POST /opensearch/count
+   * Opensearch Count
+   * tier: write · scope: search:write
+   */
+  opensearch_count_opensearch_count_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OpenSearchCountRequest;
+  };
+    output: ApiResponse_OpenSearchCountResponse_;
+  };
+  /**
+   * POST /opensearch/resolve
+   * Opensearch Resolve
+   * tier: write · scope: search:write
+   */
+  opensearch_resolve_opensearch_resolve_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OpenSearchResolveRequest;
+  };
+    output: ApiResponse_OpenSearchResolveResponse_;
+  };
+  /**
+   * POST /opensearch/search
+   * Opensearch Search
+   * tier: write · scope: search:write
+   */
+  opensearch_search_opensearch_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OpenSearchSearchRequest;
+  };
+    output: ApiResponse_OpenSearchSearchResponse_;
+  };
+}
+
+// 16 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_OpenSearchAggregateResponse_ {
+  data: OpenSearchAggregateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_OpenSearchCountResponse_ {
+  data: OpenSearchCountResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_OpenSearchResolveResponse_ {
+  data: OpenSearchResolveResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_OpenSearchSearchResponse_ {
+  data: OpenSearchSearchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface OpenSearchAggGroup {
+  /** Metric values keyed by alias, e.g. {"count": 1247, "unique_domains": 1184}. */
+  agg?: Record<string, unknown>;
+  /** The group-by field values for this group, e.g. {"COMPANY_NAICS": "3311", "COMPANY_STATE": "OH"}. */
+  key?: Record<string, unknown>;
+}
+
+/**
+ * A single aggregate metric over the grouped rows.
+ *
+ * ``count`` needs no field (it is the bucket doc count). All other functions
+ * require ``field``. ``alias`` keys the value in each group's ``agg`` map;
+ * it defaults to ``function`` when omitted (so two same-function metrics must
+ * each carry a distinct ``alias``).
+ */
+export interface OpenSearchAggSpec {
+  /** Output key for this metric in each group's `agg` map. Defaults to `function`. */
+  alias?: string | null;
+  /** RAW UPPERCASE field the metric runs over. Required for every function except `count`. For unique-company counts use uniqExact on COMPANY_ID (the index is contact-grained). */
+  field?: string | null;
+  /** count=doc count per group; uniqExact=cardinality (HLL-approximate); sum/avg/min/max=numeric metric over `field`. */
+  function?: "count" | "uniqExact" | "sum" | "avg" | "min" | "max";
+}
+
+/**
+ * Generic, allowlist-bounded GROUP BY over a whitelisted mashup index.
+ *
+ * Translates to nested OpenSearch ``terms`` aggregations (one level per
+ * ``group_by`` field) with metric sub-aggregations. ``having`` / ``sort`` /
+ * ``limit`` are applied to the flattened groups server-side. Counts from
+ * ``terms`` buckets / ``cardinality`` are APPROXIMATE on a sharded index.
+ */
+export interface OpenSearchAggregateRequest {
+  /** Metrics to compute per group (max 10). Defaults to a single `count` when omitted. */
+  agg?: Array<OpenSearchAggSpec> | null;
+  /** Pre-aggregation equality filters, identical semantics to /opensearch/search. RAW UPPERCASE field names. */
+  filters?: Record<string, unknown>;
+  /** 1-3 RAW UPPERCASE keyword fields to group on (e.g. ["COMPANY_NAICS", "COMPANY_STATE"]). Must be keyword-type fields -- the canonical COMPANY_* firmographics are. Capped at 3 dimensions to bound cluster cost. ORDER HIGHEST-CARDINALITY FIRST: deeper dimensions get smaller per-level bucket caps (1000 / 100 / 20), so a low-cardinality field placed last keeps full fidelity while a high-cardinality field placed last may be truncated. */
+  group_by: Array<string>;
+  /** Post-aggregation group filter keyed by metric alias, e.g. {"count": {"gte": 50}}. Operators: eq, gte, lte, gt, lt. */
+  having?: Record<string, Record<string, number>> | null;
+  /** Logical index to aggregate. Maps to a whitelisted physical alias. */
+  index: "mashup_contacts" | "mashup_companies" | "hem2contact" | "ip2company";
+  /** Max number of groups returned (after having + sort). Hard-capped at 1000. */
+  limit?: number;
+  /** Sort the returned groups by a metric alias, e.g. [{"count": "desc"}]. Applied after `having`. */
+  sort?: Array<Record<string, string>> | null;
+}
+
+export interface OpenSearchAggregateResponse {
+  groups?: Array<OpenSearchAggGroup>;
+  index: string;
+  took_ms?: number;
+  total_groups?: number;
+}
+
+/**
+ * Exact-count request. Same ``index`` + ``filters`` shape as search; the
+ * page-oriented fields (fields/sort/limit/cursor) are intentionally absent
+ * because a count returns no rows.
+ */
+export interface OpenSearchCountRequest {
+  /** Field equality filters, identical semantics to /opensearch/search. Scalar -> term, list -> terms (OR). RAW UPPERCASE field names (e.g. COMPANY_INDUSTRY, COMPANY_NAICS, COMPANY_COUNTRY). */
+  filters?: Record<string, unknown>;
+  /** Logical index to count. Maps to a whitelisted physical alias. */
+  index: "mashup_contacts" | "mashup_companies" | "hem2contact" | "ip2company";
+}
+
+export interface OpenSearchCountResponse {
+  count?: number;
+  index: string;
+}
+
+export interface OpenSearchHit {
+  id: string;
+  score?: number | null;
+  sort?: Array<unknown> | null;
+  source?: Record<string, unknown>;
+}
+
+export interface OpenSearchResolveRequest {
+  /** Up to 500 input IDs (HEMs or IPs). */
+  ids: Array<string>;
+  /** Which resolver path to use. */
+  kind: "hem_to_contact" | "ip_to_company";
+}
+
+export interface OpenSearchResolveResponse {
+  kind: string;
+  matched?: number;
+  requested?: number;
+  results?: Record<string, string | null>;
+}
+
+export interface OpenSearchSearchRequest {
+  /** search_after token returned from a prior page. Pair with `sort`. */
+  cursor?: Array<unknown> | null;
+  /** Optional projection. If omitted, returns the full _source. Pass a list to reduce payload size when the LLM only needs a few columns. */
+  fields?: Array<string> | null;
+  /** Field equality filters. Scalar value -> term, list -> terms (OR). Use this to narrow by COMPANY_DOMAIN, COMPANY_INDUSTRY, hem, etc. Field names are the RAW index fields (UPPERCASE, e.g. COMPANY_INDUSTRY) -- not the friendly snake_case names used by /search. */
+  filters?: Record<string, unknown>;
+  /** Logical index to search. Maps to a whitelisted physical alias. */
+  index: "mashup_contacts" | "mashup_companies" | "hem2contact" | "ip2company";
+  /** Hard-capped at 200. */
+  limit?: number;
+  /** Optional sort, list of `{field: 'asc'|'desc'}`. Required if you intend to paginate via cursor. */
+  sort?: Array<Record<string, string>> | null;
+  /** Exact-count ceiling for the returned `total`. OMIT for the default behaviour (OpenSearch saturates `total` at 10000). Pass an integer ceiling 1-1000000 (e.g. 100000) to get an exact `total` up to that bound in the SAME round trip as the page. For a count with no page payload prefer POST /opensearch/count. Does NOT lift the from+size pagination depth -- use `cursor` (search_after) for that. (0 is rejected: it would mean 'disable tracking' in OpenSearch, which is what omitting it does.) */
+  track_total_hits?: number | null;
+}
+
+export interface OpenSearchSearchResponse {
+  cursor?: Array<unknown> | null;
+  hits?: Array<OpenSearchHit>;
+  index: string;
+  took_ms?: number;
+  total?: number;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/openSearch.md

@@ -0,0 +1,297 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.openSearch`: OpenSearch
+
+4 operations (4 write).
+
+No hand-written client covers this area. Call it through `g8.api.openSearch.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [openSearch.d.ts](openSearch.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`opensearchAggregate`](#op-opensearchaggregate) | `POST /api/v1/opensearch/aggregate` | write | `search:write` | Opensearch Aggregate |
+| [`opensearchCount`](#op-opensearchcount) | `POST /api/v1/opensearch/count` | write | `search:write` | Opensearch Count |
+| [`opensearchResolve`](#op-opensearchresolve) | `POST /api/v1/opensearch/resolve` | write | `search:write` | Opensearch Resolve |
+| [`opensearchSearch`](#op-opensearchsearch) | `POST /api/v1/opensearch/search` | write | `search:write` | Opensearch Search |
+
+---
+
+<a id="op-opensearchaggregate"></a>
+
+### `g8.api.openSearch.opensearchAggregate(input)`
+
+**Opensearch Aggregate**
+
+- HTTP: `POST /api/v1/opensearch/aggregate`
+- operationId: `opensearch_aggregate_opensearch_aggregate_post` (also callable as `g8.api.call("opensearch_aggregate_opensearch_aggregate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Generic, allowlist-bounded GROUP BY over a whitelisted mashup index.
+
+Translates ``group_by`` into nested OpenSearch ``terms`` aggregations with
+metric sub-aggs, then applies ``having`` / ``sort`` / ``limit`` to the
+flattened groups. This is the matrix-walk primitive for TAM design (e.g.
+count companies by NAICS x state x employee band in one call).
+
+Guardrails: group_by depth is capped at 3, per-level bucket size tapers by
+depth (``_AGG_TERMS_SIZE_BY_DEPTH``), the agg list is capped at 10, and
+returned groups at ``limit`` (<=1000). Counts from ``terms`` /
+``cardinality`` are APPROXIMATE on a sharded index. Since
+``mashup_companies``/``mashup_contacts`` share one contact-grained index,
+use ``uniqExact`` on ``COMPANY_ID`` for true unique-company counts. Mashup
+aggregations automatically apply the organization's deliverability policy.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OpenSearchAggregateRequest` | yes | Request body; fields below. |
+
+Body fields (`OpenSearchAggregateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.group_by` | `Array<string>` | yes | 1-3 RAW UPPERCASE keyword fields to group on (e.g. ["COMPANY_NAICS", "COMPANY_STATE"]). Must be keyword-type fields -- the canonical COMPANY_* firmographics are. Capped at 3 dimensions to bound cluster cost. ORDER HIGHEST-CARDINALITY FIRST: deeper dimensions get smaller per-level bucket caps (1000 / 100 / 20), so a low-cardinality field placed last keeps full fidelity while a high-cardinality fie… min items 1, max items 3 |
+| `body.index` | `"mashup_contacts" \| "mashup_companies" \| "hem2contact" \| "ip2company"` | yes | Logical index to aggregate. Maps to a whitelisted physical alias. |
+| `body.agg` | `Array<OpenSearchAggSpec> \| null` | no | Metrics to compute per group (max 10). Defaults to a single `count` when omitted. max items 10 |
+| `body.filters` | `Record<string, unknown>` | no | Pre-aggregation equality filters, identical semantics to /opensearch/search. RAW UPPERCASE field names. |
+| `body.having` | `Record<string, Record<string, number>> \| null` | no | Post-aggregation group filter keyed by metric alias, e.g. {"count": {"gte": 50}}. Operators: eq, gte, lte, gt, lt. |
+| `body.limit` | `integer` | no | Max number of groups returned (after having + sort). Hard-capped at 1000. default `100`, min 1, max 1000 |
+| `body.sort` | `Array<Record<string, string>> \| null` | no | Sort the returned groups by a metric alias, e.g. [{"count": "desc"}]. Applied after `having`. |
+
+**Returns** `ApiResponse_OpenSearchAggregateResponse_`: the envelope `{ data: OpenSearchAggregateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OpenSearchAggregateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `index` | `string` | yes |  |
+| `groups` | `Array<OpenSearchAggGroup>` | no | default `[]` |
+| `took_ms` | `integer` | no | default `0` |
+| `total_groups` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.openSearch.opensearchAggregate({ body: { group_by: ["example"], index: "mashup_contacts" } });
+```
+
+---
+
+<a id="op-opensearchcount"></a>
+
+### `g8.api.openSearch.opensearchCount(input)`
+
+**Opensearch Count**
+
+- HTTP: `POST /api/v1/opensearch/count`
+- operationId: `opensearch_count_opensearch_count_post` (also callable as `g8.api.call("opensearch_count_opensearch_count_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Exact match count for one of the whitelisted mashup indices.
+
+Same ``index`` + ``filters`` shape as ``/opensearch/search`` but returns
+only the count via the native OpenSearch ``_count`` API, so it is NOT
+capped at the 10000 ``track_total_hits`` ceiling that ``/search``'s
+``total`` saturates at. This is the right call for TAM cell-sizing.
+
+Note: ``mashup_companies`` and ``mashup_contacts`` are the same physical,
+contact-grained index — a count over ``mashup_companies`` counts contact
+rows, not unique companies. For a unique-company total use
+``/opensearch/aggregate`` with ``uniqExact`` on ``COMPANY_ID``. Mashup
+counts automatically apply the organization's deliverability policy.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OpenSearchCountRequest` | yes | Request body; fields below. |
+
+Body fields (`OpenSearchCountRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.index` | `"mashup_contacts" \| "mashup_companies" \| "hem2contact" \| "ip2company"` | yes | Logical index to count. Maps to a whitelisted physical alias. |
+| `body.filters` | `Record<string, unknown>` | no | Field equality filters, identical semantics to /opensearch/search. Scalar -> term, list -> terms (OR). RAW UPPERCASE field names (e.g. COMPANY_INDUSTRY, COMPANY_NAICS, COMPANY_COUNTRY). |
+
+**Returns** `ApiResponse_OpenSearchCountResponse_`: the envelope `{ data: OpenSearchCountResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OpenSearchCountResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `index` | `string` | yes |  |
+| `count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.openSearch.opensearchCount({ body: { index: "mashup_contacts" } });
+```
+
+---
+
+<a id="op-opensearchresolve"></a>
+
+### `g8.api.openSearch.opensearchResolve(input)`
+
+**Opensearch Resolve**
+
+- HTTP: `POST /api/v1/opensearch/resolve`
+- operationId: `opensearch_resolve_opensearch_resolve_post` (also callable as `g8.api.call("opensearch_resolve_opensearch_resolve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Bulk HEM -> CONTACT_ID or IP -> COMPANY_ID resolution.
+
+Backed by the existing ``MashupService`` which already batches the OpenSearch
+request in chunks of 10k. Returns a dense ``{input: matched_id | null}``
+mapping so the caller can iterate the inputs without re-querying for misses.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OpenSearchResolveRequest` | yes | Request body; fields below. |
+
+Body fields (`OpenSearchResolveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ids` | `Array<string>` | yes | Up to 500 input IDs (HEMs or IPs). min items 1, max items 500 |
+| `body.kind` | `"hem_to_contact" \| "ip_to_company"` | yes | Which resolver path to use. |
+
+**Returns** `ApiResponse_OpenSearchResolveResponse_`: the envelope `{ data: OpenSearchResolveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OpenSearchResolveResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `kind` | `string` | yes |  |
+| `matched` | `integer` | no | default `0` |
+| `requested` | `integer` | no | default `0` |
+| `results` | `Record<string, string \| null>` | no | default `{}` |
+
+**Example**
+
+```ts
+const result = await g8.api.openSearch.opensearchResolve({ body: { ids: ["id"], kind: "hem_to_contact" } });
+```
+
+---
+
+<a id="op-opensearchsearch"></a>
+
+### `g8.api.openSearch.opensearchSearch(input)`
+
+**Opensearch Search**
+
+- HTTP: `POST /api/v1/opensearch/search`
+- operationId: `opensearch_search_opensearch_search_post` (also callable as `g8.api.call("opensearch_search_opensearch_search_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Structured search across one of the whitelisted mashup OpenSearch indices.
+
+Use this when the LLM needs to look up enriched person / company records
+by attribute (domain, industry, country, hem). For the hot HEM-or-IP
+resolve path, prefer ``/opensearch/resolve`` — it's a single round trip
+and friendlier to cache. Contact/company mashup searches automatically
+apply the authenticated organization's deliverability protection policy.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OpenSearchSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`OpenSearchSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.index` | `"mashup_contacts" \| "mashup_companies" \| "hem2contact" \| "ip2company"` | yes | Logical index to search. Maps to a whitelisted physical alias. |
+| `body.cursor` | `Array<unknown> \| null` | no | search_after token returned from a prior page. Pair with `sort`. |
+| `body.fields` | `Array<string> \| null` | no | Optional projection. If omitted, returns the full _source. Pass a list to reduce payload size when the LLM only needs a few columns. |
+| `body.filters` | `Record<string, unknown>` | no | Field equality filters. Scalar value -> term, list -> terms (OR). Use this to narrow by COMPANY_DOMAIN, COMPANY_INDUSTRY, hem, etc. Field names are the RAW index fields (UPPERCASE, e.g. COMPANY_INDUSTRY) -- not the friendly snake_case names used by /search. |
+| `body.limit` | `integer` | no | Hard-capped at 200. default `50`, min 1, max 200 |
+| `body.sort` | `Array<Record<string, string>> \| null` | no | Optional sort, list of `{field: 'asc'\|'desc'}`. Required if you intend to paginate via cursor. |
+| `body.track_total_hits` | `integer \| null` | no | Exact-count ceiling for the returned `total`. OMIT for the default behaviour (OpenSearch saturates `total` at 10000). Pass an integer ceiling 1-1000000 (e.g. 100000) to get an exact `total` up to that bound in the SAME round trip as the page. For a count with no page payload prefer POST /opensearch/count. Does NOT lift the from+size pagination depth -- use `cursor` (search_after) for that. (0 is… min 1, max 1000000 |
+
+**Returns** `ApiResponse_OpenSearchSearchResponse_`: the envelope `{ data: OpenSearchSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OpenSearchSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `index` | `string` | yes |  |
+| `cursor` | `Array<unknown> \| null` | no |  |
+| `hits` | `Array<OpenSearchHit>` | no | default `[]` |
+| `took_ms` | `integer` | no | default `0` |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.openSearch.opensearchSearch({ body: { index: "mashup_contacts" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-opensearchagggroup"></a>
+
+### `OpenSearchAggGroup`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `agg` | `Record<string, unknown>` | no | Metric values keyed by alias, e.g. {"count": 1247, "unique_domains": 1184}. |
+| `key` | `Record<string, unknown>` | no | The group-by field values for this group, e.g. {"COMPANY_NAICS": "3311", "COMPANY_STATE": "OH"}. |
+
+<a id="type-opensearchaggspec"></a>
+
+### `OpenSearchAggSpec`
+
+A single aggregate metric over the grouped rows. ``count`` needs no field (it is the bucket doc count). All other functions require ``field``. ``alias`` keys the value in each group's ``agg`` map; it defaults to ``function`` when omitted (so two same-function metrics must each carry a distinct ``alias``).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `alias` | `string \| null` | no | Output key for this metric in each group's `agg` map. Defaults to `function`. |
+| `field` | `string \| null` | no | RAW UPPERCASE field the metric runs over. Required for every function except `count`. For unique-company counts use uniqExact on COMPANY_ID (the index is contact-grained). |
+| `function` | `"count" \| "uniqExact" \| "sum" \| "avg" \| "min" \| "max"` | no | count=doc count per group; uniqExact=cardinality (HLL-approximate); sum/avg/min/max=numeric metric over `field`. default `"count"` |
+
+<a id="type-opensearchhit"></a>
+
+### `OpenSearchHit`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `score` | `number \| null` | no |  |
+| `sort` | `Array<unknown> \| null` | no |  |
+| `source` | `Record<string, unknown>` | no | default `{}` |