@signa-so/sdk 0.2.2 → 0.7.0

package/dist/types.d.ts

@@ -2,9 +2,9 @@ import type { components } from './generated/api-types.js';
 /** Full trademark with all optional includes (retrieve response). */
 export type Trademark = components['schemas']['TrademarkDetailResponse'];
 /** Compact trademark in list responses. */
-export type TrademarkSummary = components['schemas']['TrademarkSummary'];
+export type TrademarkSummary = components['schemas']['TrademarkSummaryV1'];
 /** Trademark event in history responses. */
-export type Event = components['schemas']['EventListItem'];
+export type Event = components['schemas']['TrademarkHistoryEvent'];
 /** Stats object shape returned by ?include=stats on attorney detail. */
 export interface AttorneyStats {
     trademark_count: number | null;
@@ -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,78 +32,49 @@ 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;
-}
-/** Specializations (top Nice classes + mark types). */
-export interface Specializations {
-    top_classes: Array<{
-        class: number;
-        count: number;
-        pct: number;
-    }> | null;
-    top_mark_types: Array<{
-        type: string;
-        count: number;
-        pct: number;
-    }> | null;
-}
-/** Top client entry (for attorneys/firms). */
-export interface TopClient {
-    owner_id: string;
-    name: string;
-    count: number;
-}
-/** Top attorney entry (for owners). */
-export interface TopAttorney {
-    attorney_id: string;
-    name: string;
-    count: number;
-}
-/** Jurisdiction breakdown entry. */
-export interface JurisdictionEntry {
-    office: string;
-    count: number;
-    registered?: number;
-    rate?: number;
-    avg_days?: number;
-}
-/** Yearly trend entry. */
-export interface TrendEntry {
-    year: number;
-    filed: number;
-    registered: number;
-    abandoned: number;
-}
 /** 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. */
+    entity_id?: string;
+    entity_id_type?: 'resolved' | 'derived';
+    /** Whether the (possibly entity-inherited) company set includes an active SEC
+     *  company with a ticker. */
+    publicly_traded?: boolean;
+    /** First SEC ticker across the (possibly inherited) company set. */
+    ticker?: string | null;
+    /** First GLEIF LEI across the (possibly inherited) company set. */
+    lei?: string | null;
+    /** Whether any GLEIF LEI is present across the (possibly inherited) set. */
+    has_lei?: boolean;
+    /** `entity` when company facts are inherited across entity members; `direct`
+     *  for an unlinked singleton. */
+    companies_source?: 'entity' | 'direct';
+    /** Public companies — when linked, the union of all members' company links
+     *  (served through the entity). Omitted entirely when empty. */
+    companies?: EntityCompany[];
     related_entities?: {
         parent: {
             id: string;
             object: 'owner';
+            name: string;
             canonical_name: string;
             country_code: string | null;
             entity_type: string | null;
@@ -108,22 +82,79 @@ export type Owner = components['schemas']['OwnerResponse'] & {
         children: Array<{
             id: string;
             object: 'owner';
+            name: string;
             canonical_name: string;
             country_code: string | null;
             entity_type: string | null;
         }>;
     };
     stats?: OwnerStats;
-    specializations?: Specializations;
-    top_attorneys?: TopAttorney[];
-    jurisdictions?: JurisdictionEntry[];
-    trend?: TrendEntry[];
 };
+/** 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';
 };
 /** Full attorney detail (retrieve response). */
 export type Attorney = components['schemas']['AttorneyResponse'] & {
@@ -132,68 +163,214 @@ 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;
     stats?: AttorneyStats;
-    specializations?: Specializations;
-    top_clients?: TopClient[];
-    jurisdictions?: JurisdictionEntry[];
-    trend?: TrendEntry[];
 };
 /** Compact attorney in list responses. */
 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). */
 export interface Firm {
     id: string;
     object: 'firm';
+    name: string;
     canonical_name: string;
-    display_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;
-    specializations?: Specializations;
-    top_clients?: TopClient[];
-    jurisdictions?: JurisdictionEntry[];
-    trend?: TrendEntry[];
     attorneys?: Array<{
         id: string;
         object: 'attorney';
+        name: string;
         canonical_name: string;
         firm_name: string | null;
         country_code: string | null;
         trademark_count: number | null;
     }>;
     attorneys_has_more?: boolean;
-    livemode: boolean;
     request_id: string;
 }
 /** Compact firm in list responses. */
 export interface FirmSummary {
     id: string;
     object: 'firm';
+    name: string;
     canonical_name: string;
-    display_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;
 }
+/** Public-company reference inherited onto an entity member / owner. */
+export interface EntityCompany {
+    source: 'sec' | 'gleif';
+    source_id: string;
+    legal_name?: string;
+    ticker: string | null;
+    exchange: string | null;
+    lei: string | null;
+    entity_status: string;
+    confidence?: number;
+    verified_at?: string | null;
+    verified_by?: string | null;
+}
+/** Public per-member link provenance on an entity-detail member. */
+export interface EntityMemberLink {
+    /** 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 (shared_identifier), when present. */
+    matched_identifiers?: string[];
+}
+/** A member owner embedded in an entity-detail response. */
+export interface EntityMember {
+    id: string;
+    object: 'owner';
+    name: string;
+    canonical_name: string;
+    country_code: string | null;
+    entity_type: string | null;
+    office_code: string | null;
+    /** null on a derived singleton's self-member (it was never linked). */
+    link: EntityMemberLink | null;
+}
+/** Compact entity in list responses (`GET /v1/entities`). */
+export interface EntitySummary {
+    id: string;
+    object: 'entity';
+    name: string;
+    country_code: string | null;
+    entity_type: string | null;
+    entity_id_type: 'resolved' | 'derived';
+    publicly_traded: boolean;
+    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 {
+    id: string;
+    object: 'entity';
+    name: string;
+    country_code: string | null;
+    entity_type: string | null;
+    entity_id_type: 'resolved' | 'derived';
+    /** 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 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;
+}
+/** A node in an entity's GLEIF family (`GET /v1/entities/{id}/family`). */
+export interface EntityFamilyNode {
+    id: string;
+    object: 'entity';
+    name: string;
+    country_code: string | null;
+    relationship: 'parent' | 'direct_subsidiary';
+    source: 'gleif';
+}
+/** GLEIF-curated direct family (parent + direct children, 1 level). */
+export interface EntityFamily {
+    object: 'entity_family';
+    parent: EntityFamilyNode | null;
+    children: EntityFamilyNode[];
+    source: 'gleif';
+    coverage_caveat: string;
+    request_id: string;
+}
 /** Proceeding in list responses. */
 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). */
@@ -207,13 +384,51 @@ 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'];
-/** Deadline rules for a jurisdiction. */
-export type DeadlineRules = components['schemas']['DeadlineRulesDetailResponse'];
+/** 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. */
 export type DesignCode = components['schemas']['DesignCode'];
 /** Vienna design code with children (retrieve response). */
@@ -222,6 +437,16 @@ export type DesignCodeDetail = components['schemas']['DesignCodeDetailResponse']
 export type Classification = components['schemas']['Classification'];
 /** Nice classification with terms (retrieve response). */
 export type ClassificationDetail = components['schemas']['ClassificationDetailResponse'];
+/** Single accepted goods/services term attached to a suggested class. */
+export type AcceptedTerm = components['schemas']['AcceptedTerm'];
+/** One suggested Nice class in the lighter classification suggestion (no terms). */
+export type ClassificationSuggestionLite = components['schemas']['ClassificationSuggestionLite'];
+/** Full response of `POST /v1/classifications/suggest` — lighter shape (classes only, no accepted terms). */
+export type ClassificationSuggestResult = components['schemas']['ClassificationSuggestionResponse'];
+/** One suggested Nice class with rationale + grounded accepted terms. */
+export type GoodsServicesSuggestionClass = components['schemas']['GoodsServicesSuggestionClass'];
+/** Full response of `POST /v1/goods-services/suggest` — classes with accepted terms per class. */
+export type GoodsServicesSuggestResult = components['schemas']['GoodsServicesSuggestionResponse'];
 /** Trademark office. */
 export type Office = components['schemas']['Office'];
 /** Trademark office with detail (retrieve response). */
@@ -230,36 +455,742 @@ export type OfficeDetail = components['schemas']['OfficeDetailResponse'];
 export type Jurisdiction = components['schemas']['Jurisdiction'];
 /** Jurisdiction with detail (retrieve response). */
 export type JurisdictionDetail = components['schemas']['JurisdictionDetailResponse'];
-/** Canonical status with office mappings. */
-export type Status = components['schemas']['StatusMapping'];
+/** Canonical status with office mappings (Phase 2 — manually typed while route is gated). */
+export interface Status {
+    object: 'status_mapping';
+    office_code: string;
+    raw_code: string;
+    status_stage: string;
+    status_reason: string | null;
+    challenge_states: string[];
+    status_source: string;
+    confidence: number;
+    notes: string | null;
+}
 /** Event type code. */
 export type EventType = components['schemas']['EventTypeMapping'];
 /** Portfolio (retrieve response). */
-export type Portfolio = components['schemas']['Portfolio'];
+export interface Portfolio {
+    id: string;
+    object: 'portfolio';
+    name: string;
+    description: string | null;
+    mark_count: number;
+    metadata: Record<string, string> | null;
+    created_at: string;
+    updated_at: string;
+}
 /** Saved search (retrieve response). */
-export type SavedSearch = components['schemas']['SavedSearch'];
-/** Watch (retrieve response). */
-export type Watch = components['schemas']['Watch'];
-/** Alert (retrieve response). */
-export type Alert = components['schemas']['Alert'];
-/** Org-level event list item. */
-export type OrgEvent = components['schemas']['EventListItem'];
-/** Org-level event detail (with changes). */
-export type OrgEventDetail = components['schemas']['EventDetail'];
-/** Identity (GET /me). */
+export interface SavedSearch {
+    id: string;
+    object: 'saved_search';
+    name: string;
+    description: string | null;
+    query: Record<string, unknown>;
+    last_executed_at: string | null;
+    result_count: number | null;
+    metadata: Record<string, string> | null;
+    created_at: string;
+    updated_at: string;
+}
+/** One of the five watch types (VAL-PRODUCT-001). */
+export type WatchType = 'mark' | 'portfolio' | 'owner' | 'class' | 'similarity';
+/** Delivery cadence. */
+export type WatchDeliveryMode = 'always_per_alert' | 'digest_above_threshold' | 'digest_only';
+/** Watch lifecycle status. */
+export type WatchStatus = 'active' | 'paused' | 'disabled';
+/**
+ * Trigger event types — ingestion-emitted fact events a watch can subscribe to.
+ *
+ * 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' | '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. 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
+ * 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).
+ *
+ * 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.
+ */
+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. */
+    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[];
+    /** 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). */
+export interface Watch {
+    id: string;
+    object: 'watch';
+    name: string;
+    watch_type: WatchType;
+    query: WatchQuery | Record<string, unknown>;
+    delivery_mode: WatchDeliveryMode;
+    status: WatchStatus;
+    /** 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;
+}
+/**
+ * Alert event types — what the API actually emits for `Alert.event_type`.
+ *
+ * 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' | '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';
+/**
+ * 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';
+    /** 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';
+/**
+ * What arrives at a customer webhook endpoint, in the body of the POST
+ * (Round 4 R4.5 — TSK-111 monitoring v1).
+ *
+ * Customers should verify the body with the `webhook-id`, `webhook-timestamp`,
+ * and `webhook-signature` headers using a Standard Webhooks library
+ * (`standardwebhooks` on npm, `svix-webhooks` for Python, etc.) before
+ * trusting `data`.
+ *
+ * `id` is a prefixed public ID (e.g. `alt_<uuid>` for `alert.created`) — the
+ * same value as the `webhook-id` header. `timestamp` is an ISO 8601 UTC
+ * instant captured at signing. `data` is the event-specific payload
+ * (see {@link AlertCreatedPayload}).
+ */
+export interface WebhookEvent<T = unknown> {
+    type: WebhookEventType;
+    /** Prefixed event ID — matches the `webhook-id` header. */
+    id: string;
+    /** ISO 8601 UTC timestamp. */
+    timestamp: string;
+    data: T;
+}
+/**
+ * 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.
+ * without conversion.
+ *
+ * Note the absence of `org_id`: the dispatcher omits it because the
+ * customer's webhook endpoint already implies the tenant, and
+ * cross-referencing internal tenant UUIDs is not part of the public API.
+ */
+export interface AlertCreatedFlatFields {
+    /** Prefixed alert ID, e.g. `alt_018f...`. */
+    alert_id: string;
+    /** Prefixed watch ID, e.g. `wat_018f...`. */
+    watch_id: string;
+    /**
+     * Prefixed trademark record ID, e.g. `tm_018f...` — same field name as the
+     * REST {@link Alert} resource (`trademark_id`), so webhook and REST
+     * consumers can share code. Optional: deliveries emitted before the
+     * dual-emit server deploy carry only `trademark_record_id`; prefer
+     * `payload.trademark_id ?? payload.trademark_record_id`.
+     */
+    trademark_id?: string;
+    /**
+     * Prefixed trademark record ID, e.g. `tm_018f...`.
+     * @deprecated Same value as `trademark_id`. Will be REMOVED in API v1.1 —
+     * switch to `trademark_id` (matches the REST Alert resource).
+     */
+    trademark_record_id: string;
+    event_type: AlertEventType;
+    /** Evaluator epoch — bumps via `/replay`. */
+    evaluation_epoch: number;
+    /** Snapshot of trademark version at evaluation time. */
+    content_version: number;
+    severity: AlertSeverity;
+    /** ISO 8601 UTC deadline for customer action; null when 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;
+    /** 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. */
+export type WebhookStatus = 'active' | 'disabled';
+/**
+ * Webhook endpoint (`whk_*`).
+ *
+ * The `secret` field is only present on the response of `webhooks.create()`
+ * and `webhooks.rotateSecret()`. List/retrieve responses redact it.
+ */
+/**
+ * Reason an endpoint transitioned to `status='disabled'`. Mirrors the
+ * `disabled_reason` slug surfaced by the API.
+ *
+ *   `auto_consecutive_100`           — dispatcher trigger A (100 consecutive failures)
+ *   `auto_failure_rate_50_over_50`   — dispatcher trigger B (>50% failure rate over 50 attempts)
+ *   `manual`                         — PATCH status='disabled' or DELETE
+ *   `null`                           — never disabled (or pre-FX3.B history)
+ */
+export type WebhookDisabledReason = 'auto_consecutive_100' | 'auto_failure_rate_50_over_50' | 'manual';
+export interface Webhook {
+    id: string;
+    object: 'webhook_endpoint';
+    url: string;
+    description: string | null;
+    enabled_events: WebhookEventType[] | string[];
+    status: WebhookStatus;
+    secret_version: number;
+    consecutive_failures: number;
+    last_success_at: string | null;
+    last_failure_at: string | null;
+    /** When the endpoint last transitioned to `status='disabled'`. Null when never disabled. */
+    disabled_at: string | null;
+    /** Slug explaining the disable; null when never disabled. See {@link WebhookDisabledReason}. */
+    disabled_reason: WebhookDisabledReason | string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    /** Plaintext secret. Returned ONLY on create / rotate-secret responses. */
+    secret?: string;
+}
+/**
+ * Status of a single webhook delivery attempt.
+ *
+ * Mirrors the `webhook_deliveries_status_check` CHECK constraint in
+ * `packages/db/src/schema/enums.ts`. The dispatcher does NOT use a
+ * transient `'in_flight'` status — concurrent workers coordinate via
+ * `SELECT ... FOR UPDATE SKIP LOCKED` instead (see
+ * `workers/webhook-dispatcher/src/dispatcher.ts:988-995`).
+ *
+ *   `pending`   — queued or scheduled for retry; not yet a final outcome.
+ *   `delivered` — receiver returned 2xx.
+ *   `failed`    — last attempt failed but more retries remain.
+ *   `exhausted` — all 7 attempts failed; replay via /redeliver.
+ */
+export type WebhookDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'exhausted';
+/** A single delivery attempt audit row. */
+export interface WebhookDelivery {
+    /** Raw UUID of the attempt row (deliveries are not prefixed-id resources). */
+    id: string;
+    object: 'webhook_delivery';
+    endpoint_id: string;
+    alert_id: string | null;
+    event_id: string;
+    event_type: string;
+    attempt: number;
+    delivery_attempt_id: string;
+    status: WebhookDeliveryStatus | string;
+    http_status: number | null;
+    response_body: string | null;
+    /**
+     * TSK-115b: terminal-error reason slug. Examples:
+     * `'endpoint_deleted'`, `'endpoint_disabled'`, `'event_unsubscribed'`,
+     * `'ssrf_blocked'`, `'non_2xx_500'`. NULL on happy-path delivered rows.
+     */
+    error_reason: string | null;
+    signature_timestamp: string;
+    next_retry_at: string | null;
+    delivered_at: string | null;
+    created_at: string;
+}
+/** Result of `watches.preview()`. */
+export interface WatchPreviewResponse {
+    object: 'watch_preview';
+    estimated_match_count: number;
+    trial_window_days: number;
+    /**
+     * Present ONLY when `estimated_match_count` is an upper-bound estimate
+     * rather than an exact count. One value, three triggers: the candidacy
+     * scan overflowed the server-side cap, search was temporarily
+     * unreachable, or the server-side time budget expired after candidates
+     * 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;
+}
+/**
+ * Lease state classification for the per-(watch, office) evaluator lease.
+ * Mirrors `LeaseState` in `api/src/services/watch-diagnostics-service.ts`.
+ *
+ *   `held`         — evaluator currently holds an active lease (started <15min ago).
+ *   `released`     — no lease, last evaluation completed cleanly.
+ *   `abandoned`    — stale lease awaiting takeover (>15min old).
+ *   `epoch_raced`  — checkpoint observed an evaluation_epoch lag (replay race).
+ *   `cas_lost`     — last release CAS matched 0 rows; another worker won.
+ */
+export type WatchDiagnosticsLeaseState = 'held' | 'released' | 'abandoned' | 'epoch_raced' | 'cas_lost';
+/** Coarse opposition-window status surfaced under `WatchDiagnostics.opposition.window_status`. */
+export type WatchDiagnosticsWindowStatus = 'open' | 'closed' | 'not_started' | 'unknown';
+/**
+ * Response shape of `watches.diagnostics(id, { trademarkId })`. The 11-field
+ * explainable trace covering candidacy, trigger filter, match outcome,
+ * delivery mode, lease state, epoch provenance, opposition citation, and
+ * retention windows.
+ *
+ * Read-only: this endpoint never writes; it surfaces fields the evaluator
+ * and dispatchers already persisted. When data has aged out of retention
+ * (`data_window.diagnostic_freshness_horizon_days`), fields gracefully
+ * degrade to null/false and `reason` surfaces the freshness limit.
+ */
+export interface WatchDiagnostics {
+    object?: undefined;
+    watch_id: string;
+    trademark_id: string;
+    office_code: string;
+    evaluated: boolean;
+    office_in_scope: boolean;
+    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 → 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;
+    lease_state: WatchDiagnosticsLeaseState | null;
+    evaluation_epoch: number;
+    /** Alert's frozen `evaluation_epoch` when emitted under a replay-bumped epoch; null otherwise. */
+    replay_epoch_origin: number | null;
+    last_relevant_sync_run: {
+        office_code: string;
+        completed_at: string | null;
+        search_indexed_at: string | null;
+    } | 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;
+        rule_version: string | null;
+        window_status: WatchDiagnosticsWindowStatus | null;
+    } | null;
+    data_window: {
+        trademark_changes_retention_days: number;
+        outbox_retention_days: number;
+        indexing_status_retention_days: number;
+        deliveries_retention_days: number;
+        alerts_retention_days: number;
+        diagnostic_freshness_horizon_days: number;
+    };
+    request_id: string;
+}
+/** Options for `watches.diagnostics()`. */
+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';
+    delivery_attempt_id: string;
+    request_id: string;
+}
+/** Result of `webhooks.redeliver()`. */
+export interface WebhookRedeliveryResponse {
+    object: 'webhook_redelivery';
+    delivery_attempt_id: string;
+    request_id: string;
+}
+/** Org-level event list item. IDs are evt_-prefixed opaque strings. */
+export interface OrgEvent {
+    id: string;
+    object: 'event';
+    type: string;
+    trademark_id: string;
+    office_code: string;
+    created_at: string;
+}
+/** Org-level event detail (with field-level before/after diffs). */
+export interface OrgEventDetail extends OrgEvent {
+    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'];
-/** Usage (GET /usage). */
+/** Usage (GET /v1/organization/usage). */
 export type Usage = components['schemas']['Usage'];
 /** API key (list/retrieve). */
 export type ApiKey = components['schemas']['ApiKey'];
 /** API key with the raw key value (returned on create/rotate only). */
 export type ApiKeyWithRawKey = components['schemas']['ApiKeyWithKey'];
+/**
+ * Request log list item (GET /v1/organization/logs).
+ *
+ * Sourced from the inline list-item shape in `RequestLogList.data`. The
+ * detail response (`GET /v1/organization/logs/{request_id}`) is represented
+ * by `RequestLogDetail` and adds top-level `request_id`.
+ */
+export type RequestLog = components['schemas']['RequestLogList']['data'][number];
+/** Request log detail (GET /v1/organization/logs/{request_id}). */
+export type RequestLogDetail = components['schemas']['RequestLogDetail'];
+/** Usage summary response (GET /v1/organization/usage/summary). */
+export type UsageSummaryResponse = components['schemas']['UsageSummaryResponse'];
+/** Usage summary item (row of `UsageSummaryResponse.data`). */
+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;
     object: string;
     deleted: true;
-    livemode: boolean;
     request_id: string;
 }
 /** Trademark source provenance (from raw_record_version). */
@@ -268,15 +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_results: number;
-    total_count_exact: boolean;
+    /**
+     * 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.
+     */
+    warnings?: SearchWarning[];
+    /**
+     * 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.
+     */
     execution_time_ms: number;
 }
 /** API error body (RFC 9457-inspired). */
@@ -286,55 +1289,201 @@ export interface APIErrorBody {
     status: number;
     detail: string;
     instance?: string;
-}
+    /**
+     * Server's explicit retryability verdict (PLN-119 C6b). When `false` the
+     * SDK will NOT auto-retry even on a normally-retryable status (e.g. the
+     * preview `504 preview_timeout` envelope — a blind retry re-runs the same
+     * over-budget work). Absent on older servers — status-based heuristics
+     * apply then.
+     */
+    retryable?: boolean;
+    /** 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 {
-    /** Comma-separated or array of relations to include. */
-    include?: Array<'owners' | 'classifications' | 'attorneys' | 'media' | 'priorities' | 'proceedings' | 'design_codes' | 'madrid' | 'history'>;
-    /** Sparse fieldset — comma-separated field names to return. */
-    fields?: string;
+    /**
+     * Optional detail projections.
+     *
+     * `office_extensions` includes the raw office-specific extension blob,
+     * which is omitted from the default detail response.
+     */
+    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 {
-    status_primary?: string;
-    'status_stage[]'?: string | string[];
-    'status_reason[]'?: string | string[];
-    'challenge_states[]'?: string | string[];
-    'mark_feature_type[]'?: string | string[];
-    'mark_legal_category[]'?: string | string[];
+    /**
+     * Coarse status bucket. Accepts a single value or an array to match any of
+     * several values — passing `['active', 'pending']` yields TESS-style "live"
+     * results. Valid values: `pending`, `active`, `inactive`, `unknown`.
+     */
+    status_primary?: string | string[];
+    status_stage?: string | string[];
+    status_reason?: string | string[];
+    challenge_states?: string | string[];
+    mark_feature_type?: string | string[];
+    mark_legal_category?: string | string[];
     right_kind?: string;
-    'filing_route[]'?: string | string[];
-    'scope_kind[]'?: string | string[];
+    filing_route?: string | string[];
+    scope_kind?: string | string[];
     application_number?: string;
     registration_number?: string;
     ir_number?: string;
     office?: string;
-    'jurisdictions[]'?: string | string[];
-    'offices[]'?: string | 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[]'?: string | string[];
-    'vienna_codes[]'?: string | string[];
-    'filing_date[gte]'?: string;
-    'filing_date[lt]'?: string;
-    'registration_date[gte]'?: string;
-    'registration_date[lt]'?: string;
-    'expiry_date[gte]'?: string;
-    'expiry_date[lt]'?: string;
-    'renewal_due_date[gte]'?: string;
-    'renewal_due_date[lt]'?: string;
-    'publication_date[gte]'?: string;
-    'publication_date[lt]'?: string;
-    'termination_date[gte]'?: string;
-    'termination_date[lt]'?: string;
-    'updated_at[gte]'?: string;
-    'updated_at[lt]'?: 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;
+    filing_date_lt?: string;
+    registration_date_gte?: string;
+    registration_date_gt?: string;
+    registration_date_lte?: string;
+    registration_date_lt?: string;
+    expiry_date_gte?: string;
+    expiry_date_gt?: string;
+    expiry_date_lte?: string;
+    expiry_date_lt?: string;
+    renewal_due_date_gte?: string;
+    renewal_due_date_gt?: string;
+    renewal_due_date_lte?: string;
+    renewal_due_date_lt?: string;
+    publication_date_gte?: string;
+    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;
+    termination_date_lt?: string;
+    updated_at_gte?: string;
+    updated_at_gt?: string;
+    updated_at_lte?: string;
+    updated_at_lt?: string;
     owner_id?: string;
     owner_name?: string;
+    owner_publicly_traded?: boolean;
+    owner_has_lei?: boolean;
+    owner_ticker?: string;
+    owner_lei?: string;
+    /**
+     * PLN-118 — resolved-entity filter (`ent_*`). The GLOBAL-portfolio feature:
+     * returns marks across ALL member owners of the entity (every office). Accepts
+     * a derived `ent_<owner-uuid>` (a singleton) too. Over the member cap → 422
+     * `entity_too_large`.
+     */
+    entity_id?: string;
+    /**
+     * PLN-118 — entity-GROUP filter (`ent_*`). Returns marks across the whole
+     * GLEIF family group (root + all descendants) — "all Pfizer-group marks".
+     * Group-level, never identity. Over the union cap → 422 `entity_too_large`.
+     */
+    entity_group?: string;
     attorney_id?: string;
     firm_id?: string;
-    has_media?: string;
-    has_proceedings?: string;
-    is_madrid?: string;
-    is_retracted?: string;
-    is_series_mark?: string;
+    has_media?: boolean;
+    has_proceedings?: boolean;
+    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;
+    /**
+     * 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`.
+     */
     sort?: string;
     limit?: number;
     cursor?: string;
@@ -342,8 +1491,8 @@ export interface TrademarkListParams {
 export interface TrademarkHistoryParams {
     event_type?: string;
     event_scope?: string;
-    'event_date[gte]'?: string;
-    'event_date[lt]'?: string;
+    event_date_gte?: string;
+    event_date_lt?: string;
     limit?: number;
     cursor?: string;
 }
@@ -359,9 +1508,11 @@ export interface TrademarkRelatedParams {
 }
 export interface TrademarkSuggestParams {
     q: string;
-    'jurisdictions[]'?: string | string[];
-    'nice_classes[]'?: number | number[];
-    'status_stage[]'?: string | string[];
+    jurisdictions?: string | string[];
+    /** How `jurisdictions` matches: `protection` (default) or `direct`. */
+    territory_match?: TerritoryMatchMode;
+    nice_classes?: number | number[];
+    status_stage?: string | string[];
 }
 export interface TrademarkCoverageParams {
     protection_status?: string;
@@ -374,52 +1525,311 @@ 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;
 }
-export interface OwnerRetrieveParams {
-    include?: Array<'related_entities' | 'stats' | 'specializations' | 'top_attorneys' | 'jurisdictions' | 'trend'>;
+/**
+ * Owner detail does not currently accept any query parameters; the server
+ * always returns the full detail tier (aliases, identifiers, stats, public
+ * companies). This empty params type is reserved for future use.
+ */
+export type OwnerRetrieveParams = Record<string, never>;
+/** Entity detail accepts no query parameters (reserved for future use). */
+export type EntityRetrieveParams = Record<string, never>;
+export interface EntityListParams {
+    q?: string;
+    country_code?: string;
+    entity_type?: string;
+    publicly_traded?: boolean;
+    ticker?: string;
+    has_lei?: boolean;
+    lei?: string;
+    sort?: '-trademark_count' | 'trademark_count' | '-name' | 'name' | '-member_count' | 'member_count';
+    include_total?: boolean;
+    limit?: number;
+    cursor?: string;
 }
+/**
+ * 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 & {
+    include_family?: boolean;
+};
+export type EntityFamilyParams = Record<string, never>;
 export interface OwnerListParams {
     q?: string;
     country_code?: string;
     entity_type?: string;
-    sort?: string;
-    jurisdiction?: string;
-    nice_class?: number;
-    active_since?: string;
-    min_filings?: number;
+    ticker?: string;
+    lei?: string;
+    publicly_traded?: boolean;
+    has_lei?: boolean;
+    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;
 }
 export interface OwnerTrademarksParams {
-    status?: string;
-    jurisdiction_code?: string;
-    nice_class?: number;
+    /**
+     * 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).
+     * Valid values: `pending`, `active`, `inactive`, `unknown`.
+     */
+    status_primary?: string | string[];
+    status_stage?: string | string[];
+    status_reason?: string | string[];
+    challenge_states?: string | string[];
+    mark_feature_type?: string | string[];
+    mark_legal_category?: string | string[];
+    right_kind?: string;
+    filing_route?: string | string[];
+    scope_kind?: string | string[];
+    application_number?: string;
+    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;
+    filing_date_lt?: string;
+    registration_date_gte?: string;
+    registration_date_gt?: string;
+    registration_date_lte?: string;
+    registration_date_lt?: string;
+    expiry_date_gte?: string;
+    expiry_date_gt?: string;
+    expiry_date_lte?: string;
+    expiry_date_lt?: string;
+    renewal_due_date_gte?: string;
+    renewal_due_date_gt?: string;
+    renewal_due_date_lte?: string;
+    renewal_due_date_lt?: string;
+    publication_date_gte?: string;
+    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;
+    termination_date_lt?: string;
+    updated_at_gte?: string;
+    updated_at_gt?: string;
+    updated_at_lte?: string;
+    updated_at_lt?: string;
+    owner_name?: string;
+    owner_publicly_traded?: boolean;
+    owner_has_lei?: boolean;
+    owner_ticker?: string;
+    owner_lei?: string;
+    attorney_id?: string;
+    firm_id?: string;
+    has_media?: boolean;
+    has_proceedings?: boolean;
+    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 interface AttorneyRetrieveParams {
-    include?: Array<'recent_trademarks' | 'stats' | 'specializations' | 'top_clients' | 'jurisdictions' | 'trend'>;
-}
+/**
+ * Attorney detail does not currently accept any query parameters; the server
+ * always returns the full detail tier (aliases, identifiers, scalar stats).
+ * This empty params type is reserved for future use.
+ */
+export type AttorneyRetrieveParams = Record<string, never>;
 export interface AttorneyListParams {
     q?: string;
-    firm?: string;
     firm_id?: string;
     country_code?: string;
-    sort?: string;
-    jurisdiction?: string;
-    nice_class?: number;
-    active_since?: string;
-    min_filings?: number;
+    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;
 }
 export interface AttorneyTrademarksParams {
-    status?: string;
-    jurisdiction_code?: string;
-    nice_class?: number;
+    /**
+     * 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).
+     * Valid values: `pending`, `active`, `inactive`, `unknown`.
+     */
+    status_primary?: string | string[];
+    status_stage?: string | string[];
+    status_reason?: string | string[];
+    challenge_states?: string | string[];
+    mark_feature_type?: string | string[];
+    mark_legal_category?: string | string[];
+    right_kind?: string;
+    filing_route?: string | string[];
+    scope_kind?: string | string[];
+    application_number?: string;
+    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;
+    filing_date_lt?: string;
+    registration_date_gte?: string;
+    registration_date_gt?: string;
+    registration_date_lte?: string;
+    registration_date_lt?: string;
+    expiry_date_gte?: string;
+    expiry_date_gt?: string;
+    expiry_date_lte?: string;
+    expiry_date_lt?: string;
+    renewal_due_date_gte?: string;
+    renewal_due_date_gt?: string;
+    renewal_due_date_lte?: string;
+    renewal_due_date_lt?: string;
+    publication_date_gte?: string;
+    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;
+    termination_date_lt?: string;
+    updated_at_gte?: string;
+    updated_at_gt?: string;
+    updated_at_lte?: string;
+    updated_at_lt?: string;
+    owner_name?: string;
+    owner_id?: string;
+    owner_publicly_traded?: boolean;
+    owner_has_lei?: boolean;
+    owner_ticker?: string;
+    owner_lei?: string;
+    firm_id?: string;
+    has_media?: boolean;
+    has_proceedings?: boolean;
+    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;
 }
@@ -428,53 +1838,326 @@ export interface AttorneyClientsParams {
     cursor?: string;
 }
 export interface FirmRetrieveParams {
-    include?: Array<'stats' | 'specializations' | 'top_clients' | 'jurisdictions' | 'trend' | 'attorneys'>;
+    include?: Array<'attorneys'>;
 }
 export interface FirmListParams {
     q?: string;
+    country_code?: string;
     min_attorneys?: number;
     min_filings?: number;
-    jurisdiction?: string;
-    nice_class?: number;
-    sort?: string;
+    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;
 }
 export interface FirmAttorneysParams {
-    sort?: string;
     limit?: number;
     cursor?: string;
 }
 export interface FirmTrademarksParams {
-    status?: string;
-    jurisdiction_code?: string;
+    /**
+     * 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).
+     * Valid values: `pending`, `active`, `inactive`, `unknown`.
+     */
+    status_primary?: string | string[];
+    status_stage?: string | string[];
+    status_reason?: string | string[];
+    challenge_states?: string | string[];
+    mark_feature_type?: string | string[];
+    mark_legal_category?: string | string[];
+    right_kind?: string;
+    filing_route?: string | string[];
+    scope_kind?: string | string[];
+    application_number?: string;
+    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;
+    filing_date_lt?: string;
+    registration_date_gte?: string;
+    registration_date_gt?: string;
+    registration_date_lte?: string;
+    registration_date_lt?: string;
+    expiry_date_gte?: string;
+    expiry_date_gt?: string;
+    expiry_date_lte?: string;
+    expiry_date_lt?: string;
+    renewal_due_date_gte?: string;
+    renewal_due_date_gt?: string;
+    renewal_due_date_lte?: string;
+    renewal_due_date_lt?: string;
+    publication_date_gte?: string;
+    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;
+    termination_date_lt?: string;
+    updated_at_gte?: string;
+    updated_at_gt?: string;
+    updated_at_lte?: string;
+    updated_at_lt?: string;
+    owner_name?: string;
+    owner_id?: string;
+    owner_publicly_traded?: boolean;
+    owner_has_lei?: boolean;
+    owner_ticker?: string;
+    owner_lei?: string;
+    attorney_id?: string;
+    has_media?: boolean;
+    has_proceedings?: boolean;
+    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;
-    type?: 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;
-    'filed_date[gte]'?: string;
-    'filed_date[lt]'?: string;
-    'decision_date[gte]'?: string;
-    'decision_date[lt]'?: string;
+    filed_date_gte?: string;
+    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;
 }
-export interface StatusListParams {
-    office?: string;
+/**
+ * Request body for `POST /v1/classifications/suggest`.
+ *
+ * Deliberately does not accept `jurisdiction_code`: Nice Classification is a
+ * WIPO international standard, so the 45-class assignment is the same in every
+ * member jurisdiction. For jurisdiction-sensitive term wording, use
+ * {@link GoodsServicesSuggestParams} on `goodsServices.suggest(...)`.
+ */
+export interface ClassificationSuggestParams {
+    /** Natural-language business description (3-500 chars). */
+    description: string;
+}
+/**
+ * POST body for `POST /v1/trademarks` (complex queries with filters, aggregations, strategies).
+ *
+ * This replaces the old `POST /v1/trademarks/search` endpoint.
+ */
+export interface DateRangeFilter {
+    gte?: string;
+    gt?: string;
+    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 SearchV2Body {
-    query: string;
+export interface TrademarkSearchBody {
+    /** Optional text query. When omitted, results are filter-only. */
+    query?: string;
+    /** Search strategies (e.g. 'exact', 'phonetic', 'fuzzy', 'prefix'). */
     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?: {
-        status_primary?: string;
+        /**
+         * 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). Valid values: `pending`, `active`, `inactive`, `unknown`.
+         */
+        status_primary?: string | string[];
         status_stage?: string[];
         status_reason?: string[];
         challenge_states?: string[];
@@ -488,37 +2171,31 @@ export interface SearchV2Body {
         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?: {
-            gte?: string;
-            lt?: string;
-        };
-        registration_date?: {
-            gte?: string;
-            lt?: string;
-        };
-        expiry_date?: {
-            gte?: string;
-            lt?: string;
-        };
-        renewal_due_date?: {
-            gte?: string;
-            lt?: string;
-        };
-        publication_date?: {
-            gte?: string;
-            lt?: string;
-        };
-        termination_date?: {
-            gte?: string;
-            lt?: string;
-        };
-        updated_at?: {
-            gte?: string;
-            lt?: 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;
         owner_name?: string;
+        owner_publicly_traded?: boolean;
+        owner_has_lei?: boolean;
+        owner_ticker?: string;
+        owner_lei?: string;
         attorney_id?: string;
         firm_id?: string;
         application_number?: string;
@@ -533,22 +2210,65 @@ export interface SearchV2Body {
         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;
+        include_timing?: boolean;
+        include_profile?: 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 explicit sort is set with `query`, relevance scoring is disabled.
+     */
     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`
+ * endpoint has been consolidated into `POST /v1/trademarks`.
+ */
+export type SearchV2Body = TrademarkSearchBody;
 export interface CrossEntitySuggestParams {
     q: string;
     type?: 'trademark' | 'owner' | 'attorney' | 'firm';
 }
-export interface ClassificationTermsParams {
-    q: string;
+/**
+ * Query parameters for `GET /v1/goods-services` (browse/search the accepted
+ * terms catalog). At least one of `q` or `class` must be provided.
+ */
+export interface GoodsServicesListParams {
+    /** Substring search across term text (2-200 characters). Optional if `class` is set. */
+    q?: string;
+    /** Nice class number (1-45). Optional if `q` is set. */
+    class?: number;
     language?: string;
     harmonised_only?: boolean | null;
     limit?: number;
+    cursor?: string;
+}
+/** Request body for `POST /v1/goods-services/suggest`. */
+export interface GoodsServicesSuggestParams {
+    /** Natural-language description of goods, services, or business (3-500 chars). */
+    description: string;
+    /** Optional ISO-3166-1 alpha-2 jurisdiction code hint. */
+    jurisdiction_code?: string;
+    /**
+     * Optional Nice class (1-45). When set, scopes the response to that
+     * single class — useful for refining wording when the class has already
+     * been chosen.
+     */
+    class_number?: number;
 }
 export interface DesignCodeListParams {
     q?: string;
@@ -576,10 +2296,10 @@ export interface PortfolioRetrieveParams {
     limit?: number;
     cursor?: string;
 }
-export interface PortfolioAddMarksBody {
+export interface PortfolioAddTrademarksBody {
     trademark_ids: string[];
 }
-export interface PortfolioRemoveMarksBody {
+export interface PortfolioRemoveTrademarksBody {
     trademark_ids: string[];
 }
 export interface PortfolioDeadlineParams {
@@ -611,53 +2331,192 @@ 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(...)`.
+ *
+ * Either `query` or `from_saved_search` (passed via the second-arg
+ * `RequestOptions`-style query — see `WatchCreateOptions`) must be set.
+ */
 export interface WatchCreateParams {
     name: string;
-    description?: string;
-    watch_type: 'status' | 'competitor' | 'class' | 'keyword' | 'portfolio';
-    criteria: Record<string, unknown>;
-    triggers: Array<'new_filing' | 'status_change' | 'any_change'>;
-    delivery_channels?: Array<'api' | 'webhook' | 'email' | 'slack' | 'teams'>;
-    scope_filters?: Record<string, unknown>;
-    metadata?: Record<string, string>;
+    watch_type: WatchType;
+    /** v1 watch query DSL. Required unless hydrating from a saved search. */
+    query?: WatchQuery | Record<string, unknown>;
+    /**
+     * v1 accepts only `'always_per_alert'` — the API rejects the digest modes
+     * with 400 because digest batching is not built yet (planned for v1.1).
+     * The response-side {@link Watch.delivery_mode} stays the wide
+     * {@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>;
+}
+/**
+ * Optional query string params for `watches.create(...)`. Pass via the
+ * SDK's `?from_saved_search=ssr_...` query string.
+ *
+ * Note: `backfill_days` was removed — the server rejects it with 400
+ * (`unsupported_in_v1`). Historical replay-from-date arrives in v1.1; in
+ * v1 only future sync_runs trigger evaluation.
+ */
+export interface WatchCreateQueryParams {
+    /** Hydrate `query` from a saved search id (`ssr_...`). */
+    from_saved_search?: string;
 }
 export interface WatchUpdateParams {
     name?: string;
-    description?: string | null;
-    criteria?: Record<string, unknown>;
-    triggers?: Array<'new_filing' | 'status_change' | 'any_change'>;
-    delivery_channels?: Array<'api' | 'webhook' | 'email' | 'slack' | 'teams'>;
-    scope_filters?: Record<string, unknown>;
-    status?: 'active' | 'paused' | 'disabled';
-    metadata?: Record<string, string | null>;
+    query?: WatchQuery | Record<string, unknown>;
+    /** v1 accepts only `'always_per_alert'` (digest modes 400 until v1.1) — see {@link WatchCreateParams.delivery_mode}. */
+    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 {
-    status?: 'active' | 'paused' | 'disabled';
-    watch_type?: string;
-    sort?: string;
+    status?: WatchStatus;
     limit?: number;
     cursor?: string;
 }
+/**
+ * Body for `watches.replay(id, body?)` — v1 accepts an EMPTY body only.
+ *
+ * `from_date` (historical replay-from-date) is reserved for v1.1; the server
+ * unconditionally rejects it with 400 whether sent in the body or the query
+ * string. It was removed from this type because it could never succeed.
+ * v1 replay bumps `evaluation_epoch` and re-evaluates from the next
+ * `sync_run.searchable` event forward only.
+ */
+export type WatchReplayParams = Record<string, never>;
+/** Body for `watches.preview(body)`. */
+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 {
+    watches: WatchCreateParams[];
+}
 export interface AlertListParams {
-    watch_id?: string;
-    status?: 'unacknowledged' | 'acknowledged' | 'dismissed';
-    severity?: 'high' | 'medium' | 'low' | 'info';
-    trademark_id?: string;
-    event_type?: string;
-    sort?: string;
+    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;
 }
-export interface AlertUpdateStatusBody {
-    status: 'acknowledged' | 'dismissed';
+/** Body for `alerts.lookup({ ids })`. Capped at 100 IDs. */
+export interface AlertLookupParams {
+    ids: string[];
 }
-export interface AlertBatchUpdateBody {
-    alert_ids: string[];
-    status: 'acknowledged' | 'dismissed';
+export interface WebhookCreateParams {
+    url: string;
+    description?: string;
+    enabled_events: Array<WebhookEventType | string>;
+    metadata?: Record<string, unknown>;
+}
+export interface WebhookUpdateParams {
+    url?: string;
+    description?: string | null;
+    enabled_events?: Array<WebhookEventType | string>;
+    status?: WebhookStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface WebhookListParams {
+    limit?: number;
+    cursor?: string;
+}
+export interface WebhookDeliveryListParams {
+    limit?: number;
+    cursor?: string;
+    /**
+     * TSK-115d FX3.C: ISO 8601 timestamp lower bound (inclusive). Only
+     * deliveries with `created_at >= since` are returned. Useful for
+     * incremental polling — set `since = last_seen_created_at` and walk
+     * pages until exhausted. 30-day retention applies regardless of the
+     * `since` value.
+     */
+    since?: string;
 }
 export interface OrgEventListParams {
-    'event_type[]'?: string[];
-    'office_code[]'?: string[];
+    event_type?: string | string[];
+    office_code?: string | string[];
     trademark_id?: string;
     since?: string;
     cursor?: string;
@@ -675,6 +2534,615 @@ export interface ApiKeyUpdateParams {
     expires_at?: string | null;
     metadata?: Record<string, string | null>;
 }
+/**
+ * Query params for `GET /v1/organization/logs`.
+ *
+ * All filters are optional; dates default to the last 24 hours and results
+ * are subject to per-plan retention windows (7/30/90 days).
+ */
+export interface LogListParams {
+    /** Start of date range (ISO 8601, YYYY-MM-DD or full datetime). */
+    start_date?: string;
+    /** End of date range (ISO 8601). */
+    end_date?: string;
+    /** Alias for `start_date`. */
+    from?: string;
+    /** Alias for `end_date`. */
+    to?: string;
+    /** Filter by HTTP status code (100-599). */
+    status_code?: number;
+    /**
+     * Filter by outcome: `true` returns succeeded requests (status < 400),
+     * `false` returns failed requests (status >= 400).
+     */
+    success?: boolean;
+    /** Filter by HTTP method (GET, POST, etc.). */
+    method?: string;
+    /** Filter by API key ID (key_...). */
+    api_key_id?: string;
+    /** Filter by endpoint type (search, read, monitoring, screening, clearance, check, image_search, export, reference, utility). */
+    endpoint_type?: string;
+    /** Case-insensitive substring match against path or request ID. */
+    search?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** Query params for `GET /v1/organization/usage/summary`. */
+export interface UsageSummaryParams {
+    /** Start of date range (YYYY-MM-DD). Required. */
+    start_date: string;
+    /** End of date range (YYYY-MM-DD), inclusive. Required. */
+    end_date: string;
+    /** Grouping dimension. Defaults to `day`. */
+    group_by?: 'day' | 'endpoint_type' | 'api_key';
+    /** 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. */
@@ -700,6 +3168,15 @@ export interface ClientOptions {
     debug?: boolean;
     /** Custom fetch implementation (for testing or platform overrides). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Silence the browser-use warning. By default, constructing the SDK in an
+     * environment where `window` is defined emits a `console.warn` because
+     * Signa API keys are long-lived secrets that do not belong in client-side
+     * code. Set this to `true` (or the `SIGNA_ALLOW_BROWSER=1` env var) if you
+     * understand the exposure and are intentionally using the SDK in a
+     * trusted browser context. Default: `false`.
+     */
+    allowBrowser?: boolean;
 }
 /** API list response shape (before SDK wraps it as SignaList). */
 export interface ListResponseBody<T> {
@@ -709,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