@bradsearch/search-sdk/dist/index.d.ts

TypeScript SDK for BradSearch API with JWT authentication, field mapping, and faceted search capabilities

type FieldType = "text" | "keyword" | "text_keyword" | "hierarchy" | "variants" | "object" | "url" | "image_url" | "integer";
/**
 * Visibility setting for facets by viewport. Undefined defaults to 'both'.
 */
type FacetsVisibility = "mobile" | "desktop" | "both";
interface FieldConfig {
    type: FieldType;
    filterable?: boolean;
    fields?: Record<string, FieldConfig>;
    label?: string;
    count?: number;
    /** Number of hierarchy depth levels to display as tree (hierarchy type only). Prunes top levels when tree is deeper than depth. */
    depth?: number;
    /** Control facets visibility by device type */
    facetsVisibility?: FacetsVisibility;
}
interface ItemMapping {
    title?: string;
    reference?: string;
    link?: string;
    imageUrl?: string;
    brand?: string;
    price?: string;
    priceTaxExcluded?: string;
    basePrice?: string;
    basePriceTaxExcluded?: string;
    [key: string]: string | undefined;
}
interface ApiSdkConfig {
    token: string;
    baseUrl: string;
    fields: Record<string, FieldConfig>;
    mapping?: ItemMapping;
}
interface Item {
    id: string;
    title: string;
    link: string;
    imageUrl: {
        small: string;
        medium: string;
    };
    reference: string;
    brand?: string;
    _highlights?: Record<string, string>;
    price?: string;
    priceTaxExcluded?: string;
    basePrice?: string;
    basePriceTaxExcluded?: string;
}
interface FacetValue {
    value: string;
    count: number;
}
interface Context {
    price: PriceContext;
}
interface PriceContext {
    withTaxes: boolean;
}
interface DidYouMean {
    categories?: string[];
    queries?: string[];
}
interface SearchResponse<T = Item> {
    limit: number;
    total: number;
    offset: number;
    facets: Record<string, FacetValue[]>;
    documents: T[];
    'did-you-mean'?: DidYouMean;
}
interface QueryOptions {
    signal?: AbortSignal;
    limit?: number;
    offset?: number;
    sortBy?: string;
    locale?: string;
    order?: "asc" | "desc";
    searchAll?: boolean;
    autocomplete?: boolean;
    context?: Context;
    correlationId?: string;
}
interface Filters {
    [fieldName: string]: string | string[];
}
declare class ApiError extends Error {
    statusCode?: number | undefined;
    constructor(message: string, statusCode?: number | undefined);
}
declare class AuthenticationError extends ApiError {
    constructor(message?: string);
}
declare class ValidationError extends ApiError {
    constructor(message?: string);
}
declare class NetworkError extends ApiError {
    constructor(message?: string);
}
declare function filterable(target: any, propertyKey: string): void;

declare class ApiClient {
    config: ApiSdkConfig;
    private baseUrl;
    constructor(config: ApiSdkConfig);
    /**
     * Get current configuration
     */
    getConfig(): ApiSdkConfig;
    /**
     * Validate SDK configuration
     */
    private validateConfig;
    /**
     * Perform search query
     * @param query Search query string
     * @param filters Optional filters
     * @param options Optional query options
     * @returns Promise with search response
     */
    query<T = Item>(query?: string, filters?: Filters, options?: QueryOptions): Promise<SearchResponse<T>>;
    /**
     * Perform search query
     * @param query Search query string
     * @param filters Optional filters
     * @param options Optional query options
     * @returns Promise with search response
     */
    autocomplete<T = Item>(query?: string, filters?: Filters, options?: QueryOptions): Promise<SearchResponse<T>>;
    /**
     * Build query parameters for API request
     */
    private buildQueryParams;
    /**
     * Make HTTP request to API
     */
    private makeRequest;
    /**
     * Process API response and transform items
     */
    private processResponse;
    /**
     * Handle and convert errors to appropriate types
     */
    private handleError;
    /**
     * Get filterable fields from configuration
     */
    getFilterableFields(): string[];
    /**
     * Update configuration (useful for token refresh)
     */
    updateConfig(updates: Partial<ApiSdkConfig>): void;
}

/**
 * Get nested value from object using dot notation
 * @param obj Source object
 * @param path Dot notation path (e.g., 'categoryDefault.localizedName')
 * @returns Value at the path or undefined
 */
declare function getNestedValue(obj: any, path: string): any;
/**
 * Transform API response item to mapped item
 * @param apiItem Raw API response item
 * @param mapping Field mapping configuration
 * @returns Mapped item
 */
declare function transformItem<T = Item>(apiItem: any, mapping?: ItemMapping): T;
/**
 * Transform array of API items to mapped items
 * @param apiItems Raw API response items
 * @param mapping Field mapping configuration
 * @returns Array of mapped items
 */
declare function transformItems<T = Item>(apiItems: any[], mapping?: ItemMapping): T[];

/**
 * Normalize filters to consistent format
 * @param filters Raw filters
 * @returns Normalized filters with arrays
 */
declare function normalizeFilters(filters: Filters): Record<string, string[]>;

export { ApiClient, ApiError, ApiClient as ApiSdk, AuthenticationError, NetworkError, ValidationError, filterable, getNestedValue, normalizeFilters, transformItem, transformItems };
export type { ApiSdkConfig, FacetValue, FacetsVisibility, FieldConfig, FieldType, Filters, Item, ItemMapping, QueryOptions, SearchResponse };