@xman.io/xman-js-sdk/dist/sdk/xman-js-sdk.d.ts

Javascript/typescript SDK to access the data published using XMan.io

/**
 * Options for reading a list
 */

interface ListParams {
  /** in page size. Default 12. Max 24. */
  pageSize?: number;
  /** the `nextPageToken` returned by the previous `list()` call. */
  nextPage?: string;
  /** property path to order by, followed by direction. E.g. `name asc` */
  orderBy?: string;
}

declare namespace XmanFieldValue {
  interface Reference {
    collection: string;
    id: string;
    /** Label is cached at the time reference is created. Not updated with the item changes. */
    label?: string;
    altText?: string;
    thumbId?: string;
  }

  interface File {
    contentType: string,
    name: string,
    storageName: string,
    md5Hash: string,
    size: number,
    publicUrl: string
  }

  interface Place {
    rawAddress?: string,
    streetAddress?: string,
    unit?: string,
    city?: string,
    state?: string,
    postal_code?: string,
    country?: string,
    neighborhood?: string,
    latitude: number,
    longitude: number,
    geohashes?: string[],
    geohash?: {
      p_1: string,
      p_2: string,
      p_3: string,
      p_4: string,
      p_5: string,
      p_6: string,
      p_7: string,
      p_8: string,
      p_9: string,
      p_10: string,
      p_11: string,
      p_12: string,
    },
    google_place?: {
      neighborhood: string,
      administrative_area_level_1: string,
      route: string,
      postal_code: string,
      locality: string,
      country: string,
      street_number: string,
      subpremise: string,
      latitude: number,
      longitude: number
    },
  }
}

interface XmanItem<T> {
  id: string;
  data: T;
  createTime: string;
  updateTime: string;
  version: number;
}

interface XmanItemsList<T> {
  items: XmanItem<T>[];
  nextPageToken?: string;
}

interface ImageSettings {
  /**
   * Key to identify the variation of the image.
   * `getImage(s)` will return variations in a map keyed by this key
   * */
  key: string;
  /** Image width. If larger than actual image width, actual width is used */
  width?: number;
  /** Image height. If larger than actual image height, actual height is used */
  height?: number;
  fit?: 'cover' | 'fill' | 'contain';
}

interface HTMLImageData {
  alt: string;
  variations: {
    [key: string]: {
      src: string;
      width?: number;
      height?: number;
    };
  };
}

interface WorkspaceWrapper {
    /**
     * Reads a specific item. *Returns `null` if item is not found*
     * @param {string} collection collection ID (e.g. xman-articles)
     * @param {string} itemId 20 character Item ID (e.g. dXEFNfms7zlMI8AdbFND)
     * @returns {Promise<XmanItem<T> | null>} an item or `null`
     */
    read<T>(collection: string, itemId: string): Promise<XmanItem<T> | null>;
    /**
     * Loads and returns the first referenced item in the reference list. If the list is empty, returns null
     *
     * @param referenceFieldValue {XmanFieldValue.Reference[]} field value of a reference field. Use directly from the response of previous calls
     * @returns {Promise<XmanItem<T> | null>} First referenced item or `null` if no items referenced
     */
    readReferencedItem<T>(referenceFieldValue?: XmanFieldValue.Reference[]): Promise<XmanItem<T> | null>;
    /**
     * Loads and returns all the referenced items in the reference list. If the list is empty, returns [].
     * This method ignores all items that fail to load. E.g. The API Client you created may not have access to some collections
     * If you want the call to fail when such errors happen, pass `failOnPartialFailure = true`
     *
     * @param referenceFieldValue {XmanFieldValue.Reference[]} field value of a reference field. Use directly from the response of previous calls
     * @param failOnPartialFailure {boolean} if `true` throws an error if any item reference throws an error
     * @returns {[Promise<XmanItem<T>]} First referenced item or `null` if no items referenced
     * @throws Error when `failOnPartialFailure = true` and one or more items fail to load
     */
    readReferencedItems<T>(referenceFieldValue?: XmanFieldValue.Reference[], failOnPartialFailure?: boolean): Promise<XmanItem<T>[]>;
    /**
     * Read a list of items. Simple paging and sorting is supported.
     *
     * Use `query()` for more sophisticated queries
     *
     * @param {string} collection
     * @param {ListParams?} listParams Parameters for the list
     */
    list<T>(collection: string, listParams?: ListParams): Promise<XmanItemsList<T>>;
    /**
     * Generates alt text and image URLs for a set of image references.
     *
     * @param {XmanFieldValue.Reference[]} imgRefs pointers to image items. You can use the reference field values directly
     * @param {ImageSettings?} imageSettings image settings
     * @returns Promise<HTMLImageData[]> list of image details
     */
    getImages(imgRefs: XmanFieldValue.Reference[], imageSettings?: ImageSettings[]): Promise<HTMLImageData[]>;
    /**
     * Generates alt text and image URLs for one image reference
     *
     * @param {XmanFieldValue.Reference} imgRef pointers to an image item. You can use the reference field value directly
     * @param {ImageSettings?} imageSettings image settings
     * @returns Promise<HTMLImageData> image details
     */
    getImage(imgRef: XmanFieldValue.Reference, imageSettings?: ImageSettings[]): Promise<HTMLImageData>;
    /**
     * Change the stage to pull data from. Default is 'live'
     * @param {String} stageName
     */
    stage(stageName?: string): WorkspaceWrapper;
    /**
     * Point to a separate delivery CDN.
     * Only applicable to "Environment" plans.
     *
     * @param {String} cdnServer CDN Server URL
     */
    cdn(cdnServer?: string): WorkspaceWrapper;
    /**
     * Provide the secret part of the key for server side access without `Origin` check
     * *DO NOT USE IN A CLIENT SIDE WEB APP*
     * Please use in server only settings for SSR apps such as NuxtJS, NextJS, Gatsby, etc.
     *
     * @param {String} secret for server side access.
     */
    secret(secret: string): WorkspaceWrapper;
}
/**
 *
 * @param clientId API client ID from XMan I/O
 * @param workspaceId Workspace ID. You can see this in the URL on XMan I/O
 * @param stageName 'live' by default
 * @param cdnServer Ignore. Unless Liquiron support has asked you to set this
 * @param secret Secret for server side access. DO NOT USE ON IN THE BROWSER
 * @returns Workspace object
 */
declare const getWorkspace: (clientId: string, workspaceId: string, stageName?: string, cdnServer?: string, secret?: string) => WorkspaceWrapper;

export { HTMLImageData, ImageSettings, ListParams, WorkspaceWrapper, XmanFieldValue, XmanItem, XmanItemsList, getWorkspace };