@snap/camera-kit/dist/lens/LensRepository.d.ts

Camera Kit Web

import type { FetchHandler } from "../handlers/defaultFetchHandler";
import type { RequestStateEventTarget } from "../handlers/requestStateEmittingHandler";
import type { LensDownloadDimensions } from "../metrics/reporters/reportLensAndAssetDownload";
import type { Handler } from "../handlers/HandlerChainBuilder";
import type { Lens, LensProtoWithGroupId } from "./Lens";
import type { LensAssetRepository } from "./assets/LensAssetRepository";
import type { LensSource } from "./LensSource";
type LensFetchHandler = Handler<[
    RequestInfo,
    LensDownloadDimensions
], [
    ArrayBuffer,
    Response
], RequestInit | undefined>;
/**
 * Lens assets are included in a manifest, and each will indicate when that asset will be used by the lens.
 *
 * Assets can have the following timing values:
 * - `required`: the lens will definitely request this asset immediately when the lens is applied.
 * - `onDemand`: the lens may request this asset at some time while the lens is applied.
 *
 * Depending on the use-case, an application may want to cache both required and onDemand assets for
 * a particular lens, or may decide to only cache required assets (or cache no assets).
 *
 * @category Lenses
 */
export type AssetTiming = "required" | "onDemand";
export interface LensBinary {
    lensBuffer: ArrayBuffer;
    lensChecksum: string;
}
/**
 * The LensRepository is used to query for lenses from specific lens groups, or for a lens with a specific ID.
 *
 * Lens groups are configured in the CameraKit Portal -- that's where you'll find lens group IDs and lens IDs.
 *
 * Lenses must be loaded by the LensRepository before they can be applied to a {@link CameraKitSession}.
 *
 * @example
 * ```ts
 * const cameraKit = await bootstrapCameraKit(options)
 * const session = await cameraKit.createSession()
 * const lens = await cameraKit.lensRepository.loadLens(lensId, groupId)
 * session.applyLens(lens)
 * ```
 *
 * @category Lenses
 */
declare class LensRepository {
    private readonly lensFetchHandler;
    private readonly lensSources;
    private readonly lensAssetRepository;
    private readonly metadataCache;
    private readonly binariesCache;
    /** @internal */
    constructor(lensFetchHandler: LensFetchHandler, lensSources: LensSource[], lensAssetRepository: LensAssetRepository);
    /**
     * Retrieve a single Lens.
     *
     * @param lensId Desired Lens's unique ID. Can be found in the CameraKit Portal.
     * @param groupId The ID of a group containing the desired Lens. Can be found in the CameraKit Portal.
     * @returns Resolves with the desired Lens, or rejects if an error occurred (including a missing Lens).
     */
    loadLens(lensId: string, groupId: string): Promise<Lens>;
    /**
     * Retrieve the Lenses contained in a list of Lens Groups.
     *
     * This may result in multiple requests to retrieve Lens data (e.g. one per desired group). If any constituent
     * requests fail, those errors will be reported in the response – but the returned Promise will not be rejected. Any
     * Lenses which could be successfully retrieved will be available in the response.
     *
     * @param groupIds A list of Lens Group IDs. Can be found in the CameraKit Portal.
     * @returns Resolves with a flattened list of all lenses in the desired groups. If any errors occurred during the
     * query operation, these will be included in a separate list. If errors are present, the list of Lenses may not
     * contain all the Lenses from the desired groups.
     */
    loadLensGroups(groupIds: string[]): Promise<{
        errors: Error[];
        lenses: Lens[];
    }>;
    /**
     * Loads and caches lens content and dependencies to reduce latency when {@link CameraKitSession.applyLens} is later
     * called to apply the lens. This is an in-memory cache, it will not be persisted across page loads.
     *
     * This may useful if the application A) knows which lenses will be applied and B) has some opportunity to call
     * this method before a lens is applied. For example, if the user must perform some other actions before lenses
     * become active, this might be a good opportunity to cache lenses to improve applyLens latency.
     *
     * @example
     * ```ts
     * const lens = await cameraKit.lensRepository.loadLens(lensId, groupId)
     * await cameraKit.lensRepository.cacheLensContent([lens])
     *
     * // sometime later -- this call will use the cached lens content, making lens application faster.
     * await cameraKitSession.applyLens(lens)
     * ```
     *
     * @param lenses Array of lenses to cache in memory.
     * @param assetTimingsToCache Lenses specify certain required assets that are necessary for the lens to render, and
     * other assets which may be needed by the lens. By default this method will cache all of those assets, but this
     * behavior can be modified to only load the required assets, only the "onDemand" assets, or neither (by passing
     * an empty array).
     */
    cacheLensContent(lenses: Lens[], assetTimingsToCache?: AssetTiming[]): Promise<void>;
    /**
     * Returns loaded Lens metadata if available.
     */
    getLensMetadata(lensId: string): LensProtoWithGroupId | undefined;
    /**
     * Removes Lens content from the in-memory cache.
     */
    removeCachedLenses(lenses: Lens[]): void;
    /**
     * Fetches lens content and assets. This may come from the cache, otherwise network requests will be made.
     *
     * @internal
     *
     * @param lens Lens to fetch content for.
     * @param lowPriority Flag indicating if the fetch requests should be treated with lower priority,
     *                    leveraging browser capabilities to defer or deprioritize network traffic.
     */
    getLensContent(lens: Lens, lowPriority?: boolean): Promise<LensBinary>;
}
export { LensRepository };
/**
 * @internal
 */
export declare const lensRepositoryFactory: {
    (args_0: RequestStateEventTarget, args_1: FetchHandler, args_2: LensSource[], args_3: LensAssetRepository): LensRepository;
    token: "LensRepository";
    dependencies: readonly ["requestStateEventTarget", "defaultFetchHandler", "lensSources", "lensAssetRepository"];
};
//# sourceMappingURL=LensRepository.d.ts.map