filestack-js
Version:
Official JavaScript library for Filestack
365 lines (364 loc) • 13.2 kB
TypeScript
import { EventEmitter } from 'eventemitter3';
import { Hosts } from '../config';
import { MetadataOptions, RetrieveOptions } from './api/file';
import { TransformOptions } from './api/transform';
import * as Utils from './utils';
import { InputFile, UploadOptions, StoreUploadOptions, UploadTags } from './api/upload';
import { PreviewOptions } from './api/preview';
import { PrefetchResponse, PrefetchOptions } from './api/prefetch';
import { FsResponse } from './request/types';
import { StoreParams } from './filelink';
import { PickerInstance, PickerOptions } from './picker';
export interface Session {
apikey: string;
urls: Hosts;
cname?: string;
policy?: string;
signature?: string;
prefetch?: PrefetchResponse;
}
export interface Security {
policy: string;
signature: string;
}
export interface ClientOptions {
[option: string]: any;
/**
* Security object with policy and signature keys.
* Can be used to limit client capabilities and protect public URLs.
* It is intended to be used with server-side policy and signature generation.
* Read about [security policies](https://www.filestack.com/docs/concepts/security).
*/
security?: Security;
/**
* Domain to use for all URLs. __Requires the custom CNAME addon__.
* If this is enabled then you must also set up your own OAuth applications
* for each cloud source you wish to use in the picker.
*/
cname?: string;
/**
* Enable/disable caching of the cloud session token. Default is false.
* This ensures that users will be remembered on your domain when calling the cloud API from the browser.
* Please be aware that tokens stored in localStorage are accessible by other scripts on the same domain.
*/
sessionCache?: boolean;
/**
* Enable forwarding error logs to sentry
* @default false
*/
forwardErrors?: boolean;
}
/**
* The Filestack client, the entry point for all public methods. Encapsulates session information.
*
* ### Example
* ```js
* // ES module
* import * as filestack from 'filestack-js';
* const client = filestack.init('apikey');
* ```
*
* ```js
* // UMD module in browser
* <script src="https://static.filestackapi.com/filestack-js/3.x.x/filestack.min.js"></script>
* const client = filestack.init('apikey');
* ```
*/
export declare class Client extends EventEmitter {
private options?;
session: Session;
private cloud;
private prefetchInstance;
private forwardErrors;
/**
* Returns filestack utils
*
* @readonly
* @memberof Client
*/
get utils(): typeof Utils;
constructor(apikey: string, options?: ClientOptions);
/**
* Make basic prefetch request to check permissions
*
* @param params
*/
prefetch(params: PrefetchOptions): Promise<PrefetchResponse>;
/**
* Set security object
*
* @param {Security} security
* @memberof Client
*/
setSecurity(security: Security): void;
/**
* Set custom cname
*
* @param {string} cname
* @returns
* @memberof Client
*/
setCname(cname: string): void;
/**
* Clear all current cloud sessions in the picker.
* Optionally pass a cloud source name to only log out of that cloud source.
* This essentially clears the OAuth authorization codes from the Filestack session.
* @param name Optional cloud source name.
*/
logout(name?: string): Promise<any>;
/**
* Retrieve detailed data of stored files.
*
* ### Example
*
* ```js
* client
* .metadata('DCL5K46FS3OIxb5iuKby')
* .then((res) => {
* console.log(res);
* })
* .catch((err) => {
* console.log(err);
* }));
* ```
* @see [File API - Metadata](https://www.filestack.com/docs/api/file#metadata).
* @param handle Valid Filestack handle.
* @param options Metadata fields to enable on response.
* @param security Optional security override.
*/
metadata(handle: string, options?: MetadataOptions, security?: Security): Promise<any>;
/**
* Construct a new picker instance.
*/
picker(options?: PickerOptions): PickerInstance;
/**
* Used for viewing files via Filestack handles or storage aliases, __requires Document Viewer addon to your Filestack application__.
* Opens document viewer in new window if id option is not provided.
*
* ### Example
*
* ```js
* // <div id="preview"></div>
*
* client.preview('DCL5K46FS3OIxb5iuKby', { id: 'preview' });
* ```
* @param handle Valid Filestack handle.
* @param options Preview options
*/
preview(handle: string, options?: PreviewOptions): HTMLIFrameElement | Window;
/**
* Remove a file from storage and the Filestack system.
*
* __Requires a valid security policy and signature__. The policy and signature will be pulled from the client session, or it can be overridden with the security parameter.
*
* ### Example
*
* ```js
* client
* .remove('DCL5K46FS3OIxb5iuKby')
* .then((res) => {
* console.log(res);
* })
* .catch((err) => {
* console.log(err);
* }));
* ```
* @see [File API - Delete](https://www.filestack.com/docs/api/file#delete)
* @param handle Valid Filestack handle.
* @param security Optional security override.
*/
remove(handle: string, security?: Security): Promise<any>;
/**
* Remove a file **only** from the Filestack system. The file remains in storage.
*
* __Requires a valid security policy and signature__. The policy and signature will be pulled from the client session, or it can be overridden with the security parameter.
*
* ### Example
*
* ```js
* client
* .removeMetadata('DCL5K46FS3OIxb5iuKby')
* .then((res) => {
* console.log(res);
* })
* .catch((err) => {
* console.log(err);
* }));
* ```
* @see [File API - Delete](https://www.filestack.com/docs/api/file#delete)
* @param handle Valid Filestack handle.
* @param security Optional security override.
*/
removeMetadata(handle: string, security?: Security): Promise<any>;
/**
* Store a file from its URL.
*
* ### Example
*
* ```js
* client
* .storeURL('https://d1wtqaffaaj63z.cloudfront.net/images/NY_199_E_of_Hammertown_2014.jpg')
* .then(res => console.log(res));
* ```
* @see [File API - Store](https://www.filestack.com/docs/api/file#store)
* @param url Valid URL to a file.
* @param options Configure file storage.
* @param token Optional control token to call .cancel()
* @param security Optional security override.
* @param uploadTags Optional tags visible in webhooks.
* @param headers Optional headers to send
* @param workflowIds Optional workflowIds to send
*/
storeURL(url: string, storeParams?: StoreParams, token?: any, security?: Security, uploadTags?: UploadTags, headers?: {
[key: string]: string;
}, workflowIds?: string[]): Promise<Object>;
/**
* Access files via their Filestack handles.
*
* If head option is provided - request headers are returned in promise
* If metadata option is provided - metadata object is returned in promise
* Otherwise file blob is returned
* Metadata and head options cannot be mixed
*
* ### Example
*
* ```js
* client.retrieve('fileHandle', {
* metadata: true,
* }).then((response) => {
* console.log(response);
* }).catch((err) => {
* console.error(err);
* })
* ```
*
* @see [File API - Download](https://www.filestack.com/docs/api/file#download)
* @deprecated use metadata or download methods instead
* @param handle Valid file handle
* @param options RetrieveOptions
* @param security Optional security override.
* @throws Error
*/
retrieve(handle: string, options?: RetrieveOptions, security?: Security): Promise<Object | Blob>;
/**
* Download file by handle
*
*
* ### Browser Example
*
* ```js
* client.download('fileHandle').then((response) => {
* const img = new Image();
* img.src = URL.createObjectURL(res.data)
* document.body.appendChild(img);
* }).catch((err) => {
* console.error(err);
* })
* ```
*
* @see [File API - Download](https://www.filestack.com/docs/api/file#download)
* @param handle Valid file handle
* @throws Error
*/
download(handle: string, security?: Security): Promise<FsResponse>;
/**
* Interface to the Filestack [Processing API](https://www.filestack.com/docs/api/processing).
* Convert a URL, handle, or storage alias to another URL which links to the transformed file.
* You can optionally store the returned URL with client.storeURL.
*
* Transform params can be provided in camelCase or snakeCase style ie: partial_pixelate or partialPixelate
*
* ### Example
*
* ```js
* const transformedUrl = client.transform(url, {
* crop: {
* dim: [x, y, width, height],
* },
* vignette: {
* blurmode: 'gaussian',
* amount: 50,
* },
* flip: true,
* partial_pixelate: {
* objects: [[10, 20, 200, 250], [275, 91, 500, 557]],
* },
* };
*
* // optionally store the new URL
* client.storeURL(transformedUrl).then(res => console.log(res));
* ```
* @see [Filestack Processing API](https://www.filestack.com/docs/api/processing)
* @param url Single or multiple valid URLs (http(s)://), file handles, or storage aliases (src://) to an image.
* @param options Transformations are applied in the order specified by this object.
* @param b64 Use new more safe format for generating transforms url (default=false) Note: If there will be any issues with url please test it with enabled b64 support
* @returns A new URL that points to the transformed resource.
*/
transform(url: string | string[], options: TransformOptions, b64?: boolean): string;
/**
* Initiates a multi-part upload flow. Use this for Filestack CIN and FII uploads.
*
* In Node runtimes the file argument is treated as a file path.
* Uploading from a Node buffer is not yet implemented.
*
* ### Example
*
* ```js
* const token = {};
* const onRetry = (obj) => {
* console.log(`Retrying ${obj.location} for ${obj.filename}. Attempt ${obj.attempt} of 10.`);
* };
*
* client.upload(file, { onRetry }, { filename: 'foobar.jpg' }, token)
* .then(res => console.log(res));
*
* client.upload({file, name}, { onRetry }, { filename: 'foobar.jpg' }, token)
* .then(res => console.log(res));
*
* token.pause(); // Pause flow
* token.resume(); // Resume flow
* token.cancel(); // Cancel flow (rejects)
* ```
* @param {InputFile} file Must be a valid [File | Blob | Buffer | string]
* @param uploadOptions Uploader options.
* @param storeOptions Storage options.
* @param token A control token that can be used to call cancel(), pause(), and resume().
* @param security Optional security policy and signature override.
*
* @returns {Promise}
*/
upload(file: InputFile, options?: UploadOptions, storeOptions?: StoreUploadOptions, token?: any, security?: Security): Promise<any>;
/**
* Initiates a multi-part upload flow. Use this for Filestack CIN and FII uploads.
*
* In Node runtimes the file argument is treated as a file path.
* Uploading from a Node buffer is not yet implemented.
*
* ### Example
*
* ```js
* const token = {};
* const onRetry = (obj) => {
* console.log(`Retrying ${obj.location} for ${obj.filename}. Attempt ${obj.attempt} of 10.`);
* };
*
* client.multiupload([file], { onRetry }, token)
* .then(res => console.log(res));
*
* client.multiupload([{file, name}], { onRetry }, token)
* .then(res => console.log(res));
*
* token.pause(); // Pause flow
* token.resume(); // Resume flow
* token.cancel(); // Cancel flow (rejects)
* ```
* @param {InputFile[]} file Must be a valid [File | Blob | Buffer | string (base64)]
* @param uploadOptions Upload options.
* @param storeOptions Storage options.
* @param token A control token that can be used to call cancel(), pause(), and resume().
* @param security Optional security policy and signature override.
*
* @returns {Promise}
*/
multiupload(file: InputFile[], options?: UploadOptions, storeOptions?: StoreUploadOptions, token?: any, security?: Security): Promise<any>;
}