@agility/management-sdk 0.1.2 → 0.1.4-beta.1

package/dist/apiMethods/authMethods.d.ts

@@ -0,0 +1,239 @@
+import { Options } from "../models/options";
+import { OAuthTokenResponse, AuthUrlOptions, TokenExchangeRequest, TokenRefreshRequest, TokenValidationResponse, TokenManagerConfig, AuthState } from "../models/authTokens";
+/**
+ * Internal authentication methods - not exposed publicly
+ * Handles OAuth flow and token management with secure storage
+ */
+export declare class AuthMethods {
+    private _options;
+    private _clientInstance;
+    private _tokenStorage;
+    constructor(options: Options);
+    /**
+     * Generate OAuth authorization URL for user authentication
+     * @param options - Authorization URL configuration options
+     * @returns Complete authorization URL for user redirection
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     * const authUrl = client.authMethods.generateAuthUrl({
+     *     redirectUri: 'https://yourapp.com/auth/callback',
+     *     scope: 'openid profile email offline_access',
+     *     state: 'random-state-string'
+     * });
+     *
+     * // Redirect user to authorization URL
+     * window.location.href = authUrl;
+     * ```
+     */
+    generateAuthUrl(options: AuthUrlOptions): string;
+    /**
+     * Exchange authorization code for access tokens
+     * Automatically stores tokens securely and sets them in Options
+     * @param request - Token exchange request parameters
+     * @returns Promise containing access and refresh tokens
+     */
+    exchangeCodeForToken(request: TokenExchangeRequest, region?: string): Promise<OAuthTokenResponse>;
+    /**
+     * Refresh an expired access token using refresh token
+     * Automatically updates stored tokens and Options
+     * @param request - Token refresh request parameters
+     * @returns Promise containing new access token
+     */
+    refreshAccessToken(request: TokenRefreshRequest, region?: string): Promise<OAuthTokenResponse>;
+    /**
+     * Validate an access token and get token information
+     * @param token - Access token to validate
+     * @returns Promise containing token validation information
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const tokenInfo = await client.authMethods.validateToken('your_access_token');
+     *
+     * if (tokenInfo.active) {
+     *     console.log('Token is valid');
+     *     console.log('Expires at:', new Date(tokenInfo.exp * 1000));
+     *     console.log('Scope:', tokenInfo.scope);
+     * } else {
+     *     console.log('Token is invalid or expired');
+     * }
+     * ```
+     */
+    validateToken(token: string, region?: string): Promise<TokenValidationResponse>;
+    /**
+     * Revoke an access token or refresh token
+     * @param token - Token to revoke
+     * @returns Promise indicating success
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * // Revoke access token on logout
+     * await client.authMethods.revokeToken('access_token');
+     *
+     * // Clear the client's token
+     * client.clearToken();
+     * ```
+     */
+    revokeToken(token: string, region?: string): Promise<void>;
+    /**
+     * Set the access token in the shared Options instance
+     * Also stores token in keytar for consistency
+     * @param token - Valid access token
+     */
+    setAccessToken(token: string): Promise<void>;
+    /**
+     * Get a valid access token - automatically refreshes if expired
+     * @returns Promise containing valid access token or null if authentication required
+     */
+    getValidAccessToken(): Promise<string | null>;
+    /**
+     * Perform OAuth authentication flow
+     * @param options - OAuth configuration options
+     * @returns Promise resolving when authentication is complete
+     */
+    performOAuthFlow(options: AuthUrlOptions): Promise<void>;
+    /**
+     * Clear all authentication data
+     */
+    clearAuthentication(): Promise<void>;
+    /**
+     * Check if user is authenticated (has valid token)
+     * @returns Promise resolving to true if authenticated
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Check if a token is expired based on expiration timestamp
+     * @param expiresAt - Token expiration timestamp (seconds since epoch)
+     * @param bufferSeconds - Buffer time in seconds to consider token expired early (default: 300 = 5 minutes)
+     * @returns True if token is expired or will expire within buffer time
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const expiresAt = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+     *
+     * if (client.authMethods.isTokenExpired(expiresAt)) {
+     *     console.log('Token is expired or will expire soon');
+     *     // Refresh token or re-authenticate
+     * }
+     * ```
+     */
+    isTokenExpired(expiresAt: number, bufferSeconds?: number): boolean;
+    /**
+     * Calculate token expiration timestamp from expires_in value
+     * @param expiresIn - Token lifetime in seconds
+     * @returns Expiration timestamp (seconds since epoch)
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const tokens = await client.authMethods.exchangeCodeForToken(request);
+     * const expiresAt = client.authMethods.calculateExpirationTime(tokens.expires_in);
+     *
+     * // Store expiration time for later use
+     * localStorage.setItem('token_expires_at', expiresAt.toString());
+     * ```
+     */
+    calculateExpirationTime(expiresIn: number): number;
+    /**
+     * Generate a cryptographically secure random state parameter for OAuth
+     * @param length - Length of the state string (default: 32)
+     * @returns Random state string
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const state = client.authMethods.generateState();
+     *
+     * // Store state for validation
+     * sessionStorage.setItem('oauth_state', state);
+     *
+     * // Use in authorization URL
+     * const authUrl = client.authMethods.generateAuthUrl({
+     *     redirectUri: 'https://yourapp.com/callback',
+     *     state: state
+     * });
+     * ```
+     */
+    generateState(length?: number): string;
+    /**
+     * Create a token manager for automatic token refresh
+     * @param config - Token manager configuration
+     * @returns Token manager instance
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const tokenManager = client.authMethods.createTokenManager({
+     *     accessToken: 'current_access_token',
+     *     refreshToken: 'current_refresh_token',
+     *     expiresAt: 1234567890
+     * });
+     *
+     * // Get valid token (auto-refreshes if needed and updates client)
+     * const validToken = await tokenManager.getValidToken();
+     *
+     * // Client is now updated with fresh token - make API calls
+     * const content = await client.contentMethods.getContentItem(123, guid, locale);
+     * ```
+     */
+    createTokenManager(config: TokenManagerConfig): TokenManager;
+    /**
+     * Get current authentication state
+     * @param token - Current access token
+     * @param expiresAt - Token expiration timestamp
+     * @param refreshToken - Optional refresh token
+     * @returns Authentication state information
+     *
+     * @example
+     * ```typescript
+     * const client = new ApiClient();
+     *
+     * const authState = client.authMethods.getAuthState(
+     *     localStorage.getItem('access_token'),
+     *     parseInt(localStorage.getItem('token_expires_at')),
+     *     localStorage.getItem('refresh_token')
+     * );
+     *
+     * if (authState.isAuthenticated) {
+     *     console.log('User is authenticated');
+     * } else {
+     *     console.log('User needs to authenticate');
+     * }
+     * ```
+     */
+    getAuthState(token?: string, expiresAt?: number, refreshToken?: string): AuthState;
+}
+/**
+ * Token manager class for automatic token refresh
+ */
+export declare class TokenManager {
+    private authMethods;
+    private config;
+    constructor(authMethods: AuthMethods, config: TokenManagerConfig);
+    /**
+     * Get a valid access token, refreshing if necessary
+     * This automatically updates the shared token in the AuthMethods instance
+     * @returns Promise containing valid access token
+     */
+    getValidToken(): Promise<string>;
+    /**
+     * Update the token configuration
+     * @param config - New token configuration
+     */
+    updateConfig(config: Partial<TokenManagerConfig>): void;
+    /**
+     * Get current token configuration
+     * @returns Current token configuration
+     */
+    getConfig(): TokenManagerConfig;
+}