feat(ts): add comments to properties and methods (box/box-codegen#537) (#284)

Co-authored-by: box-sdk-build <[email protected]>

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "871ac70", "specHash": "e50af18", "version": "1.3.0" }
+{ "engineHash": "525674e", "specHash": "e50af18", "version": "1.3.0" }

package-lock.json

@@ -11,10 +11,20 @@ import { BoxSdkError } from './errors.js';
 import { PostOAuth2Token } from '../schemas/postOAuth2Token.generated.js';
 import { PostOAuth2Revoke } from '../schemas/postOAuth2Revoke.generated.js';
 export class CcgConfig {
+  /**
+   * Box API key used for identifying the application the user is authenticating with */
   readonly clientId!: string;
+  /**
+   * Box API secret used for making auth requests. */
   readonly clientSecret!: string;
+  /**
+   * The ID of the Box Developer Edition enterprise. */
   readonly enterpriseId?: string;
+  /**
+   * The user id to authenticate. This value is not required. But if it is provided, then the user will be auto-authenticated at the time of the first API call. */
   readonly userId?: string;
+  /**
+   * Object responsible for storing token. If no custom implementation provided,the token will be stored in memory. */
   readonly tokenStorage: TokenStorage = new InMemoryTokenStorage({});
   constructor(
     fields: Omit<CcgConfig, 'tokenStorage'> &
@@ -38,16 +48,34 @@ export class CcgConfig {
   }
 }
 export interface CcgConfigInput {
+  /**
+   * Box API key used for identifying the application the user is authenticating with */
   readonly clientId: string;
+  /**
+   * Box API secret used for making auth requests. */
   readonly clientSecret: string;
+  /**
+   * The ID of the Box Developer Edition enterprise. */
   readonly enterpriseId?: string;
+  /**
+   * The user id to authenticate. This value is not required. But if it is provided, then the user will be auto-authenticated at the time of the first API call. */
   readonly userId?: string;
+  /**
+   * Object responsible for storing token. If no custom implementation provided,the token will be stored in memory. */
   readonly tokenStorage?: TokenStorage;
 }
 export class BoxCcgAuth implements Authentication {
+  /**
+   * Configuration object of Client Credentials Grant auth. */
   readonly config!: CcgConfig;
+  /**
+   * An object responsible for storing token. If no custom implementation provided, the token will be stored in memory. */
   readonly tokenStorage: TokenStorage;
+  /**
+   * The ID of the user or enterprise to authenticate as. If not provided, defaults to the enterprise ID if set, otherwise defaults to the user ID. */
   readonly subjectId?: string;
+  /**
+   * The type of the subject ID provided. Must be either 'user' or 'enterprise'. */
   readonly subjectType?: PostOAuth2TokenBoxSubjectTypeField;
   constructor(
     fields: Omit<
@@ -75,6 +103,11 @@ export class BoxCcgAuth implements Authentication {
       ? ('user' as PostOAuth2TokenBoxSubjectTypeField)
       : ('enterprise' as PostOAuth2TokenBoxSubjectTypeField);
   }
+  /**
+   * Get a new access token using CCG auth
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async refreshToken(networkSession?: NetworkSession): Promise<AccessToken> {
     const authManager: AuthorizationManager = new AuthorizationManager({
       networkSession: !(networkSession == void 0)
@@ -91,6 +124,11 @@ export class BoxCcgAuth implements Authentication {
     await this.tokenStorage.store(token);
     return token;
   }
+  /**
+   * Return a current token or get a new one when not available.
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async retrieveToken(networkSession?: NetworkSession): Promise<AccessToken> {
     const oldToken: undefined | AccessToken = await this.tokenStorage.get();
     if (oldToken == void 0) {
@@ -99,12 +137,25 @@ export class BoxCcgAuth implements Authentication {
     }
     return oldToken!;
   }
+  /**
+   * @param {NetworkSession} networkSession
+   * @returns {Promise<string>}
+   */
   async retrieveAuthorizationHeader(
     networkSession?: NetworkSession
   ): Promise<string> {
     const token: AccessToken = await this.retrieveToken(networkSession);
     return ''.concat('Bearer ', token.accessToken!) as string;
   }
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided user ID as the subject ID.
+   * May be one of this application's created App User. Depending on the configured User Access Level, may also be any other App User or Managed User in the enterprise.
+   * <https://developer.box.com/en/guides/applications/>
+   * <https://developer.box.com/en/guides/authentication/select/>
+   * @param {string} userId The id of the user to authenticate
+   * @param {TokenStorage} tokenStorage Object responsible for storing token in newly created BoxCCGAuth. If no custom implementation provided, the token will be stored in memory.
+   * @returns {BoxCcgAuth}
+   */
   withUserSubject(
     userId: string,
     tokenStorage: TokenStorage = new InMemoryTokenStorage({})
@@ -118,6 +169,12 @@ export class BoxCcgAuth implements Authentication {
     });
     return new BoxCcgAuth({ config: newConfig });
   }
+  /**
+   * Create a new BoxCCGAuth instance that uses the provided enterprise ID as the subject ID.
+   * @param {string} enterpriseId The id of the enterprise to authenticate
+   * @param {TokenStorage} tokenStorage Object responsible for storing token in newly created BoxCCGAuth. If no custom implementation provided, the token will be stored in memory.
+   * @returns {BoxCcgAuth}
+   */
   withEnterpriseSubject(
     enterpriseId: string,
     tokenStorage: TokenStorage = new InMemoryTokenStorage({})
@@ -131,6 +188,14 @@ export class BoxCcgAuth implements Authentication {
     });
     return new BoxCcgAuth({ config: newConfig });
   }
+  /**
+   * Downscope access token to the provided scopes. Returning a new access token with the provided scopes, with the original access token unchanged.
+   * @param {readonly string[]} scopes The scope(s) to apply to the resulting token.
+   * @param {string} resource The file or folder to get a downscoped token for. If None and shared_link None, the resulting token will not be scoped down to just a single item. The resource should be a full URL to an item, e.g. https://api.box.com/2.0/files/123456.
+   * @param {string} sharedLink The shared link to get a downscoped token for. If None and item None, the resulting token will not be scoped down to just a single item.
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async downscopeToken(
     scopes: readonly string[],
     resource?: string,
@@ -161,6 +226,11 @@ export class BoxCcgAuth implements Authentication {
     } satisfies PostOAuth2Token);
     return downscopedToken;
   }
+  /**
+   * Revoke the current access token and remove it from token storage.
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<undefined>}
+   */
   async revokeToken(networkSession?: NetworkSession): Promise<undefined> {
     const oldToken: undefined | AccessToken = await this.tokenStorage.get();
     if (oldToken == void 0) {

src/box/ccgAuth.generated.ts

@@ -15,7 +15,11 @@ export interface DeveloperTokenConfig {
 }
 export class BoxDeveloperTokenAuth implements Authentication {
   readonly token!: string;
+  /**
+   * Configuration object of DeveloperTokenAuth. */
   readonly config: DeveloperTokenConfig = {} satisfies DeveloperTokenConfig;
+  /**
+   * An object responsible for storing token. If no custom implementation provided, the token will be stored in memory. */
   readonly tokenStorage: TokenStorage;
   constructor(
     fields: Omit<
@@ -40,24 +44,43 @@ export class BoxDeveloperTokenAuth implements Authentication {
       token: { accessToken: this.token } satisfies AccessToken,
     });
   }
+  /**
+   * Retrieves stored developer token
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async retrieveToken(networkSession?: NetworkSession): Promise<AccessToken> {
     const token: undefined | AccessToken = await this.tokenStorage.get();
     if (token == void 0) {
       throw new BoxSdkError({ message: 'No access token is available.' });
     }
     return token!;
   }
+  /**
+   * Developer token cannot be refreshed
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async refreshToken(networkSession?: NetworkSession): Promise<AccessToken> {
     throw new BoxSdkError({
       message: 'Developer token has expired. Please provide a new one.',
     });
   }
+  /**
+   * @param {NetworkSession} networkSession
+   * @returns {Promise<string>}
+   */
   async retrieveAuthorizationHeader(
     networkSession?: NetworkSession
   ): Promise<string> {
     const token: AccessToken = await this.retrieveToken(networkSession);
     return ''.concat('Bearer ', token.accessToken!) as string;
   }
+  /**
+   * Revoke an active Access Token, effectively logging a user out that has been previously authenticated.
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<undefined>}
+   */
   async revokeToken(networkSession?: NetworkSession): Promise<undefined> {
     const token: undefined | AccessToken = await this.tokenStorage.get();
     if (token == void 0) {
@@ -76,6 +99,14 @@ export class BoxDeveloperTokenAuth implements Authentication {
     await this.tokenStorage.clear();
     return void 0;
   }
+  /**
+   * Downscope access token to the provided scopes. Returning a new access token with the provided scopes, with the original access token unchanged.
+   * @param {readonly string[]} scopes The scope(s) to apply to the resulting token.
+   * @param {string} resource The file or folder to get a downscoped token for. If None and shared_link None, the resulting token will not be scoped down to just a single item. The resource should be a full URL to an item, e.g. https://api.box.com/2.0/files/123456.
+   * @param {string} sharedLink The shared link to get a downscoped token for. If None and item None, the resulting token will not be scoped down to just a single item.
+   * @param {NetworkSession} networkSession An object to keep network session state
+   * @returns {Promise<AccessToken>}
+   */
   async downscopeToken(
     scopes: readonly string[],
     resource?: string,