@flike/recommend/lib/index.d.ts

Wrapper for the Flike Recommendation API.

import { AxiosInstance } from "axios";
export interface FlikeErrorInvalidParams {
    error: "Invalid Parameters";
    statusCode: 400;
    /** List of parameter names that are invalid */
    detail: string[];
    /** A human-friendly hint about what to do */
    hint?: string;
}
export interface FlikeErrorUnauthorized {
    error: "Unauthorized";
    statusCode: 401;
    /** A human-friendly hint about what to do */
    hint?: string;
}
export interface FlikeErrorForbidden {
    error: "Forbidden";
    statusCode: 403;
    /** A human-friendly hint about what to do */
    hint?: string;
}
export interface FlikeErrorUnknown {
    error: "Unknown";
    hint?: string;
}
export declare type FlikeError = FlikeErrorInvalidParams | FlikeErrorUnauthorized | FlikeErrorForbidden | FlikeErrorUnknown;
/**
 * Recommendation of a content item for a user.
 */
export interface Recommendation {
    /** Unique identifier of the content item being recommended. */
    itemId: string;
    /** Probability of a user 'liking' the recommended item. */
    probability: number;
}
export interface RecommendationsResponse {
    /** Recommendations for a user. */
    items: Recommendation[];
    /** The unique identifier of this recommendation. */
    correlationId: string;
}
export declare type BatchRecommendationsResponseBase = {
    jobId: string;
    numUsers: number;
    submittedAt: string;
    inputsFile: string;
    resultsFormat: string;
};
export declare type BatchRecommendationsCreatingResponse = BatchRecommendationsResponseBase & {
    status: "creating";
};
export declare type BatchRecommendationsRunningResponse = BatchRecommendationsResponseBase & {
    status: "running";
};
export declare type BatchRecommendationsCompletedResponse = BatchRecommendationsResponseBase & {
    status: "completed";
    completedAt: string;
    resultsFile: string;
};
/**
 * Batch Recommendations for a large number of users
 */
export declare type BatchRecommendationsResponse = BatchRecommendationsCreatingResponse | BatchRecommendationsRunningResponse | BatchRecommendationsCompletedResponse;
export interface BatchRecommendOptionsBase {
    /** Optional - webhook to invoke when the job status changes to running or completed. */
    callback?: string;
    /** Format of the results file (one of `jsonl`, `json-array`, or `json-object`). Defaults to `jsonl` */
    resultsFormat?: string;
}
export declare type BatchRecommendOptions = BatchRecommendOptionsBase | (BatchRecommendOptionsBase & {
    /** Optional - list of user ids for which to predict recommended items. Limited to 100'000 users and mutually exclusive with userIdsFile. */
    userIds: string[];
    userIdsFile?: never;
}) | (BatchRecommendOptionsBase & {
    userIds?: never;
    /**  Optional - URL to a file containing lines of user ids for which to predict recommendations. Mutually exclusive with userIds. */
    userIdsFile: string;
    /** Optional - headers to send along when downloading the userIdsFile. Use this to manage authorization. */
    userIdsFileReqHeaders?: Record<string, string>;
});
export declare class BatchRecommendationsJob {
    /** @internal */
    recommender: Recommender;
    jobId: string;
    numUsers: number;
    submittedAt: Date;
    completedAt: undefined | Date;
    status: "creating" | "running" | "completed";
    inputsFile: string;
    resultsFile: undefined | string;
    /** @internal */
    constructor(recommender: Recommender, creationResponse: BatchRecommendationsCreatingResponse);
    /**
     * Update the job's execution status.
     *
     * Updates the job in-place.
     *
     * @returns A reference to the job itself
     *
     * @throws FlikeError when information about the job is not available.
     * */
    update_status(): Promise<BatchRecommendationsJob>;
    /**
     * Poll until the job completes.
     *
     * It is strongly recommended to instead use the webhook callback parameter
     * when creating the job.
     *
     * @param interval Interval in seconds between polling the server for status changes (default: 60).
     *
     * @throws FlikeError when information about the job is not available.
     */
    poll(interval?: number): Promise<BatchRecommendationsJob>;
}
/**
 * Flike Recommender lets you easily recommend content items to users based on their interactions.
 */
export declare class Recommender {
    /** @internal */
    server_url: string;
    /** @internal */
    version: string;
    /** @internal */
    api_key: string;
    /** @internal */
    axiosInstance: AxiosInstance;
    /**
     *
     *
     * @param api_key Your API key.
     * @param server_url (only used for internal testing)
     * @param version Version of the API to use. Defaults to the most current version.
     */
    constructor(api_key: string, server_url?: string, version?: string);
    /**
     * Validates the connectivity to the API.
     *
     * @returns Resolves to `true` if the connection is successful, `false` otherwise.
     */
    validate(): Promise<boolean>;
    /**
     * Get an array of content items that a user is probable to consume/buy/subscribe/like or similar.
     * Recommendations are sorted by descending probability of a user 'liking' them.
     *
     * @param userId The unique identifier of the user.
     * @param numResults Number of content items that should be suggested.
     * @returns Resolves to a `RecommendationsResponse` if successful. Otherwise, it will throw an exception.
     *
     * @throws FlikeError when the recommendation fails.
     */
    recommend(userId: string, numResults: number, context?: {
        itemId: string;
        longitude: number;
        latitude: number;
    }): Promise<RecommendationsResponse>;
    /**
     * Create a new batch recommendation job for a large quantity of users.
     *
     * This starts a long-running computation whose status you can check with the
     * {@link batch_recommend_query} method.
     *
     * @param numResults Number of results to compute per user.
     * @param options: Optional settings for the batch job (see {@link BatchRecommendOptions}).
     * @returns Resolves to a `BatchRecommendationsJob` if successful. Otherwise, throws an exception.
     *
     * @throws FlikeError when the job cannot be created.
     */
    batch_recommend(numResults: number, options: BatchRecommendOptions): Promise<BatchRecommendationsJob>;
    /**
     * Check the status of a batch recommendation job.
     *
     * The job must have previously been created using {@link batch_recommend}.
     *
     * Note that instead of polling, you can pass a webhook URL to {@link
     * batch_recommend}. This webhook will be invoked whenever the job status
     * changes to receive a POST request with the `BatchRecommendationsResponse`
     * as payload.
     *
     * @see {@link batch_recommend}
     * @param jobId The UUID of the job to query.
     * @returns Resolves to a `BatchRecommendationsResponse` if successful. Otherwise, throws an exception.
     *
     * @throws FlikeError when information about the job is not available.
     */
    batch_recommend_query(jobId: string): Promise<BatchRecommendationsResponse>;
}