/** * @fileoverview Box SDK for Node.js */// ------------------------------------------------------------------------------// Requirements// ------------------------------------------------------------------------------import { EventEmitter } from 'events';import * as qs from 'querystring';import CCGAPISession = require('./sessions/ccg-session');import APIRequestManager = require('./api-request-manager');import BoxClient = require('./box-client');import TokenManager = require('./token-manager');const Config = require('./util/config'), BasicAPISession = require('./sessions/basic-session'), PersistentAPISession = require('./sessions/persistent-session'), AppAuthSession = require('./sessions/app-auth-session'), Webhooks = require('./managers/webhooks');// ------------------------------------------------------------------------------// Typedefs and Callbacks// ------------------------------------------------------------------------------/** * Object representing interface functions for PersistentClient to interact with the consumer app's central storage layer. * @typedef {Object} TokenStore * @property {ReadTokenInfoFromStore} read - read TokenInfo from app central store. * @property {WriteTokenInfoToStore} write - write TokenInfo to the app's central store. * @property {ClearTokenInfoFromStore} clear - delete TokenInfo from the app's central store. *//** * Acquires TokenInfo from the consumer app's central store. * @typedef {Function} ReadTokenInfoFromStore * @param {Function} callback - err if store read issue occurred, otherwise propagates a TokenInfo object *//** * Writes TokenInfo to the consumer app's central store * @typedef {Function} WriteTokenInfoToStore * @param {TokenInfo} tokenInfo - the token info to be written * @param {Function} callback - err if store write issue occurred, otherwise propagates null err * and null result to indicate success *//** * Clears TokenInfo from the consumer app's central store * @typedef {Function} ClearTokenInfoFromStore * @param {Function} callback - err if store delete issue occurred, otherwise propagates null err * and null result to indicate success */type TokenStore = object /* FIXME */;type UserConfigurationOptions = object /* FIXME */;type TokenRequestOptions = object /* FIXME */;type CCGConfig = { boxSubjectType: "user" | "enterprise", boxSubjectId: string}// ------------------------------------------------------------------------------// Private// ------------------------------------------------------------------------------// ------------------------------------------------------------------------------// Public// ------------------------------------------------------------------------------/** * A backend NodeJS SDK to interact with the Box V2 API. * This is the single entry point for all SDK consumer interactions. This is the only file that a 3rd party app * should require. All other components are private and reached out to via this component. * 1. Provides getters to spawn client instances for users to interact with the Box API. * 2. Provides manual capability to acquire tokens via token grant endpoints. * However, it is recommended to use clients to do this for you. * 3. Emits notification events about relevant request/response events. Useful for logging Box API interactions. * Notification events: request retries, exceeding max retries, permanent failures. * * @param {UserConfigurationOptions} params User settings used to initialize and customize the SDK * @constructor */class BoxSDKNode extends EventEmitter { accessLevels: any /* FIXME */; collaborationRoles: any /* FIXME */; CURRENT_USER_ID: any /* FIXME */; config: any /* FIXME */; _eventBus!: EventEmitter; requestManager!: APIRequestManager; tokenManager!: TokenManager; ccgSession!: CCGAPISession; /** * Expose the BoxClient property enumerations to the SDK as a whole. This allows * the consumer to access and use these values from anywhere in their application * (like a helper) by requiring the SDK, instead of needing to pass the client. */ static accessLevels = BoxSDKNode.prototype.accessLevels; static collaborationRoles = BoxSDKNode.prototype.collaborationRoles; static CURRENT_USER_ID = BoxSDKNode.prototype.CURRENT_USER_ID; /** * Expose Webhooks.validateMessage() to the SDK as a whole. This allows * the consumer to call BoxSDK.validateWebhookMessage() by just requiring the SDK, * instead of needing to create a client (which is not needed to validate messages). */ static validateWebhookMessage = Webhooks.validateMessage; constructor(params: UserConfigurationOptions) { super(); const eventBus = new EventEmitter(); const self = this; eventBus.on('response', function () { const args: any /* FIXME */ = [].slice.call(arguments); args.unshift('response'); self.emit.apply(self, args); }); // Setup the configuration with the given params this.config = new Config(params); this._eventBus = eventBus; this._setup(); } /** * Setup the SDK instance by instantiating necessary objects with current * configuration values. * * @returns {void} * @private */ _setup() { // Instantiate the request manager this.requestManager = new APIRequestManager(this.config, this._eventBus); // Initialize the rest of the SDK with the given configuration this.tokenManager = new TokenManager(this.config, this.requestManager); this.ccgSession = new CCGAPISession( this.config, this.tokenManager ); } /** * Gets the BoxSDKNode instance by passing boxAppSettings json downloaded from the developer console. * * @param {Object} appConfig boxAppSettings object retrieved from Dev Console. * @returns {BoxSDKNode} an instance that has been preconfigured with the values from the Dev Console */ static getPreconfiguredInstance(appConfig: any /* FIXME */) { if (typeof appConfig.boxAppSettings !== 'object') { throw new TypeError( 'Configuration does not include boxAppSettings object.' ); } const boxAppSettings = appConfig.boxAppSettings; const webhooks = appConfig.webhooks; if (typeof webhooks === 'object') { Webhooks.setSignatureKeys(webhooks.primaryKey, webhooks.secondaryKey); } const params: { clientID?: string; clientSecret?: string; appAuth?: { keyID?: string; privateKey?: string; passphrase?: string; }; enterpriseID?: string; } = {}; if (typeof boxAppSettings.clientID === 'string') { params.clientID = boxAppSettings.clientID; } if (typeof boxAppSettings.clientSecret === 'string') { params.clientSecret = boxAppSettings.clientSecret; } // Only try to assign app auth settings if they are present // Some configurations do not include them (but might include other info, e.g. webhooks) if ( typeof boxAppSettings.appAuth === 'object' && boxAppSettings.appAuth.publicKeyID ) { params.appAuth = { keyID: boxAppSettings.appAuth.publicKeyID, // Assign publicKeyID to keyID privateKey: boxAppSettings.appAuth.privateKey, }; const passphrase = boxAppSettings.appAuth.passphrase; if (typeof passphrase === 'string') { params.appAuth.passphrase = passphrase; } } if (typeof appConfig.enterpriseID === 'string') { params.enterpriseID = appConfig.enterpriseID; } return new BoxSDKNode(params); } /** * Updates the SDK configuration with new parameters. * * @param {UserConfigurationOptions} params User settings * @returns {void} */ configure(params: UserConfigurationOptions) { this.config = this.config.extend(params); this._setup(); } /** * Returns a Box Client with a Basic API Session. The client is able to make requests on behalf of a user. * A basic session has no access to a user's refresh token. Because of this, once the session's tokens * expire the client cannot recover and a new session will need to be generated. * * @param {string} accessToken A user's Box API access token * @returns {BoxClient} Returns a new Box Client paired to a new BasicAPISession */ getBasicClient(accessToken: string) { const apiSession = new BasicAPISession(accessToken, this.tokenManager); return new BoxClient(apiSession, this.config, this.requestManager); } /** * Returns a Box Client with a Basic API Session. The client is able to make requests on behalf of a user. * A basic session has no access to a user's refresh token. Because of this, once the session's tokens * expire the client cannot recover and a new session will need to be generated. * * @param {string} accessToken A user's Box API access token * @returns {BoxClient} Returns a new Box Client paired to a new BasicAPISession */ static getBasicClient(accessToken: string) { return new BoxSDKNode({ clientID: '', clientSecret: '', }).getBasicClient(accessToken); } /** * Returns a Box Client with a persistent API session. A persistent API session helps manage the user's tokens, * and can refresh them automatically if the access token expires. If a central data-store is given, the session * can read & write tokens to it. * * NOTE: If tokenInfo or tokenStore are formatted incorrectly, this method will throw an error. If you * haven't explicitly created either of these objects or are otherwise not completly confident in their validity, * you should wrap your call to getPersistentClient in a try-catch to handle any potential errors. * * @param {TokenInfo} tokenInfo A tokenInfo object to use for authentication * @param {TokenStore} [tokenStore] An optional token store for reading/writing tokens to session * @returns {BoxClient} Returns a new Box Client paired to a new PersistentAPISession */ getPersistentClient(tokenInfo: any /* FIXME */, tokenStore?: TokenStore) { const apiSession = new PersistentAPISession( tokenInfo, tokenStore, this.config, this.tokenManager ); return new BoxClient(apiSession, this.config, this.requestManager); } /** * Returns a Box Client configured to use Client Credentials Grant for a service account. Requires enterprise ID * to be set when configuring SDK instance. * * @returns {BoxClient} Returns a new Box Client paired to a AnonymousAPISession. All Anonymous API Sessions share the * same tokens, which allows them to refresh them efficiently and reduce load on both the application and * the API. */ getAnonymousClient() { if (!this.config.enterpriseID) { throw new Error('Enterprise ID must be passed'); } return this._getCCGClient({boxSubjectType: "enterprise", boxSubjectId: this.config.enterpriseID}); } /** * Returns a Box Client configured to use Client Credentials Grant for a specified user. * * @param userId the user ID to use when getting the access token * @returns {BoxClient} Returns a new Box Client paired to a AnonymousAPISession. All Anonymous API Sessions share the * same tokens, which allows them to refresh them efficiently and reduce load on both the application and * the API. */ getCCGClientForUser(userId: string) { return this._getCCGClient({boxSubjectType: "user", boxSubjectId: userId}) } _getCCGClient(config: CCGConfig) { const anonymousTokenManager = new TokenManager( { ...this.config, ...config }, this.requestManager ); const newAnonymousSession = new CCGAPISession( this.config, anonymousTokenManager ); return new BoxClient( newAnonymousSession, this.config, this.requestManager ); } /** * Create a new client using App Auth for the given entity. This allows either * managing App Users (as the enterprise) or performing operations as the App * Users or Managed Users themselves (as a user). * * @param {string} type The type of entity to operate as, "enterprise" or "user" * @param {string} [id] (Optional) The Box ID of the entity to operate as * @param {TokenStore} [tokenStore] (Optional) the token store to use for caching tokens * @returns {BoxClient} A new client authorized as the app user or enterprise */ getAppAuthClient(type: string, id?: string, tokenStore?: TokenStore) { if (type === 'enterprise' && !id) { if (this.config.enterpriseID) { id = this.config.enterpriseID; } else { throw new Error('Enterprise ID must be passed'); } } const appAuthSession = new AppAuthSession( type, id, this.config, this.tokenManager, tokenStore ); return new BoxClient(appAuthSession, this.config, this.requestManager); } /** * Generate the URL for the authorize page to send users to for the first leg of * the OAuth2 flow. * * @param {Object} params The OAuth2 parameters * @returns {string} The authorize page URL */ getAuthorizeURL(params: { client_id?: string }) { params.client_id = this.config.clientID; return `${this.config.authorizeRootURL}/oauth2/authorize?${qs.stringify( params )}`; } /** * Acquires token info using an authorization code * * @param {string} authorizationCode - authorization code issued by Box * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant, null for default behavior * @param {Function} [callback] - passed a TokenInfo object if tokens were granted successfully * @returns {Promise<TokenInfo>} Promise resolving to the token info */ getTokensAuthorizationCodeGrant( authorizationCode: string, options?: TokenRequestOptions | null, callback?: Function ) { return this.tokenManager .getTokensAuthorizationCodeGrant( authorizationCode, options as any /* FIXME */ ) .asCallback(callback); } /** * Refreshes the access and refresh tokens for a given refresh token. * * @param {string} refreshToken - A valid OAuth refresh token * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant, null for default behavior * @param {Function} [callback] - passed a TokenInfo object if tokens were granted successfully * @returns {Promise<TokenInfo>} Promise resolving to the token info */ getTokensRefreshGrant( refreshToken: string, options?: TokenRequestOptions | Function | null, callback?: Function ) { if (typeof options === 'function') { callback = options; options = null; } return this.tokenManager .getTokensRefreshGrant(refreshToken, options as any /* FIXME */) .asCallback(callback); } /** * Gets tokens for enterprise administration of app users * @param {string} enterpriseID The ID of the enterprise to generate a token for * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant, null for default behavior * @param {Function} [callback] Passed the tokens if successful * @returns {Promise<TokenInfo>} Promise resolving to the token info */ getEnterpriseAppAuthTokens( enterpriseID: string, options?: TokenRequestOptions | Function | null, callback?: Function ) { if (typeof options === 'function') { callback = options; options = null; } if (!enterpriseID) { if (this.config.enterpriseID) { enterpriseID = this.config.enterpriseID; } else { throw new Error('Enterprise id must be passed'); } } return this.tokenManager .getTokensJWTGrant('enterprise', enterpriseID, options as any /* FIXME */) .asCallback(callback); } /** * Gets tokens for App Users via a JWT grant * @param {string} userID The ID of the App User to generate a token for * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant, null for default behavior * @param {Function} [callback] Passed the tokens if successful * @returns {Promise<TokentInfo>} Promise resolving to the token info */ getAppUserTokens( userID: string, options?: TokenRequestOptions | Function | null, callback?: Function ) { if (typeof options === 'function') { callback = options; options = null; } return this.tokenManager .getTokensJWTGrant('user', userID, options as any /* FIXME */) .asCallback(callback); } /** * Revokes a token pair associated with a given access or refresh token. * * @param {string} token - A valid access or refresh token to revoke * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant, null for default behavior * @param {Function} [callback] - If err, revoke failed. Otherwise, revoke succeeded. * @returns {Promise<TokenInfo>} Promise resolving to the token info */ revokeTokens( token: string, options?: TokenRequestOptions | Function | null, callback?: Function ) { if (typeof options === 'function') { callback = options; options = null; } return this.tokenManager .revokeTokens(token, options as any /* FIXME */) .asCallback(callback); }}/** * Expose the BoxClient property enumerations to the SDK as a whole. This allows * the consumer to access and use these values from anywhere in their application * (like a helper) by requiring the SDK, instead of needing to pass the client. */BoxSDKNode.prototype.accessLevels = BoxClient.prototype.accessLevels;BoxSDKNode.prototype.collaborationRoles = BoxClient.prototype.collaborationRoles;BoxSDKNode.prototype.CURRENT_USER_ID = BoxClient.prototype.CURRENT_USER_ID;/** @module box-node-sdk/lib/box-node-sdk */export = BoxSDKNode;