@signa-so/sdk 0.4.0 → 0.7.0

package/dist/types.d.ts

@@ -13,7 +13,10 @@ export interface AttorneyStats {
     cancelled_count: number | null;
     pending_count: number | null;
     abandoned_count: number | null;
+    /** @deprecated Use `grant_rate` — same value. `registration_rate` is a misnomer (share of concluded prosecutions ever granted, not share currently registered). */
     registration_rate: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate: number | null;
     abandonment_rate: number | null;
     avg_prosecution_days: number | null;
     jurisdiction_count: number | null;
@@ -29,33 +32,24 @@ export interface OwnerStats {
     cancelled_count: number | null;
     pending_count: number | null;
     abandoned_count: number | null;
+    /** @deprecated Use `grant_rate` — same value. `registration_rate` is a misnomer (share of concluded prosecutions ever granted, not share currently registered). */
     registration_rate: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate: number | null;
     abandonment_rate: number | null;
     jurisdiction_count: number | null;
     earliest_filing: string | null;
     latest_filing: string | null;
     computed_at: string | null;
 }
-/** Stats object shape returned by ?include=stats on firm detail. */
-export interface FirmStats {
-    trademark_count: number | null;
-    registered_count: number | null;
-    expired_count: number | null;
-    cancelled_count: number | null;
-    pending_count: number | null;
-    abandoned_count: number | null;
-    registration_rate: number | null;
-    abandonment_rate: number | null;
-    avg_prosecution_days: number | null;
-    jurisdiction_count: number | null;
-    earliest_filing: string | null;
-    latest_filing: string | null;
-    computed_at: string | null;
-}
 /** Full owner detail (retrieve response). */
 export type Owner = components['schemas']['OwnerResponse'] & {
     trademark_count?: number | null;
+    active_count?: number | null;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate?: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate?: number | null;
     latest_filing?: string | null;
     /** Resolved-entity id this owner belongs to (the derived `ent_<owner-uuid>`
      *  singleton when unlinked). Always present. */
@@ -96,10 +90,68 @@ export type Owner = components['schemas']['OwnerResponse'] & {
     };
     stats?: OwnerStats;
 };
+/** Composed live portfolio analytics report for an owner, attorney, firm, or entity. */
+export interface AnalyticsReport {
+    object: 'analytics_report';
+    subject: {
+        id: string;
+        object: 'owner' | 'attorney' | 'firm' | 'entity';
+        name: string;
+    };
+    portfolio: {
+        mark_count: number;
+        active_count: number;
+        dead_count: number;
+        status_distribution: Record<string, number>;
+        class_distribution: Record<string, number>;
+        jurisdiction_spread: Record<string, number>;
+        filing_trend: Record<string, number>;
+    };
+    litigation: {
+        subject: {
+            owner_id: string | null;
+            entity_id: string | null;
+        };
+        proceedings_total: number;
+        as_challenger: {
+            total: number;
+            by_type: Record<string, number>;
+            outcomes: Record<string, number>;
+            decided: number;
+            win_rate: number | null;
+            avg_duration_days: number | null;
+        };
+        as_defendant: {
+            total: number;
+            by_type: Record<string, number>;
+            outcomes: Record<string, number>;
+            decided: number;
+            win_rate: number | null;
+            avg_duration_days: number | null;
+        };
+    } | null;
+    transactions: {
+        transaction_count: number;
+        by_type: Record<string, number>;
+        unreleased_security_interests: number;
+        marks_with_liens: number;
+        acquired_count: number;
+        divested_count: number;
+        first_transaction_date: string | null;
+        last_transaction_date: string | null;
+    } | null;
+    generated_at: string;
+    /** Per-request id echoed at the top level of the response body (`AnalyticsReportResponse` in the OpenAPI spec). */
+    request_id: string;
+}
 /** Compact owner in list responses. */
 export type OwnerSummary = components['schemas']['OwnerSummary'] & {
     trademark_count?: number | null;
+    active_count?: number | null;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate?: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate?: number | null;
     latest_filing?: string | null;
     entity_id?: string;
     entity_id_type?: 'resolved' | 'derived';
@@ -111,7 +163,11 @@ export type Attorney = components['schemas']['AttorneyResponse'] & {
     phone?: string | null;
     address?: unknown | null;
     trademark_count?: number | null;
+    active_count?: number | null;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate?: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate?: number | null;
     latest_filing?: string | null;
     recent_trademarks?: Array<Record<string, unknown>>;
     recent_trademarks_has_more?: boolean;
@@ -121,7 +177,11 @@ export type Attorney = components['schemas']['AttorneyResponse'] & {
 export type AttorneySummary = components['schemas']['AttorneySummary'] & {
     firm_id?: string | null;
     trademark_count?: number | null;
+    active_count?: number | null;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate?: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate?: number | null;
     latest_filing?: string | null;
 };
 /** Full firm detail (retrieve response). */
@@ -132,11 +192,14 @@ export interface Firm {
     canonical_name: string;
     attorney_count: number;
     trademark_count: number;
+    active_count: number;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate: number | null;
     latest_filing: string | null;
     created_at: string;
     updated_at: string;
-    stats?: FirmStats;
     attorneys?: Array<{
         id: string;
         object: 'attorney';
@@ -157,7 +220,11 @@ export interface FirmSummary {
     canonical_name: string;
     attorney_count: number;
     trademark_count: number;
+    active_count: number;
+    /** @deprecated Use `grant_rate` — same value; `registration_rate` is a misnomer. */
     registration_rate: number | null;
+    /** Share of concluded prosecutions that were ever granted. Same value as the deprecated `registration_rate`. */
+    grant_rate: number | null;
     latest_filing: string | null;
     created_at: string;
 }
@@ -174,17 +241,17 @@ export interface EntityCompany {
     verified_at?: string | null;
     verified_by?: string | null;
 }
-/** Whitelisted per-member link evidence on an entity-detail member. */
+/** Public per-member link provenance on an entity-detail member. */
 export interface EntityMemberLink {
-    signal: string;
-    tier: string | null;
-    confidence: number | null;
-    decided_by: string;
-    /** token-overlap count from the name guard, when present. */
-    guard_overlap?: number;
-    /** matched canonical IR numbers (madrid_ir tier), when present. */
+    /** How this member was linked into the entity (stable public vocabulary). */
+    method: 'international_registration' | 'shared_identifier' | 'public_company' | 'portfolio_overlap' | 'manual_review' | 'other';
+    /** Coarse confidence band; null when not scored. */
+    match_strength: 'high' | 'medium' | 'low' | null;
+    /** Whether the link was confirmed by adjudication/manual review. */
+    reviewed: boolean;
+    /** matched canonical IR numbers (international_registration), when present. */
     matched_irs?: string[];
-    /** matched office-identifier values (office_identifier tier), when present. */
+    /** matched office-identifier values (shared_identifier), when present. */
     matched_identifiers?: string[];
 }
 /** A member owner embedded in an entity-detail response. */
@@ -211,8 +278,36 @@ export interface EntitySummary {
     ticker: string | null;
     lei: string | null;
     trademark_count: number;
+    active_count: number;
     member_count: number;
 }
+/** The nearest listed ancestor of a `subsidiary_of_listed` entity, when it
+ *  resolves to a live entity in our system. */
+export interface EntityListedAncestor {
+    id: string;
+    object: 'entity';
+    name: string;
+    /** The listed ancestor's own ticker. */
+    ticker: string | null;
+}
+/** Public-listing decoration (ENG-117). Present on {@link EntityDetail} ONLY when
+ *  the entity is listed or a subsidiary of a listed company; OMITTED otherwise
+ *  (absence ≠ confirmed-private). */
+export interface EntityListing {
+    /** 'listed' = the entity is itself publicly listed; 'subsidiary_of_listed' =
+     *  it inherits a ticker from a listed ancestor. */
+    status: 'listed' | 'subsidiary_of_listed';
+    /** The entity's own ticker (listed) or the inherited ancestor ticker (subsidiary). */
+    ticker: string | null;
+    /** Exchange / market code (display only). */
+    exch_code: string | null;
+    /** LEI of the listed company: the entity's own LEI when listed, else the ancestor's. */
+    lei: string | null;
+    /** Derived from status: 'listed' → 'direct', 'subsidiary_of_listed' → 'inherited'. */
+    source: 'direct' | 'inherited';
+    /** The nearest listed ancestor; null for a directly-listed entity or when unresolvable. */
+    listed_ancestor: EntityListedAncestor | null;
+}
 /** Full entity detail (`GET /v1/entities/{id}`). Resolved entities embed
  *  members[] with link evidence; derived singletons carry a member-of-one. */
 export interface EntityDetail {
@@ -222,21 +317,28 @@ export interface EntityDetail {
     country_code: string | null;
     entity_type: string | null;
     entity_id_type: 'resolved' | 'derived';
-    /** Public-company facts aggregated over member companies ("served through the
-     *  entity"). Always present. A derived singleton exposes the owner's own
-     *  public-company facts when present (pco-linked); otherwise false/null/empty. */
+    /** True when a member company is an active SEC ticker OR the entity itself is
+     *  listed / a subsidiary of a listed company (ENG-117 — matches the list filter).
+     *  A derived singleton exposes the owner's own public-company facts (pco-linked),
+     *  else false. */
     publicly_traded: boolean;
     /** Survivorship ticker (first of {@link tickers}); null when none. */
     ticker: string | null;
-    /** Deduped uppercased SEC tickers across all member companies. */
+    /** Deduped uppercased tickers: member-company SEC tickers UNION the entity's own
+     *  direct/inherited (subsidiary_of_listed) listing_ticker (ENG-117). Includes
+     *  inherited subsidiary tickers; direct-vs-inherited provenance is in {@link listing}. */
     tickers: string[];
     lei: string | null;
     /** Whether any member company carries a GLEIF LEI. */
     has_lei: boolean;
     trademark_count: number;
+    active_count: number;
     member_count: number;
     /** Resolved entities only — the GLEIF parent entity id, when present. */
     parent_entity_id?: string | null;
+    /** Public-listing block (ENG-117). Present only when the entity is listed or a
+     *  subsidiary of a listed company; omitted otherwise. */
+    listing?: EntityListing;
     members: EntityMember[];
     updated_at: string;
     request_id: string;
@@ -263,6 +365,12 @@ export interface EntityFamily {
 export type Proceeding = components['schemas']['Proceeding'];
 /** Full proceeding detail with embedded trademark (retrieve response). */
 export type ProceedingDetail = components['schemas']['ProceedingResponse'];
+/** Recorded assignment in list responses. */
+export type Assignment = components['schemas']['Assignment'];
+/** Full assignment detail with parties and affected marks. */
+export type AssignmentDetail = components['schemas']['AssignmentResponse'];
+/** Assignment item returned under a trademark's chain of title. */
+export type TrademarkAssignment = components['schemas']['TrademarkAssignmentSub'];
 /** Request body for POST /v1/trademarks/batch. */
 export type TrademarkBatchBody = components['schemas']['TrademarkBatchRequest'];
 /** Response shape for POST /v1/trademarks/batch (non-paginated). */
@@ -276,15 +384,49 @@ export type TrademarkSuggestion = components['schemas']['TrademarkSuggestion'];
 /** Attorney client (owner) entry with shared count. */
 export type AttorneyClient = components['schemas']['AttorneyClient'];
 /** Search result item (V2 with match explanations and faceted aggregations). */
-export type SearchV2Result = components['schemas']['SearchResultV2'];
+export type TrademarkSearchResult = components['schemas']['TrademarkSearchResult'];
 /** Cross-entity suggestion item. */
 export type CrossEntitySuggestion = components['schemas']['CrossEntitySuggestion'];
 /** Goods & services term (Nice classification). */
 export type GoodsServicesTerm = components['schemas']['GoodsServicesTerm'];
 /** Single maintenance deadline rule (item in `GET /v1/deadline-rules`). */
 export type DeadlineRule = components['schemas']['DeadlineRule'];
+/** Single computed maintenance deadline. */
+export type ComputedDeadline = components['schemas']['ComputedDeadline'];
+/** Per-item result from `POST /v1/deadlines/compute`. */
+export type DeadlineComputation = components['schemas']['DeadlineComputation'];
+/** Input item for `POST /v1/deadlines/compute`. */
+export type DeadlineComputeItem = components['schemas']['DeadlineComputeItem'];
+/** Request body for `POST /v1/deadlines/compute`. */
+export type DeadlineComputeParams = components['schemas']['DeadlineComputeRequest'];
+/** List response from `POST /v1/deadlines/compute`. */
+export type DeadlineComputeResponse = components['schemas']['DeadlineComputeResponse'];
 /** Single opposition window rule (item in `GET /v1/opposition-rules`). */
 export type OppositionRule = components['schemas']['OppositionRule'];
+/** Common extension available for an opposition window, when modeled. */
+export type OppositionCommonExtension = components['schemas']['OppositionCommonExtension'];
+/** Source citation surfaced on an opposition window computation. */
+export type OppositionWindowSource = components['schemas']['OppositionWindowSource'];
+/** Per-item result from `POST /v1/oppositions/compute`. */
+export type OppositionWindowComputation = components['schemas']['OppositionWindowComputation'];
+/** Input item for `POST /v1/oppositions/compute`. */
+export type OppositionComputeItem = components['schemas']['OppositionComputeItem'];
+/** Request body for `POST /v1/oppositions/compute`. */
+export type OppositionComputeParams = components['schemas']['OppositionComputeRequest'];
+/** List response from `POST /v1/oppositions/compute`. */
+export type OppositionComputeResponse = components['schemas']['OppositionComputeResponse'];
+/** Single field comparison from `POST /v1/reconcile`. */
+export type ReconcileFieldDiff = components['schemas']['ReconcileFieldDiff'];
+/** Caller-supplied field values for `POST /v1/reconcile`. */
+export type ReconcileYourFields = components['schemas']['ReconcileYourFields'];
+/** Input item for `POST /v1/reconcile`. */
+export type ReconcileItem = components['schemas']['ReconcileItem'];
+/** Request body for `POST /v1/reconcile`. */
+export type ReconcileParams = components['schemas']['ReconcileRequest'];
+/** Per-item result from `POST /v1/reconcile`. */
+export type Reconciliation = components['schemas']['Reconciliation'];
+/** List response from `POST /v1/reconcile`. */
+export type ReconcileResponse = components['schemas']['ReconcileResponse'];
 /** Statutory citation + URL surfaced on rule items. */
 export type RuleSource = components['schemas']['RuleSource'];
 /** Vienna design code. */
@@ -360,15 +502,22 @@ export type WatchStatus = 'active' | 'paused' | 'disabled';
 /**
  * Trigger event types — ingestion-emitted fact events a watch can subscribe to.
  *
- * v1 accepts exactly these 3 values. `trademark.retracted` and
- * `trademark.corrected` were listed in earlier SDK revisions but were NEVER
- * accepted by the API (create/update reject them with 400) and are never
- * emitted by the evaluator. Source of truth:
- * `api/src/modules/watches/validators.ts` `ALLOWED_TRIGGER_EVENTS`.
+ * All 5 values are accepted as `trigger_events` on create/update. The DEFAULT
+ * trigger set applied when you OMIT `trigger_events` is the original 3
+ * (`trademark.created`, `trademark.updated`, `trademark.status_changed`).
+ * `trademark.retracted` and `trademark.corrected` are OPT-IN: they fire only
+ * for watches that explicitly list them in `trigger_events`, and the evaluator
+ * actively derives + emits both. Source of truth:
+ * `api/src/modules/watches/validators.ts` `ALLOWED_TRIGGER_EVENTS`
+ * (= `ALERT_EVENT_TYPES` from `@signa/types`) and `DEFAULT_TRIGGER_EVENTS`.
  */
-export type WatchTriggerEvent = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed';
+export type WatchTriggerEvent = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed' | 'trademark.retracted' | 'trademark.corrected';
+/** Search strategy names accepted by watch similarity queries. */
+export type WatchSearchStrategy = 'exact' | 'phonetic' | 'fuzzy' | 'prefix';
+/** Attribution tier gate for watch similarity queries. */
+export type WatchMinMatchTier = 'exact' | 'normalized' | 'fuzzy' | 'phonetic';
 /**
- * Watch query DSL (v1). Five watch types share one shape — the
+ * Watch query DSL. Five watch types share one shape — the
  * `watch_type` selects which scoping field is required, but the body
  * shape is identical to a trademark search body. See the
  * [Watches guide](https://docs.signa.so/guides/monitoring/watches) for
@@ -377,28 +526,40 @@ export type WatchTriggerEvent = 'trademark.created' | 'trademark.updated' | 'tra
  * `q` is a whitespace-separated keyword list (max 20, each ≥3 chars, no
  * stop words). `filters` accepts the same vocabulary as the trademark
  * search API (`trademarkIds`, `ownerId`, `niceClasses`, `jurisdictions`,
- * `offices`, etc.). `trigger_events` narrows which lifecycle events
- * fire alerts. `score_threshold` (0..1) gates similarity matches.
+ * `offices`, etc.). `strategies` uses the same selector as public trademark
+ * search. `trigger_events` narrows which lifecycle events fire alerts.
+ * `min_match_tier` gates similarity matches by retrieval attribution tier.
+ * `score_threshold` is NOT currently supported — sending it on a write is
+ * rejected with 400; scores are informational (see `match_score` on alerts).
  *
  * Forbidden DSL keys (`function_score`, `script`, `sort`, `cursor`,
  * `aggregations`, `highlight`) are rejected with 400. `query.match` is
  * rejected in ANY form (object or string) — earlier doc revisions described
  * shapes that were never honored by the evaluator. Use `filters.ownerId`,
  * `filters.trademarkIds`, `filters.niceClasses` for scoping and
- * `score_threshold` for similarity precision. Unknown `filters` keys are
+ * `min_match_tier` for similarity precision. Unknown `filters` keys are
  * rejected with 400 listing the allowed vocabulary; `filters.offices`
  * accepts any casing and is stored lowercase.
  */
 export interface WatchQuery {
-    /** Always `"v1"` for monitoring v1. */
-    version: 'v1';
+    /** `"v2"` for tier-based watch matching. `"v1"` is accepted during migration. */
+    version: 'v1' | 'v2';
     /** Optional keyword query (required for similarity watches). Whitespace-separated; each ≥3 chars; no stop words. */
     q?: string;
+    /** Search strategies to use. Omit for the public-search default (`exact` + `fuzzy`). */
+    strategies?: WatchSearchStrategy[];
     /** Filter object — same vocabulary as the trademark search API. Common keys: `trademarkIds`, `ownerId`, `niceClasses`, `jurisdictions`, `offices`, `statusPrimary`. */
     filters?: Record<string, unknown>;
     /** Restrict alert generation to specific trigger event types. */
     trigger_events?: WatchTriggerEvent[];
-    /** Similarity score threshold (0..1). Only matches scoring at-or-above fire alerts. Valid for `watch_type: "similarity"`. */
+    /** Minimum attribution tier for similarity watches. `phonetic` is the broad "any tier" setting. */
+    min_match_tier?: WatchMinMatchTier;
+    /**
+     * NOT currently supported — sending this on create/update/bulk/preview is
+     * rejected with 400. Scores are informational (see `match_score` on alerts).
+     * The field is retained on the type so existing stored watch queries still
+     * deserialize on GET. Contact support for calibrated-band thresholds.
+     */
     score_threshold?: number;
 }
 /** Watch (retrieve / create / update response). */
@@ -413,6 +574,8 @@ export interface Watch {
     /** Last 24h alert count when retrieving a single watch; null on list responses. */
     alert_count_24h: number | null;
     last_alerted_at: string | null;
+    /** Customer passthrough label set on the watch; null if unset. */
+    customer_reference: string | null;
     metadata: Record<string, unknown>;
     created_at: string;
     updated_at: string;
@@ -420,42 +583,156 @@ export interface Watch {
 /**
  * Alert event types — what the API actually emits for `Alert.event_type`.
  *
- * In v1 this is identical to {@link WatchTriggerEvent}: watches can subscribe
- * to exactly these 3 events, and alerts only ever carry these 3 values.
- * (Earlier SDK revisions claimed watches accepted 5 trigger events — they
- * never did; the API rejects `trademark.retracted` / `trademark.corrected`
- * with 400.) The two types are kept separate so they can diverge in later
- * API versions without a breaking rename.
- *
- * R4.5 fix: previously this declared 5 values; SDK consumers switching on
- * `'trademark.retracted'` or `'trademark.corrected'` had dead `case` branches
- * that never fired.
+ * In v1 this is identical to {@link WatchTriggerEvent}: all 5 canonical values
+ * are accepted as `trigger_events`, and alerts may carry any of them. The
+ * DEFAULT trigger set (when `trigger_events` is omitted) is the original 3
+ * (`trademark.created`, `trademark.updated`, `trademark.status_changed`);
+ * `trademark.retracted` and `trademark.corrected` are OPT-IN and fire only for
+ * watches that explicitly subscribe to them — the evaluator derives + emits
+ * both. The two types are kept separate so they can diverge in later API
+ * versions without a breaking rename.
  */
-export type AlertEventType = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed';
+export type AlertEventType = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed' | 'trademark.retracted' | 'trademark.corrected';
 /** Alert severity. */
 export type AlertSeverity = 'normal' | 'high' | 'critical';
 /** Opposition-window state for the matched mark, when applicable. */
 export type OppositionWindowStatus = 'open' | 'closing_soon' | 'critical' | 'closed';
-/** Alert (immutable — no PATCH/dismiss in monitoring v1). */
+/**
+ * One entry in an alert's `event.diff`. Parent-field changes carry real
+ * `from`/`to` values; child-entity changes are opaque (`{ path, op:'changed' }`,
+ * `from`/`to` absent).
+ */
+export interface AlertDiffEntry {
+    path: string;
+    op: 'set' | 'unset' | 'changed';
+    from?: unknown;
+    to?: unknown;
+}
+/**
+ * Match metadata — why/how the mark matched the watch. The whole block is
+ * `null` for pure-filter / pre-v2 alerts that carry no match scoring.
+ */
+export interface AlertMatch {
+    /** Human-readable explanation of the match; null when not captured. */
+    reason: string | null;
+    /** Relevance score (e.g. OpenSearch); null when not applicable. */
+    score: number | null;
+    /** What the score is derived from, e.g. `opensearch_relevance`; null when none. */
+    score_basis: string | null;
+}
+/**
+ * Compact mark summary embedded on the alert (Alerts v2 `trademark` block).
+ * Mirrors the trademark SEARCH summary vocabulary. The summary fields degrade
+ * (absent) for pre-v2 alerts, where only `id`, `as_of`, and `links` are present.
+ */
+export interface AlertTrademarkSnapshot {
+    /** Prefixed trademark ID (`tm_*`). */
+    id: string;
+    mark_text?: string | null;
+    mark_feature_type?: string | null;
+    office_code?: string;
+    status?: {
+        primary: string;
+        stage: string;
+    };
+    filing_date?: string | null;
+    registration_date?: string | null;
+    nice_classes?: number[];
+    owner_name?: string | null;
+    /** When the source change occurred (`source_occurred_at`); null on pre-v2 alerts. */
+    as_of: string | null;
+    links: {
+        self: string;
+    };
+}
+/**
+ * Alert (immutable — no PATCH/dismiss in monitoring v1).
+ *
+ * Alerts v2 nested shape — mirrors the REST `AlertResponse` (see
+ * `api/src/modules/alerts/routes.ts`). The webhook body for `alert.created`
+ * carries the same canonical object minus `request_id` / `evaluation_epoch`.
+ */
+/**
+ * REST-only alert provenance block (ENG-170) — the alert's evidence chain.
+ * NOT part of the signed webhook contract (see {@link AlertCreatedPayload}).
+ */
+export interface AlertProvenance {
+    /** Prefixed sync-run id (`srun_*`); omitted when the alert has no linked run. */
+    sync_run?: string;
+    /** The trademark_record version the alert froze at. */
+    content_version: number;
+    /**
+     * created_at minus occurred_at, in seconds. Null when occurred_at is null
+     * or in the future relative to created_at (unknown, never negative).
+     */
+    detection_latency_seconds: number | null;
+    /** True when detection latency exceeded the office's expected cadence. False whenever latency is unknown. */
+    late_detection: boolean;
+}
 export interface Alert {
     id: string;
     object: 'alert';
-    watch_id: string;
-    watch_name: string;
-    trademark_id: string;
-    event_type: AlertEventType;
-    /** Snapshot of trademark version at the moment of evaluation (immutable). */
-    content_version: number;
-    /** Computed customer-action deadline; null if no deadline applies. */
-    must_act_by: string | null;
-    /** Current opposition-window state for this mark; null when no window applies. */
-    opposition_window_status: OppositionWindowStatus | null;
-    severity: AlertSeverity;
-    /** Optional compact mark summary (mark text, owner, office) included by some routes. */
-    trademark_summary?: Record<string, unknown>;
-    /** Optional human-readable explanation of why the mark matched the watch. */
-    match_reason?: string;
-    created_at: string;
+    /** Alerts v2 wire schema version, e.g. `'2026-06-01'`. */
+    schema_version: string;
+    watch: {
+        id: string;
+        name: string;
+        type: WatchType;
+    };
+    /** Customer passthrough set on the watch; null if unset. */
+    customer_reference: string | null;
+    event: {
+        type: AlertEventType;
+        /** Short human-readable description, e.g. `"Status primary changed: pending → registered"`. */
+        summary: string;
+        diff: AlertDiffEntry[];
+        /**
+         * Set to `true` when the diff was clipped to stay under the wire byte
+         * budget (entries dropped and/or long values replaced with `[truncated]`).
+         * Absent/undefined for normal, un-clipped alerts.
+         */
+        diff_truncated?: boolean;
+    };
+    /** Match metadata, or null for pure-filter / pre-v2 alerts. */
+    match: AlertMatch | null;
+    trademark: AlertTrademarkSnapshot;
+    deadline: {
+        severity: AlertSeverity;
+        /** Current opposition-window state for this mark; null when no window applies. */
+        opposition_window_status: OppositionWindowStatus | null;
+        /** Computed customer-action deadline; null if no deadline applies. */
+        must_act_by: string | null;
+    };
+    /**
+     * True when this alert was generated well after the underlying change
+     * occurred (e.g. the monitoring pipeline recovered from a stall and
+     * processed backlogged changes). Late alerts remain fully visible via the
+     * REST API (filter with `?detected_late=true|false`) but are EXCLUDED from
+     * webhook delivery by default.
+     */
+    detected_late: boolean;
+    timestamps: {
+        /** When the source change occurred; null on pre-v2 alerts. */
+        occurred_at: string | null;
+        /** When the underlying change was ingested; omitted when no change row is linked. */
+        ingested_at?: string;
+        created_at: string;
+    };
+    links: {
+        trademark: string;
+        watch: string;
+    };
+    /**
+     * REST-only: evaluation epoch the alert was emitted under (NOT part of the
+     * webhook contract). Lets clients distinguish prior-query-revision alerts
+     * when listing with `?epoch=all`.
+     */
+    evaluation_epoch: number;
+    /**
+     * REST-only: the alert's evidence chain (ENG-170). NOT part of the webhook
+     * contract; webhook consumers re-fetch the alert via the API to obtain it.
+     */
+    provenance: AlertProvenance;
 }
 /** Webhook event types delivered by the dispatcher. */
 export type WebhookEventType = 'alert.created' | 'webhook.test';
@@ -482,7 +759,12 @@ export interface WebhookEvent<T = unknown> {
     data: T;
 }
 /**
- * Inner payload of an `alert.created` webhook delivery.
+ * Preserved FLAT fields on an `alert.created` webhook delivery.
+ *
+ * These are the lean, backward-compatible top-level fields the dispatcher has
+ * always emitted. They are kept alongside the rich {@link Alert} object (see
+ * {@link AlertCreatedPayload}) so existing consumers that read flat fields
+ * never break.
  *
  * IDs are prefixed (Round 4 R4.5) — `alert_id`, `watch_id`, and
  * `trademark_record_id` feed straight into `GET /v1/alerts/{id}` etc.
@@ -492,7 +774,7 @@ export interface WebhookEvent<T = unknown> {
  * customer's webhook endpoint already implies the tenant, and
  * cross-referencing internal tenant UUIDs is not part of the public API.
  */
-export interface AlertCreatedPayload {
+export interface AlertCreatedFlatFields {
     /** Prefixed alert ID, e.g. `alt_018f...`. */
     alert_id: string;
     /** Prefixed watch ID, e.g. `wat_018f...`. */
@@ -524,6 +806,30 @@ export interface AlertCreatedPayload {
     /** Hash of the source data payload that triggered the alert; null when not available. */
     source_data_hash: string | null;
 }
+/**
+ * Inner payload of an `alert.created` webhook delivery.
+ *
+ * The dispatcher (`buildSelfContainedAlertData` in
+ * `workers/webhook-dispatcher/src/dispatcher.ts`) emits a SELF-CONTAINED body:
+ * the full rich {@link Alert} object (`watch`, `event`, `match`, `trademark`,
+ * `deadline`, `timestamps`, `schema_version`, `customer_reference`, `links`,
+ * `id`, `object`) SPREAD together with the preserved {@link AlertCreatedFlatFields}.
+ * Rich-first, flat-last, so the lean flat fields win on any future key overlap.
+ *
+ * The flat fields ({@link AlertCreatedFlatFields}) are ALWAYS present. The rich
+ * half mirrors the REST {@link Alert} resource MINUS `evaluation_epoch`
+ * (REST-only — the webhook carries the epoch as a flat field instead, see
+ * {@link AlertCreatedFlatFields.evaluation_epoch}), and is OPTIONAL: the rich
+ * fields (`event`, `trademark`, `match`, `watch`, `deadline`, `timestamps`,
+ * `schema_version`, `links`, `id`, `object`, `customer_reference`) are present
+ * on normal deliveries but ABSENT on the rare lean-fallback delivery — when the
+ * alert row was hard-deleted between emit and dispatch, hydration returns null
+ * and the dispatcher emits ONLY the flat fields.
+ *
+ * Consumers that read rich fields should feature-detect, e.g.
+ * `if (data.event) { … }`, rather than assume they are present.
+ */
+export type AlertCreatedPayload = AlertCreatedFlatFields & Partial<Omit<Alert, 'evaluation_epoch' | 'provenance'>>;
 /** Webhook envelope for an `alert.created` delivery. */
 export type AlertCreatedEvent = WebhookEvent<AlertCreatedPayload>;
 /** Webhook endpoint status. */
@@ -618,6 +924,16 @@ export interface WatchPreviewResponse {
      * were found (partial result). Absent = exact count.
      */
     estimate_basis?: 'candidacy_upper_bound';
+    /**
+     * A page of the actual matching trademarks in the canonical summary shape
+     * (identical to `GET /v1/trademarks` results). Returned BY DEFAULT; omitted
+     * only when the request set `count_only: true`. Up to `result_limit` items.
+     */
+    results?: TrademarkSummary[];
+    /** Whether more matches exist beyond `results`. Omitted when count_only. */
+    has_more?: boolean;
+    /** Echo of the effective page size for `results`. Omitted when count_only. */
+    result_limit?: number;
     request_id: string;
 }
 /**
@@ -654,13 +970,24 @@ export interface WatchDiagnostics {
     candidacy_passed: boolean;
     trigger_event_type: string | null;
     trigger_event_in_filter: boolean;
+    /**
+     * Persisted per-match relevance score (`match_score` on the most recent
+     * alert for this watch+trademark); null when no alert exists or the watch
+     * has no scored (`q`) clause. Informational only.
+     */
     opensearch_score: number | null;
+    /**
+     * Stored (legacy) threshold, surfaced for existing watches that carry one.
+     * INERT — no longer gates matching, and rejected on new writes.
+     */
     score_threshold: number | null;
+    min_match_tier: WatchMinMatchTier | null;
     alert_fired: boolean;
     /**
      * Walked in order: alert fired → office not in scope → freshness limit →
-     * candidacy missing → trigger event filtered → score below threshold →
-     * rolled into digest → fallback. See the diagnostics docs for the full enum.
+     * candidacy missing → trigger event filtered → rolled into digest →
+     * fallback. (No score-threshold reason: the field is inert.) See the
+     * diagnostics docs for the full enum.
      */
     reason: string;
     delivery_mode_effective: 'per_alert' | 'digest' | null;
@@ -669,13 +996,15 @@ export interface WatchDiagnostics {
     /** Alert's frozen `evaluation_epoch` when emitted under a replay-bumped epoch; null otherwise. */
     replay_epoch_origin: number | null;
     last_relevant_sync_run: {
-        id: string;
         office_code: string;
         completed_at: string | null;
         search_indexed_at: string | null;
     } | null;
-    /** `event_outbox` UUID — cross-reference against the `webhook-id` on delivery audit rows. */
-    outbox_event_id: string | null;
+    /**
+     * Public ID (`alt_*`) of the alert that fired, or null. Cross-reference
+     * against `alert_id` on `webhooks.listDeliveries()` rows.
+     */
+    alert_id: string | null;
     opposition: {
         must_act_by: string | null;
         rule_source: string | null;
@@ -697,6 +1026,105 @@ export interface WatchDiagnosticsParams {
     /** Required prefixed trademark ID (`tm_*`). */
     trademarkId: string;
 }
+/** A disclosed coverage gap on a per-office attestation entry. */
+export interface WatchAttestationGap {
+    from: string;
+    through: string;
+    /**
+     * `office_lagging` = coverage was stale beyond the office SLO for this
+     * interval. `evaluation_failed` is reserved (not emitted in v1: gaps cover
+     * coverage-staleness only).
+     */
+    reason: 'office_lagging' | 'evaluation_failed';
+    /** True once coverage caught back up within the period. */
+    resolved: boolean;
+}
+/**
+ * Per-office attestation entry. `status: 'unsupported'` (an in-scope office
+ * Signa does not ingest) carries NO evaluation claims — the numeric fields are
+ * omitted entirely. `status: 'no_evaluations'` (a supported office with zero
+ * evaluations in the period) carries zero counts, no coverage claims, and a
+ * full-period gap — an un-evaluated month never reads as a clean silent month.
+ */
+export interface WatchAttestationOffice {
+    office_code: string;
+    office_name: string;
+    status: 'evaluated' | 'no_evaluations' | 'unsupported';
+    evaluations_count?: number;
+    sync_runs_evaluated?: string[];
+    /**
+     * Changes evaluated against your query this period (candidacy volume). NOT
+     * the size of the whole office corpus.
+     */
+    changes_evaluated?: number;
+    match_count?: number;
+    alerts_emitted?: number;
+    coverage_from?: string | null;
+    coverage_through?: string | null;
+    coverage_basis?: 'source_dates' | 'date_range' | 'run_completed' | null;
+    gaps?: WatchAttestationGap[];
+}
+/**
+ * The filable monthly proof-of-monitoring artifact. Deterministic for a closed
+ * period: re-fetch and compare `content_hash` to verify integrity. The hash
+ * excludes `generated_at`, `request_id`, `content_hash`,
+ * `watch_status_at_generation`, `watch.name`, and
+ * `watch.configuration_changed_since_period` (generation-time / display-only
+ * facts).
+ */
+export interface WatchAttestation {
+    object: 'watch_attestation';
+    schema_version: string;
+    watch: {
+        id: string;
+        /** Display-only; excluded from `content_hash` (mutable via PATCH). */
+        name: string;
+        query_fingerprint: string;
+        /**
+         * The fingerprint describes the CURRENT watch configuration (a true
+         * evaluated-time snapshot requires the deferred watch-revision history).
+         */
+        fingerprint_basis: 'current_configuration';
+        trigger_events: string[];
+        /** Evaluation-epoch deltas occurred WITHIN the period. */
+        configuration_changed_in_period: boolean;
+        /**
+         * The live configuration is ahead of every epoch seen in the period (a
+         * post-period change happened; the fingerprint no longer describes the
+         * period). Generation-time fact; excluded from `content_hash`.
+         */
+        configuration_changed_since_period: boolean;
+        epochs_in_period?: number[];
+    };
+    period: {
+        start: string;
+        end: string;
+        partial: boolean;
+    };
+    offices: WatchAttestationOffice[];
+    totals: {
+        evaluations: number;
+        alerts_emitted: number;
+    };
+    reconciliation: 'consistent' | 'mismatch';
+    statement: string;
+    slo_reference: string;
+    /**
+     * Present ('paused' | 'disabled') when the watch is not active at generation
+     * time. Pause history within the period is not reconstructable in v1.
+     * Generation-time fact; excluded from `content_hash`.
+     */
+    watch_status_at_generation?: string;
+    generated_at: string;
+    content_hash: string;
+    request_id: string;
+}
+export interface WatchAttestationParams {
+    /** UTC calendar month `YYYY-MM`. Default: previous month. */
+    period?: string;
+    /** Set true to allow an interim artifact for the current (open) month. */
+    partial?: boolean;
+}
 /** Result of `webhooks.test()`. */
 export interface WebhookTestResponse {
     object: 'webhook_test';
@@ -709,22 +1137,24 @@ export interface WebhookRedeliveryResponse {
     delivery_attempt_id: string;
     request_id: string;
 }
-/** Org-level event list item. */
+/** Org-level event list item. IDs are evt_-prefixed opaque strings. */
 export interface OrgEvent {
-    id: number;
+    id: string;
     object: 'event';
-    event_type: string;
+    type: string;
     trademark_id: string;
     office_code: string;
     created_at: string;
 }
-/** Org-level event detail (with changes). */
+/** Org-level event detail (with field-level before/after diffs). */
 export interface OrgEventDetail extends OrgEvent {
-    changes: Array<{
-        field: string;
+    version: number;
+    changed_fields: string[];
+    changes: Record<string, {
         before: unknown;
         after: unknown;
     }>;
+    request_id: string;
 }
 /** Identity (GET /v1/organization/me). */
 export type Identity = components['schemas']['Identity'];
@@ -750,6 +1180,12 @@ export type UsageSummaryResponse = components['schemas']['UsageSummaryResponse']
 export type UsageSummaryItem = components['schemas']['UsageSummaryItem'];
 /** Billing period context on a usage summary response. */
 export type UsageBillingPeriod = components['schemas']['BillingPeriodContext'];
+/** Pooled credit balance response (GET /v1/organization/credits). */
+export type CreditBalance = components['schemas']['CreditBalanceResponse'];
+/** Remaining-credit breakdown by grant type on a credit balance response. */
+export type CreditGrantBreakdown = components['schemas']['CreditGrantBreakdown'];
+/** A single grant entry in the credit expiry schedule. */
+export type CreditExpiryScheduleEntry = components['schemas']['CreditExpiryScheduleEntry'];
 /** Generic delete confirmation. */
 export interface DeletedResponse {
     id: string;
@@ -763,26 +1199,87 @@ export type TrademarkSource = components['schemas']['TrademarkSourceResponse'];
 export type TrademarkCoverage = components['schemas']['TrademarkCoverage'];
 /** Trademark proceeding (with parties) as returned by /trademarks/{id}/proceedings. */
 export type TrademarkProceeding = components['schemas']['TrademarkProceedingSub'];
+/** Source synchronization state for lazy trademark document metadata. */
+export interface TrademarkDocumentSourceSync {
+    status: 'synced' | 'pending' | 'unsupported';
+    last_synced_at: string | null;
+}
+/** Trademark office document metadata returned by /trademarks/{id}/documents. */
+export interface TrademarkDocument {
+    id: string;
+    object: 'trademark_document';
+    document_kind: 'office_action' | 'certificate' | 'correspondence' | 'filed_form' | 'other';
+    official_date: string | null;
+    description: string | null;
+    mime_type: string;
+    page_count: number | null;
+    url: string;
+}
 /** Owner related entity (GLEIF corporate hierarchy). */
 export type OwnerRelated = components['schemas']['OwnerRelated'];
+/**
+ * A `search_meta.warnings[]` element (mirror of the API spec). Two families
+ * share this shape:
+ *   • strategy-skip warnings — a REQUESTED strategy produced zero clauses for
+ *     the query shape (e.g. `strategies=[phonetic]` on a query too short or
+ *     high-collision); carries `strategy`.
+ *   • filter-coverage warnings — an applied filter (e.g. `opposition_status`,
+ *     `seniority_claims`) has partial index coverage; carries `severity`,
+ *     `affected_filter`, `affected_offices`, `behavior`.
+ */
+export interface SearchWarning {
+    code: string;
+    message: string;
+    strategy?: string;
+    severity?: 'info' | 'warning';
+    affected_filter?: string;
+    /** WIPO ST.3 office codes (e.g. 'US', 'EM', 'WO') affected by the caveat. */
+    affected_offices?: string[];
+    behavior?: string;
+}
 /** Search metadata (V2 — timing, totals, strategy info). */
+/**
+ * ENG-106 — how the query text is matched against the mark text.
+ * `similar` (default) runs the ranked strategies ladder (relevance scoring).
+ * `exact` | `starts_with` | `ends_with` | `contains` are deterministic
+ * (date-led sort, `relevance_score` null on every row). Deterministic modes
+ * require a query and disallow `strategies` / `ranking_profile`; `contains`
+ * additionally needs a folded query of at least 3 characters.
+ */
+export type MatchMode = 'similar' | 'exact' | 'starts_with' | 'ends_with' | 'contains';
 export interface SearchMeta {
     search_id: string;
-    query: string;
+    query: string | null;
+    /** Public strategies used for the served set. Empty `[]` for deterministic match modes. */
     strategies_used: string[];
     /**
-     * Total matching results. Only present when the caller set
-     * `options.include_total = true` (or requested aggregations). Absent
-     * on default searches so the API can skip OpenSearch hit counting
-     * and return faster on broad queries. See api-spec-v1 §5.
+     * ENG-106 — the match mode actually applied. Echoed for ALL modes (including
+     * `'similar'`).
+     */
+    match: MatchMode;
+    international_registrations: 'grouped' | 'expanded';
+    fallback_reason?: string;
+    /**
+     * The `jurisdictions` matching mode actually applied: `'protection'` (default,
+     * regional-membership expansion) or `'direct'` (literal territory legs).
+     * Echoed on every response, including when no `jurisdictions` filter is present.
+     */
+    territory_match: TerritoryMatchMode;
+    /**
+     * Search warnings. Two families share this array: per-strategy skip warnings
+     * (a REQUESTED strategy produced zero clauses for the query shape) and
+     * filter-coverage warnings (an applied filter has partial index coverage).
+     * Omitted when there is nothing to warn about.
      */
-    total_results?: number;
+    warnings?: SearchWarning[];
     /**
-     * `true` if `total_results` is an exact count, `false` if it is a
-     * lower bound (capped at 10k). Only present when `total_results` is
-     * present.
+     * NOTE: the total matching-result count is NOT on `search_meta`. It surfaces
+     * as `pagination.total_count` (+ `pagination.total_count_approximate`) when
+     * the caller sets `options.include_total = true` — see
+     * `SignaList.total_count`. The former `search_meta.total_results` /
+     * `total_count_exact` / `total_count_approximate` fields were removed in the
+     * ENG-14 beta break.
      */
-    total_count_exact?: boolean;
     execution_time_ms: number;
 }
 /** API error body (RFC 9457-inspired). */
@@ -803,17 +1300,43 @@ export interface APIErrorBody {
     /** Server-suggested seconds to wait before retrying (body-level mirror of the Retry-After header). */
     retry_after?: number;
 }
+export type TrademarkSearchInclude = 'full_goods_services';
+export type TrademarkDetailInclude = 'office_extensions';
+/**
+ * How a `jurisdictions` filter matches. `protection` (default) selects rights
+ * that protect, or seek protection, in the requested territory: a country
+ * request also matches regional rights whose membership covers it (a EUTM for
+ * `jurisdictions: ['FR']`). `direct` matches only literal territory legs
+ * (national filings + Madrid designations of the exact territory), reproducing
+ * the pre-2026-07 behavior. Inert when no `jurisdictions` filter is present.
+ */
+export type TerritoryMatchMode = 'protection' | 'direct';
+export type OppositionStatus = 'open' | 'not_started' | 'closed' | 'unknown';
+export type SeniorityClaims = 'claimed' | 'none' | 'unknown';
 export interface TrademarkRetrieveParams {
     /**
-     * Optional relations to embed alongside the trademark detail.
+     * Optional detail projections.
      *
-     * Currently only `history` is supported. Including `history` embeds the 50
-     * most recent prosecution events with a `has_more` indicator. Owners,
-     * classifications, attorneys, media, priorities, proceedings, and Madrid
-     * coverage are always returned inline at the detail tier.
+     * `office_extensions` includes the raw office-specific extension blob,
+     * which is omitted from the default detail response.
      */
-    include?: Array<'history'>;
+    include?: TrademarkDetailInclude[];
+    /** Sparse top-level field projection. `id` and `object` are always retained. */
+    fields?: string[];
+    /**
+     * Preferred goods/services language for classification rows. When multiple
+     * language variants exist for the same Nice class, the API returns the
+     * requested language if present; groups without that language keep all rows
+     * in default classification order.
+     */
+    language?: string;
 }
+/**
+ * ENG-67 — the closed set of faceted aggregation dimensions accepted by both
+ * `GET /v1/trademarks?aggregations=` and `POST /v1/trademarks` `options.aggregations`.
+ * Mirrors the server-side `AggregationEnum` and the generated OpenAPI enum.
+ */
+export type TrademarkAggregationName = 'status_stage' | 'office_code' | 'jurisdiction_code' | 'nice_classes' | 'filing_year' | 'mark_feature_type' | 'mark_legal_category' | 'filing_route' | 'right_kind' | 'scope_kind' | 'firm_id' | 'attorney_id' | 'owner_country' | 'owner_id' | 'entity_id';
 export interface TrademarkListParams {
     /**
      * Coarse status bucket. Accepts a single value or an array to match any of
@@ -833,11 +1356,25 @@ export interface TrademarkListParams {
     registration_number?: string;
     ir_number?: string;
     office?: string;
+    /**
+     * Jurisdiction codes selecting rights that protect, or seek protection, in
+     * these territories. Protection-scope by default (a EUTM matches
+     * `jurisdictions: ['FR']`); see `territory_match` to control expansion.
+     */
     jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
     offices?: string | string[];
     owner_country?: string;
     nice_classes?: number | number[];
     vienna_codes?: string | string[];
+    us_design_codes?: string | string[];
+    filing_basis?: string | string[];
+    us_register_type?: 'principal' | 'supplemental';
+    opposition_status?: OppositionStatus;
+    opposition_closes_before?: string;
+    opposition_closes_after?: string;
+    seniority_claims?: SeniorityClaims;
     filing_date_gte?: string;
     filing_date_gt?: string;
     filing_date_lte?: string;
@@ -858,6 +1395,22 @@ export interface TrademarkListParams {
     publication_date_gt?: string;
     publication_date_lte?: string;
     publication_date_lt?: string;
+    status_effective_date_gte?: string;
+    status_effective_date_gt?: string;
+    status_effective_date_lte?: string;
+    status_effective_date_lt?: string;
+    priority_date_gte?: string;
+    priority_date_gt?: string;
+    priority_date_lte?: string;
+    priority_date_lt?: string;
+    first_use_anywhere_date_gte?: string;
+    first_use_anywhere_date_gt?: string;
+    first_use_anywhere_date_lte?: string;
+    first_use_anywhere_date_lt?: string;
+    first_use_in_commerce_date_gte?: string;
+    first_use_in_commerce_date_gt?: string;
+    first_use_in_commerce_date_lte?: string;
+    first_use_in_commerce_date_lt?: string;
     termination_date_gte?: string;
     termination_date_gt?: string;
     termination_date_lte?: string;
@@ -892,18 +1445,36 @@ export interface TrademarkListParams {
     is_madrid?: boolean;
     is_retracted?: boolean;
     is_series_mark?: boolean;
+    international_registrations?: 'grouped' | 'expanded';
     /** Optional text query (triggers relevance ranking when no explicit sort). */
     q?: string;
+    /** ENG-67 — faceted bucket counts (TMview "Statistics view"). Field names to aggregate. */
+    aggregations?: TrademarkAggregationName[];
+    /** ENG-67 — when true, return only aggregation counts (no result documents). */
+    aggregations_only?: boolean;
     /** Search strategies to apply (e.g. 'exact', 'phonetic', 'fuzzy', 'prefix'). */
     strategies?: string[];
     /** Ranking profile to use. */
     ranking_profile?: string;
+    /**
+     * ENG-106 — how `q` matches the mark text. `'similar'` (default, ranked) vs
+     * the deterministic `'exact'` / `'starts_with'` / `'ends_with'` / `'contains'`
+     * modes. Deterministic modes require `q` and disallow `strategies` /
+     * `ranking_profile`; `'contains'` needs a folded query ≥ 3 chars.
+     */
+    match?: MatchMode;
+    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
+    mark_text_not_contains?: string;
     /** When true, include total_count in pagination (adds latency). */
     include_total?: boolean;
     /** When true, include match highlight spans. */
     highlights?: boolean;
     /** When true, include execution timing in search_meta. */
     include_timing?: boolean;
+    /** Optional row projections. `full_goods_services` disables summary G&S truncation. */
+    include?: TrademarkSearchInclude[];
+    /** Sparse top-level field projection. `id` and `object` are always retained. */
+    fields?: string[];
     goods_services_text?: string;
     origin_office_code?: string;
     renewal_due_before?: string;
@@ -938,6 +1509,8 @@ export interface TrademarkRelatedParams {
 export interface TrademarkSuggestParams {
     q: string;
     jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
     nice_classes?: number | number[];
     status_stage?: string | string[];
 }
@@ -952,6 +1525,20 @@ export interface TrademarkProceedingsParams {
     limit?: number;
     cursor?: string;
 }
+export interface TrademarkAssignmentsParams {
+    conveyance_type?: ConveyanceType;
+    /** Alias for conveyance_type. */
+    type?: ConveyanceType;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkDocumentParams {
+    document_kind?: TrademarkDocument['document_kind'] | TrademarkDocument['document_kind'][];
+    official_date_gte?: string;
+    official_date_lt?: string;
+    limit?: number;
+    cursor?: string;
+}
 export interface OwnerRelatedParams {
     limit?: number;
     cursor?: string;
@@ -961,11 +1548,9 @@ export interface OwnerRelatedParams {
  * always returns the full detail tier (aliases, identifiers, stats, public
  * companies). This empty params type is reserved for future use.
  */
-export interface OwnerRetrieveParams {
-}
+export type OwnerRetrieveParams = Record<string, never>;
 /** Entity detail accepts no query parameters (reserved for future use). */
-export interface EntityRetrieveParams {
-}
+export type EntityRetrieveParams = Record<string, never>;
 export interface EntityListParams {
     q?: string;
     country_code?: string;
@@ -983,10 +1568,14 @@ export interface EntityListParams {
  * Trademark filters for `GET /v1/entities/{id}/trademarks` — the same
  * Appendix-A filter set as the owner/attorney sub-resources (it runs through
  * the same `listTrademarksViaSearch` path), fanned out across ALL member owners.
+ *
+ * `include_family` (ENG-117) additionally expands the set to this entity AND all
+ * of its family-tree descendants (via `entities.parent_entity_id`).
  */
-export type EntityTrademarksParams = OwnerTrademarksParams;
-export interface EntityFamilyParams {
-}
+export type EntityTrademarksParams = OwnerTrademarksParams & {
+    include_family?: boolean;
+};
+export type EntityFamilyParams = Record<string, never>;
 export interface OwnerListParams {
     q?: string;
     country_code?: string;
@@ -995,7 +1584,11 @@ export interface OwnerListParams {
     lei?: string;
     publicly_traded?: boolean;
     has_lei?: boolean;
-    sort?: '-trademark_count' | 'trademark_count' | '-registration_rate' | 'registration_rate' | '-latest_filing' | 'latest_filing' | '-name' | 'name';
+    sort?: '-trademark_count' | 'trademark_count'
+    /** @deprecated Use `grant_rate` — same value. */
+     | '-registration_rate'
+    /** @deprecated Use `grant_rate` — same value. */
+     | 'registration_rate' | '-grant_rate' | 'grant_rate' | '-latest_filing' | 'latest_filing' | '-name' | 'name';
     include_total?: boolean;
     limit?: number;
     cursor?: string;
@@ -1019,11 +1612,25 @@ export interface OwnerTrademarksParams {
     registration_number?: string;
     ir_number?: string;
     office?: string;
+    /**
+     * Jurisdiction codes selecting rights that protect, or seek protection, in
+     * these territories. Protection-scope by default (a EUTM matches
+     * `jurisdictions: ['FR']`); see `territory_match` to control expansion.
+     */
     jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
     offices?: string | string[];
     owner_country?: string;
     nice_classes?: number | number[];
     vienna_codes?: string | string[];
+    us_design_codes?: string | string[];
+    filing_basis?: string | string[];
+    us_register_type?: 'principal' | 'supplemental';
+    opposition_status?: OppositionStatus;
+    opposition_closes_before?: string;
+    opposition_closes_after?: string;
+    seniority_claims?: SeniorityClaims;
     filing_date_gte?: string;
     filing_date_gt?: string;
     filing_date_lte?: string;
@@ -1044,6 +1651,22 @@ export interface OwnerTrademarksParams {
     publication_date_gt?: string;
     publication_date_lte?: string;
     publication_date_lt?: string;
+    status_effective_date_gte?: string;
+    status_effective_date_gt?: string;
+    status_effective_date_lte?: string;
+    status_effective_date_lt?: string;
+    priority_date_gte?: string;
+    priority_date_gt?: string;
+    priority_date_lte?: string;
+    priority_date_lt?: string;
+    first_use_anywhere_date_gte?: string;
+    first_use_anywhere_date_gt?: string;
+    first_use_anywhere_date_lte?: string;
+    first_use_anywhere_date_lt?: string;
+    first_use_in_commerce_date_gte?: string;
+    first_use_in_commerce_date_gt?: string;
+    first_use_in_commerce_date_lte?: string;
+    first_use_in_commerce_date_lt?: string;
     termination_date_gte?: string;
     termination_date_gt?: string;
     termination_date_lte?: string;
@@ -1064,6 +1687,20 @@ export interface OwnerTrademarksParams {
     is_madrid?: boolean;
     is_retracted?: boolean;
     is_series_mark?: boolean;
+    international_registrations?: 'grouped' | 'expanded';
+    include_total?: boolean;
+    include?: TrademarkSearchInclude[];
+    fields?: string[];
+    /** Text query to match against the mark text within this portfolio. Required for any deterministic `match` mode. */
+    q?: string;
+    /**
+     * ENG-106 — how `q` matches the mark text. `'similar'` (default, ranked) vs
+     * the deterministic `'exact'` / `'starts_with'` / `'ends_with'` / `'contains'`
+     * modes. Deterministic modes require `q`; `'contains'` needs a folded query ≥ 3 chars.
+     */
+    match?: MatchMode;
+    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
+    mark_text_not_contains?: string;
     limit?: number;
     cursor?: string;
 }
@@ -1072,13 +1709,16 @@ export interface OwnerTrademarksParams {
  * always returns the full detail tier (aliases, identifiers, scalar stats).
  * This empty params type is reserved for future use.
  */
-export interface AttorneyRetrieveParams {
-}
+export type AttorneyRetrieveParams = Record<string, never>;
 export interface AttorneyListParams {
     q?: string;
     firm_id?: string;
     country_code?: string;
-    sort?: '-trademark_count' | 'trademark_count' | '-name' | 'name';
+    sort?: '-trademark_count' | 'trademark_count'
+    /** @deprecated Use `grant_rate` — same value. */
+     | '-registration_rate'
+    /** @deprecated Use `grant_rate` — same value. */
+     | 'registration_rate' | '-grant_rate' | 'grant_rate' | '-avg_prosecution_days' | 'avg_prosecution_days' | '-latest_filing' | 'latest_filing' | '-name' | 'name';
     limit?: number;
     cursor?: string;
 }
@@ -1101,11 +1741,25 @@ export interface AttorneyTrademarksParams {
     registration_number?: string;
     ir_number?: string;
     office?: string;
+    /**
+     * Jurisdiction codes selecting rights that protect, or seek protection, in
+     * these territories. Protection-scope by default (a EUTM matches
+     * `jurisdictions: ['FR']`); see `territory_match` to control expansion.
+     */
     jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
     offices?: string | string[];
     owner_country?: string;
     nice_classes?: number | number[];
     vienna_codes?: string | string[];
+    us_design_codes?: string | string[];
+    filing_basis?: string | string[];
+    us_register_type?: 'principal' | 'supplemental';
+    opposition_status?: OppositionStatus;
+    opposition_closes_before?: string;
+    opposition_closes_after?: string;
+    seniority_claims?: SeniorityClaims;
     filing_date_gte?: string;
     filing_date_gt?: string;
     filing_date_lte?: string;
@@ -1126,6 +1780,22 @@ export interface AttorneyTrademarksParams {
     publication_date_gt?: string;
     publication_date_lte?: string;
     publication_date_lt?: string;
+    status_effective_date_gte?: string;
+    status_effective_date_gt?: string;
+    status_effective_date_lte?: string;
+    status_effective_date_lt?: string;
+    priority_date_gte?: string;
+    priority_date_gt?: string;
+    priority_date_lte?: string;
+    priority_date_lt?: string;
+    first_use_anywhere_date_gte?: string;
+    first_use_anywhere_date_gt?: string;
+    first_use_anywhere_date_lte?: string;
+    first_use_anywhere_date_lt?: string;
+    first_use_in_commerce_date_gte?: string;
+    first_use_in_commerce_date_gt?: string;
+    first_use_in_commerce_date_lte?: string;
+    first_use_in_commerce_date_lt?: string;
     termination_date_gte?: string;
     termination_date_gt?: string;
     termination_date_lte?: string;
@@ -1146,6 +1816,20 @@ export interface AttorneyTrademarksParams {
     is_madrid?: boolean;
     is_retracted?: boolean;
     is_series_mark?: boolean;
+    international_registrations?: 'grouped' | 'expanded';
+    include_total?: boolean;
+    include?: TrademarkSearchInclude[];
+    fields?: string[];
+    /** Text query to match against the mark text within this portfolio. Required for any deterministic `match` mode. */
+    q?: string;
+    /**
+     * ENG-106 — how `q` matches the mark text. `'similar'` (default, ranked) vs
+     * the deterministic `'exact'` / `'starts_with'` / `'ends_with'` / `'contains'`
+     * modes. Deterministic modes require `q`; `'contains'` needs a folded query ≥ 3 chars.
+     */
+    match?: MatchMode;
+    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
+    mark_text_not_contains?: string;
     limit?: number;
     cursor?: string;
 }
@@ -1154,14 +1838,18 @@ export interface AttorneyClientsParams {
     cursor?: string;
 }
 export interface FirmRetrieveParams {
-    include?: Array<'stats' | 'specializations' | 'jurisdictions' | 'trend' | 'attorneys'>;
+    include?: Array<'attorneys'>;
 }
 export interface FirmListParams {
     q?: string;
     country_code?: string;
     min_attorneys?: number;
     min_filings?: number;
-    sort?: '-trademark_count' | 'trademark_count' | '-attorney_count' | 'attorney_count' | '-registration_rate' | 'registration_rate' | '-name' | 'name';
+    sort?: '-trademark_count' | 'trademark_count' | '-attorney_count' | 'attorney_count'
+    /** @deprecated Use `grant_rate` — same value. */
+     | '-registration_rate'
+    /** @deprecated Use `grant_rate` — same value. */
+     | 'registration_rate' | '-grant_rate' | 'grant_rate' | '-name' | 'name';
     limit?: number;
     cursor?: string;
 }
@@ -1188,11 +1876,25 @@ export interface FirmTrademarksParams {
     registration_number?: string;
     ir_number?: string;
     office?: string;
+    /**
+     * Jurisdiction codes selecting rights that protect, or seek protection, in
+     * these territories. Protection-scope by default (a EUTM matches
+     * `jurisdictions: ['FR']`); see `territory_match` to control expansion.
+     */
     jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
     offices?: string | string[];
     owner_country?: string;
     nice_classes?: number | number[];
     vienna_codes?: string | string[];
+    us_design_codes?: string | string[];
+    filing_basis?: string | string[];
+    us_register_type?: 'principal' | 'supplemental';
+    opposition_status?: OppositionStatus;
+    opposition_closes_before?: string;
+    opposition_closes_after?: string;
+    seniority_claims?: SeniorityClaims;
     filing_date_gte?: string;
     filing_date_gt?: string;
     filing_date_lte?: string;
@@ -1213,6 +1915,22 @@ export interface FirmTrademarksParams {
     publication_date_gt?: string;
     publication_date_lte?: string;
     publication_date_lt?: string;
+    status_effective_date_gte?: string;
+    status_effective_date_gt?: string;
+    status_effective_date_lte?: string;
+    status_effective_date_lt?: string;
+    priority_date_gte?: string;
+    priority_date_gt?: string;
+    priority_date_lte?: string;
+    priority_date_lt?: string;
+    first_use_anywhere_date_gte?: string;
+    first_use_anywhere_date_gt?: string;
+    first_use_anywhere_date_lte?: string;
+    first_use_anywhere_date_lt?: string;
+    first_use_in_commerce_date_gte?: string;
+    first_use_in_commerce_date_gt?: string;
+    first_use_in_commerce_date_lte?: string;
+    first_use_in_commerce_date_lt?: string;
     termination_date_gte?: string;
     termination_date_gt?: string;
     termination_date_lte?: string;
@@ -1233,15 +1951,33 @@ export interface FirmTrademarksParams {
     is_madrid?: boolean;
     is_retracted?: boolean;
     is_series_mark?: boolean;
+    international_registrations?: 'grouped' | 'expanded';
+    include_total?: boolean;
+    include?: TrademarkSearchInclude[];
+    fields?: string[];
+    /** Text query to match against the mark text within this portfolio. Required for any deterministic `match` mode. */
+    q?: string;
+    /**
+     * ENG-106 — how `q` matches the mark text. `'similar'` (default, ranked) vs
+     * the deterministic `'exact'` / `'starts_with'` / `'ends_with'` / `'contains'`
+     * modes. Deterministic modes require `q`; `'contains'` needs a folded query ≥ 3 chars.
+     */
+    match?: MatchMode;
+    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
+    mark_text_not_contains?: string;
     limit?: number;
     cursor?: string;
 }
+export type ProceedingAggregation = 'outcome' | 'party_role' | 'nice_class' | 'office_code' | 'filed_year';
 export interface ProceedingListParams {
     trademark_id?: string;
     proceeding_type?: string;
     status?: string;
     q?: string;
     party_owner_id?: string;
+    party_entity_id?: string;
+    /** Alias for party_entity_id. */
+    entity_id?: string;
     party_role?: 'opponent' | 'petitioner' | 'respondent' | 'intervener' | 'other';
     contested_class?: number;
     office_code?: string;
@@ -1249,10 +1985,26 @@ export interface ProceedingListParams {
     filed_date_lt?: string;
     decision_date_gte?: string;
     decision_date_lt?: string;
+    aggregations?: ProceedingAggregation[];
     sort?: '-filed_date' | 'filed_date' | '-decided_date' | 'decided_date';
     limit?: number;
     cursor?: string;
 }
+export type ConveyanceType = 'assignment' | 'security_interest' | 'release' | 'merger' | 'name_change' | 'license' | 'partial_assignment' | 'correction' | 'entity_conversion' | 'other';
+export interface AssignmentListParams {
+    owner_id?: string;
+    entity_id?: string;
+    trademark_id?: string;
+    conveyance_type?: ConveyanceType | ConveyanceType[];
+    /** Alias for conveyance_type. */
+    type?: ConveyanceType | ConveyanceType[];
+    recorded_date_gte?: string;
+    recorded_date_lt?: string;
+    role?: 'assignor' | 'assignee';
+    sort?: '-recorded_date' | 'recorded_date';
+    limit?: number;
+    cursor?: string;
+}
 export interface ClassificationListParams {
     q?: string;
 }
@@ -1279,6 +2031,110 @@ export interface DateRangeFilter {
     lte?: string;
     lt?: string;
 }
+/** Normalized crop box (fractions of width/height, each in [0,1]). */
+export interface ImageSearchCrop {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Efficient-filtered facets for image search. */
+export interface ImageSearchFilters {
+    offices?: string[];
+    jurisdictions?: string[];
+    statuses?: string[];
+    include?: 'live' | 'all';
+    nice_classes?: number[];
+    feature_types?: string[];
+    vienna_codes?: string[];
+    design_code_keys?: string[];
+}
+export type ImageSearchChannel = 'visual' | 'logo_text' | 'exact_dup' | 'vienna_overlap';
+/**
+ * Image-search request. Provide EXACTLY ONE image source: raw `image` bytes
+ * (multipart upload), an `image_url` (https), or a `media_id`.
+ */
+export interface TrademarkImageSearchParams {
+    /** Query image bytes for a multipart upload. */
+    image?: Blob | ArrayBuffer | Uint8Array;
+    /** Optional filename for the uploaded part. */
+    image_filename?: string;
+    /** https URL of the query image (SSRF-guarded server-side). */
+    image_url?: string;
+    /** Existing media id (med_…) — reuse its stored vector, no re-embed. */
+    media_id?: string;
+    filters?: ImageSearchFilters;
+    /**
+     * How `filters.jurisdictions` matches: `protection` (default) or `direct`.
+     * Top-level field, not nested inside `filters`.
+     */
+    territory_match?: TerritoryMatchMode;
+    crop?: ImageSearchCrop;
+    /** Bounded top-K page size (1-100, default 20). */
+    limit?: number;
+    /** Signal channels (default: visual, logo_text, exact_dup). */
+    channels?: ImageSearchChannel[];
+}
+export interface ImageSearchSignals {
+    visual: {
+        score: number;
+        band: 'identical' | 'strong' | 'moderate' | 'weak';
+        embedding_spec: string;
+    };
+    logo_text: {
+        query_text: string;
+        matched_clause: string;
+    } | null;
+    exact_dup: {
+        checksum_match: boolean;
+        phash_distance: number | null;
+    } | null;
+    vienna_overlap: {
+        codes: string[];
+    } | null;
+}
+export interface ImageSearchHit {
+    object: 'image_search_hit';
+    score: number;
+    band: 'identical' | 'strong' | 'moderate' | 'weak';
+    signals: ImageSearchSignals;
+    matched_image: {
+        image_id: string;
+        checksum: string;
+        office: string;
+        jurisdiction: string;
+        thumbnail_url: string | null;
+    };
+    thumbnail_url: string | null;
+    trademark: TrademarkSummary;
+}
+export interface ImageSearchResults {
+    object: 'list';
+    data: ImageSearchHit[];
+    has_more: boolean;
+    /**
+     * ENG-19 — the returned-hit count rides `pagination.total_count`
+     * (`total_count_approximate` is always `false`: image search is bounded
+     * top-K, the count is exact). Both are ALWAYS emitted by this endpoint.
+     * The former `search_meta.total_results` was removed in the ENG-14 beta
+     * break.
+     */
+    pagination: {
+        cursor: string | null;
+        total_count: number;
+        total_count_approximate: false;
+    };
+    search_meta: {
+        search_id: string;
+        query_mode: 'upload' | 'image_url' | 'media_id';
+        channels: ImageSearchChannel[];
+        embedding_spec: string;
+        retrieval_bundle: string;
+        index_version: number;
+        execution_time_ms: number;
+    };
+    request_id?: string;
+}
 export interface TrademarkSearchBody {
     /** Optional text query. When omitted, results are filter-only. */
     query?: string;
@@ -1286,6 +2142,15 @@ export interface TrademarkSearchBody {
     strategies?: ('exact' | 'phonetic' | 'fuzzy' | 'prefix')[];
     /** Ranking profile to use. */
     ranking_profile?: string;
+    /**
+     * ENG-106 — how `query` matches the mark text. `'similar'` (default, ranked)
+     * vs the deterministic `'exact'` / `'starts_with'` / `'ends_with'` /
+     * `'contains'` modes. Deterministic modes require `query` and disallow
+     * `strategies` / `ranking_profile`; `'contains'` needs a folded query ≥ 3 chars.
+     */
+    match?: MatchMode;
+    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
+    mark_text_not_contains?: string;
     filters?: {
         /**
          * Coarse status bucket. Accepts a single value or an array to match any
@@ -1306,12 +2171,23 @@ export interface TrademarkSearchBody {
         owner_country?: string;
         nice_classes?: number[];
         vienna_codes?: string[];
+        us_design_codes?: string[];
+        filing_basis?: string[];
+        us_register_type?: 'principal' | 'supplemental';
+        opposition_status?: OppositionStatus;
+        opposition_closes_before?: string;
+        opposition_closes_after?: string;
+        seniority_claims?: SeniorityClaims;
         goods_services_text?: string;
         filing_date?: DateRangeFilter;
         registration_date?: DateRangeFilter;
         expiry_date?: DateRangeFilter;
         renewal_due_date?: DateRangeFilter;
         publication_date?: DateRangeFilter;
+        status_effective_date?: DateRangeFilter;
+        priority_date?: DateRangeFilter;
+        first_use_anywhere_date?: DateRangeFilter;
+        first_use_in_commerce_date?: DateRangeFilter;
         termination_date?: DateRangeFilter;
         updated_at?: DateRangeFilter;
         owner_id?: string;
@@ -1334,7 +2210,7 @@ export interface TrademarkSearchBody {
         is_series_mark?: boolean;
     };
     options?: {
-        aggregations?: ('status_stage' | 'office_code' | 'jurisdiction_code' | 'nice_classes' | 'filing_year' | 'mark_feature_type' | 'mark_legal_category' | 'filing_route' | 'right_kind' | 'scope_kind')[];
+        aggregations?: TrademarkAggregationName[];
         aggregations_only?: boolean;
         include_total?: boolean;
         highlights?: boolean;
@@ -1349,6 +2225,14 @@ export interface TrademarkSearchBody {
     sort?: string;
     limit?: number;
     cursor?: string;
+    international_registrations?: 'grouped' | 'expanded';
+    /**
+     * How `filters.jurisdictions` matches: `protection` (default) or `direct`.
+     * Top-level field, NOT nested inside `filters`.
+     */
+    territory_match?: TerritoryMatchMode;
+    include?: TrademarkSearchInclude[];
+    fields?: string[];
 }
 /**
  * @deprecated Use `TrademarkSearchBody` instead. The `/v1/trademarks/search`
@@ -1447,6 +2331,59 @@ export interface SavedSearchExecuteParams {
     limit?: number;
     cursor?: string;
 }
+/** Feedback type discriminator. */
+export type FeedbackType = 'data_issue' | 'bug' | 'feature_request' | 'other';
+/** Feedback lifecycle status. */
+export type FeedbackStatus = 'open' | 'acknowledged' | 'resolved';
+/** A submitted feedback item. */
+export interface Feedback {
+    id: string;
+    object: 'feedback';
+    /** Public ID (key_…) of the API key that filed this report; null if unattributed. */
+    api_key_id: string | null;
+    type: FeedbackType;
+    status: FeedbackStatus;
+    message: string;
+    /** Public ID of the referenced entity, if any (tm_/own_/…). */
+    resource_id: string | null;
+    /** The request_id the customer referenced, echoed verbatim. */
+    request_ref: string | null;
+    field: string | null;
+    expected_value: string | null;
+    context: Record<string, unknown>;
+    resolution_note: string | null;
+    metadata: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+    resolved_at: string | null;
+}
+/** Body for `feedback.create(...)`. */
+export interface FeedbackCreateParams {
+    type: FeedbackType;
+    message: string;
+    /** Optional public ID of any referenced entity (tm_/own_/att_/firm_/prc_/…). */
+    resource_id?: string;
+    /** Optional request_id (req_…) where the problem was observed. */
+    request_id?: string;
+    /** For data issues: which field is wrong. */
+    field?: string;
+    /** For data issues: the expected value. */
+    expected_value?: string;
+    metadata?: Record<string, string>;
+}
+/** Query params for `feedback.list(...)`. All filters optional and combinable. */
+export interface FeedbackListParams {
+    /** Filter by type(s). */
+    type?: FeedbackType | FeedbackType[];
+    /** Filter by status(es). */
+    status?: FeedbackStatus | FeedbackStatus[];
+    /** Return feedback created at or after this time (YYYY-MM-DD or ISO 8601). */
+    created_at_gte?: string;
+    /** Return feedback created strictly before this time (YYYY-MM-DD or ISO 8601). */
+    created_at_lt?: string;
+    cursor?: string;
+    limit?: number;
+}
 /**
  * Body for `watches.create(...)`.
  *
@@ -1465,6 +2402,11 @@ export interface WatchCreateParams {
      * {@link WatchDeliveryMode} union for forward compatibility.
      */
     delivery_mode?: 'always_per_alert';
+    /**
+     * Customer passthrough label echoed back on the watch and on every alert it
+     * fires. Max 200 chars on create; pass `null` to clear.
+     */
+    customer_reference?: string | null;
     metadata?: Record<string, unknown>;
 }
 /**
@@ -1486,6 +2428,11 @@ export interface WatchUpdateParams {
     delivery_mode?: 'always_per_alert';
     /** PATCH supports active/paused only — use `pause()` / `resume()` for clarity. */
     status?: 'active' | 'paused';
+    /**
+     * Customer passthrough label echoed back on the watch and on every alert it
+     * fires. Max 200 chars on create; pass `null` to clear.
+     */
+    customer_reference?: string | null;
     metadata?: Record<string, unknown>;
 }
 export interface WatchListParams {
@@ -1508,6 +2455,14 @@ export interface WatchPreviewParams {
     query: WatchQuery | Record<string, unknown>;
     /** Trial window for the dry-run match count (1..365 days). Default 7. */
     trial_window_days?: number;
+    /**
+     * Skip hydrating the matching marks and return only `estimated_match_count`.
+     * The cheap path for high-frequency "how many would this catch" calls.
+     * Default false — `results` are returned by default.
+     */
+    count_only?: boolean;
+    /** Page size for `results` (1..50, default 20). Ignored when count_only. */
+    result_limit?: number;
 }
 /** Body for `watches.bulk(body)` — up to 100 watches in one call. */
 export interface WatchBulkParams {
@@ -1516,6 +2471,13 @@ export interface WatchBulkParams {
 export interface AlertListParams {
     severity?: AlertSeverity;
     event_type?: AlertEventType;
+    /**
+     * Which evaluation epochs to include. `'current'` (default) returns only
+     * alerts from the watch's current evaluation epoch — alerts from prior query
+     * revisions (bumped via `/replay`) are excluded. `'all'` returns every alert
+     * regardless of the epoch it fired under.
+     */
+    epoch?: 'all' | 'current';
     limit?: number;
     cursor?: string;
 }
@@ -1616,6 +2578,571 @@ export interface UsageSummaryParams {
     /** Restrict summary to a specific endpoint type. */
     endpoint_type?: string;
 }
+/** Shared `GET /v1/screening` options (everything except the candidate). */
+export interface ScreenOptions {
+    /** Intended Nice class numbers (1-45). */
+    nice_classes?: number[];
+    /** Free-text description of intended goods/services (max 2,000 characters). */
+    goods_services?: string;
+    /** Restrict to these jurisdiction (territory) codes. */
+    jurisdictions?: string[];
+    /** Restrict to these registering office codes. */
+    offices?: string[];
+    /** `live` (default) keeps live marks; `all` includes dead marks. */
+    include?: 'live' | 'all';
+    /** Band-admission threshold. */
+    sensitivity?: 'strict' | 'standard' | 'broad';
+    /**
+     * BETA (flag-gated) — goods/services resolution cascade knob. `auto` (default) runs the
+     * deterministic + semantic-on-refusal cascade (bimodal latency; the tier-3 LLM lane adds a
+     * ~4s p50 uncached tail once it lands); `deterministic` is the budget-safe, sub-ms/SLA mode
+     * that never calls the LLM lane; `llm` is not yet implemented (501). Honored only when the
+     * cascade-modes flag is enabled server-side; ignored otherwise.
+     */
+    resolution_mode?: 'auto' | 'deterministic' | 'llm';
+    /** Page size (1-50, default 20). */
+    limit?: number;
+}
+/**
+ * `GET /v1/screening` query parameters. EXACTLY ONE candidate is required:
+ * either `q` (mark text, 2-200 non-whitespace chars) OR `trademark_id`
+ * (an existing register record) — the XOR is enforced at the type level, so
+ * supplying both or neither is a compile error, mirroring the API's 400.
+ */
+export type ScreenParams = ScreenOptions & ({
+    q: string;
+    trademark_id?: never;
+} | {
+    trademark_id: string;
+    q?: never;
+});
+export type ScreeningRiskLevel = 'high' | 'medium' | 'low';
+/**
+ * `GET /v1/screening` verdict. `needs_review` is a would-be `clear` the screen
+ * could not complete to `clear` standard. The usual cause is incomplete register
+ * coverage for a requested territory, but a stale corpus, a capped analysis
+ * horizon, a failed lane, an unsupported language, low-confidence class
+ * inference, or a coverage assessment that could not be read at all produce it
+ * too. Inspect `ScreenResult.screening.coverage` for the details when present,
+ * it can be absent when the assessment itself failed. Found conflicts still band
+ * `high_risk` / `caution` regardless of coverage. The listing verdict
+ * (`ListingCheckResult.listing.verdict`) is a SEPARATE enum without
+ * `needs_review`, incomplete coverage surfaces there as `caution`.
+ */
+export type ScreeningVerdict = 'clear' | 'caution' | 'needs_review' | 'high_risk';
+export type ScreeningMarkMatchLevel = 'identical' | 'strong' | 'weak';
+export type ScreeningGoodsServicesMatchLevel = 'same_class' | 'related_class' | 'unrelated';
+export type ScreeningLitigationRiskLevel = 'high' | 'medium' | 'low' | 'unknown';
+export type ScreeningCoverageStatus = 'complete' | 'partial' | 'stale' | 'unavailable';
+/** Per-office register freshness on the coverage gate's office axis. */
+export interface ScreeningOfficeCoverage {
+    /** Public office code (WIPO ST.3, e.g. `US`, `EM` for the EUIPO). */
+    office: string;
+    status: ScreeningCoverageStatus;
+    /** Corpus freshness watermark (ISO ts), or `null` when unavailable. */
+    as_of: string | null;
+}
+/** Per-requested-territory protection-scope register coverage. */
+export interface ScreeningTerritoryCoverage {
+    /** Requested territory code (jurisdiction code, e.g. `DE`, `EU`; `EM` normalized to `EU`). */
+    territory: string;
+    /** The territory's own national register; `office` is `null` when no office models it. */
+    national_register: {
+        office: string | null;
+        covered: boolean;
+    };
+    /** Regional registers that also protect here (EU/BX/OA). Empty for a regional request. */
+    regional_registers: Array<{
+        code: string;
+        covered: boolean;
+    }>;
+    /**
+     * For a REGIONAL request (`jurisdictions: ['EU']`) only: since screening
+     * expands a region down to its member states, `uncovered` lists the member
+     * territories whose national register is dark. Absent for a country request.
+     */
+    member_registers?: {
+        total: number;
+        uncovered: string[];
+    };
+    complete: boolean;
+}
+/**
+ * Register-coverage assessment behind a screening verdict. Present whenever the
+ * coverage registry was readable. `complete_for_clear:false` is why an otherwise
+ * `clear` verdict was downgraded to `needs_review`.
+ */
+export interface ScreeningCoverage {
+    /** Office-freshness axis (ST.3 codes). */
+    offices: ScreeningOfficeCoverage[];
+    /** Protection-scope axis (jurisdiction codes). Empty for offices-scoped/unscoped requests. */
+    territories: ScreeningTerritoryCoverage[];
+    classes: {
+        requested: number[];
+        resolved: number[];
+        expanded: number[];
+        searched: number[];
+        source: 'requested' | 'inferred' | 'expanded';
+        inference_confidence: 'high' | 'medium' | 'low' | null;
+    };
+    lanes: {
+        planned: string[];
+        completed: string[];
+        capped: string[];
+        failed: string[];
+    };
+    language: {
+        detected: string | null;
+        supported: boolean;
+    };
+    horizon: {
+        analyzed: number;
+        cap: number;
+        capped: boolean;
+        cap_reason: string | null;
+    };
+    complete_for_clear: boolean;
+}
+/** One banded conflict returned by `GET /v1/screening`. */
+export interface ScreeningHit {
+    object: 'screening_hit';
+    risk_level: ScreeningRiskLevel;
+    reason_codes: string[];
+    mark_match: {
+        level: ScreeningMarkMatchLevel;
+        admitted_match_levels: string[];
+    };
+    goods_services_match: {
+        level: ScreeningGoodsServicesMatchLevel;
+        matched_nice_classes: number[];
+    };
+    jurisdiction_match: {
+        requested: string[];
+        matched: string[];
+    };
+    litigation_risk: {
+        level: ScreeningLitigationRiskLevel;
+        owner_publicly_traded: boolean | null;
+        owner_ticker: string | null;
+        prior_proceedings: number | null;
+        owner_portfolio_size: number | null;
+    };
+    trademark: TrademarkSummary;
+}
+/** `GET /v1/screening` response — bespoke list envelope. */
+export interface ScreenResult {
+    object: 'list';
+    screening: {
+        verdict: ScreeningVerdict;
+        summary: {
+            high: number;
+            medium: number;
+            low: number;
+            truncated: boolean;
+        };
+        litigation_risk: {
+            high: number;
+            medium: number;
+        };
+        candidate: {
+            mark: string;
+            normalized: string;
+            trademark_id?: string;
+        };
+        inferred_nice_classes?: number[];
+        rules_version: string;
+        /**
+         * BETA — present only when the cascade-modes flag is enabled server-side. Request-level
+         * rollup of how the goods/services coverage was resolved, plus per-area suggestion marking
+         * (TUR P1d). Each area carries two independent axes: `method` (which lane produced it) and
+         * `suggested` (whether the caller should verify before relying on it) so a consumer can render
+         * an uncertain answer distinctly from a certain one.
+         */
+        resolution?: {
+            /** The resolution_mode the request asked for. */
+            mode_requested: 'auto' | 'deterministic' | 'llm';
+            /**
+             * Deepest cascade lane that actually contributed. `llm`/`llm_cached` are reserved for
+             * tier-3 and not emitted yet.
+             */
+            method: 'deterministic' | 'semantic' | 'llm' | 'llm_cached';
+            /**
+             * Top-1 semantic retrieval score (quantized scale) across the semantic areas that
+             * contributed; null when method is not `semantic`.
+             */
+            top_semantic_score_q: number | null;
+            /**
+             * BETA (tier-3) — the pinned model revision that produced a billed LLM adjudication
+             * (method `llm`/`llm_cached`), so a customer can verify which model they paid for. null on
+             * the deterministic/semantic path.
+             */
+            llm_model: string | null;
+            /**
+             * BETA (tier-3) — cache disposition of an LLM adjudication: `hit` (replayed, billed
+             * llm_cached), `miss` (a model call ran, billed llm), or null (no LLM lane / honest fallback).
+             */
+            cache: 'hit' | 'miss' | null;
+            /** Per-area suggestion marking. */
+            areas: Array<{
+                nice_class: number;
+                label: string;
+                role: 'core' | 'related' | 'adjacent' | 'conditional' | 'administrative';
+                /** WHICH LANE produced this area (provenance only, NOT a certainty claim). */
+                method: 'deterministic' | 'semantic' | 'llm';
+                /**
+                 * WHETHER THE CALLER SHOULD VERIFY before relying on this area (independent of `method`).
+                 * true when semantic-derived, OR confidence is below `high`, OR provenance is a
+                 * low-certainty deterministic source (e.g. class_fallback). Only a high-confidence
+                 * grounded deterministic area is false.
+                 */
+                suggested: boolean;
+                /** Semantic-derived areas are capped at medium; below-high confidence sets suggested=true. */
+                confidence: 'high' | 'medium' | 'low';
+                /** Machine-readable per-area provenance, e.g. `['semantic_match']`, `['class_fallback']`. */
+                basis_codes: string[];
+                /** Quantized semantic score for a semantic area; null on deterministic areas. */
+                score_q: number | null;
+            }>;
+        };
+        as_of: string | null;
+        admitted_match_levels: string[];
+        /**
+         * Register-coverage assessment (protection-scope). Present whenever the
+         * coverage registry was readable. `coverage.complete_for_clear:false` is why
+         * a would-be `clear` was downgraded to `needs_review`.
+         */
+        coverage?: ScreeningCoverage;
+        note?: string;
+        warnings: string[];
+    };
+    data: ScreeningHit[];
+    has_more: boolean;
+    pagination: {
+        cursor: string | null;
+    };
+    request_id?: string;
+}
+/** A structured description of the candidate's intended use. */
+export interface CompareUseProfile {
+    /** Intended Nice class numbers (1-45). */
+    nice_classes?: number[];
+    /** Structured goods/services lines, optionally pinned to a Nice class. */
+    goods_services?: Array<{
+        nice_class?: number;
+        text: string;
+    }>;
+    /** Plain-English description of the business or intended use. */
+    business_description?: string;
+}
+export type CompareCandidate = {
+    trademark_id: string;
+    mark?: never;
+    use?: never;
+} | {
+    trademark_id?: never;
+    mark: string;
+    use: CompareUseProfile;
+};
+export type CompareConflict = {
+    trademark_id: string;
+    mark?: never;
+    nice_classes?: never;
+    goods_services?: never;
+    status?: never;
+} | {
+    trademark_id?: never;
+    mark: string;
+    nice_classes: number[];
+    goods_services?: string;
+    status?: 'active' | 'pending' | 'inactive' | 'unknown';
+};
+/** A compare batch contains at least one and at most ten conflicts. */
+export type CompareConflicts = [CompareConflict] | [CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict] | [CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict, CompareConflict];
+/** `POST /v1/compare` request body. `conflicts` accepts 1-10 items. */
+export interface CompareParams {
+    candidate: CompareCandidate;
+    conflicts: CompareConflicts;
+    jurisdictions?: string[];
+    offices?: string[];
+}
+export type ComparisonStatus = 'ok' | 'not_found' | 'not_comparable';
+export type CompareRiskLevel = 'high' | 'medium' | 'low';
+export type CompareMarkMatchLevel = 'identical' | 'strong' | 'weak' | 'none';
+export type CompareGoodsServicesLevel = 'same_class' | 'related_class' | 'unrelated';
+/** One request-ordered pair result from `POST /v1/compare`. */
+export interface ComparisonResult {
+    object: 'comparison_result';
+    comparison_status: ComparisonStatus;
+    /** Conservative human-review signal: true for ok pairs where a mark-similarity clause fired. */
+    review_recommended: boolean;
+    /** Open vocabulary; tolerate warnings added in future. */
+    warnings: string[];
+    conflict: {
+        trademark_id?: string;
+        mark: string | null;
+        nice_classes: number[] | null;
+        status_as_evaluated: string | null;
+        record_as_of: string | null;
+    };
+    risk_level: CompareRiskLevel | null;
+    /** Open vocabulary; tolerate reason codes added in future. */
+    reason_codes: string[] | null;
+    mark_match: {
+        level: CompareMarkMatchLevel;
+        /** Compare engine clauses; unlike Screening, Compare has no sensitivity admission gate. */
+        matched_levels: string[];
+    } | null;
+    goods_services: {
+        level: CompareGoodsServicesLevel;
+        overlap_classes: number[];
+        text_similarity: number | null;
+    } | null;
+    similarity: {
+        string: number;
+        phonetic: number;
+        /** Reserved for a future semantic dimension; currently always `null`. */
+        semantic: null | number;
+    } | null;
+}
+/** `POST /v1/compare` response — bespoke list envelope. */
+export interface CompareResult {
+    object: 'list';
+    comparison: {
+        candidate: {
+            trademark_id?: string;
+            mark: string;
+            normalized: string;
+            effective_nice_classes: number[];
+        };
+        rules_version: 'compare-v1.1';
+        /** Serving screening strategy identifier; intentionally not a string literal. */
+        band_rules_version: string;
+        mapping_version: string;
+        resolver: {
+            engine_version: string;
+            ruleset_version: string;
+            catalog_version: string;
+        };
+        as_of: string | null;
+        /** Open vocabulary; tolerate warnings added in future. */
+        warnings: string[];
+        disclaimer: string;
+    };
+    data: ComparisonResult[];
+    summary: {
+        high: number;
+        medium: number;
+        low: number;
+        none: number;
+        not_comparable: number;
+        /** Count of ok results where a mark-similarity clause fired. */
+        review_recommended: number;
+    };
+    has_more: false;
+    pagination: {
+        cursor: null;
+    };
+    request_id: string;
+}
+/**
+ * Coarse listing/candidate verdict band. Beta: common-word listings are
+ * over-flagged, so treat `caution` as no-signal pending the ENG-199 redesign.
+ */
+export type ListingVerdict = 'clear' | 'caution' | 'high_risk';
+/** `POST /v1/screening/listings` request body. Generic commerce-text fields only. */
+export interface ListingCheckParams {
+    /** Listing title (required). */
+    title: string;
+    /** Explicit brand/seller name — always screened, never suppressed. */
+    brand?: string;
+    /** Listing description — high-precision markers only (quoted / ™®-adjacent / "compatible with X"). */
+    description?: string;
+    /** Platform-neutral tags/keywords/search terms. */
+    keywords?: string[];
+    /** Listing category label — context only, never itself a candidate. */
+    category?: string;
+    /** Intended Nice class numbers (1-45). */
+    nice_classes?: number[];
+    /** Restrict to these jurisdiction (territory) codes. */
+    jurisdictions?: string[];
+    /** Restrict to these registering office codes. */
+    offices?: string[];
+    /** `live` (default) keeps live marks; `all` includes dead. */
+    include?: 'live' | 'all';
+    /** Band-admission threshold for the primary tier. Title/keyword tier is always `strict`. */
+    sensitivity?: 'strict' | 'standard' | 'broad';
+}
+/** One DuPont-mapped factor in the informational screening ledger. */
+export interface ScreeningFactorEntry {
+    factor_id: string;
+    dupont_factor: number;
+    assessment: string;
+    confidence: string;
+    evidence: Array<Record<string, unknown>>;
+    limitations: string[];
+    computed_by: string;
+    version: string;
+}
+/** One conflict under a listing candidate (byte-identical to a GET /v1/screening hit + `informational`). */
+export interface ListingCandidateHit {
+    object: 'screening_hit';
+    risk_level: 'high' | 'medium' | 'low';
+    reason_codes: string[];
+    mark_match: {
+        level: string;
+        admitted_match_levels: string[];
+    };
+    goods_services_match: {
+        level: string;
+        matched_nice_classes: number[];
+    };
+    jurisdiction_match: {
+        requested: string[];
+        matched: string[];
+    };
+    litigation_risk: Record<string, unknown>;
+    trademark: Record<string, unknown>;
+    /** Surfaced but non-escalating conflict. Informational; not legal advice. */
+    informational?: boolean;
+    /** Closed reason explaining why the conflict is informational. Informational; not legal advice. */
+    informational_reason?: 'unrelated_class_identical' | 'generic_term_no_corroboration' | 'crowded_field_no_corroboration' | 'identical_unrelated_no_corroboration' | 'nominative_compat';
+    /** Origin of the served risk band. Informational; not legal advice. */
+    band_source?: 'v1_table' | 'v3_scorer';
+    /** Additive v3 scorer read; never the served band. Informational; not legal advice. */
+    model_assessment?: {
+        band: 'high' | 'medium' | 'borderline' | 'low';
+        confidence: 'high' | 'medium' | 'low';
+        band_source: 'v1_table' | 'v3_scorer';
+    };
+    /** DuPont factor ledger with supporting evidence. Informational; not legal advice. */
+    factor_ledger?: ScreeningFactorEntry[];
+}
+/**
+ * Analysis-completeness status — closed enum, ORTHOGONAL to verdict. Derived
+ * deterministically from completeness signals; `complete` means the listing was
+ * fully screened. Read this together with `auto_approve_eligible`, not the
+ * tri-state verdict alone. Mirrors `ListingMeta.analysis_status` in the OpenAPI
+ * contract.
+ */
+export type AnalysisStatus = 'complete' | 'incomplete_budget' | 'incomplete_timeout' | 'incomplete_backend' | 'incomplete_unscreenable' | 'incomplete_variant_shed' | 'incomplete_stale_snapshot' | 'unsupported_language';
+/** Provenance of a matched candidate within the listing (evidence-first payload). */
+export interface ListingMatchCandidate {
+    term: string;
+    normalized: string;
+    tier: 'P' | 'S';
+    field: 'title' | 'brand' | 'description' | 'keywords';
+}
+/**
+ * Evidence-first PRIMARY payload entry: one matched mark, deduped + attributed.
+ * Discriminated on `source`: `live_register` carries live-register `registration`
+ * evidence (rights_domain `trademark`); `curated_bank` carries `bank_entry`
+ * provenance for a non-register persona/character right (rights_domain
+ * `character_ip` | `persona_publicity` | `franchise`). Mirrors the `ListingMatch`
+ * schema in the OpenAPI contract.
+ */
+export type ListingMatch = {
+    object: 'listing_match';
+    source: 'live_register';
+    disposition: 'actionable' | 'informational';
+    reason_codes: string[];
+    /** Live-register trademark match. */
+    rights_domain: 'trademark';
+    goods_services_text_available: boolean;
+    candidate: ListingMatchCandidate;
+    /** Registration evidence — byte-identical to the matching `data[].hits[]` entry. */
+    registration: ListingCandidateHit;
+} | {
+    object: 'listing_match';
+    source: 'curated_bank';
+    disposition: 'actionable' | 'informational';
+    reason_codes: string[];
+    /** Curated non-register persona/character right — NOT a live-register lookup. */
+    rights_domain: 'character_ip' | 'persona_publicity' | 'franchise';
+    goods_services_text_available: boolean;
+    candidate: ListingMatchCandidate;
+    /** Curated bank provenance — canonical name + review date. Honest labeling. */
+    bank_entry: {
+        canonical: string;
+        review_date: string;
+        note: string;
+    };
+};
+/** One extracted, screened candidate mark. */
+export interface ListingCandidate {
+    object: 'listing_candidate';
+    term: string;
+    normalized: string;
+    tier: 'P' | 'S';
+    reference?: boolean;
+    reference_intent?: 'compat' | 'attribution' | 'prose';
+    counterfeit?: boolean;
+    sources: Array<{
+        field: string;
+        span: [number, number];
+        keyword_index?: number;
+    }>;
+    verdict: ListingVerdict;
+    nice_classes_used: number[];
+    hits: ListingCandidateHit[];
+}
+/** A candidate that was NOT screened, with a closed reason code (auditability). */
+export interface SuppressedListingCandidate {
+    object: 'suppressed_candidate';
+    term: string;
+    normalized: string;
+    field: string;
+    span: [number, number];
+    keyword_index?: number;
+    reason: 'charset' | 'stopword' | 'jargon' | 'descriptive' | 'generic_term' | 'no_index_hit' | 'containment' | 'cap' | 'protected_cap' | 'numeric_id_brand' | 'unscreenable';
+}
+/** `POST /v1/screening/listings` response — bespoke envelope. */
+export interface ListingCheckResult {
+    object: 'list';
+    listing: {
+        verdict: ListingVerdict;
+        summary: {
+            high: number;
+            medium: number;
+            low: number;
+            informational: number;
+        };
+        candidates_screened: number;
+        rules_version: 'screening-v1';
+        verdict_version: components['schemas']['ListingMeta']['verdict_version'];
+        extractor_version: string;
+        selector_version: string;
+        as_of: string | null;
+        warnings: string[];
+        note?: string;
+        analysis_status: AnalysisStatus;
+        auto_approve_eligible: boolean;
+        class_provenance: {
+            source: 'provided_platform' | 'provided_unverified' | 'inferred' | 'none';
+            confidence: number | null;
+        };
+        resolved_nice_classes: number[];
+        /** Content hash of the deterministic dictionaries. */
+        dictionaries_version: string;
+        /** Cheap content hash over the decision-asset version tuple. */
+        decision_asset_version: string;
+        /** Fan-out forms actually evaluated (present whenever variant shedding occurred). */
+        forms_evaluated?: number;
+        /** Total fan-out forms before shedding (present whenever variant shedding occurred). */
+        forms_total?: number;
+    };
+    /**
+     * Evidence-first PRIMARY payload: one entry per matched mark (deduped,
+     * attributed). Leads with disposition + reason codes + registration evidence.
+     */
+    matches: ListingMatch[];
+    data: ListingCandidate[];
+    suppressed: SuppressedListingCandidate[];
+    has_more: boolean;
+    pagination: {
+        cursor: string | null;
+    };
+    request_id?: string;
+}
 /** Per-request overrides. Accepted as the last argument on every method. */
 export interface RequestOptions {
     /** Request timeout in ms. Overrides client default. */
@@ -1659,10 +3186,75 @@ export interface ListResponseBody<T> {
     pagination: {
         cursor: string | null;
         total_count?: number;
+        total_count_approximate?: boolean;
     };
     request_id: string;
     search_meta?: SearchMeta;
+    source_sync?: TrademarkDocumentSourceSync;
     /** Faceted aggregation buckets (V2 search and saved search results). */
     aggregations?: Record<string, Record<string, number>>;
+    /**
+     * TSK-127 — display-name labels for aggregation bucket keys, shaped
+     * `{ <aggName>: { <bucketKey>: name } }`. Currently populated for the
+     * `entity_id` facet (entity id → display name) so consumers can render
+     * human-readable bucket labels without a follow-up lookup.
+     */
+    aggregation_metadata?: Record<string, Record<string, string>>;
+}
+export interface OfficeAnalytics {
+    object: 'office_analytics';
+    code: string;
+    total_marks: number;
+    registered_count: number;
+    pending_count: number;
+    expired_count: number;
+    cancelled_count: number;
+    abandoned_count: number;
+    registration_rate: number | null;
+    jurisdiction_count: number;
+    earliest_filing: string | null;
+    latest_filing: string | null;
+    top_classes: Array<{
+        class: number;
+        count: number;
+        pct: number;
+    }> | null;
+    yearly_trend: Array<{
+        year: number;
+        filed: number;
+        registered: number;
+        abandoned: number;
+    }> | null;
+    stats_computed_at: string;
+    /** Per-request id echoed at the top level of the response body (`*Response` in the OpenAPI spec). */
+    request_id: string;
+}
+export interface MarketAnalytics {
+    object: 'market_analytics';
+    total_marks: number;
+    active_count: number;
+    by_status: Record<string, number>;
+    by_office: Record<string, number>;
+    top_classes: Array<{
+        class: number;
+        count: number;
+        pct: number;
+    }>;
+    filing_trend: Record<string, number>;
+    computed_at: string;
+    /** Per-request id echoed at the top level of the response body (`*Response` in the OpenAPI spec). */
+    request_id: string;
+}
+export interface ClassificationAnalytics {
+    object: 'classification_analytics';
+    nice_class: number;
+    total_marks: number;
+    active_count: number;
+    by_status: Record<string, number>;
+    by_office: Record<string, number>;
+    filing_trend: Record<string, number>;
+    computed_at: string;
+    /** Per-request id echoed at the top level of the response body (`*Response` in the OpenAPI spec). */
+    request_id: string;
 }
 //# sourceMappingURL=types.d.ts.map