@signa-so/sdk 0.16.0 → 0.17.0

package/dist/resources/watches.js

@@ -6,9 +6,27 @@ import { createList } from '../pagination.js';
  * Five watch types compile to one query shape (VAL-PRODUCT-001):
  * `'mark' | 'portfolio' | 'owner' | 'class' | 'similarity'`. `query.match`
  * is rejected in ANY form (object or string) — use `filters.ownerId`,
- * `filters.trademarkIds`, `filters.niceClasses` for scoping and
- * `min_match_tier` for similarity precision. See {@link WatchQuery} and
- * the watches guide for worked examples.
+ * `filters.trademarkIds`, `filters.niceClasses` for scoping.
+ *
+ * Similarity watches (0.17.0) take `version: 'v3'`, `q`, `similarity` (the
+ * search channels; {@link Presets} spread in) and `min_tier` (the weakest
+ * tier that alerts, default `related`):
+ *
+ * ```typescript
+ * await signa.watches.create({
+ *   name: 'LIMBER look-alikes',
+ *   watch_type: 'similarity',
+ *   query: { version: 'v3', q: 'limber', ...Presets.clearance, min_tier: 'similar' },
+ * });
+ * ```
+ *
+ * The old `strategies` / `min_match_tier` keys are accepted by the API until
+ * 2026-12-28 and reported in the response `deprecations`; a watch written
+ * with them keeps its legacy matching until it is re-saved without them.
+ * Every other written query is stored as `v3`, even a plain
+ * `{ version: 'v2', q }`. Preview and
+ * diagnostics report `similarity_applied` and `min_tier` (`null` for a watch
+ * in the old form). See {@link WatchQuery} and the watches guide.
  */
 export class Watches extends BaseResource {
     /** Create a watch. */

package/dist/resources/watches.js.map

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

package/dist/types.d.ts

@@ -455,51 +455,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).
  *
- * 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.
+ * 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.
+ *
+ * `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 +531,12 @@ export interface Watch {
     metadata: Record<string, unknown>;
     created_at: string;
     updated_at: string;
+    /**
+     * 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 +613,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).
@@ -1133,6 +1154,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 +1207,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 →
@@ -1544,21 +1576,15 @@ 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). `strategies_used` and `match` are deprecated and removed on
+ * 2026-12-28. `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 +1592,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 +1734,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). Replaces a list in `q` and `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 +1857,7 @@ 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 SearchTextParams {
     /**
      * 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 +1973,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 +1996,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 +2112,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 +2217,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 +2238,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 +2343,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 +2370,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 +2475,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;
 }
@@ -2474,7 +2561,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 +2677,21 @@ 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}.
+     */
+    q?: 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 +2759,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 +2773,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;