box-node-sdk 3.8.0 → 3.8.2

package/lib-esm/box-client.d.ts

@@ -0,0 +1,274 @@
+/**
+ * @fileoverview Box API Client
+ */
+import AI from './managers/ai.generated';
+import Collaborations from './managers/collaborations';
+import Events from './managers/events';
+import Files from './managers/files';
+import Folders from './managers/folders';
+import SignRequests from './managers/sign-requests.generated';
+import SignTemplates from './managers/sign-templates.generated';
+import Webhooks from './managers/webhooks';
+import FileRequestsManager from './managers/file-requests-manager';
+import ShieldInformationBarriers from './managers/shield-information-barriers.generated';
+import ShieldInformationBarrierSegments from './managers/shield-information-barrier-segments.generated';
+import ShieldInformationBarrierSegmentMembers from './managers/shield-information-barrier-segment-members.generated';
+import ShieldInformationBarrierSegmentRestrictions from './managers/shield-information-barrier-segment-restrictions.generated';
+import ShieldInformationBarrierReports from './managers/shield-information-barrier-reports.generated';
+import IntegrationMappings from './managers/integration-mappings';
+/**
+ * A collaboration role constant
+ * @typedef {string} CollaborationRole
+ */
+type CollaborationRole = string;
+/**
+ * A Box file or folder type constant
+ * @typedef {string} ItemType
+ */
+type ItemType = 'file' | 'folder';
+/**
+ * An access level constant. Used for setting and updating shared links, folder upload, etc.
+ * @typedef {?Object} AccessLevel
+ */
+type AccessLevel = object | null;
+type APISession = any;
+type APIRequestManager = any;
+declare class BoxClient {
+    _session: APISession;
+    _requestManager: APIRequestManager;
+    _customHeaders: any;
+    _baseURL: any;
+    _uploadBaseURL: any;
+    _uploadRequestTimeoutMS: any;
+    _useIterators: any;
+    _analyticsClient: any;
+    _tokenOptions: any;
+    ai: AI;
+    users: any;
+    files: Files;
+    fileRequests: FileRequestsManager;
+    folders: Folders;
+    comments: any;
+    collaborations: Collaborations;
+    groups: any;
+    sharedItems: any;
+    metadata: any;
+    collections: any;
+    events: Events;
+    search: any;
+    tasks: any;
+    trash: any;
+    enterprise: any;
+    legalHoldPolicies: any;
+    weblinks: any;
+    retentionPolicies: any;
+    devicePins: any;
+    webhooks: Webhooks;
+    recentItems: any;
+    collaborationAllowlist: any;
+    termsOfService: any;
+    storagePolicies: any;
+    signRequests: SignRequests;
+    signTemplates: SignTemplates;
+    shieldInformationBarriers: ShieldInformationBarriers;
+    shieldInformationBarrierSegments: ShieldInformationBarrierSegments;
+    shieldInformationBarrierSegmentMembers: ShieldInformationBarrierSegmentMembers;
+    shieldInformationBarrierSegmentRestrictions: ShieldInformationBarrierSegmentRestrictions;
+    shieldInformationBarrierReports: ShieldInformationBarrierReports;
+    integrationMappings: IntegrationMappings;
+    collaborationRoles: Record<string, CollaborationRole>;
+    itemTypes: Record<string, ItemType>;
+    accessLevels: Record<string, AccessLevel>;
+    CURRENT_USER_ID: string;
+    /**
+     * The BoxClient can make API calls on behalf of a valid API Session. It is responsible
+     * for formatting the requests and handling the response. Its goal is to deliver
+     * sensible results to the user.
+     *
+     * @param {APISession} apiSession An initialized API Session, used to get/revoke tokens and handle
+     * unauthorized responses from the API.
+     * @param {Config} config The SDK configuration options
+     * @param {APIRequestManager} requestManager The API Request Manager
+     * @constructor
+     */
+    constructor(apiSession: APISession, config: any, requestManager: APIRequestManager);
+    /**
+     * Returns an object containing the given headers as well as other headers (like the authorization header and
+     * custom headers) that should be included in a request.
+     * @param {?Object} callerHeaders - headers that the caller wishes to include in the request. This method will not
+     * override these headers with its own. Thus, if all the headers that this method was planning to add are already
+     * specified here, this method will return an object with exactly the same headers.
+     * @param {string} accessToken - the access token that will be used to make the request
+     * @returns {Object} - a new object with the headers needed for the request
+     * @private
+     */
+    _createHeadersForRequest(callerHeaders: object | null, accessToken: string): Record<string, string>;
+    /**
+     * Makes an API request to the Box API on behalf of the client. Before executing
+     * the request, it first ensures the user has usable tokens. Will be called again
+     * if the request returns a temporary error. Will propogate error if request returns
+     * a permanent error, or if usable tokens are not available.
+     *
+     * @param {Object} params - Request lib params to configure the request
+     * @param {Function} [callback] - passed response data
+     * @returns {Promise} Promise resolving to the response
+     * @private
+     */
+    _makeRequest(params: any, callback?: Function): any;
+    /**
+     * Set a custom header. A custom header is applied to every request for the life of the client. To
+     * remove a header, set it's value to null.
+     *
+     * @param {string} header The name of the custom header to set.
+     * @param {*} value The value of the custom header. Set to null to remove the given header.
+     * @returns {void}
+     */
+    setCustomHeader(header: string, value: any): void;
+    /**
+     * Sets the list of requesting IP addresses for the X-Forwarded-For header. Used to give the API
+     * better information for uploads, rate-limiting, etc.
+     *
+     * @param {string[]} ips - Array of IP Addresses
+     * @returns {void}
+     */
+    setIPs(ips: string[]): void;
+    /**
+     * Sets the shared item context on the API Session. Overwrites any current context.
+     *
+     * @param {string} url The shared link url
+     * @param {?string} password The shared link password, null if no password exists.
+     * @returns {void}
+     */
+    setSharedContext(url: string, password: string | null): void;
+    /**
+     * Removes any current shared item context from API Session.
+     *
+     * @returns {void}
+     */
+    revokeSharedContext(): void;
+    /**
+     * Set up the As-User context, which is used by enterprise admins to
+     * impersonate their managed users and perform actions on their behalf.
+     *
+     * @param {string} userID - The ID of the user to impersonate
+     * @returns {void}
+     */
+    asUser(userID: string): void;
+    /**
+     * Revoke the As-User context and return to making calls on behalf of the user
+     * who owns the client's access token.
+     *
+     * @returns {void}
+     */
+    asSelf(): void;
+    /**
+     * Revokes the client's access tokens. The client will no longer be tied to a user
+     * and will be unable to make calls to the API, rendering it effectively useless.
+     *
+     * @param {Function} [callback] Called after revoking, with an error if one existed
+     * @returns {Promise} A promise resolving when the client's access token is revoked
+     */
+    revokeTokens(callback: Function): any;
+    /**
+     * Exchange the client access token for one with lower scope
+     * @param {string|string[]} scopes The scope(s) requested for the new token
+     * @param {string} [resource] The absolute URL of an API resource to scope the new token to
+     * @param {Object} [options] - Optional parameters
+     * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens with Token Auth client
+     * @param {SharedLinkParams} [options.sharedLink] - Optional shared link parameters for creating tokens using shared links
+     * @param {Function} [callback] Called with the new token
+     * @returns {Promise<TokenInfo>} A promise resolving to the exchanged token info
+     */
+    exchangeToken(scopes: string | string[], resource?: string, options?: Function | object, callback?: Function): any;
+    /**
+     * Makes GET request to Box API V2 endpoint
+     *
+     * @param {string} path - path to a certain API endpoint (ex: /file)
+     * @param {?Object} params - object containing parameters for the request, such as query strings and headers
+     * @param {Function} [callback] - passed final API response or err if request failed
+     * @returns {void}
+     */
+    get(path: string, params?: object | null, callback?: Function): any;
+    /**
+     * Makes POST request to Box API V2 endpoint
+     *
+     * @param {string} path - path to a certain API endpoint (ex: /file)
+     * @param {?Object} params - object containing parameters for the request, such as query strings and headers
+     * @param {Function} [callback] - passed final API response or err if request failed
+     * @returns {void}
+     */
+    post(path: string, params: object | null, callback?: Function): any;
+    /**
+     * Makes PUT request to Box API V2 endpoint
+     *
+     * @param {string} path - path to a certain API endpoint (ex: /file)
+     * @param {?Object} params - object containing parameters for the request, such as query strings and headers
+     * @param {Function} callback - passed final API response or err if request failed
+     * @returns {void}
+     */
+    put(path: string, params?: object | null, callback?: Function): any;
+    /**
+     * Makes DELETE request to Box API V2 endpoint
+     *
+     * @param {string} path - path to a certain API endpoint (ex: /file)
+     * @param {?Object} params - object containing parameters for the request, such as query strings and headers
+     * @param {Function} callback - passed final API response or err if request failed
+     * @returns {void}
+     */
+    del(path: string, params: object | null, callback?: Function): any;
+    /**
+     * Makes an OPTIONS call to a Box API V2 endpoint
+     *
+     * @param {string} path - Path to an API endpoint (e.g. /files/content)
+     * @param {?Object} params - An optional object containing request parameters
+     * @param {Function} callback - Called with API call results, or err if call failed
+     * @returns {void}
+     */
+    options(path: string, params: object | null, callback?: Function): any;
+    /**
+     * Makes a POST call to a Box API V2 upload endpoint
+     * @param {string} path - path to an upload API endpoint
+     * @param {?Object} params - an optional object containing request parameters
+     * @param {?Object} formData - multipart form data to include in the upload request {@see https://github.com/mikeal/request#multipartform-data-multipart-form-uploads}
+     * @param {Function} callback - called with API call results, or an error if the call failed
+     * @returns {void}
+     */
+    upload(path: string, params: object | null, formData: object | null, callback: Function): any;
+    /**
+     * Build the 'BoxApi' Header used for authenticating access to a shared item
+     *
+     * @param {string} url The shared link url
+     * @param {string} [password] The shared link password
+     * @returns {string} A properly formatted 'BoxApi' header
+     */
+    buildSharedItemAuthHeader(url: string, password: string | null): any;
+    /**
+     * Return a callback that properly handles a successful response code by passing the response
+     * body to the original callback. Any request error or unsuccessful response codes are propagated
+     * back to the callback as errors. This is the standard behavior of most endpoints.
+     *
+     * @param {Function} callback The original callback given by the consumer
+     * @returns {?Function} A new callback that processes the response before passing it to the callback.
+     */
+    defaultResponseHandler(callback: Function): ((err: any, response: any) => void) | null;
+    /**
+     * Wrap a client method with the default handler for both callback and promise styles
+     * @param {Function} method The client method (e.g. client.get)
+     * @returns {Function}  The wrapped method
+     */
+    wrapWithDefaultHandler(method: Function): Function;
+    /**
+     * Add a SDK plugin. Warning: This will modify the box-client interface and can override existing properties.
+     * @param {string} name Plugin name. Will be accessible via client.<plugin-name>
+     * @param {Function} plugin The SDK plugin to add
+     * @param {Object} [options] Plugin-specific options
+     * @returns {void}
+     * @throws Will throw an error if plugin name matches an existing method on box-client
+     */
+    plug(name: string, plugin: Function, options: object): void;
+}
+/**
+ * @module box-node-sdk/lib/box-client
+ * @see {@Link BoxClient}
+ */
+export = BoxClient;