@signa-so/sdk 0.16.0 → 0.21.0

package/dist/types.d.ts

@@ -199,8 +199,10 @@ export type DeadlineListRow = components['schemas']['DeadlineListRow'];
  * A maintenance rule that applies to a mark but was declined because the
  * record lacks the date the statute anchors it on, so no deadline row exists
  * for it. Carried as `unsupported_rules` on `POST /v1/deadlines/compute`
- * items and `unsupported_marks[]` entries, and as
- * `derived.deadlines.unsupported_rules` on a trademark row.
+ * items and `unsupported_marks[]` entries, as
+ * `derived.deadlines.unsupported_rules` on a trademark row, and as
+ * `computed.unsupported_rules` on a `POST /v1/reconcile` result requested
+ * with `verdict_detail: true`.
  */
 export type UnsupportedDeadlineRule = components['schemas']['UnsupportedDeadlineRule'];
 /**
@@ -455,51 +457,60 @@ export type WatchStatus = 'active' | 'paused' | 'disabled';
  * (= `ALERT_EVENT_TYPES` from `@signa/types`) and `DEFAULT_TRIGGER_EVENTS`.
  */
 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. */
+/**
+ * Legacy attribution tier gate, echoed by diagnostics for a watch stored in
+ * the v1/v2 form. New watches use `min_tier` ({@link MatchTier}).
+ */
 export type WatchMinMatchTier = 'exact' | 'normalized' | 'fuzzy' | 'phonetic';
 /**
- * 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
+ * Watch query DSL. Five watch types share one shape; the `watch_type`
+ * selects which scoping field is required. See the
  * [Watches guide](https://docs.signa.so/guides/monitoring/watches) for
  * the per-type required-field table.
  *
- * `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.). `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).
+ * Send `version: 'v3'`, `q`, optional `similarity` (the search channels,
+ * same default as search) and optional `min_tier` (the weakest
+ * {@link MatchTier} that alerts; default `related`, everything through).
+ * The API stores every written query as `v3` whatever `version` it sends, so
+ * a plain `{ version: 'v2', q }` gets the default channels and `min_tier:
+ * 'related'` too. `filters` keeps its camelCase vocabulary (`trademarkIds`,
+ * `ownerId`, `niceClasses`, `jurisdictions`, `offices`, ...).
+ * `trigger_events` narrows which lifecycle events fire alerts. Watches do
+ * not accept the search `mark_text_*` filters or exclusions (400).
+ *
+ * The old `strategies` and `min_match_tier` keys are removed from this type
+ * (0.17.0). The API still accepts them until 2026-12-28: a watch written
+ * with them is kept as a legacy watch, with its original matching, until it
+ * is re-saved without them, and the write response lists them in
+ * `deprecations`. Stored watches are never rewritten: a watch saved in the
+ * v1/v2 form keeps its matching until its query changes.
  *
- * 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
- * `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.
+ * `score_threshold` is NOT supported on write (400); scores are
+ * informational (see `match.score` on alerts). Forbidden DSL keys
+ * (`function_score`, `script`, `sort`, `cursor`, `aggregations`,
+ * `highlight`) and `query.match` in any form are rejected with 400. Unknown
+ * `filters` keys are rejected with 400 listing the allowed vocabulary.
  */
 export interface WatchQuery {
-    /** `"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. */
+    /**
+     * Required on write. `'v1'`, `'v2'` and `'v3'` are accepted; send `'v3'`. A new or changed query is
+     * stored as `'v3'` whatever version it sends, unless it uses the deprecated keys; `'v1'` / `'v2'`
+     * otherwise appear only on stored legacy queries.
+     */
+    version: 'v1' | 'v2' | 'v3';
+    /** Search text (required for similarity watches). */
     q?: string;
-    /** Search strategies to use. Omit for the public-search default (`exact` + `fuzzy`). */
-    strategies?: WatchSearchStrategy[];
+    /** Similarity channels for `q`. Omit for the search default (`identical`, `fuzzy`, `embedded`, `lookalike`). */
+    similarity?: readonly SimilarityChannel[];
+    /** The weakest similarity tier that alerts. Default `related` (every tier). */
+    min_tier?: MatchTier;
     /** 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[];
-    /** 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).
+     * 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.
      */
@@ -522,6 +533,16 @@ export interface Watch {
     metadata: Record<string, unknown>;
     created_at: string;
     updated_at: string;
+    /** Health state; populated on list and retrieve, `null` on create/update responses. */
+    health_status: components['schemas']['Watch']['health_status'];
+    /** Health with per-office coverage and issues; populated only on retrieve, `null` elsewhere. */
+    health: components['schemas']['Watch']['health'];
+    /**
+     * Present on create, update and bulk responses when the written query used
+     * a deprecated key (`strategies`, `min_match_tier`); the watch is kept as a
+     * legacy watch until re-saved without them.
+     */
+    deprecations?: SearchDeprecation[];
 }
 /**
  * Alert event types — what the API actually emits for `Alert.event_type`.
@@ -598,6 +619,12 @@ export interface AlertMatch {
     score: number | null;
     /** What the score is derived from, e.g. `opensearch_relevance`; null when none. */
     score_basis: string | null;
+    /**
+     * Similarity tier of the matched mark, the same label a search hit carries
+     * as `match.tier`. `null` for filter-only watches, marks found only by their
+     * number, and alerts emitted before 0.17.0.
+     */
+    tier: MatchTier | null;
 }
 /**
  * Compact mark summary embedded on the alert (Alerts v2 `trademark` block).
@@ -728,19 +755,21 @@ export interface Alert {
 /**
  * Webhook event types delivered by the dispatcher.
  *
- * The first three are the STATIC subscribable set for `enabled_events` — the
+ * The first four are the STATIC subscribable set for `enabled_events`: the
  * API accepts them at all times, independently of our rollout state. Source of
  * truth: `WEBHOOK_SUBSCRIBABLE_EVENT_TYPES` in `@signa/types`, pinned by
  * `packages/types/src/api-events.test.ts` (a source-text pin, because the
  * published SDK must not depend on `@signa/types` at runtime).
  *
- * `trademark.status_changed` and `office_action.issued` are delivered only for
- * marks in one of the organization's portfolios.
+ * `trademark.status_changed`, `trademark.corrected` and `office_action.issued`
+ * are delivered only for marks in one of the organization's portfolios. An
+ * endpoint subscribed to `trademark.status_changed` also receives
+ * `trademark.corrected` ({@link TrademarkCorrectedEvent}).
  *
  * `webhook.test` is the shape delivered by `webhooks.test()` only; it is not a
  * subscribable type and `enabled_events` rejects it.
  */
-export type WebhookEventType = 'alert.created' | 'trademark.status_changed' | 'office_action.issued' | 'webhook.test';
+export type WebhookEventType = 'alert.created' | 'trademark.status_changed' | 'trademark.corrected' | 'office_action.issued' | 'webhook.test';
 /**
  * What arrives at a customer webhook endpoint, in the body of the POST
  * (Round 4 R4.5 — TSK-111 monitoring v1).
@@ -934,6 +963,31 @@ export type TrademarkStatusChangedEvent = Omit<WebhookEvent<TrademarkStatusChang
     type: 'trademark.status_changed';
     payload_version: number;
 };
+/**
+ * Why a `trademark.corrected` status change is a correction of a status Signa
+ * published earlier.
+ *
+ * - `status`: Signa published a wrong status and this event reverses it (for
+ *   example a mark shown as expired that the office records as renewed).
+ * - `late_office_record`: office records reached Signa late and show the mark
+ *   lapsing, or a dead mark returning.
+ */
+export interface TrademarkCorrection {
+    kind: 'status' | 'late_office_record';
+}
+/**
+ * `trademark.corrected` data: the {@link TrademarkStatusChangedData} body (same
+ * keys, same `payload_version` rules) plus `correction`. Delivered for marks in
+ * one of the organization's portfolios, to every endpoint subscribed to
+ * `trademark.status_changed` or `trademark.corrected`.
+ */
+export interface TrademarkCorrectedData extends TrademarkStatusChangedData {
+    correction: TrademarkCorrection;
+}
+export type TrademarkCorrectedEvent = Omit<WebhookEvent<TrademarkCorrectedData>, 'type' | 'payload_version'> & {
+    type: 'trademark.corrected';
+    payload_version: number;
+};
 /**
  * `office_action.issued` data at `payload_version` 1: the prosecution row's
  * fields flattened beside the identity fields.
@@ -1133,6 +1187,12 @@ export interface WatchPreviewResponse {
     has_more?: boolean;
     /** Echo of the effective page size for `results`. Omitted when count_only. */
     result_limit?: number;
+    /** The similarity channels the query runs. `null` without `q` and for a query with the deprecated keys. */
+    similarity_applied: SimilarityChannel[] | null;
+    /** The weakest tier that alerts. `null` for a query with the deprecated keys. */
+    min_tier: MatchTier | null;
+    /** Deprecated query keys the previewed query used (see {@link Watch.deprecations}). */
+    deprecations?: SearchDeprecation[];
     request_id: string;
 }
 /**
@@ -1180,7 +1240,12 @@ export interface WatchDiagnostics {
      * INERT — no longer gates matching, and rejected on new writes.
      */
     score_threshold: number | null;
+    /** Legacy tier gate of a watch stored in the v1/v2 form; `null` otherwise. */
     min_match_tier: WatchMinMatchTier | null;
+    /** The similarity channels the watch query runs. `null` without `q`, and for a legacy watch (stored with the deprecated keys, or before v3 and not re-saved since). */
+    similarity_applied: SimilarityChannel[] | null;
+    /** The weakest tier that alerts. `null` for a legacy watch (stored with the deprecated keys, or before v3 and not re-saved since), which reports `min_match_tier`. */
+    min_tier: MatchTier | null;
     alert_fired: boolean;
     /**
      * Walked in order: alert fired → office not in scope → freshness limit →
@@ -1233,6 +1298,13 @@ export interface WatchDiagnostics {
         close_adjustment: HolidayAdjustment | null;
         window_status: WatchDiagnosticsWindowStatus | null;
     } | null;
+    /** Consecutive evaluation failures on this watch/office checkpoint (0 = healthy); null without a checkpoint. */
+    evaluation_consecutive_failures: number | null;
+    /**
+     * Sanitized class of the last evaluation error for this office (e.g.
+     * `entity_unresolved`, `budget_declined`); never a raw error string.
+     */
+    last_evaluation_error: string | null;
     data_window: {
         trademark_changes_retention_days: number;
         outbox_retention_days: number;
@@ -1438,6 +1510,8 @@ export interface TrademarkOrgEventDetail extends OrgEvent {
     source_date?: string | null;
     /** Frozen membership snapshot. See {@link EventPortfolioRef}. */
     portfolios?: EventPortfolioRef[];
+    /** `trademark.corrected` only: why this status change is a correction. See {@link TrademarkCorrection}. */
+    correction?: TrademarkCorrection;
     request_id: string;
 }
 /** Alert-family event detail. Family-specific trademark fields are absent. */
@@ -1544,21 +1618,14 @@ export interface TrademarkDocument {
 }
 /** Owner related entity (GLEIF corporate hierarchy). */
 export type OwnerRelated = components['schemas']['OwnerRelated'];
-/**
- * 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`; `contains` additionally needs a
- * folded query of at least 3 characters.
- */
-export type MatchMode = 'similar' | 'exact' | 'starts_with' | 'ends_with' | 'contains';
 /**
  * Search metadata on trademark search and list responses.
  *
- * 0.14.0: `fallback_reason` is gone; every caveat is a coded entry in
- * `warnings[]` (e.g. `expanded_fallback` with `affected_filters`, or
- * `partial_results`). `index_generation` names the index that served the page;
+ * 0.17.0: `similarity_applied` (the channels `q` ran on), `ranking_version`
+ * (cursors are bound to it), `order` (the order applied), `complete` /
+ * `incomplete_reason` (false only with `allow_partial`), `identifier` (when
+ * `q` was read as a trademark number) and `deprecations` (old parameters the
+ * request used). `index_generation` names the index that served the page;
  * cursors are bound to it, so a cursor from before an index rebuild returns
  * `400 cursor_invalid` and pagination restarts.
  *
@@ -1566,11 +1633,45 @@ export type MatchMode = 'similar' | 'exact' | 'starts_with' | 'ends_with' | 'con
  * (`SignaList.total_count`) when the request sets `include_total`.
  */
 export type SearchMeta = NonNullable<components['schemas']['SearchResponseV2']['search_meta']>;
+/**
+ * A similarity channel for a ranked `q`. The default set is `identical`,
+ * `fuzzy`, `embedded` and `lookalike`; `identical` is always on. See
+ * {@link Presets} for the knockout and clearance sets.
+ */
+export type SimilarityChannel = SearchMeta['similarity_applied'][number];
+/**
+ * `match` on a search hit: `tier` (strongest similarity tier matched; `null`
+ * without `q` or for a hit found only by its number), `via` (channels that
+ * matched, plus `identifier`), `terms` (the `mark_text_*` values the hit
+ * satisfied) and, with `include: ['match_details']`, `details`.
+ */
+export type TrademarkMatch = components['schemas']['TrademarkMatch'];
+/**
+ * Similarity tier, strongest first: `identical`, `near_identical`, `similar`,
+ * `related`. A retrieval category, not a measured edit distance. Used by
+ * search hits (`match.tier`), watch `min_tier` and alerts (`match.tier`).
+ */
+export type MatchTier = NonNullable<TrademarkMatch['tier']>;
+/**
+ * Mark text operators (POST `filters.mark_text` and `exclude.mark_text`).
+ * Values within one operator are OR; operators are AND. Up to 100 values of
+ * 200 characters each.
+ */
+export type MarkTextFilters = components['schemas']['MarkTextFilters'];
+/** One mark text operator: `is`, `word`, `starts_with`, `ends_with`, `contains`, `pattern`. */
+export type MarkTextOperator = keyof MarkTextFilters;
+/** POST `exclude`: rows matching any value are removed. Never affects ranking. */
+export type SearchExclude = components['schemas']['SearchExclude'];
+/**
+ * A `search_meta.deprecations[]` (and watch `deprecations[]`) entry: an old
+ * parameter the request used, its replacement, and the date (`sunset`) from
+ * which the old parameter is a `400`.
+ */
+export type SearchDeprecation = NonNullable<SearchMeta['deprecations']>[number];
 /**
  * A `search_meta.warnings[]` element: a stable `code` plus a human `message`,
- * and the code's own detail fields (`strategy`, `affected_filter(s)`,
- * `affected_offices`, `dropped_strategies`, ...). Keep a default branch: new
- * codes can appear.
+ * and the code's own detail fields (`channel`, `affected_filter(s)`,
+ * `affected_offices`, ...). Keep a default branch: new codes can appear.
  */
 export type SearchWarning = NonNullable<SearchMeta['warnings']>[number];
 /** API error body (RFC 9457-inspired). */
@@ -1674,7 +1775,84 @@ export interface ResourceQuotaExceededErrorBody extends APIErrorBody {
      */
     suggestion?: string;
 }
-export type TrademarkSearchInclude = 'full_goods_services';
+/**
+ * Optional search row projections. `full_goods_services` disables summary G&S
+ * truncation; `match_details` adds `match.details` (matched lanes and applied
+ * ranking factors) to each hit.
+ */
+export type TrademarkSearchInclude = 'full_goods_services' | 'match_details';
+/**
+ * One value or a list for a repeated-key GET param (`mark_text_*`, `*_not`).
+ * A scalar is a one-element list; commas inside a value are never split.
+ */
+export type SearchTextList = string | readonly string[];
+/**
+ * The search request surface shared by `trademarks.list()` and the owner,
+ * attorney, firm and entity `trademarks()` sub-resources (search v2, 0.17.0).
+ *
+ * `q` ranks; the `mark_text_*` filters decide which marks qualify; the
+ * `mark_text_not_*` and `*_not` exclusions remove marks and never affect
+ * ranking. Values within one key are OR; different keys (and `q`) are AND.
+ * The `mark_text_*` and `*_not` lists go on the wire as repeated keys
+ * (`mark_text_is=a&mark_text_is=b`), so a comma inside a mark is safe.
+ *
+ * ```typescript
+ * import { Presets } from '@signa-so/sdk';
+ * await signa.trademarks.list({ q: 'limber', ...Presets.clearance, mark_text_not_is: ['LIMBER'] });
+ * ```
+ */
+export interface SearchTextParams {
+    /**
+     * Search text, ranked through the `similarity` channels (1-500 characters,
+     * at least 2 after folding; 1 on the party sub-resources). Always literal.
+     * A trademark number in `q` (`1939139`, `US 5123456`, `tm_...`) is also
+     * looked up, and its records lead the page (`search_meta.identifier`).
+     */
+    q?: string;
+    /**
+     * Similarity channels for `q`: `identical`, `fuzzy`, `embedded`,
+     * `phonetic`, `lookalike`. Default `identical`, `fuzzy`, `embedded`,
+     * `lookalike`; `identical` is always on. Requires `q`. See {@link Presets}.
+     */
+    similarity?: readonly SimilarityChannel[];
+    /** Whole-mark equality (case, accents, punctuation, spacing and trademark notices ignored), letters as written. Replaces `match: 'exact'`. */
+    mark_text_is?: SearchTextList;
+    /** The value appears as a whole word, or consecutive words, of the mark. */
+    mark_text_word?: SearchTextList;
+    /** The folded mark begins with the value. Replaces `match: 'starts_with'`. */
+    mark_text_starts_with?: SearchTextList;
+    /** The folded mark ends with the value (at least 3 characters). Replaces `match: 'ends_with'`. */
+    mark_text_ends_with?: SearchTextList;
+    /** The value appears anywhere in the folded mark (at least 3 characters). Replaces `match: 'contains'`. */
+    mark_text_contains?: SearchTextList;
+    /** `*` any run, `?` one character, `\` escapes the next character; everything else literal. */
+    mark_text_pattern?: SearchTextList;
+    /** Exclude marks equal to any value (same folding as `mark_text_is`). */
+    mark_text_not_is?: SearchTextList;
+    /** Exclude marks containing any value as a whole word. */
+    mark_text_not_word?: SearchTextList;
+    /** Exclude marks beginning with any value. */
+    mark_text_not_starts_with?: SearchTextList;
+    /** Exclude marks ending with any value. */
+    mark_text_not_ends_with?: SearchTextList;
+    /** Exclude marks containing any value (punctuation and spacing folded, like the other operators). A list since 0.17.0. */
+    mark_text_not_contains?: SearchTextList;
+    /** Exclude marks matching any pattern. */
+    mark_text_not_pattern?: SearchTextList;
+    /** Exclude marks whose owners are linked to these entities (`ent_*`). */
+    entity_id_not?: SearchTextList;
+    /** Exclude marks linked to any entity in these entities' corporate families (`ent_*`). */
+    entity_group_not?: SearchTextList;
+    /** Exclude marks held by these owners (`own_*`). */
+    owner_id_not?: SearchTextList;
+    /** Exclude these trademarks (`tm_*`); on the grouped view, the family row containing them. */
+    trademark_ids_not?: SearchTextList;
+    /**
+     * Return `200` with `search_meta.complete: false` when the search hits its
+     * time limit or loses a shard, instead of a retryable `503`. Default false.
+     */
+    allow_partial?: boolean;
+}
 export type TrademarkDetailInclude = 'office_extensions';
 /**
  * How a `jurisdictions` filter matches. `protection` (default) selects rights
@@ -1720,7 +1898,17 @@ export type TrademarkAggregationName = 'status_stage' | 'office_code' | 'jurisdi
  | 'entity_count';
 /** How aggregation counts relate to filters (`aggregation_mode`). */
 export type TrademarkAggregationMode = 'filtered' | 'exclude_own_filter';
-export interface TrademarkListParams {
+export interface TrademarkListParams extends Omit<SearchTextParams, 'q'> {
+    /**
+     * Search text (see {@link SearchTextParams.q}), or a list of 1-100 terms
+     * (e.g. spelling variants) ranked together through the same `similarity`
+     * channels: a hit ranks by its best term and `match.terms` names the terms
+     * that reached it. A list over 10 terms needs `similarity` limited to
+     * `identical` and `lookalike`; with `fuzzy`, `embedded` or `phonetic` a list
+     * takes 10 terms and 30 words in total. A list is never read as a trademark
+     * number.
+     */
+    q?: string | readonly string[];
     /**
      * Coarse status bucket. Accepts a single value or an array to match any of
      * several values — passing `['active', 'pending']` yields TESS-style "live"
@@ -1836,41 +2024,19 @@ export interface TrademarkListParams {
     is_retracted?: boolean;
     is_series_mark?: boolean;
     international_registrations?: 'grouped' | 'expanded';
-    /**
-     * Optional text query (triggers relevance ranking when no explicit sort),
-     * or a list of exact terms: every mark that is an exact match under
-     * `match: 'exact'` rules (case, accents, punctuation and spacing) for ANY
-     * of the terms, each hit carrying `matched_terms[]`. A list takes 1-100
-     * terms, runs `match: 'exact'` (the default for a list) and costs the same
-     * as one search page. `list()` sends it as a JSON array
-     * (`q=["limber","bimber"]`), and by POST when the query string would pass
-     * the API's 2 KB GET limit.
-     */
-    q?: string | string[];
     /** ENG-67 — faceted bucket counts (TMview "Statistics view"). Field names to aggregate. */
     aggregations?: TrademarkAggregationName[];
     /** `filtered` (default): aggregations respect every filter. `exclude_own_filter`: each aggregation ignores its own filter (drill-down sidebars). */
     aggregation_mode?: TrademarkAggregationMode;
     /** 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[];
-    /**
-     * 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`;
-     * `'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. */
+    /** Optional row projections: `full_goods_services`, `match_details`. */
     include?: TrademarkSearchInclude[];
     /** Sparse top-level field projection. `id` and `object` are always retained. */
     fields?: string[];
@@ -1881,8 +2047,10 @@ export interface TrademarkListParams {
     /**
      * Sort spec. Prefix with `-` for descending. Comma-separated for multi-field.
      * E.g. `-filing_date`, `registration_date`, `-filing_date,office_code`.
-     * When `q` is present and no sort is given, results are ranked by relevance.
-     * When no `q` and no sort, defaults to `-filing_date`.
+     * Default: relevance with `q`; mark text order (exact fits first, then
+     * prefix fits, then shorter marks) with a `mark_text_*` filter and no `q`;
+     * otherwise `-filing_date`. With `q`, `relevance_score` and `match` stay on
+     * every hit under any sort. `search_meta.order` reports the order applied.
      */
     sort?: string;
     limit?: number;
@@ -1995,7 +2163,7 @@ export interface OwnerListParams {
     limit?: number;
     cursor?: string;
 }
-export interface OwnerTrademarksParams {
+export interface OwnerTrademarksParams extends SearchTextParams {
     /**
      * Coarse status bucket. Accepts a single value or an array to match any of
      * several values (e.g. `['active', 'pending']` for TESS-style "live" marks).
@@ -2100,16 +2268,6 @@ export interface OwnerTrademarksParams {
     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;
 }
@@ -2131,7 +2289,7 @@ export interface AttorneyListParams {
     limit?: number;
     cursor?: string;
 }
-export interface AttorneyTrademarksParams {
+export interface AttorneyTrademarksParams extends SearchTextParams {
     /**
      * Coarse status bucket. Accepts a single value or an array to match any of
      * several values (e.g. `['active', 'pending']` for TESS-style "live" marks).
@@ -2236,16 +2394,6 @@ export interface AttorneyTrademarksParams {
     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;
 }
@@ -2273,7 +2421,7 @@ export interface FirmAttorneysParams {
     limit?: number;
     cursor?: string;
 }
-export interface FirmTrademarksParams {
+export interface FirmTrademarksParams extends SearchTextParams {
     /**
      * Coarse status bucket. Accepts a single value or an array to match any of
      * several values (e.g. `['active', 'pending']` for TESS-style "live" marks).
@@ -2378,16 +2526,6 @@ export interface FirmTrademarksParams {
     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;
 }
@@ -2398,8 +2536,25 @@ export interface ProceedingListParams {
     trademark_role?: 'contested' | 'asserted';
     proceeding_type?: string;
     status?: string;
+    /**
+     * Case-insensitive substring of a recorded party name. Combined with
+     * `party_role` / `party_owner_id` / `party_entity_id`, all must match the
+     * same party (`q: 'Acme', party_role: 'opponent'` = Acme is the opponent).
+     */
     q?: string;
+    /**
+     * Proceedings where a party is linked to this owner. Only linked parties
+     * match. Most Canadian and Australian opponents are not linked (they are
+     * matched only against the owner of the mark under challenge), nor are
+     * suffix-only name matches and multi-party names; use `q` for name matching
+     * or complete coverage.
+     */
     party_owner_id?: string;
+    /**
+     * Proceedings where a party is linked to any member owner of the entity.
+     * Linked parties only, as for `party_owner_id`; use `q` for name matching.
+     * Malformed id → 400; over the member-owner cap → 422 `entity_too_large`.
+     */
     party_entity_id?: string;
     /** Alias for party_entity_id. */
     entity_id?: string;
@@ -2474,7 +2629,7 @@ export interface ClassificationSuggestParams {
     description: string;
 }
 /**
- * POST body for `POST /v1/trademarks` (complex queries with filters, aggregations, strategies).
+ * POST body for `POST /v1/trademarks` (structured filters, `mark_text` operators, exclusions, aggregations).
  *
  * This replaces the old `POST /v1/trademarks/search` endpoint.
  */
@@ -2590,23 +2745,22 @@ export interface ImageSearchResults {
 }
 export interface TrademarkSearchBody {
     /**
-     * Optional text query, or a list of exact terms (see
-     * `TrademarkListParams.q`). When omitted, results are filter-only.
+     * Search text, ranked through the `similarity` channels. Always literal;
+     * omit it for a filtered listing. See {@link SearchTextParams.q}; a list of
+     * terms as in {@link TrademarkListParams.q}.
+     */
+    q?: string | readonly string[];
+    /**
+     * Similarity channels for `q` (default `identical`, `fuzzy`, `embedded`,
+     * `lookalike`; `identical` always on). Requires `q`. See {@link Presets}.
      */
-    query?: string | string[];
-    /** Alias for `query`. Send one or the other, not both. */
-    q?: string | string[];
-    /** Search strategies (e.g. 'exact', 'phonetic', 'fuzzy', 'prefix'). */
-    strategies?: ('exact' | 'phonetic' | 'fuzzy' | 'prefix')[];
+    similarity?: readonly SimilarityChannel[];
     /**
-     * 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`; `'contains'` needs a folded query ≥ 3 chars.
+     * Exclusions: `mark_text` operators and the `entity_id`, `entity_group`,
+     * `owner_id` and `trademark_ids` lists. A row matching any value is removed;
+     * exclusions never affect ranking.
      */
-    match?: MatchMode;
-    /** ENG-106 — exclude marks whose text contains this substring (case/accent-insensitive). Composable with any match mode. */
-    mark_text_not_contains?: string;
+    exclude?: SearchExclude;
     filters?: {
         /**
          * Coarse status bucket. Accepts a single value or an array to match any
@@ -2674,6 +2828,12 @@ export interface TrademarkSearchBody {
         is_madrid?: boolean;
         is_retracted?: boolean;
         is_series_mark?: boolean;
+        /**
+         * Mark text operators: `is`, `word`, `starts_with`, `ends_with`,
+         * `contains`, `pattern`. Values within one operator are OR; operators
+         * (and `q`) are AND.
+         */
+        mark_text?: MarkTextFilters;
     };
     options?: {
         aggregations?: TrademarkAggregationName[];
@@ -2682,12 +2842,14 @@ export interface TrademarkSearchBody {
         include_total?: boolean;
         highlights?: boolean;
         include_timing?: boolean;
+        /** Return `200` with `search_meta.complete: false` on an engine timeout or shard failure instead of `503`. Default false. */
+        allow_partial?: boolean;
     };
     /**
      * Sort spec. Prefix with `-` for descending. Comma-separated for multi-field.
-     * When `query` is present and no sort is given, results are ranked by relevance.
-     * When no `query` and no sort, defaults to `-filing_date`.
-     * When explicit sort is set with `query`, relevance scoring is disabled.
+     * Default: relevance with `q`; mark text order with a `filters.mark_text`
+     * operator and no `q`; otherwise `-filing_date`. With `q`, `relevance_score`
+     * and `match` stay on every hit under any sort.
      */
     sort?: string;
     limit?: number;
@@ -3027,6 +3189,7 @@ export interface WebhookDeliveryListParams {
     since?: string;
 }
 export interface OrgEventListParams {
+    /** Event type(s). As on webhooks, `trademark.status_changed` also matches `trademark.corrected`. */
     event_type?: string | string[];
     office_code?: string | string[];
     trademark_id?: string;
@@ -3259,6 +3422,12 @@ export interface ScreeningHit {
         owner_portfolio_size: number | null;
     };
     trademark: TrademarkSummary;
+    /** Origin of the served risk band. Informational; not legal advice. */
+    band_source?: components['schemas']['ScreeningHit']['band_source'];
+    /** Additive v3 scorer read; never the served band. Informational; not legal advice. */
+    model_assessment?: components['schemas']['ScreeningHit']['model_assessment'];
+    /** DuPont factor ledger with supporting evidence. Informational; not legal advice. */
+    factor_ledger?: ScreeningFactorEntry[];
 }
 /** `GET /v1/screening` response — bespoke list envelope. */
 export interface ScreenResult {
@@ -3660,6 +3829,10 @@ export interface ListingCandidate {
     verdict: ListingVerdict;
     nice_classes_used: number[];
     hits: ListingCandidateHit[];
+    /** Derived confidence that this candidate is a real conflict (a projection of verdict and band, not a model). */
+    confidence?: components['schemas']['ListingCandidate']['confidence'];
+    /** Severity rank within the listing (0 = most severe); does not reorder `data`. */
+    rank?: number;
 }
 /** A candidate that was NOT screened, with a closed reason code (auditability). */
 export interface SuppressedListingCandidate {