@signa-so/sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,719 @@
+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'];
+/** Trademark event in history responses. */
+export type Event = components['schemas']['EventListItem'];
+/** Stats object shape returned by ?include=stats on attorney detail. */
+export interface AttorneyStats {
+    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;
+}
+/** Stats object shape returned by ?include=stats on owner detail. */
+export interface OwnerStats {
+    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;
+    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;
+    registration_rate?: number | null;
+    latest_filing?: string | null;
+    related_entities?: {
+        parent: {
+            id: string;
+            object: 'owner';
+            canonical_name: string;
+            country_code: string | null;
+            entity_type: string | null;
+        } | null;
+        children: Array<{
+            id: string;
+            object: 'owner';
+            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;
+};
+/** Full attorney detail (retrieve response). */
+export type Attorney = components['schemas']['AttorneyResponse'] & {
+    firm_id?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    address?: unknown | null;
+    trademark_count?: number | null;
+    registration_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;
+    registration_rate?: number | null;
+    latest_filing?: string | null;
+};
+/** Full firm detail (retrieve response). */
+export interface Firm {
+    id: string;
+    object: 'firm';
+    canonical_name: string;
+    display_name: string;
+    attorney_count: number;
+    trademark_count: number;
+    registration_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';
+        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';
+    canonical_name: string;
+    display_name: string;
+    attorney_count: number;
+    trademark_count: number;
+    registration_rate: number | null;
+    latest_filing: string | null;
+    created_at: 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'];
+/** Request body for POST /v1/trademarks/batch. */
+export type TrademarkBatchBody = components['schemas']['TrademarkBatchRequest'];
+/** Response shape for POST /v1/trademarks/batch (non-paginated). */
+export type TrademarkBatchResponse = components['schemas']['TrademarkBatchResponse'];
+/** Version-level change entry. */
+export type TrademarkChange = components['schemas']['TrademarkChange'];
+/** Mark-to-mark relationship entry. */
+export type TrademarkRelationship = components['schemas']['TrademarkRelated'];
+/** Trademark autocomplete suggestion entry. */
+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'];
+/** 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'];
+/** Vienna design code. */
+export type DesignCode = components['schemas']['DesignCode'];
+/** Vienna design code with children (retrieve response). */
+export type DesignCodeDetail = components['schemas']['DesignCodeDetailResponse'];
+/** Nice classification. */
+export type Classification = components['schemas']['Classification'];
+/** Nice classification with terms (retrieve response). */
+export type ClassificationDetail = components['schemas']['ClassificationDetailResponse'];
+/** Trademark office. */
+export type Office = components['schemas']['Office'];
+/** Trademark office with detail (retrieve response). */
+export type OfficeDetail = components['schemas']['OfficeDetailResponse'];
+/** Jurisdiction. */
+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'];
+/** Event type code. */
+export type EventType = components['schemas']['EventTypeMapping'];
+/** Portfolio (retrieve response). */
+export type Portfolio = components['schemas']['Portfolio'];
+/** 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 type Identity = components['schemas']['Identity'];
+/** Usage (GET /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'];
+/** Generic delete confirmation. */
+export interface DeletedResponse {
+    id: string;
+    object: string;
+    deleted: true;
+    livemode: boolean;
+    request_id: string;
+}
+/** Trademark source provenance (from raw_record_version). */
+export type TrademarkSource = components['schemas']['TrademarkSourceResponse'];
+/** Trademark coverage (Madrid IR designation). */
+export type TrademarkCoverage = components['schemas']['TrademarkCoverage'];
+/** Trademark proceeding (with parties) as returned by /trademarks/{id}/proceedings. */
+export type TrademarkProceeding = components['schemas']['TrademarkProceedingSub'];
+/** Owner related entity (GLEIF corporate hierarchy). */
+export type OwnerRelated = components['schemas']['OwnerRelated'];
+/** Search metadata (timing, totals). */
+export interface SearchMeta {
+    took_ms: number;
+    timed_out?: boolean;
+    total?: {
+        value: number;
+        relation: string;
+    };
+    index_lag_ms?: number | null;
+}
+/** API error body (RFC 9457-inspired). */
+export interface APIErrorBody {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    instance?: string;
+}
+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;
+}
+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[];
+    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[]'?: 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;
+    owner_id?: string;
+    owner_name?: string;
+    attorney_id?: string;
+    firm_id?: string;
+    has_media?: string;
+    has_proceedings?: string;
+    is_madrid?: string;
+    is_retracted?: string;
+    is_series_mark?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkHistoryParams {
+    event_type?: string;
+    event_scope?: string;
+    'event_date[gte]'?: string;
+    'event_date[lt]'?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkChangesParams {
+    changed_field?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkRelatedParams {
+    relationship_type?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkSuggestParams {
+    q: string;
+    'jurisdictions[]'?: string | string[];
+    'nice_classes[]'?: number | number[];
+    'status_stage[]'?: string | string[];
+}
+export interface TrademarkCoverageParams {
+    protection_status?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface TrademarkProceedingsParams {
+    proceeding_type?: string;
+    status?: 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'>;
+}
+export interface OwnerListParams {
+    q?: string;
+    country_code?: string;
+    entity_type?: string;
+    sort?: string;
+    jurisdiction?: string;
+    nice_class?: number;
+    active_since?: string;
+    min_filings?: number;
+    limit?: number;
+    cursor?: string;
+}
+export interface OwnerTrademarksParams {
+    status?: string;
+    jurisdiction_code?: string;
+    nice_class?: number;
+    limit?: number;
+    cursor?: string;
+}
+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;
+    limit?: number;
+    cursor?: string;
+}
+export interface AttorneyTrademarksParams {
+    status?: string;
+    jurisdiction_code?: string;
+    nice_class?: number;
+    limit?: number;
+    cursor?: string;
+}
+export interface AttorneyClientsParams {
+    limit?: number;
+    cursor?: string;
+}
+export interface FirmRetrieveParams {
+    include?: Array<'stats' | 'specializations' | 'top_clients' | 'jurisdictions' | 'trend' | 'attorneys'>;
+}
+export interface FirmListParams {
+    q?: string;
+    min_attorneys?: number;
+    min_filings?: number;
+    jurisdiction?: string;
+    nice_class?: number;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface FirmAttorneysParams {
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface FirmTrademarksParams {
+    status?: string;
+    jurisdiction_code?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface ProceedingListParams {
+    trademark_id?: string;
+    type?: string;
+    status?: string;
+    q?: string;
+    office_code?: string;
+    'filed_date[gte]'?: string;
+    'filed_date[lt]'?: string;
+    'decision_date[gte]'?: string;
+    'decision_date[lt]'?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface ClassificationListParams {
+    q?: string;
+}
+export interface StatusListParams {
+    office?: string;
+}
+export interface SearchV2Body {
+    query: string;
+    strategies?: ('exact' | 'phonetic' | 'fuzzy' | 'prefix')[];
+    filters?: {
+        status_primary?: string;
+        status_stage?: string[];
+        status_reason?: string[];
+        challenge_states?: string[];
+        mark_feature_type?: string[];
+        mark_legal_category?: string[];
+        right_kind?: string;
+        filing_route?: string[];
+        scope_kind?: string[];
+        jurisdictions?: string[];
+        offices?: string[];
+        owner_country?: string;
+        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;
+        };
+        owner_id?: string;
+        owner_name?: string;
+        attorney_id?: string;
+        firm_id?: string;
+        application_number?: string;
+        registration_number?: string;
+        ir_number?: string;
+        office?: string;
+        origin_office_code?: string;
+        has_media?: boolean;
+        has_proceedings?: boolean;
+        is_madrid?: boolean;
+        is_retracted?: boolean;
+        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_only?: boolean;
+    };
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface CrossEntitySuggestParams {
+    q: string;
+    type?: 'trademark' | 'owner' | 'attorney' | 'firm';
+}
+export interface ClassificationTermsParams {
+    q: string;
+    language?: string;
+    harmonised_only?: boolean | null;
+    limit?: number;
+}
+export interface DesignCodeListParams {
+    q?: string;
+    depth?: number;
+    category?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface PortfolioCreateParams {
+    name: string;
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface PortfolioUpdateParams {
+    name?: string;
+    description?: string | null;
+    metadata?: Record<string, string | null>;
+}
+export interface PortfolioListParams {
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface PortfolioRetrieveParams {
+    limit?: number;
+    cursor?: string;
+}
+export interface PortfolioAddMarksBody {
+    trademark_ids: string[];
+}
+export interface PortfolioRemoveMarksBody {
+    trademark_ids: string[];
+}
+export interface PortfolioDeadlineParams {
+    due_before: string;
+    type?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface PortfolioDeadlinesIcalParams {
+    reminder_days?: string;
+}
+export interface SavedSearchCreateParams {
+    name: string;
+    description?: string;
+    query: Record<string, unknown>;
+    metadata?: Record<string, string>;
+}
+export interface SavedSearchUpdateParams {
+    name?: string;
+    description?: string | null;
+    query?: Record<string, unknown>;
+    metadata?: Record<string, string | null>;
+}
+export interface SavedSearchListParams {
+    limit?: number;
+    cursor?: string;
+}
+export interface SavedSearchExecuteParams {
+    limit?: number;
+    cursor?: string;
+}
+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>;
+}
+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>;
+}
+export interface WatchListParams {
+    status?: 'active' | 'paused' | 'disabled';
+    watch_type?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface AlertListParams {
+    watch_id?: string;
+    status?: 'unacknowledged' | 'acknowledged' | 'dismissed';
+    severity?: 'high' | 'medium' | 'low' | 'info';
+    trademark_id?: string;
+    event_type?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface AlertUpdateStatusBody {
+    status: 'acknowledged' | 'dismissed';
+}
+export interface AlertBatchUpdateBody {
+    alert_ids: string[];
+    status: 'acknowledged' | 'dismissed';
+}
+export interface OrgEventListParams {
+    'event_type[]'?: string[];
+    'office_code[]'?: string[];
+    trademark_id?: string;
+    since?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface ApiKeyCreateParams {
+    name: string;
+    scopes: string[];
+    expires_at?: string | null;
+    metadata?: Record<string, string>;
+}
+export interface ApiKeyUpdateParams {
+    name?: string;
+    scopes?: string[];
+    expires_at?: string | null;
+    metadata?: Record<string, string | null>;
+}
+/** Per-request overrides. Accepted as the last argument on every method. */
+export interface RequestOptions {
+    /** Request timeout in ms. Overrides client default. */
+    timeout?: number;
+    /** Max retries. Overrides client default. */
+    max_retries?: number;
+    /** Extra headers merged with client defaults. */
+    headers?: Record<string, string>;
+    /** Idempotency key for future write operations. */
+    idempotency_key?: string;
+}
+/** Client constructor options. */
+export interface ClientOptions {
+    /** API key. Falls back to SIGNA_API_KEY env var. */
+    api_key?: string;
+    /** Base URL. Default: https://api.signa.so */
+    base_url?: string;
+    /** Default request timeout in ms. Default: 30000. */
+    timeout?: number;
+    /** Default max retries on 429/5xx. Default: 2. */
+    max_retries?: number;
+    /** Log request/response to stderr. Default: false. */
+    debug?: boolean;
+    /** Custom fetch implementation (for testing or platform overrides). */
+    fetch?: typeof globalThis.fetch;
+}
+/** API list response shape (before SDK wraps it as SignaList). */
+export interface ListResponseBody<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+    pagination: {
+        cursor: string | null;
+        total_count?: number;
+    };
+    request_id: string;
+    search_meta?: SearchMeta;
+    /** Faceted aggregation buckets (V2 search and saved search results). */
+    aggregations?: Record<string, Record<string, number>>;
+}
+//# sourceMappingURL=types.d.ts.map