@stackend/api/api/index.d.ts

JS bindings to api.stackend.com

import { Request } from '../request';
import { Community, Module } from '../stackend';
import { User } from '../user';
import { Content, Page, SubSite } from '../cms';
import { Privilege } from '../user/privileges';
import { Dispatch } from 'redux';
import { ListProductsQuery, ShopDataResult } from '../shop';
import Logger from '../util/Logger';
import XcapObject from './XcapObject';
/**
 * Stackend logger
 */
export declare let logger: Logger;
/**
 * Get the stackend logger
 */
export declare function getLogger(): Logger;
/**
 * Set the default logger
 * @param newLogger
 */
export declare function setLogger(newLogger: Logger): void;
export declare const STACKEND_DEFAULT_SERVER = "https://api.stackend.com";
export declare const STACKEND_DEFAULT_CONTEXT_PATH = "";
/**
 * Xcap API configuration
 */
export interface Config {
    /** Absolute url to the api server*/
    server: string;
    /** Context path on the api server */
    contextPath: string;
    /** Absolute url to the api server including context path and /api */
    apiUrl: string;
    /** Deploy profile */
    deployProfile: DeployProfile;
    /** Recaptcha site key */
    recaptchaSiteKey: string | null;
    /** Google Analytics key */
    gaKey: string | null;
    /** Other configuration properties */
    [propName: string]: any;
}
/**
 * Known deploy profiles
 */
export declare enum DeployProfile {
    STACKEND = "stackend"
}
export declare let configDefaults: Partial<Config>;
/**
 * Set default configuration options
 * @param defaults
 */
export declare function setConfigDefaults(defaults: Partial<Config>): void;
/**
 * Is the app running server side?
 */
export declare function isRunningServerSide(): boolean;
/**
 * Is the app running in the browser
 */
export declare function isRunningInBrowser(): boolean;
export declare function setRunningServerSide(ssr: boolean): void;
/**
 * The default community ("stackend")
 * @type {string}
 */
export declare const DEFAULT_COMMUNITY = "stackend";
/**
 * Key holding related objects in the json response.
 * @type {string}
 */
export declare const RELATED_OBJECTS = "__relatedObjects";
/**
 * Key holding related objects that are not IdAware in the json response.
 * @type {string}
 */
export declare const EXTRA_OBJECTS = "__extraObjects";
/**
 * Key holding related likes in the json response.
 * @type {string}
 */
export declare const LIKES = "likes";
/**
 * Key holding related votes in the json response.
 * @type {string}
 */
export declare const VOTES = "votes";
/**
 * Parameter name holding the community
 * @type {string}
 */
export declare const COMMUNITY_PARAMETER = "__community";
/**
 * Parameter specifying an alternative rich content chain used to serialize the result
 * @type {string}
 */
export declare const RICH_CONTENT_CHAIN_PARAMETER = "xcap.rich-content-chain";
/**
 * API errors
 */
export interface XcapJsonErrors {
    /**
     * Error messages from the API
     */
    actionErrors: Array<string>;
    /**
     * Field errors. Maps from a field (parameter) name to validation error messages for that parameter.
     */
    fieldErrors: {
        [fieldName: string]: Array<string>;
    };
}
/**
 * Extra objects that are not IdAware.
 * The key and id is implementation dependant.
 */
export declare type ExtraObjects = {
    [key: string]: {
        [context: string]: {
            [id: string]: any;
        };
    };
};
/**
 * Base type for API results
 */
export interface XcapJsonResult {
    /**
     * Action specific result code.
     * Common codes includes: "success", "input", "notfound" etc.
     */
    __resultCode: string;
    /**
     * Error messages. Not present if the API call was successful
     */
    error?: XcapJsonErrors;
    /**
     * Additional debug messages (non errors) from the API
     */
    __messages?: Array<string>;
    /**
     * Related objects mapped from a hash string to the actual object.
     * Present only when a call is successful.
     */
    __relatedObjects?: {
        [ref: string]: XcapObject;
    };
    /**
     * Related objects that are not IdAware
     * Present only when a call is successful and has extra objects.
     */
    __extraObjects?: ExtraObjects;
    /** Additional properties specific to the called API method  */
    [propName: string]: any;
}
/**
 * Redux store state
 */
export declare type State = {
    [key: string]: any;
};
/**
 * Function that dispatches actions against the store
 */
export declare type Thunk<A> = (dispatch: Dispatch, getState: () => State) => A;
/**
 * Construct basic configuration from the environment.
 */
export declare function _constructConfig(): Config;
/**
 * Get the API configuration object
 * @type {Thunk<Config>}
 */
export declare function getConfiguration(): Thunk<Config>;
/**
 * Set the API configuration
 * @param config
 */
export declare function setConfiguration(config: Partial<Config>): Thunk<any>;
/**
 * Reset the API configuration to the defaults
 */
export declare function resetConfiguration(): Thunk<any>;
/**
 * Server domain enabling CORS calls
 * @type {string}
 */
export declare function getServer(): Thunk<string>;
/**
 * Server domain enabling CORS calls
 * @type {string}
 */
export declare function _getServer(config: Config | null): string;
/**
 * @deprecated bad practise to dispatch getters which doesn't set any state, use api._getDeployProfile instead
 * Get the deploy profile name. Allows customized styling for different deployments
 * @return a profile name, or the empty string.
 */
export declare function getDeployProfile(): Thunk<string>;
/**
 * Get the deploy profile name. Allows customized styling for different deployments
 * @return a profile name, or the empty string.
 */
export declare function _getDeployProfile(config: Config | null): string;
/**
 * ContextPath of Api server
 * @return {Thunk<string>}
 */
export declare function getContextPath(): Thunk<string>;
/**
 * ContextPath of Api server
 * @type {string}
 */
export declare function _getContextPath(config: Config | null): string;
/**
 * Server domain address with ContextPath
 * @return {Thunk<string>}
 */
export declare function getServerWithContextPath(): Thunk<string>;
/**
 * Server domain address with ContextPath from redux store
 */
export declare function getServerWithContextPathFromStore(config: Config): string;
/**
 * Server domain address with ContextPath
 */
export declare function _getServerWithContextPath(config: Config): string;
/**
 * Get the path to the current community.
 * For example "/stackend/test"
 * @return never null
 */
export declare function getCommunityPath(): Thunk<string>;
/**
 * Get the path to the current community.
 * For example "/stackend/test"
 * @return never null
 */
export declare function getCommunityPathFromStore({ request }: {
    request: Request;
}): string;
/**
 * Get the absolute path to the current community, including host name.
 * For example "stackend.com/stackend/test"
 * Same as request.absoluteCommunityUrl.
 * @return {Thunk<string>}
 */
export declare function getAbsoluteCommunityPath(): Thunk<string>;
/**
 * Get the community path. In stackend /stacks/, return the context path, not the current community path.
 * @return {Thunk<string>}
 */
export declare function getEffectiveCommunityPath(): Thunk<string>;
/**
 * Api url containing server and ContextPath if necessary.
 * @param community Optional community
 * @return {Thunk<string>}
 */
export declare function getAbsoluteApiBaseUrl(community: string): Thunk<string>;
/**
 * Api url containing server and ContextPath if necessary.
 * @param config Xcap config
 * @param communityPermalink Optional community permalink
 * @type {string}
 */
export declare function _getAbsoluteApiBaseUrl({ config, communityPermalink }: {
    config: Config;
    communityPermalink?: string;
}): string;
/**
 * Get the current community name (For example "c123")
 * @return may return null
 */
export declare function getCurrentCommunity(): Thunk<Community | null>;
/**
 * Get the current community permalink as used in name (For example "test").
 *
 * @return May return null
 */
export declare function getCurrentCommunityPermalink(): Thunk<string | null>;
/**
 * Get the base url to the api server.
 * Typically '/APP/api/endpoint'
 * @param state Store state
 * @param url extra url
 * @param parameters extra parameters (optional)
 * @param notFromApi boolean if the url is not in the api
 * @param community community name
 * @param componentName Component name used to look up config
 * @param context Context name used to look up config
 * @returns {String} the api url
 * @see COMMUNITY_PARAMETER
 */
export declare function _getApiUrl({ state, url, parameters, notFromApi, community, componentName, context }: {
    state: State;
    url: string;
    parameters?: any;
    notFromApi?: boolean;
    community?: string | null;
    componentName?: string | null;
    context?: string | null;
}): string;
/**
 * Get the base url to the api server.
 * Typically '/APP/api/endpoint'
 * @param url extra url
 * @param parameters extra parameters (optional)
 * @param notFromApi boolean if the url is not in the api
 * @param community community name
 * @param componentName Component name used to look up config
 * @param context Context name used to look up config
 * @returns {Thunk} the api url
 * @see COMMUNITY_PARAMETER
 */
export declare function getApiUrl({ url, parameters, notFromApi, community, componentName, context }: {
    url: string;
    parameters?: any;
    notFromApi?: boolean;
    community?: string | null;
    componentName?: string | null;
    context?: string | null;
}): Thunk<string>;
/**
 * Add any related objects received to the store
 * @param dispatch
 * @param json
 */
export declare function addRelatedObjectsToStore(dispatch: Dispatch, json: any): void;
export declare type XcapOptionalParameters = {
    /** Set the community parameter to target a specific community (typically from admin) */
    [COMMUNITY_PARAMETER]?: string | null | undefined;
};
/**
 * Parameters for requests requiring an appid and api key
 */
export declare type StackendApiKeyParameters = {
    /** Set this if the request requires a stackend app id and api key */
    stackend_appid?: string | null | undefined;
    /** Set this if the request requires a stackend app id and api key */
    stackend_apikey?: string | null | undefined;
};
export declare type ParameterValue = string | number | boolean | null | undefined | Array<string | number | boolean | null>;
export declare type Parameters = (XcapOptionalParameters & StackendApiKeyParameters & {
    [name: string]: ParameterValue;
}) | string;
export interface XcapJsonRequest {
    /** Path on the api server */
    url: string;
    /** Parameters as a js object */
    parameters?: Parameters | IArguments;
    /** Community permalink */
    community?: string | null;
    /** Component name used for config (for example "like") */
    componentName?: string | null;
    /** Community context used for config (for example "forum") */
    context?: string | null;
    /** Optional cookie string to pass on */
    cookie?: string | null;
    /** if the url is not in the api
     * @deprecated
     */
    notFromApi?: boolean;
}
/**
 * Get json from the api.
 *
 * @param url
 * @param parameters
 * @param notFromApi boolean if the url is not in the api
 * @param community Current community name
 * @param componentName Component name used for config (for example "like")
 * @param context Community context used for config (for example "forum")
 * @param cookie Optional cookie string to pass on. Typically used for SSR only
 * @returns {Thunk}
 */
export declare function getJson<T extends XcapJsonResult>({ url, parameters, notFromApi, community, componentName, context, cookie }: XcapJsonRequest): Thunk<Promise<T>>;
/**
 * Get json from the api.
 *
 * @param url
 * @param parameters
 * @returns {Promise}
 */
export declare function getJsonOutsideApi({ url, parameters }: {
    url: string;
    parameters?: any;
}): Thunk<Promise<XcapJsonResult>>;
/**
 * Post using the json api.
 * @param url
 * @param parameters
 * @param community Current community name
 * @param componentName Component name used for config (for example "like")
 * @param context Community context used for config (for example "forum")
 * @returns {Thunk}
 */
export declare function post<T extends XcapJsonResult>({ url, parameters, community, componentName, context }: {
    url: string;
    parameters?: Parameters | IArguments;
    community?: string | null;
    componentName?: string | null;
    context?: string | null;
}): Thunk<Promise<T>>;
export interface GetExpressTokenResult extends XcapJsonResult {
    xpressToken: string;
    xcapAjaxToken: string;
}
/**
 * Get a token used for CSRF prevention.
 */
export declare function getXpressToken({ community, componentName, context }: {
    community?: string | null;
    componentName?: string | null;
    context?: string | null;
}): Thunk<Promise<GetExpressTokenResult>>;
/**
 * Get a configuration variable.
 *
 * <p>When looking up a key, the following order is used:</p>
 * <ol>
 *  <li>COMPONENT.CONTEXT.KEY</li>
 *  <li>COMPONENT.KEY</li>
 *  <li>KEY</li>
 *  <li>Default value</li>
 * </ol>
 *
 * @param key configuration key
 * @param componentName Component name (Optional)
 * @param context Community context(Optional)
 * @param defaultValue Default value (Optional)
 */
export declare function getConfig({ key, componentName, context, defaultValue }: {
    key: string;
    componentName?: string;
    context?: string;
    defaultValue?: any;
}): Thunk<any>;
export declare function _getConfig({ config, key, componentName, context, defaultValue }: {
    config: Config;
    key: string;
    componentName?: string | null;
    context?: string | null;
    defaultValue?: any;
}): any;
/**
 * Construct an url to the UI.
 *
 * @param path Path
 * @param parameters Parameters map
 * @param hash
 */
export declare function createUrl({ path, params, hash }: {
    path: string;
    params?: any;
    hash?: string;
}): string;
/**
 * Construct an url to a community in the UI.
 *
 * @param request Request object from requestReducers.ts
 * @param path Path
 * @param parameters Parameters map
 * @param hash
 * @param absolute Should the url be absolute (boolean)
 */
export declare function createCommunityUrl({ request, path, params, hash, absolute }: {
    request?: Request;
    path: string;
    params?: any;
    hash?: string;
    absolute?: boolean;
}): string;
/**
 * Convert an Arguments, Array or Object to an object
 * @param args
 * @return {Object}
 */
export declare function argsToObject(args: Parameters | IArguments | undefined | null): null | Parameters;
/**
 * Post process  data from the XCAP json api.
 *
 * - Turns timestamps into Date objects
 * - Resolves references to objects
 *
 * The method modifies data in place to avoid copying.
 *
 * @param result
 * @return {Object}
 */
export declare function postProcessApiResult(result: XcapJsonResult): XcapJsonResult | null;
/**
 * Format the response action and field errors object to a string.
 * @return {String}
 */
export declare function getJsonErrorText(response?: XcapJsonResult): string;
/**
 * Construct a new XcapJsonResult
 * @param resultCode
 * @param actionErrors
 * @param fieldErrors
 * @param data
 */
export declare function _newXcapJsonResult<T extends XcapJsonResult>(resultCode: string, actionErrors: undefined | string | Array<string>, fieldErrors: undefined | {
    [fieldName: string]: string;
}, data?: any): T;
/**
 * Construct a new API result
 * @param resultCode
 * @param data
 */
export declare function newXcapJsonResult<T extends XcapJsonResult>(resultCode: string, data?: any): T;
/**
 * Construct a new API result
 * @param actionErrors
 * @param fieldErrors
 */
export declare function newXcapJsonErrorResult<T extends XcapJsonResult>(actionErrors: string | Array<string>, fieldErrors?: {
    [fieldName: string]: string;
}): T;
/**
 * Get a human readable type of an xcap object
 * @param objectOrClassName
 * @return {String}
 */
export declare function getTypeName(objectOrClassName: string | XcapObject): string;
/**
 * Translations
 */
export interface Translations {
    /** Language code */
    lang: string;
    messages: {
        [key: string]: string;
    };
}
/**
 * Extra data required by some modules, like for example comment listings for comment modules
 */
export interface ModuleExtraData {
    [moduleType: string]: {
        [referenceOrModuleId: number]: any;
    };
}
export interface GetInitialStoreValuesResult extends XcapJsonResult {
    /** Was the community determined from the domain rather that from the permalink? */
    communityFromDomain: boolean;
    /** Permalink of community */
    permalink: string;
    /** Current community. may be null */
    stackendCommunity: Community | null;
    /** Privilege of current community (when running in /stacks) */
    communityPrivilegeType: Privilege;
    domain: string | null;
    /** Current user. Stackend user when running in /stacks */
    user: User | null;
    xcapApiConfiguration: {
        [key: string]: any;
    };
    numberOfUnseen: number;
    modules: {
        [id: string]: Module;
    };
    /** Maps from id to content */
    cmsContents: {
        [id: string]: Content;
    };
    /** Maps from id to  Page */
    cmsPages: {
        [id: string]: Page;
    };
    /** Maps from id to  SubSite */
    subSites: {
        [id: string]: SubSite;
    };
    /** Maps the referenceUrl parameter to an id */
    referenceUrlId: number;
    /** Maps the shopify domain to an id */
    shopifyDomainReferenceUrlId: number;
    /** Shop data, if requested */
    shopData: ShopDataResult | null;
    /** Translation data, if not stackend.com */
    translations: Translations | null;
    /** Extra data for modules */
    data: ModuleExtraData;
}
/**
 * Extra module specific parameters
 */
export interface ModuleExtraParameters {
    /**
     * Key given by module handler, for example comments
     */
    [moduleHandlerKey: string]: {
        /**
         * Key: moduleId + "_" + referenceId
         */
        [moduleId_referenceId: string]: {
            /**
             * Parameter names and values
             */
            [name: string]: any;
        };
    };
}
/**
 * Add all extra parameters
 * @param params
 * @param moduleKey
 * @param moduleId (may be 0 if not used)
 * @param referenceId (may be 0 if not used)
 * @param values
 */
export declare function addModuleExtraParameters(params: ModuleExtraParameters, moduleKey: string, moduleId: number, referenceId: number, values: {
    [name: string]: any;
}): void;
export interface GetInitialStoreValuesRequest {
    permalink?: string;
    domain?: string;
    communityId?: number;
    moduleIds?: Array<number>;
    contentIds?: Array<number>;
    pageIds?: Array<number>;
    subSiteIds?: Array<number>;
    cookie?: string;
    referenceUrl?: string;
    stackendMode?: boolean;
    productHandles?: Array<string>;
    productCollectionHandles?: Array<string>;
    productListings?: Array<ListProductsQuery>;
    shopImageMaxWidth?: number;
    shopListingImageMaxWidth?: number;
    /**
     * Module specific parameters
     */
    moduleExtraParameters?: ModuleExtraParameters;
}
/**
 * Load the initial store values
 */
export declare function getInitialStoreValues(params: GetInitialStoreValuesRequest): Thunk<Promise<GetInitialStoreValuesResult>>;
/**
 * Log a javascript error
 * @param error Browser Error object
 * @param store
 */
export declare function logJsError(error: any, store?: any): Promise<any>;
/**
 * Create a hash code of a string. Roughly the same impl as java.
 * @param str
 * @returns {number}
 */
export declare function getHashCode(str: string): number;
//# sourceMappingURL=index.d.ts.map