@searchstack/public-api 1.0.0

package/dist/Types.d.ts

@@ -0,0 +1,753 @@
+/** RFC 7807 problem details returned by the API for any non-success status. */
+export type Problem = {
+    type: string;
+    title: string;
+    status: number;
+    instance: string;
+    detail: string;
+};
+export type GeoPoint = {
+    lat: number;
+    lon: number;
+};
+/** A named value used when writing facet / searchable / resource fields. */
+export type NameAndValue = {
+    name: string;
+    value: unknown;
+};
+/**
+ * Discriminated result of an API call. Every service method resolves to a
+ * `Response` rather than throwing, so callers branch on `isSuccess` (network and
+ * JSON errors are surfaced as a `Problem` with status 500).
+ */
+export declare abstract class Response<S, F> {
+    readonly isSuccess: boolean;
+    constructor(isSuccess: boolean);
+    abstract toSuccess(): S;
+    abstract toProblem(): F;
+}
+/** Successful result carrying the deserialized payload. */
+export declare class SuccessResponse<S> extends Response<S, Problem> {
+    readonly data: S;
+    constructor(data: S);
+    toSuccess(): S;
+    toProblem(): Problem;
+}
+/** Failed result carrying the parsed problem details. */
+export declare class ProblemResponse<S> extends Response<S, Problem> {
+    readonly problem: Problem;
+    constructor(problem: Problem);
+    toSuccess(): S;
+    toProblem(): Problem;
+}
+/**
+ * A single search result. The per-modality score fields are prefixed with `@`
+ * exactly as the API emits them, and `fields` carries the result's custom data.
+ */
+export type SearchHit = {
+    '@text_score'?: number | null;
+    '@image_score'?: number | null;
+    '@document_score'?: number | null;
+    '@video_score'?: number | null;
+    '@audio_score'?: number | null;
+    name: string;
+    list_name?: string | null;
+    version?: number | null;
+    distance?: number | null;
+    location?: GeoPoint | null;
+    fields: Record<string, unknown>;
+};
+export type SearchResponse = {
+    results: SearchHit[];
+    count: number;
+    total_count: number;
+    query_id?: string | null;
+};
+export type ExtractedDocument = {
+    uri: string;
+    page_count?: number | null;
+    text?: string | null;
+    error?: string | null;
+};
+export type ExtractDocumentTextResponse = {
+    search_result_name: string;
+    max_pages: number;
+    documents: ExtractedDocument[];
+};
+/** A typeahead suggestion is an opaque record of the suggested fields. */
+export type Suggestion = Record<string, unknown>;
+export type ListRefResponse = {
+    list_name: string;
+    account_name: string;
+    created: number;
+};
+export type ModelResponse = {
+    model_name: string;
+    model_value: string;
+    model_provider: string;
+    supports_documents: boolean;
+    max_text_characters: number;
+    max_images: number;
+    max_image_payload_bytes: number;
+    max_document_pages: number;
+    max_videos: number;
+    max_video_payload_bytes: number;
+    max_audios: number;
+    max_audio_payload_bytes: number;
+    created_utc: number;
+};
+export type RerankerDetailsResponse = {
+    account_name: string;
+    name: string;
+    provider: string;
+    provider_display_name: string;
+    model: string;
+    created_utc: number;
+};
+export type ApiKeyResponse = {
+    account_name: string;
+    api_key_name: string;
+    created: number;
+    permissions: string[];
+    expires_utc?: number | null;
+};
+export type SubscriptionResponse = {
+    subscription_name: string;
+    subscription_display_name: string;
+    status: string;
+    expires_utc: number;
+    created_utc: number;
+    is_active: boolean;
+    max_lists: number;
+    max_results?: number | null;
+    max_lists_per_group: number;
+    cost_per_month: number;
+    region: string;
+    search_service_name: string;
+    provider: string;
+    provider_name: string;
+    type: string;
+    search_result_byte_size: number;
+    search_result_count: number;
+    max_size_gb?: number | null;
+};
+export type MediaStoreResponse = {
+    account_name: string;
+    store_name: string;
+    provider: string;
+    provider_display_name: string;
+    created_utc: number;
+    is_default: boolean;
+};
+export type CacheServiceDetailsResponse = {
+    account_name: string;
+    name: string;
+    provider: string;
+    provider_display_name: string;
+    region?: string | null;
+    created_utc: number;
+};
+export type WebhookSubscriptionResponse = {
+    id: string;
+    account_name: string;
+    url: string;
+    events: string[];
+    is_active: boolean;
+    is_suspended: boolean;
+    created_on: number;
+};
+export type SearchServiceResponse = {
+    search_service_name: string;
+    region: string;
+    provider: string;
+    created: number;
+    search_service_is_shared: boolean;
+};
+export type AccountResponse = {
+    account_name: string;
+    owner: string;
+    image_path: string;
+    created: number;
+    lists: ListRefResponse[];
+    models: ModelResponse[];
+    rerankers: RerankerDetailsResponse[];
+    country: string;
+    api_keys: ApiKeyResponse[];
+    subscriptions: SubscriptionResponse[];
+    groups: GroupResponse[];
+    github_connected: boolean;
+    media_stores: MediaStoreResponse[];
+    cache_services: CacheServiceDetailsResponse[];
+    webhook_subscriptions: WebhookSubscriptionResponse[];
+    search_services: SearchServiceResponse[];
+};
+export type AccountNameResponse = {
+    account_name: string;
+};
+export type FacetResponse = {
+    facet_name: string;
+    field_type: string;
+};
+export type ResourceResponse = {
+    resource_name: string;
+    vectorize: boolean;
+};
+export type SearchableFieldResponse = {
+    searchable_field_name: string;
+    vectorize: boolean;
+};
+export type ContributorResponse = {
+    contributor_name: string;
+};
+export type SuggestionTargetResponse = {
+    target_list_name: string;
+    minimum_result_count: number;
+    is_active: boolean;
+    minimum_characters: number;
+    minimum_occurrences: number;
+    lookback_days: number;
+    require_click: boolean;
+};
+export type ListResponse = {
+    account_name: string;
+    list_name: string;
+    created: number;
+    default_search_size: number;
+    default_suggest_size: number;
+    search_result_count: number;
+    search_result_byte_size: number;
+    use_miles: boolean;
+    typo_tolerance: boolean;
+    default_ttl_seconds?: number | null;
+    purge_inactive_after_days?: number | null;
+    version: number;
+    subscription_name: string;
+    show_coordinates: boolean;
+    suggestion_target?: SuggestionTargetResponse | null;
+    model_name: string;
+    media_store?: string | null;
+    cache_service?: string | null;
+    reranker_name?: string | null;
+    facets: FacetResponse[];
+    contributors: ContributorResponse[];
+    searchable_fields: SearchableFieldResponse[];
+    resources: ResourceResponse[];
+    ip_addresses: string[];
+};
+export type ListIdentityResponse = {
+    list_name: string;
+    version: number;
+    created: number;
+    account_name: string;
+};
+/** A restore that rolls a List forward to the content of a past version. */
+export type ListRestoreResponse = {
+    list: ListResponse;
+    restored_from_version: number;
+    new_version: number;
+};
+export type GroupResponse = {
+    account_name: string;
+    group_name: string;
+    subscription_name: string;
+    model_name: string;
+    reranker_name?: string | null;
+    default_search_size: number;
+    default_suggest_size: number;
+    created: number;
+    /** Current membership version. Search/suggest against a specific version. */
+    current_version: number;
+    /** True when a member list has a newer version than the one pinned here. */
+    update_available: boolean;
+    lists: ListIdentityResponse[];
+    ip_addresses: string[];
+    use_miles?: boolean | null;
+};
+/** A restore that rolls a Group's membership forward to a past version. */
+export type GroupRestoreResponse = {
+    group: GroupResponse;
+    restored_from_version: number;
+    /** Member lists that could not be restored (e.g. since deleted). */
+    skipped_lists: ListIdentityResponse[];
+};
+export type GroupVersionsResponse = {
+    current_version: number;
+    versions: number[];
+};
+export type GroupVersionMembersResponse = {
+    group_version: number;
+    lists: ListIdentityResponse[];
+};
+export type DeleteMediaResponse = {
+    deleted: boolean;
+};
+export type AnalyticsTermCountResponse = {
+    term: string;
+    count: number;
+};
+export type AnalyticsDailyPointResponse = {
+    /** UTC date, `yyyy-MM-dd`. */
+    date: string;
+    searches: number;
+    zero_result_searches: number;
+    clicks: number;
+};
+export type AnalyticsReportResponse = {
+    account: string;
+    scope: string;
+    target: string;
+    /** UTC date, `yyyy-MM-dd`. */
+    from: string;
+    /** UTC date, `yyyy-MM-dd`. */
+    to: string;
+    total_searches: number;
+    zero_result_searches: number;
+    total_clicks: number;
+    click_through_rate: number;
+    top_searches: AnalyticsTermCountResponse[];
+    top_zero_result_searches: AnalyticsTermCountResponse[];
+    daily: AnalyticsDailyPointResponse[];
+    reranked_searches: number;
+    reranker_top_changed_rate: number;
+    reranker_mean_displacement: number;
+    reranker_click_lift: number;
+    reranker_lift_sample_size: number;
+};
+export type CreateSearchResultRequest = {
+    account_name: string;
+    list_name: string;
+    search_result_name: string;
+    active?: boolean;
+    /** Relative time-to-live in seconds; resolved to an absolute expiry. Ignored when expires_at is set. */
+    ttl_seconds?: number | null;
+    /** Absolute expiry (epoch ticks). Takes precedence over ttl_seconds and the list default. */
+    expires_at?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    facets?: NameAndValue[];
+    searchable_fields?: NameAndValue[];
+    resources?: NameAndValue[];
+};
+export type UpdateSearchResultRequest = {
+    search_result_name?: string | null;
+    active?: boolean | null;
+    /** Relative TTL in seconds, anchored to the record's creation time. Negative clears the expiry; null/omitted leaves it unchanged. */
+    ttl_seconds?: number | null;
+    /** Absolute expiry. Takes precedence over ttl_seconds. */
+    expires_at?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    facets?: NameAndValue[];
+    searchable_fields?: NameAndValue[];
+    resources?: NameAndValue[];
+};
+export type UpdateSearchResultVectorRequest = {
+    text_vector?: number[];
+    image_vector?: number[];
+    document_vector?: number[];
+};
+/** Free-text / vector search options. All fields are optional. */
+export type SearchOptions = {
+    query?: string;
+    size?: number;
+    skip?: number;
+    filter?: string;
+    radius?: string;
+    cache?: boolean;
+    vector_search?: boolean;
+    reranker?: boolean;
+    ranking?: string;
+    minimum_text_score?: number;
+    minimum_image_score?: number;
+    minimum_document_score?: number;
+    minimum_video_score?: number;
+    minimum_audio_score?: number;
+    order_by?: string;
+    typo_tolerance?: boolean;
+};
+/** Options for finding results related to a seed result. */
+export type RelatedOptions = {
+    filter?: string;
+    size?: number;
+    skip?: number;
+    radius?: string;
+    minimum_text_score?: number;
+    minimum_image_score?: number;
+    minimum_document_score?: number;
+    minimum_video_score?: number;
+    minimum_audio_score?: number;
+    cache?: boolean;
+    ranking?: string;
+};
+export type SearchByImageRequest = {
+    image_path: string;
+    filter?: string;
+    radius?: string;
+    size?: number;
+    skip?: number;
+    minimum_text_score?: number;
+    minimum_image_score?: number;
+    minimum_document_score?: number;
+    minimum_video_score?: number;
+    minimum_audio_score?: number;
+    cache?: boolean;
+    ranking?: string;
+};
+export type SearchByImageBase64Request = {
+    image_base64: string;
+    filter?: string;
+    radius?: string;
+    size?: number;
+    skip?: number;
+    minimum_text_score?: number;
+    minimum_image_score?: number;
+    minimum_document_score?: number;
+    minimum_video_score?: number;
+    minimum_audio_score?: number;
+    cache?: boolean;
+    ranking?: string;
+};
+export type RecordClickRequest = {
+    query_id: string;
+    result_id: string;
+    /** Required when recording a click against a group; the list the result came from. */
+    list_name?: string | null;
+};
+export type CreateListRequest = {
+    account_name: string;
+    list_name: string;
+    subscription_name: string;
+    model_name?: string | null;
+    cache_service?: string | null;
+    reranker_name?: string | null;
+    default_ttl_seconds?: number | null;
+};
+export type UpdateListRequest = {
+    default_suggest_size?: number | null;
+    default_search_size?: number | null;
+    use_miles?: boolean | null;
+    typo_tolerance?: boolean | null;
+    default_ttl_seconds?: number | null;
+};
+export type CreateFacetRequest = {
+    account_name: string;
+    list_name: string;
+    facet_name: string;
+    field_type?: string | null;
+};
+export type RenameFacetRequest = {
+    new_facet_name: string;
+};
+export type CreateResourceRequest = {
+    account_name: string;
+    list_name: string;
+    resource_name: string;
+    vectorize?: boolean;
+};
+export type RenameResourceRequest = {
+    resource_name: string;
+    new_resource_name: string;
+    vectorize?: boolean;
+};
+export type CreateSearchableFieldRequest = {
+    account_name: string;
+    list_name: string;
+    searchable_field_name: string;
+    /** When false, the field is excluded from the semantic text embedding (stays keyword-searchable). Defaults to true. */
+    vectorize?: boolean;
+};
+export type RenameSearchableFieldRequest = {
+    new_searchable_field_name: string;
+    /** When false, the field is excluded from the semantic text embedding (stays keyword-searchable). Defaults to true. */
+    vectorize?: boolean;
+};
+export type AddContributorRequest = {
+    account_name: string;
+    list_name: string;
+    contributor_name: string;
+};
+export type CreateGroupRequest = {
+    account_name: string;
+    subscription_name: string;
+    group_name: string;
+    model_name?: string | null;
+    reranker_name?: string | null;
+};
+export type CloneGroupRequest = {
+    new_group_name: string;
+    /** Re-pin members to their latest version. Defaults to true. */
+    pin_latest?: boolean;
+};
+export type EditGroupRequest = {
+    default_search_size?: number | null;
+    default_suggest_size?: number | null;
+    use_miles?: boolean | null;
+};
+export type AddListToGroupRequest = {
+    list_name: string;
+    version: number;
+    /** Adapt the added list's model to match the group's first list. Defaults to false. */
+    adapt_to_first_list?: boolean;
+};
+export type EditGroupModelRequest = {
+    model_name: string;
+};
+export type AddGroupRerankerRequest = {
+    reranker: string;
+};
+export type AddIpAddressRequest = {
+    ip_address: string;
+};
+export type TransferGroupRequest = {
+    new_subscription_name: string;
+};
+/** Filter selecting the search results to delete. Omit to match all. */
+export type DeleteByFilterRequest = {
+    filter?: string | null;
+};
+/** Acknowledgement that a (soft-)delete-by-filter job has been accepted. */
+export type DeleteByFilterResponse = {
+    accepted: boolean;
+};
+export type SuggestOptions = {
+    size?: number;
+    skip?: number;
+    filter?: string;
+    radius?: string;
+    cache?: boolean;
+};
+/** A single query in an eval set, as returned by the API. */
+export type EvalQueryResponse = {
+    text: string;
+    size: number;
+    filter?: string | null;
+    text_fields: string[];
+    image_fields: string[];
+};
+export type EvalSetResponse = {
+    account_name: string;
+    name: string;
+    list_name?: string | null;
+    list_version?: number | null;
+    group_name?: string | null;
+    group_version?: number | null;
+    target_created_utc: number;
+    judge_name?: string | null;
+    judge_created_utc?: number | null;
+    context_text: string;
+    context_image_uris: string[];
+    /** Events that trigger an automatic run, e.g. "ingest", "schedule". */
+    auto_run_on: string[];
+    queries: EvalQueryResponse[];
+    created_utc: number;
+};
+export type EvalQueryResultResponse = {
+    query_index: number;
+    query_text: string;
+    ordered_candidate_ids: string[];
+    judge_run_id?: string | null;
+    hit_count: number;
+    passed_count: number;
+    errored_count: number;
+};
+export type EvalRunStatusResponse = {
+    run_id: string;
+    account_name: string;
+    eval_set_name: string;
+    /** e.g. "pending", "running", "completed", "failed". */
+    status: string;
+    trigger_source: string;
+    total_queries: number;
+    processed_queries: number;
+    zero_result_queries: number;
+    total_candidates: number;
+    passed_count: number;
+    errored_count: number;
+    pass_rate?: number | null;
+    zero_result_rate?: number | null;
+    model_name?: string | null;
+    reranker_name?: string | null;
+    judge_name?: string | null;
+    membership_drifted: boolean;
+    created_utc: number;
+    completed_utc?: number | null;
+    /** Per-query detail; present once the run has produced results. */
+    results?: EvalQueryResultResponse[] | null;
+};
+export type EvalRunHistoryResponse = {
+    runs: EvalRunStatusResponse[];
+    continuation_token?: string | null;
+};
+export type RunEvalResponse = {
+    run_id: string;
+    estimated_judge_calls: number;
+};
+/** A query supplied when creating an eval set. */
+export type EvalQueryDto = {
+    text: string;
+    size?: number | null;
+    filter?: string | null;
+    text_fields?: string[];
+    image_fields?: string[];
+};
+export type CreateEvalSetRequest = {
+    name: string;
+    list_name?: string | null;
+    list_version?: number | null;
+    group_name?: string | null;
+    group_version?: number | null;
+    judge_name?: string | null;
+    context_text?: string | null;
+    context_image_uris?: string[];
+    auto_run_on?: string[];
+    queries: EvalQueryDto[];
+};
+export type BootstrapEvalSetRequest = {
+    name: string;
+    /** Judge run ids whose judged candidates seed the new eval set. */
+    source_run_ids: string[];
+    context_text?: string | null;
+    context_image_uris?: string[];
+};
+/** Health of a background-checked BYO service. */
+export type ServiceHealthResponse = {
+    /** One of: `unknown`, `healthy`, `degraded`, `failing`. */
+    status: string;
+    last_checked_utc?: number | null;
+    last_success_utc?: number | null;
+    message?: string | null;
+};
+export type JudgeDetailsResponse = {
+    account_name: string;
+    name: string;
+    provider: string;
+    provider_display_name: string;
+    model: string;
+    instructions: string;
+    /** JSON Schema (as a string) the judge's structured output must satisfy. */
+    output_schema: string;
+    /** Boolean field in the judge output that decides pass/fail. */
+    pass_field?: string | null;
+    created_utc: number;
+    health?: ServiceHealthResponse | null;
+};
+export type CreateJudgeRequest = {
+    provider: string;
+    model: string;
+    api_key: string;
+    instructions: string;
+    output_schema: string;
+    pass_field?: string | null;
+    /** Custom endpoint for the provider, when self-hosted / proxied. */
+    endpoint?: string | null;
+};
+export type JudgeContextDto = {
+    text: string;
+    image_uris?: string[];
+};
+export type JudgeCandidateDto = {
+    id: string;
+    text: string;
+    image_uris?: string[];
+};
+/** Instead of supplying candidates, have the judge run over live search hits. */
+export type JudgeSearchDto = {
+    list_name?: string | null;
+    version?: number | null;
+    group_name?: string | null;
+    group_version?: number | null;
+    query?: string | null;
+    size?: number | null;
+    filter?: string | null;
+    text_fields?: string[];
+    image_fields?: string[];
+};
+export type RunJudgeRequest = {
+    context: JudgeContextDto;
+    /** Explicit candidates to judge. Mutually exclusive with `search`. */
+    candidates?: JudgeCandidateDto[] | null;
+    /** Judge live search results instead of explicit candidates. */
+    search?: JudgeSearchDto | null;
+    batch: boolean;
+};
+export type RunJudgeResponse = {
+    run_id: string;
+};
+export type TryJudgeRequest = {
+    context: JudgeContextDto;
+    candidate: JudgeCandidateDto;
+};
+/** The synchronous result of trying a judge against a single candidate. */
+export type TryJudgeResponse = {
+    /** The judge's raw structured (JSON) output. */
+    json: string;
+    passed: boolean;
+    error?: string | null;
+};
+export type JudgeResultResponse = {
+    candidate_id: string;
+    json: string;
+    passed: boolean;
+    error?: string | null;
+};
+export type JudgeRunStatusResponse = {
+    run_id: string;
+    status: string;
+    total_candidates: number;
+    processed_count: number;
+    passed_count: number;
+    errored_count: number;
+    created_utc: number;
+    completed_utc?: number | null;
+    results: JudgeResultResponse[];
+};
+export type ApiAuthInfo = {
+    type: string;
+    description: string;
+};
+export type ApiErrorCode = {
+    code: string;
+    status: number;
+    description: string;
+};
+export type ApiMcpInfo = {
+    supported: boolean;
+    description: string;
+    example_config_url: string;
+};
+export type ApiInfo = {
+    name: string;
+    description: string;
+    version: string;
+    openapi_url: string;
+    documentation_url: string;
+    examples_url: string;
+    authentication: ApiAuthInfo;
+    error_codes: ApiErrorCode[];
+    mcp: ApiMcpInfo;
+};
+export type ApiExample = {
+    id: string;
+    title: string;
+    description: string;
+    method: string;
+    path: string;
+    request_body?: unknown;
+    response_status: number;
+    response_example: unknown;
+};
+export type ApiExamples = {
+    examples: ApiExample[];
+};
+export type ApiCatalogLink = {
+    anchor: string;
+    rel: string;
+    href: string;
+    type: string;
+    title: string;
+};
+/** IETF api-catalog document (RFC 9727) linking to the API's resources. */
+export type ApiCatalog = {
+    linkset: ApiCatalogLink[];
+};
+//# sourceMappingURL=Types.d.ts.map