@headband/react 0.1.1 → 0.2.1

package/dist/index.d.mts

@@ -1,13 +1,152 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
 
+/**
+ * Runtime helpers for Headband-managed retrieval experiments.
+ *
+ * Headband stores experiment rules, but applications own runtime assignment.
+ * These helpers fetch the saved rules and deterministically assign a subject
+ * to a variant without adding another dependency.
+ */
+type ExperimentConfigStatus = "draft" | "active" | "paused" | "archived";
+interface ExperimentVariantConfig {
+    key: string;
+    indexUid: string;
+    weight: number;
+}
+interface ExperimentConfig {
+    id?: string;
+    experimentKey: string;
+    name: string;
+    status: ExperimentConfigStatus;
+    trafficPercent: number;
+    killSwitch: boolean;
+    primaryMetric: string;
+    guardrailMetric: string | null;
+    assignmentSalt: string;
+    variants: ExperimentVariantConfig[];
+    updatedAt?: string;
+}
+interface ExperimentSearchMetadata {
+    experimentKey: string;
+    variant: string;
+    sessionId?: string;
+}
+type ExperimentEventType = "experiment_view" | "search_result_click" | "conversion" | "custom";
+interface ExperimentEventInput extends ExperimentSearchMetadata {
+    eventType: ExperimentEventType;
+    indexUid: string;
+    query?: string;
+    filters?: string;
+    conversionValue?: number;
+    metadata?: Record<string, unknown>;
+}
+interface ExperimentEventResponse {
+    accepted: boolean;
+    eventType: ExperimentEventType;
+    experimentKey: string;
+    variant: string;
+    indexUid: string;
+}
+interface ExperimentAssignment extends ExperimentSearchMetadata {
+    indexUid: string;
+    config: ExperimentConfig;
+}
+interface HostedExperimentAssignmentQuery {
+    projectId?: string;
+    indexUid?: string;
+    experimentKey: string;
+    subjectId: string;
+    sessionId?: string;
+}
+interface HostedExperimentAssignmentResponse {
+    assigned: boolean;
+    reason?: "not_runnable" | "outside_rollout" | "no_weight";
+    experimentKey: string;
+    variant?: string;
+    indexUid?: string;
+    sessionId: string;
+    config: {
+        status: ExperimentConfigStatus;
+        trafficPercent: number;
+        killSwitch: boolean;
+        updatedAt?: string;
+    };
+}
+interface ExperimentConfigQuery {
+    projectId?: string;
+    indexUid?: string;
+    experimentKey?: string;
+}
+interface ExperimentConfigResponse {
+    data?: {
+        experiments?: ExperimentConfig[];
+    };
+}
+declare function buildExperimentConfigPath(query?: ExperimentConfigQuery): string;
+declare function isRunnableExperiment(config: ExperimentConfig): boolean;
+declare function chooseExperimentVariant(config: ExperimentConfig, subjectId: string): ExperimentVariantConfig | null;
+declare function assignExperiment(config: ExperimentConfig, subjectId: string, options?: {
+    sessionId?: string;
+}): ExperimentAssignment | null;
+declare function experimentSearchMetadata(assignment: ExperimentAssignment | null | undefined): ExperimentSearchMetadata | undefined;
+
+/**
+ * Search events for click feedback: `search_result_click` and `conversion`.
+ *
+ * A search response carries a `queryId` when click feedback is on for your organization. Send it
+ * with a click so Headband knows which search showed the result. Clicks and conversions are
+ * counted per query; when an index has "Use click feedback in ranking" on, results people pick
+ * for a query move up for that query. No experiment is needed.
+ */
+type SearchEventType = "search_result_click" | "conversion";
+interface SearchEvent {
+    type: SearchEventType;
+    /** The index the result came from. */
+    index: string;
+    /** The clicked or converted document's id (its primary key). */
+    docId: string | number;
+    /** The `queryId` of the search that showed the result. */
+    queryId?: string;
+    /** 1-based position of the result in the whole result list, not just the page. */
+    position?: number;
+    /** A stable id for the visitor's session. Strongly recommended: events without one count half. */
+    sessionId?: string;
+    /** Optional, non-negative: an order value for a conversion. */
+    value?: number;
+}
+type SearchEventRejectReason = "invalid_event" | "invalid_type" | "invalid_index" | "invalid_doc_id" | "invalid_query_id" | "invalid_position" | "invalid_session_id" | "invalid_value" | "index_not_found" | "bot";
+interface SendEventsResponse {
+    accepted: number;
+    /** `index` is the event's position in the array you sent. */
+    rejected: Array<{
+        index: number;
+        reason: SearchEventRejectReason;
+    }>;
+}
+/**
+ * A session id for this browser tab, kept in sessionStorage when it is available and in memory
+ * otherwise. It identifies nothing about the visitor; Headband stores it only as a keyed hash.
+ */
+declare function browserSessionId(): string;
+
 /**
  * Headband search client.
  *
- * Makes requests to the Headband `/v1/search` and `/v1/multi-search` endpoints.
+ * Makes requests to the Headband `/v1/search`, `/v1/multi-search`, `/v1/warm` and
+ * `/v1/relevance/events` endpoints.
+ */
+
+/**
+ * Visor's ranking mode: `instant` (the default, typo-tolerant, as-you-type) or `retrieval` (BM25F,
+ * for longer queries), on the same index. Indexes on the other engines ignore it.
  */
+type SearchMode = "instant" | "retrieval";
 interface SearchParams {
-    filter?: string;
+    experimentKey?: string;
+    variant?: string;
+    sessionId?: string;
+    filter?: string | string[];
     facets?: string[];
     sort?: string[];
     limit?: number;
@@ -15,12 +154,21 @@ interface SearchParams {
     attributesToHighlight?: string[];
     attributesToRetrieve?: string[];
     attributesToCrop?: string[];
+    /** Visor crops to 20 words and refuses any other value with 400 feature_not_supported. */
     cropLength?: number;
+    /** Visor returns no match positions and refuses `true` with 400 feature_not_supported. */
     showMatchesPosition?: boolean;
+    /** Visor matches as `last` does and refuses `all` and `frequency` with 400 feature_not_supported. */
     matchingStrategy?: "all" | "last" | "frequency";
+    mode?: SearchMode;
 }
 interface SearchResponse {
     hits: Record<string, unknown>[];
+    /**
+     * The id of this search, `q_` and 16 characters, when click feedback is on for your
+     * organization. Send it with clicks (`trackClick`) so Headband knows which search showed them.
+     */
+    queryId?: string;
     estimatedTotalHits?: number;
     totalHits?: number;
     processingTimeMs: number;
@@ -34,22 +182,60 @@ interface SearchResponse {
 interface MultiSearchQuery {
     indexUid: string;
     q: string;
-    filter?: string;
+    filter?: string | string[];
     facets?: string[];
     sort?: string[];
     limit?: number;
     offset?: number;
     attributesToHighlight?: string[];
     attributesToRetrieve?: string[];
+    mode?: SearchMode;
 }
 interface MultiSearchResponse {
     results: Array<SearchResponse & {
         indexUid: string;
     }>;
 }
+interface ExperimentConfigsResponse {
+    experiments: ExperimentConfig[];
+}
+/** `auto` starts an engine used in the last 24 hours and stages an older one. */
+type WarmLevel = "auto" | "stage" | "start";
+/** Indexes by name, or every index of a project. */
+type WarmInput = {
+    indexes: string[];
+} | {
+    project: string;
+    branch?: string;
+};
+interface WarmResponse {
+    level: WarmLevel;
+    indexes: Array<{
+        index: string;
+        engine: string;
+        state: "awake" | "staging" | "staged" | "starting" | "refused";
+        reason?: string;
+    }>;
+}
 interface HeadbandClient {
     search(index: string, query: string, params?: SearchParams): Promise<SearchResponse>;
     multiSearch(queries: MultiSearchQuery[]): Promise<MultiSearchResponse>;
+    getExperimentConfigs(query?: ExperimentConfigQuery): Promise<ExperimentConfigsResponse>;
+    assignExperiment(query: HostedExperimentAssignmentQuery): Promise<HostedExperimentAssignmentResponse>;
+    recordExperimentEvent(event: ExperimentEventInput): Promise<ExperimentEventResponse>;
+    /** Pre-wakes indexes, or a project's, so the next search does not wait for a sleeping engine. Free. */
+    warm(target: WarmInput, opts?: {
+        level?: WarmLevel;
+    }): Promise<WarmResponse>;
+    /** Sends up to 100 click and conversion events (POST /v1/relevance/events). */
+    sendEvents(events: SearchEvent[]): Promise<SendEventsResponse>;
+    /**
+     * Records a click on a search result. Pass the search's `queryId`; the client remembers it for
+     * the document so a later `trackConversion` names the same search.
+     */
+    trackClick(event: Omit<SearchEvent, "type">): Promise<SendEventsResponse>;
+    /** Records a conversion (a purchase, a sign-up) of a document found by search. */
+    trackConversion(event: Omit<SearchEvent, "type" | "position">): Promise<SendEventsResponse>;
 }
 declare class HeadbandError extends Error {
     readonly status: number;
@@ -58,6 +244,25 @@ declare class HeadbandError extends Error {
 }
 declare function headband(host: string, apiKey: string): HeadbandClient;
 
+type FilterValue = string | number | boolean;
+type FilterInput = string | string[] | null | undefined;
+declare function quoteFilterValue(value: FilterValue): string;
+declare function filterEq(attribute: string, value: FilterValue): string;
+declare function filterNotEq(attribute: string, value: FilterValue): string;
+declare function filterIn(attribute: string, values: FilterValue[]): string;
+declare function filterExists(attribute: string): string;
+declare function filterRange(attribute: string, range: {
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    min?: number;
+    max?: number;
+}): string | undefined;
+declare function andFilters(...filters: FilterInput[]): string | undefined;
+declare function orFilters(...filters: FilterInput[]): string | undefined;
+declare function combineFilters(baseFilter: FilterInput, generatedFilter: FilterInput): string | string[] | undefined;
+
 /** Map of attribute -> selected values for facet refinements. */
 type RefinementMap = Map<string, Set<string>>;
 /** Numeric range filter: attribute -> { min?, max? }. */
@@ -92,20 +297,56 @@ interface SearchActions {
     unregisterFacet: (attribute: string) => void;
     refresh: () => void;
 }
+/** How useClickTracking finds a hit's id and the visitor's session. */
+interface ClickTrackingConfig {
+    /** The field hits carry the document id in. Default `id`. */
+    idField: string;
+    /** The session id events carry; a per-tab id when absent. */
+    sessionId?: string;
+}
 interface HeadbandContextValue {
     client: HeadbandClient;
     index: string;
     state: SearchState;
     actions: SearchActions;
+    tracking: ClickTrackingConfig;
 }
 declare function useHeadbandContext(): HeadbandContextValue;
 interface HeadbandProviderProps {
     client: HeadbandClient;
     index: string;
     initialQuery?: string;
+    experiment?: ExperimentSearchMetadata | null;
+    /**
+     * Optional app-owned filter expression(s) ANDed with UI refinements/ranges.
+     * Use this for tenant, permission, availability, or custom OR/AND groups that
+     * should apply to every search request.
+     */
+    baseFilter?: FilterInput;
+    /**
+     * Visor's ranking mode for every search: `instant` (the engine's default) or `retrieval` (BM25F,
+     * for longer queries). Indexes on the other engines ignore it.
+     */
+    mode?: SearchMode;
+    /**
+     * Store-style facet counts (default true). With a value ticked in a facet list, that list still
+     * counts its other values, so a shopper can tick a second one. Each facet with a ticked value
+     * costs one more search per request. Set false for one search per request, and lists that narrow
+     * to the ticked values.
+     */
+    disjunctiveFacets?: boolean;
+    /**
+     * The field your documents' ids are in, for click feedback (`useClickTracking`). Default `id`.
+     */
+    idField?: string;
+    /**
+     * A stable id for the visitor's session, sent with click and conversion events. Without it the
+     * experiment's session id is used, else an id kept for this browser tab.
+     */
+    sessionId?: string;
     children: ReactNode;
 }
-declare function HeadbandProvider({ client, index, initialQuery, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
+declare function HeadbandProvider({ client, index, initialQuery, experiment, baseFilter, mode, disjunctiveFacets, idField, sessionId, children, }: HeadbandProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core hook that exposes the full search state and actions.
@@ -273,6 +514,31 @@ interface UseHighlightReturn {
  */
 declare function useHighlight({ hit, attribute, }: UseHighlightProps): UseHighlightReturn;
 
+interface UseClickTrackingReturn {
+    /** The current search's id, when click feedback is on for your organization. */
+    queryId: string | undefined;
+    /**
+     * Records a click on a hit. `positionOnPage` is the hit's 0-based place in the current page;
+     * the absolute position is worked out from the page. Never throws: tracking must not break a
+     * results page, so a failed send resolves to null.
+     */
+    trackClick: (hit: Record<string, unknown>, positionOnPage?: number) => Promise<SendEventsResponse | null>;
+    /**
+     * Records a conversion of a document. It names the search the document was last clicked from
+     * in this tab, unless you pass a `queryId`. Never throws.
+     */
+    trackConversion: (docId: string | number, opts?: {
+        value?: number;
+        queryId?: string;
+    }) => Promise<SendEventsResponse | null>;
+}
+/**
+ * Click feedback events for the provider's index: `search_result_click` and `conversion`. When the
+ * index has "Use click feedback in ranking" on, results people pick for a query move up for that
+ * query.
+ */
+declare function useClickTracking(): UseClickTrackingReturn;
+
 interface SearchBoxProps {
     /** Placeholder text. */
     placeholder?: string;
@@ -413,4 +679,4 @@ interface PoweredByProps {
  */
 declare function PoweredBy({ className, styled, href, }: PoweredByProps): react_jsx_runtime.JSX.Element;
 
-export { type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchParams, type SearchResponse, type SearchState, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, headband, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };
+export { type ClickTrackingConfig, type ExperimentAssignment, type ExperimentConfig, type ExperimentConfigQuery, type ExperimentConfigResponse, type ExperimentConfigStatus, type ExperimentConfigsResponse, type ExperimentEventInput, type ExperimentEventResponse, type ExperimentEventType, type ExperimentSearchMetadata, type ExperimentVariantConfig, type FilterInput, type FilterValue, type HeadbandClient, type HeadbandContextValue, HeadbandError, HeadbandProvider, type HeadbandProviderProps, Highlight, type HighlightProps, type Hit, Hits, type HitsProps, type HostedExperimentAssignmentQuery, type HostedExperimentAssignmentResponse, type MultiSearchQuery, type MultiSearchResponse, Pagination, type PaginationProps, PoweredBy, type PoweredByProps, RangeInput, type RangeInputProps, type RangeMap, RefinementList, type RefinementListItem, type RefinementListProps, type RefinementMap, type SearchActions, SearchBox, type SearchBoxProps, type SearchEvent, type SearchEventRejectReason, type SearchEventType, type SearchMode, type SearchParams, type SearchResponse, type SearchState, type SendEventsResponse, SortBy, type SortByItem, type SortByProps, Stats, type StatsProps, type UseClickTrackingReturn, type UseHighlightProps, type UseHighlightReturn, type UseHitsReturn, type UsePaginationReturn, type UseRangeProps, type UseRangeReturn, type UseRefinementListProps, type UseRefinementListReturn, type UseSearchBoxReturn, type UseSortByProps, type UseSortByReturn, type UseStatsReturn, type WarmInput, type WarmLevel, type WarmResponse, andFilters, assignExperiment, browserSessionId, buildExperimentConfigPath, chooseExperimentVariant, combineFilters, experimentSearchMetadata, filterEq, filterExists, filterIn, filterNotEq, filterRange, headband, isRunnableExperiment, orFilters, quoteFilterValue, useClickTracking, useHeadbandContext, useHighlight, useHits, usePagination, useRange, useRefinementList, useSearch, useSearchBox, useSortBy, useStats };