@akropolys/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,377 @@
+import React from 'react';
+
+type Product<T extends Record<string, any> = Record<string, any>> = {
+    name: string;
+    price: string;
+    url: string;
+    brand?: string;
+    description?: string;
+    originalPrice?: string;
+    discount?: string;
+    currency?: string;
+    stock?: string;
+    availability?: string;
+    rating?: string;
+    reviewCount?: number;
+    category?: string;
+    subCategory?: string;
+    tags?: string[];
+    images?: string[];
+    specs?: Record<string, string>;
+    priceNumeric?: number;
+    slug?: string;
+    metadata?: Record<string, any>;
+} & T;
+type RawProductInput<T extends Record<string, any> = Record<string, any>> = {
+    name?: string;
+    title?: string;
+    productName?: string;
+    price?: string | number;
+    priceNumeric?: number;
+    url?: string;
+    image?: string;
+    thumbnail?: string;
+    images?: string[];
+    slug?: string;
+    id?: string;
+    productId?: string;
+    brand?: string;
+    description?: string;
+    originalPrice?: string;
+    discount?: string;
+    currency?: string;
+    stock?: string;
+    availability?: string;
+    rating?: string;
+    reviewCount?: number;
+    category?: string;
+    subCategory?: string;
+    tags?: string[];
+    specs?: Record<string, string>;
+    metadata?: Record<string, any>;
+} & T;
+interface CartItem {
+    id: string;
+    cart_id: string;
+    external_id?: string;
+    product_url: string;
+    name: string;
+    price: string;
+    price_numeric: number;
+    currency: string;
+    image: string;
+    brand: string;
+    category: string;
+    quantity: number;
+}
+interface CartPayload {
+    cart_id: string;
+    shopper_id: string;
+    site_id: string;
+    status: string;
+    items: CartItem[];
+    total: number;
+    currency: string;
+    item_count: number;
+}
+interface AkropolysConfig {
+    siteId?: string;
+    apiUrl?: string;
+    apiToken?: string;
+    shopperId?: string;
+    vertical?: 'commerce' | 'property' | 'motor' | 'blog' | string;
+    onCheckout?: (cart: CartPayload) => void;
+    onError?: (error: AkropolysError) => void;
+    authLoading?: boolean;
+}
+interface SearchRequest {
+    query: string;
+    siteId: string;
+    limit?: number;
+}
+interface SearchResult {
+    id: string;
+    score: number;
+    product: Product;
+}
+interface SearchResponse {
+    results: SearchResult[];
+    query: string;
+}
+interface IngestResponse {
+    success: boolean;
+    message?: string;
+    count?: number;
+}
+interface AkropolysError {
+    status: number;
+    message: string;
+}
+interface AkropolysTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+}
+interface CheckoutConfig {
+    payment_methods: Record<string, {
+        enabled: boolean;
+    }>;
+}
+interface PaymentInitResponse {
+    merchantReference: string;
+    checkoutRequestId?: string;
+}
+interface PaymentStatusResponse {
+    status: 'PENDING' | 'COMPLETED' | 'FAILED';
+    message?: string;
+}
+type ChatAction = {
+    type: 'add_to_cart';
+    [key: string]: any;
+} | {
+    type: 'remove_from_cart';
+    [key: string]: any;
+} | {
+    type: 'clear_cart';
+    [key: string]: any;
+} | {
+    type: 'view_cart';
+    [key: string]: any;
+} | {
+    type: 'checkout';
+    [key: string]: any;
+} | {
+    type: 'request_phone';
+    [key: string]: any;
+} | {
+    type: 'awaiting_payment';
+    merchantReference?: string | null;
+    [key: string]: any;
+} | {
+    type: string;
+    [key: string]: any;
+};
+
+declare class AkropolysAPI {
+    private apiUrl;
+    private siteId;
+    private apiToken;
+    private getShopperId?;
+    private getSessionId?;
+    private vertical?;
+    constructor(apiUrl: string, siteId: string, apiToken: string, getShopperId?: (() => string | undefined) | undefined, getSessionId?: (() => string | undefined) | undefined, vertical?: string | undefined);
+    private post;
+    ingest(product: Product): Promise<IngestResponse>;
+    ingestBatch(products: Product[]): Promise<IngestResponse>;
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    searchVector(query: string, limit?: number): Promise<SearchResponse>;
+    searchAutocomplete(query: string, limit?: number): Promise<SearchResponse>;
+    chat(query: string, history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>): Promise<{
+        answer: string;
+        sources: any[];
+        intent?: string;
+        checkout?: CartPayload;
+        action?: any;
+    }>;
+    chatStream(query: string, history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>, signal?: AbortSignal): Promise<Response>;
+    private buildHeaders;
+    getCart(): Promise<CartPayload>;
+    clearCart(): Promise<CartPayload>;
+    checkoutCart(): Promise<CartPayload>;
+    getCheckoutConfig(): Promise<CheckoutConfig>;
+    initiatePayment(phoneNumber: string, email?: string, firstName?: string, lastName?: string): Promise<PaymentInitResponse>;
+    getPaymentStatus(ref: string): Promise<PaymentStatusResponse>;
+}
+
+interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    cartSnapshot?: CartPayload;
+    actionType?: string;
+}
+interface ChatSource {
+    id?: string;
+    name: string;
+    price?: string;
+    currency?: string;
+    category?: string;
+    url?: string;
+    image?: string;
+    brand?: string;
+    availability?: string;
+}
+interface ChatMetadata {
+    intent: string;
+    sources: ChatSource[];
+    action?: ChatAction;
+    checkout?: CartPayload;
+}
+declare class KikuStream {
+    private listeners;
+    private aborted;
+    private responsePromise;
+    private abortController;
+    constructor(responsePromise: Promise<Response>, abortController: AbortController);
+    on(event: 'token' | 'meta' | 'done' | 'error', callback: Function): this;
+    off(event: 'token' | 'meta' | 'done' | 'error', callback: Function): this;
+    destroy(): void;
+    private emit;
+    private startReading;
+}
+
+declare function setSDKDefaultVertical(v: string): void;
+declare class AkropolysClient {
+    readonly api: AkropolysAPI;
+    readonly vertical: string;
+    private ingestQueue;
+    private ingestTimer;
+    private ingestedUrls;
+    private onlineHandler;
+    private shopperId?;
+    private sessionId;
+    private authLoading?;
+    onCheckout?: (cart: CartPayload) => void;
+    onError?: (error: AkropolysError) => void;
+    private static INGEST_CACHE_KEY;
+    private static INGEST_CACHE_TTL;
+    private loadIngestedCache;
+    private saveIngestedCache;
+    constructor(config: AkropolysConfig);
+    chat(query: string, history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>): KikuStream;
+    reRegister(): void;
+    setShopperId(id: string | undefined): void;
+    setAuthLoading(loading: boolean): void;
+    getShopperId(): string | undefined;
+    getSessionId(): string;
+    private initSession;
+    destroy(): void;
+    queueIngest(rawProduct: RawProductInput): Promise<void>;
+    queueIngestBatch(rawProducts: RawProductInput[]): Promise<void>;
+    private scheduleFlush;
+    private flushQueue;
+}
+declare function initAkropolys(config: AkropolysConfig): AkropolysClient;
+declare function getAkropolysClient(): AkropolysClient;
+
+interface AkropolysProviderProps extends AkropolysConfig {
+    children: React.ReactNode;
+}
+declare function AkropolysProvider({ siteId, apiUrl, apiToken, shopperId, vertical, authLoading, onCheckout, onError, children }: AkropolysProviderProps): React.JSX.Element;
+declare function useAkropolysContext(): AkropolysClient;
+
+/**
+ * @deprecated Use <AkropolysProvider> instead to avoid SSR issues.
+ */
+declare function useAkropolys(config: AkropolysConfig): AkropolysClient;
+
+interface UseSearchReturn {
+    results: SearchResult[];
+    loading: boolean;
+    error: string | null;
+    search: (query: string, limit?: number) => Promise<void>;
+    clear: () => void;
+}
+declare function useSearch(): UseSearchReturn;
+
+interface UseIngestReturn {
+    ingest: (product: RawProductInput) => void;
+    ingestBatch: (products: RawProductInput[]) => void;
+    /**
+     * @deprecated Ingest is fire-and-forget. This is always `false` and will be
+     * removed in the next major version. Remove it from your destructuring.
+     */
+    loading: false;
+    /**
+     * @deprecated Ingest is fire-and-forget. This is always `null` and will be
+     * removed in the next major version. Remove it from your destructuring.
+     */
+    error: null;
+}
+declare function useIngest(): UseIngestReturn;
+
+/**
+ * useListIngest — drop this into any catalog or list page.
+ * It automatically ingests all items in the array, using a built-in
+ * component-lifecycle ref guard to prevent duplicate calls during mounts.
+ *
+ * @example
+ * export function CategoryPage({ products }) {
+ *   useListIngest(products);
+ *   return <ProductGrid products={products} />;
+ * }
+ */
+declare function useListIngest(products: RawProductInput[] | null | undefined): void;
+
+/**
+ * usePageIngest — drop this into any product page component.
+ * The moment a customer's browser renders the page, the product is
+ * automatically captured and queued for ingestion into the vector index.
+ *
+ * No configuration needed beyond <AkropolysProvider> in your layout.
+ *
+ * @example
+ * // Product detail page — Next.js or React
+ * export function ProductPage({ product }) {
+ *   usePageIngest({
+ *     name: product.title,
+ *     price: product.price,
+ *     url: window.location.href,
+ *     images: [product.thumbnail],
+ *     category: product.category,
+ *   });
+ *   return <div>...</div>;
+ * }
+ */
+declare function usePageIngest(product: RawProductInput | null | undefined): void;
+
+interface UseKikuOptions {
+    initialMessages?: ChatMessage[];
+    onToken?: (token: string) => void;
+    onMeta?: (meta: any) => void;
+    onDone?: (fullMessage: string) => void;
+    onError?: (error: Error) => void;
+}
+interface UseKikuReturn {
+    messages: ChatMessage[];
+    sources: ChatSource[];
+    loading: boolean;
+    streaming: boolean;
+    error: string | null;
+    lastAction: ChatAction | null;
+    lastIntent: string | null;
+    send: (query: string, displayQuery?: string) => Promise<void>;
+    reset: () => void;
+}
+declare function useKiku(options?: UseKikuOptions): UseKikuReturn;
+
+declare function useCart(): {
+    cart: CartPayload | null;
+    loading: boolean;
+    fetchCart: () => Promise<void>;
+};
+
+interface UsePaymentPollingProps {
+    client: AkropolysAPI;
+    merchantReference: string | null;
+    onSuccess?: () => void;
+    onFailure?: (errorMsg?: string) => void;
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+declare function usePaymentPolling({ client, merchantReference, onSuccess, onFailure, intervalMs, timeoutMs, }: UsePaymentPollingProps): {
+    status: "PENDING" | "COMPLETED" | "FAILED" | "IDLE";
+    error: string | null;
+};
+
+export { AkropolysAPI, AkropolysClient, type AkropolysConfig, type AkropolysError, AkropolysProvider, type AkropolysTheme, type CartItem, type CartPayload, type ChatAction, type ChatMessage, type ChatMetadata, type ChatSource, type CheckoutConfig, type IngestResponse, KikuStream, type PaymentInitResponse, type PaymentStatusResponse, type Product, type RawProductInput, type SearchRequest, type SearchResponse, type SearchResult, type UsePaymentPollingProps, getAkropolysClient, initAkropolys, setSDKDefaultVertical, useAkropolys, useAkropolysContext, useCart, useIngest, useKiku, useListIngest, usePageIngest, usePaymentPolling, useSearch };