@jargon/platform-sdk-core/dist/resourceManager/index.d.ts

Core components of the Jargon Platform SDK for node.js

import { Platform, ResponseVariant } from './defs';
import { JargonResourceManagerFactory } from './factory';
export interface ResourceManagerOptions {
    /** When true (default), the resource manager will use the same random value
     * when randomly selecting among variations; this ensures that calls to different routines
     * (speak, reprompt, etc.) with identical RenderItem inputs will render the same output.
     * When false, each render call will use a different random value, leading to possible
     * inconsistencies in the final response. Note that this option can be overridden via
     * a RenderItem option.
     */
    consistentRandom?: boolean;
    /** Resource files for the provided locales will be loaded during initialization instead
     * of on first use; default is none.
     */
    localesToPreload?: string[];
    /** When true (default), the resource manager will keep track of which variation it selected,
     * allowing clients to view those selections through a call to selectedVariation(s)
     */
    trackSelectedVariations?: boolean;
    /** The directory where resources files are stored; defaults to './resources' */
    resourceDirectory?: string;
    /** Fallback locale configuration, overriding configuration (if any) present in the
     * resource manifest. The key in the record is the locale you're configuring the
     * fallbacks for; the value is the ordered list of locales to use for fallback content.
     */
    fallbackLocales?: Record<string, string[]>;
}
export declare const DefaultResourceManagerOptions: Required<ResourceManagerOptions>;
/**
 * Constructs ResourceManager instances for a specific locale
 */
export interface ResourceManagerFactory {
    /** Constructs a ResourceManager for the specified locale and platform
     * @param {string} locale The locale (such as 'en-US')
     * @param {string} platform One of 'ActionsOnGoogle' | 'Alexa' | 'Bixby' | 'Siri'
     */
    forLocaleAndPlatform(locale: string, platform: Platform): Promise<ResourceManager>;
}
/**
 * Exposes the core methods needed for runtime resource handling,
 * specifically the rendering of locale-specific strings based
 * on an input key and optional parameters
 */
export interface ResourceManager {
    /** Renders a string in the current locale
     * @param {RenderItem} item The item to render
     * @returns {Promise<string>} A promise to the rendered string.
     *  The promise will be rejected if the item doesn't exist
     */
    render(item: RenderItem): Promise<string>;
    /** Renders multiple string items
     * @param {RenderItem[]} items The items to render
     * @returns {Promise<string[]} A promise to the rendered strings.
     *  The promise will be rejected if any item doesn't exist
     */
    renderBatch(items: RenderItem[]): Promise<string[]>;
    /** Renders an object in the current locale
     * @param {RenderItem} item The item to render
     * @returns {Promise<T>} A promise to the rendered object.
     *  The promise will be rejected if the item doesn't exist
     */
    renderObject<T extends object>(item: RenderItem): Promise<T>;
    /** Renders a response in the current locale
     * @param {RenderItem} item The item to render
     * @returns {Promise<ResponseVariant>} A promise to the rendered response.
     *  The promise will be rejected if the item doesn't exist
     */
    renderResponse(item: RenderItem): Promise<ResponseVariant>;
    /** Renders multiple items. Unlike renderBatch the items may be of any type
     * @param {TypedRenderItem[]} items The items to render
     * @returns {Promise<RenderResult[]>} A promise to the results of the render operation.
     *   Those results include if each item was found; an item not existing will not result
     *   in the promise being rejected
     */
    renderAll(items: TypedRenderItem[]): Promise<RenderResult[]>;
    /** Retrieves information about the selected variant for a rendered item. This
     * will only return a result when rendering the item required a variation
     * selection. If item has been used for multiple calls to a render routine
     * the result of the first operation will be returned; use selectedVariations
     * to see all results. Only supported when using a local ResourceManager implementation
     * @param {RenderItem} item The item to retrieve the selected variant for
     * @return {Promise<SelectedVariation>} A promise to the selected variation
     */
    selectedVariation(item: RenderItem): Promise<SelectedVariation>;
    /** Retrieves information about all selected variations for rendered item. This
     * will only return a result for items that required a variation selection
     * during rendering. Results are ordered by the ordering of the calls to render
     * routines. Only supported when using a local ResourceManager implementation
     * @return {Promise<SelectedVariation[]>} A promise to the selected variations
     */
    selectedVariations(): Promise<SelectedVariation[]>;
    /** The locale the resource manager uses */
    readonly locale: string;
}
/**
 * Parameters used when rendering a resource. Keys must be
 * strings, and values either strings, numbers, or RenderItem
 * objects. When a RenderItem is used as a value the resource
 * manager will recursively call render() to obtain the parameter
 * value.
 */
export interface RenderParams {
    [param: string]: string | number | RenderItem;
}
/**
 * Options control additional rendering behavior, overriding the
 * settings configured at the ResourceManager level.
 */
export interface RenderOptions {
    /** When true, forces the use of a new random value for selecting variations,
     * overriding consistentRandom. Only valid when for local ResourceManager
     * implementations
     */
    readonly forceNewRandom?: boolean;
}
export declare const DefaultRenderOptions: RenderOptions;
/**
 * An item to render
 */
export interface RenderItem {
    /** The resource key to render */
    key: string;
    /** Params to use during rendering (optional) */
    params?: RenderParams;
    /** Render options (optional) */
    options?: RenderOptions;
}
export declare type ItemType = 'object' | 'response' | 'string';
export declare type RenderStatus = 'found' | 'not_found' | 'param_not_found';
export interface TypedRenderItem extends RenderItem {
    type: ItemType;
}
export interface RenderResult {
    key: string;
    type: ItemType;
    status: RenderStatus;
}
export interface ObjectRenderResult extends RenderResult {
    type: 'object';
    result: object;
}
export interface ResponseRenderResult extends RenderResult {
    type: 'response';
    result: ResponseVariant;
}
export interface StringRenderResult extends RenderResult {
    type: 'string';
    result: string;
}
/**
 * Helper function for constructing a RenderItem
 * @param key The resource key to render
 * @param params Optional params for the render operation
 * @param options Options for the rendering operation
 */
export declare function ri(key: string, params?: RenderParams, options?: RenderOptions): RenderItem;
/**
 * Helper function for constructing a TypedRenderItem
 * @param type The type of resource to render
 * @param key The resource key to render
 * @param params Optional params for the render operation
 * @param options Options for the rendering operation
 */
export declare function tri(type: ItemType, key: string, params?: RenderParams, options?: RenderOptions): TypedRenderItem;
export interface SelectedVariation {
    /** The RenderItem instance passed to render(Batch) */
    readonly item: RenderItem;
    /** The full key of the selected variation (i.e., this.ri.key + '.' + this.variationKey) */
    readonly key: string;
    /** The selected variation subkey */
    readonly variationKey: string;
}
export declare const DefaultResourceManagerFactory: typeof JargonResourceManagerFactory;
export * from './defs';
export * from './remoteFactory';