@signa-so/sdk 0.2.1 → 0.4.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;
@@ -52,55 +52,35 @@ export interface FirmStats {
     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;
     registration_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 +88,21 @@ 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[];
 };
 /** Compact owner in list responses. */
 export type OwnerSummary = components['schemas']['OwnerSummary'] & {
     trademark_count?: number | null;
     registration_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'] & {
@@ -137,10 +116,6 @@ export type Attorney = components['schemas']['AttorneyResponse'] & {
     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'] & {
@@ -153,8 +128,8 @@ export type AttorneySummary = components['schemas']['AttorneySummary'] & {
 export interface Firm {
     id: string;
     object: 'firm';
+    name: string;
     canonical_name: string;
-    display_name: string;
     attorney_count: number;
     trademark_count: number;
     registration_rate: number | null;
@@ -162,34 +137,128 @@ export interface Firm {
     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;
     registration_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;
+}
+/** Whitelisted per-member link evidence on an entity-detail member. */
+export interface EntityMemberLink {
+    signal: string;
+    tier: string | null;
+    confidence: number | null;
+    decided_by: string;
+    /** token-overlap count from the name guard, when present. */
+    guard_overlap?: number;
+    /** matched canonical IR numbers (madrid_ir tier), when present. */
+    matched_irs?: string[];
+    /** matched office-identifier values (office_identifier tier), 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;
+    member_count: number;
+}
+/** 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';
+    /** Public-company facts aggregated over member companies ("served through the
+     *  entity"). Always present. A derived singleton exposes the owner's own
+     *  public-company facts when present (pco-linked); otherwise false/null/empty. */
+    publicly_traded: boolean;
+    /** Survivorship ticker (first of {@link tickers}); null when none. */
+    ticker: string | null;
+    /** Deduped uppercased SEC tickers across all member companies. */
+    tickers: string[];
+    lei: string | null;
+    /** Whether any member company carries a GLEIF LEI. */
+    has_lei: boolean;
+    trademark_count: number;
+    member_count: number;
+    /** Resolved entities only — the GLEIF parent entity id, when present. */
+    parent_entity_id?: string | null;
+    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). */
@@ -212,8 +281,12 @@ export type SearchV2Result = components['schemas']['SearchResultV2'];
 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 opposition window rule (item in `GET /v1/opposition-rules`). */
+export type OppositionRule = components['schemas']['OppositionRule'];
+/** 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 +295,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 +313,448 @@ 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'];
+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.
+ *
+ * v1 accepts exactly these 3 values. `trademark.retracted` and
+ * `trademark.corrected` were listed in earlier SDK revisions but were NEVER
+ * accepted by the API (create/update reject them with 400) and are never
+ * emitted by the evaluator. Source of truth:
+ * `api/src/modules/watches/validators.ts` `ALLOWED_TRIGGER_EVENTS`.
+ */
+export type WatchTriggerEvent = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed';
+/**
+ * Watch query DSL (v1). 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.). `trigger_events` narrows which lifecycle events
+ * fire alerts. `score_threshold` (0..1) gates similarity matches.
+ *
+ * Forbidden DSL keys (`function_score`, `script`, `sort`, `cursor`,
+ * `aggregations`, `highlight`) are rejected with 400. `query.match` is
+ * rejected in ANY form (object or string) — earlier doc revisions described
+ * shapes that were never honored by the evaluator. Use `filters.ownerId`,
+ * `filters.trademarkIds`, `filters.niceClasses` for scoping and
+ * `score_threshold` for similarity precision. Unknown `filters` keys are
+ * rejected with 400 listing the allowed vocabulary; `filters.offices`
+ * accepts any casing and is stored lowercase.
+ */
+export interface WatchQuery {
+    /** Always `"v1"` for monitoring v1. */
+    version: 'v1';
+    /** Optional keyword query (required for similarity watches). Whitespace-separated; each ≥3 chars; no stop words. */
+    q?: string;
+    /** Filter object — same vocabulary as the trademark search API. Common keys: `trademarkIds`, `ownerId`, `niceClasses`, `jurisdictions`, `offices`, `statusPrimary`. */
+    filters?: Record<string, unknown>;
+    /** Restrict alert generation to specific trigger event types. */
+    trigger_events?: WatchTriggerEvent[];
+    /** Similarity score threshold (0..1). Only matches scoring at-or-above fire alerts. Valid for `watch_type: "similarity"`. */
+    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;
+    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}: watches can subscribe
+ * to exactly these 3 events, and alerts only ever carry these 3 values.
+ * (Earlier SDK revisions claimed watches accepted 5 trigger events — they
+ * never did; the API rejects `trademark.retracted` / `trademark.corrected`
+ * with 400.) The two types are kept separate so they can diverge in later
+ * API versions without a breaking rename.
+ *
+ * R4.5 fix: previously this declared 5 values; SDK consumers switching on
+ * `'trademark.retracted'` or `'trademark.corrected'` had dead `case` branches
+ * that never fired.
+ */
+export type AlertEventType = 'trademark.created' | 'trademark.updated' | 'trademark.status_changed';
+/** Alert severity. */
+export type AlertSeverity = 'normal' | 'high' | 'critical';
+/** Opposition-window state for the matched mark, when applicable. */
+export type OppositionWindowStatus = 'open' | 'closing_soon' | 'critical' | 'closed';
+/** Alert (immutable — no PATCH/dismiss in monitoring v1). */
+export interface Alert {
+    id: string;
+    object: 'alert';
+    watch_id: string;
+    watch_name: string;
+    trademark_id: string;
+    event_type: AlertEventType;
+    /** Snapshot of trademark version at the moment of evaluation (immutable). */
+    content_version: number;
+    /** Computed customer-action deadline; null if no deadline applies. */
+    must_act_by: string | null;
+    /** Current opposition-window state for this mark; null when no window applies. */
+    opposition_window_status: OppositionWindowStatus | null;
+    severity: AlertSeverity;
+    /** Optional compact mark summary (mark text, owner, office) included by some routes. */
+    trademark_summary?: Record<string, unknown>;
+    /** Optional human-readable explanation of why the mark matched the watch. */
+    match_reason?: string;
+    created_at: string;
+}
+/** 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;
+}
+/**
+ * Inner payload of an `alert.created` webhook delivery.
+ *
+ * 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 AlertCreatedPayload {
+    /** 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;
+}
+/** 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';
+    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;
+    opensearch_score: number | null;
+    score_threshold: number | null;
+    alert_fired: boolean;
+    /**
+     * Walked in order: alert fired → office not in scope → freshness limit →
+     * candidacy missing → trigger event filtered → score below threshold →
+     * rolled into digest → fallback. See the diagnostics docs for the full enum.
+     */
+    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: {
+        id: string;
+        office_code: string;
+        completed_at: string | null;
+        search_indexed_at: string | null;
+    } | null;
+    /** `event_outbox` UUID — cross-reference against the `webhook-id` on delivery audit rows. */
+    outbox_event_id: string | null;
+    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;
+}
+/** 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. */
-export type OrgEvent = components['schemas']['EventListItem'];
+export interface OrgEvent {
+    id: number;
+    object: 'event';
+    event_type: string;
+    trademark_id: string;
+    office_code: string;
+    created_at: string;
+}
 /** Org-level event detail (with changes). */
-export type OrgEventDetail = components['schemas']['EventDetail'];
-/** Identity (GET /me). */
+export interface OrgEventDetail extends OrgEvent {
+    changes: Array<{
+        field: string;
+        before: unknown;
+        after: unknown;
+    }>;
+}
+/** 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'];
 /** Generic delete confirmation. */
 export interface DeletedResponse {
     id: string;
     object: string;
     deleted: true;
-    livemode: boolean;
     request_id: string;
 }
 /** Trademark source provenance (from raw_record_version). */
@@ -275,8 +770,19 @@ export interface SearchMeta {
     search_id: string;
     query: string;
     strategies_used: string[];
-    total_results: number;
-    total_count_exact: boolean;
+    /**
+     * Total matching results. Only present when the caller set
+     * `options.include_total = true` (or requested aggregations). Absent
+     * on default searches so the API can skip OpenSearch hit counting
+     * and return faster on broad queries. See api-spec-v1 §5.
+     */
+    total_results?: number;
+    /**
+     * `true` if `total_results` is an exact count, `false` if it is a
+     * lower bound (capped at 10k). Only present when `total_results` is
+     * present.
+     */
+    total_count_exact?: boolean;
     execution_time_ms: number;
 }
 /** API error body (RFC 9457-inspired). */
@@ -286,55 +792,127 @@ 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 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 relations to embed alongside the trademark detail.
+     *
+     * Currently only `history` is supported. Including `history` embeds the 50
+     * most recent prosecution events with a `has_more` indicator. Owners,
+     * classifications, attorneys, media, priorities, proceedings, and Madrid
+     * coverage are always returned inline at the detail tier.
+     */
+    include?: Array<'history'>;
 }
 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[];
+    jurisdictions?: string | string[];
+    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[];
+    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;
+    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;
+    /** Optional text query (triggers relevance ranking when no explicit sort). */
+    q?: string;
+    /** Search strategies to apply (e.g. 'exact', 'phonetic', 'fuzzy', 'prefix'). */
+    strategies?: string[];
+    /** Ranking profile to use. */
+    ranking_profile?: 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;
+    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 +920,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 +937,9 @@ export interface TrademarkRelatedParams {
 }
 export interface TrademarkSuggestParams {
     q: string;
-    'jurisdictions[]'?: string | string[];
-    'nice_classes[]'?: number | number[];
-    'status_stage[]'?: string | string[];
+    jurisdictions?: string | string[];
+    nice_classes?: number | number[];
+    status_stage?: string | string[];
 }
 export interface TrademarkCoverageParams {
     protection_status?: string;
@@ -378,48 +956,196 @@ export interface OwnerRelatedParams {
     limit?: number;
     cursor?: string;
 }
+/**
+ * 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 interface OwnerRetrieveParams {
-    include?: Array<'related_entities' | 'stats' | 'specializations' | 'top_attorneys' | 'jurisdictions' | 'trend'>;
+}
+/** Entity detail accepts no query parameters (reserved for future use). */
+export interface EntityRetrieveParams {
+}
+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.
+ */
+export type EntityTrademarksParams = OwnerTrademarksParams;
+export interface EntityFamilyParams {
 }
 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' | '-registration_rate' | 'registration_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;
+    jurisdictions?: string | string[];
+    offices?: string | string[];
+    owner_country?: string;
+    nice_classes?: number | number[];
+    vienna_codes?: string | string[];
+    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;
+    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;
     limit?: number;
     cursor?: string;
 }
+/**
+ * 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 interface AttorneyRetrieveParams {
-    include?: Array<'recent_trademarks' | 'stats' | 'specializations' | 'top_clients' | 'jurisdictions' | 'trend'>;
 }
 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' | '-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;
+    jurisdictions?: string | string[];
+    offices?: string | string[];
+    owner_country?: string;
+    nice_classes?: number | number[];
+    vienna_codes?: string | string[];
+    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;
+    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;
     limit?: number;
     cursor?: string;
 }
@@ -428,53 +1154,145 @@ export interface AttorneyClientsParams {
     cursor?: string;
 }
 export interface FirmRetrieveParams {
-    include?: Array<'stats' | 'specializations' | 'top_clients' | 'jurisdictions' | 'trend' | 'attorneys'>;
+    include?: Array<'stats' | 'specializations' | 'jurisdictions' | 'trend' | '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' | '-registration_rate' | 'registration_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;
+    jurisdictions?: string | string[];
+    offices?: string | string[];
+    owner_country?: string;
+    nice_classes?: number | number[];
+    vienna_codes?: string | string[];
+    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;
+    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;
     limit?: number;
     cursor?: string;
 }
 export interface ProceedingListParams {
     trademark_id?: string;
-    type?: string;
+    proceeding_type?: string;
     status?: string;
     q?: string;
+    party_owner_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;
+    sort?: '-filed_date' | 'filed_date' | '-decided_date' | 'decided_date';
     limit?: number;
     cursor?: string;
 }
 export interface ClassificationListParams {
     q?: string;
 }
-export interface StatusListParams {
-    office?: string;
-}
-export interface SearchV2Body {
-    query: 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;
+}
+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;
     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[];
@@ -489,36 +1307,19 @@ export interface SearchV2Body {
         nice_classes?: number[];
         vienna_codes?: string[];
         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;
+        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;
@@ -535,20 +1336,55 @@ export interface SearchV2Body {
     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_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;
 }
+/**
+ * @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 +1412,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 +1447,114 @@ export interface SavedSearchExecuteParams {
     limit?: number;
     cursor?: string;
 }
+/**
+ * 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';
+    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';
+    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;
+}
+/** 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;
     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 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 AlertBatchUpdateBody {
-    alert_ids: string[];
-    status: 'acknowledged' | 'dismissed';
+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 +1572,50 @@ 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;
+}
 /** Per-request overrides. Accepted as the last argument on every method. */
 export interface RequestOptions {
     /** Request timeout in ms. Overrides client default. */
@@ -700,6 +1641,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> {