xing-api-client/dist/auth.d.ts

A client library for interacting with the Xing API

/**
 * Parameters required to build the XING OAuth 2.0 authorization URL.
 */
interface XingGetAuthorizationUrlParameters {
    /**
     * The client ID obtained during app registration.
     * @example "your-client-id"
     */
    client_id: string;
    /**
     * The URL to which the user will be redirected after authorization.
     * Must match the URL registered with the application.
     * @example "https://your-redirect-uri.com/callback"
     */
    redirect_uri: string;
    /**
     * An optional parameter for maintaining state between the request and the callback.
     * Can be used to prevent CSRF attacks or to recall user-specific information.
     * @example "random-state-value"
     */
    state?: string;
}

/**
 * Generates the URL for initiating the Authorization Code grant type flow.
 * This URL should be used to redirect the user's browser to XING's OAuth 2.0 authorization endpoint.
 *
 * Once the user successfully authorizes the application, they will be redirected to the provided `redirectUri`.
 * The optional `state` parameter can be used to maintain state between the request and the callback.
 *
 * Note: Although the OAuth 2 specification supports a `scope` parameter, XING OAuth 2 does not use it.
 *
 * @param {XingGetAuthorizationUrlParameters} parameters - Parameters required to build the authorization URL.
 * @param {string} parameters.client_id - The client ID obtained during app registration.
 * @param {string} parameters.redirect_uri - The URL to which the user will be redirected after authorization.
 * @param {string} [parameters.state] - An optional string to maintain state between the flow and callback.
 *
 * @returns {string} The generated authorization URL.
 *
 * @example
 * // Example 1: Basic usage
 * const url = getAuthorizationUrl({
 *     client_id: "your-client-id",
 *     redirect_uri: "https://your-redirect-uri.com/callback"
 * });
 * console.log(url);
 *
 * @example
 * // Example 2: Providing state
 * const url = getAuthorizationUrl({
 *     client_id: "your-client-id",
 *     redirect_uri: "https://your-redirect-uri.com/callback",
 *     state: "random-state-value"
 * });
 * console.log(url);
 */
declare function getAuthorizationUrl(parameters: XingGetAuthorizationUrlParameters): string;

/**
 * Parameters required to obtain an access token from Xing.
 *
 * @example
 * const params: XingGetTokenParameters = {
 *   clientId: "your-client-id",
 *   clientSecret: "your-client-secret",
 *   redirectUri: "https://example.com/callback",
 *   code: "authorization-code"
 * };
 */
interface XingGetAccessTokenParameters {
    /**
     * The client ID obtained during application registration.
     * @example "your-client-id"
     */
    client_id: string;
    /**
     * The client secret obtained during application registration, corresponding to the client ID.
     * @example "your-client-secret"
     */
    client_secret: string;
    /**
     * The redirect URI used during authorization.
     * Must match the one registered in Xing.
     * @example "https://example.com/callback"
     */
    redirect_uri: string;
    /**
     * The authorization code received after the user grants permission.
     * @example "authorization-code"
     */
    code: string;
}

/**
 * The response received after obtaining an access token from Xing.
 *
 * @example
 * const response: XingGetTokenResponse = {
 *   access_token: "abcd1234efgh5678ijkl",
 *   refresh_token: "mnop1234qrst5678uvwx",
 *   expires_in: 3600,
 *   token_type: "bearer",
 *   user_id: "12345678"
 * };
 */
interface XingGetAccessTokenResponse {
    /**
     * The access token issued by Xing.
     * @example "abcd1234efgh5678ijkl"
     */
    access_token: string;
    /**
     * The refresh token used to obtain a new access token.
     * @example "mnop1234qrst5678uvwx"
     */
    refresh_token: string;
    /**
     * The duration in seconds for which the access token is valid.
     * @example 3600
     */
    expires_in: number;
    /**
     * The type of token issued (always "bearer").
     * @example "bearer"
     */
    token_type: string;
    /**
     * The user ID associated with the access token.
     * @example "12345678"
     */
    user_id: string;
}

/**
 * Retrieves an access token from the Xing API using the provided parameters.
 *
 * @param {XingGetAccessTokenParameters} parameters - An object containing the necessary parameters to fetch
 *      the access token.
 * @param {string} parameters.client_id - The client ID issued when the application was registered.
 * @param {string} parameters.client_secret - The client secret issued when the application was registered.
 * @param {string} parameters.redirect_uri - The redirect URI matching the one used during the authorization request.
 * @param {string} parameters.code - The authorization code received from the authorization server.
 *
 * @return {Promise<XingGetAccessTokenResponse>} A promise that resolves with the access token response.
 *
 * @example
 * // Using .then() and .catch()
 * const parameters: XingGetAccessTokenParameters = {
 *   client_id: 'your-client-id',
 *   client_secret: 'your-client-secret',
 *   redirect_uri: 'https://example.com/callback',
 *   code: 'authorization-code',
 * };
 *
 * getAccessToken(parameters)
 *   .then(response => {
 *     console.log('Access token:', response.access_token);
 *     console.log('Refresh token:', response.refresh_token);
 *   })
 *   .catch(error => {
 *     console.error('Error fetching access token:', error);
 *   });
 *
 * @example
 * // Using async/await
 * async function fetchAccessToken() {
 *   try {
 *     const parameters: XingGetAccessTokenParameters = {
 *       client_id: 'your-client-id',
 *       client_secret: 'your-client-secret',
 *       redirect_uri: 'https://example.com/callback',
 *       code: 'authorization-code',
 *     };
 *     const response = await getAccessToken(parameters);
 *     console.log('Access token:', response.access_token);
 *     console.log('Refresh token:', response.refresh_token);
 *   } catch (error) {
 *     console.error('Error fetching access token:', error);
 *   }
 * }
 */
declare function getAccessToken(parameters: XingGetAccessTokenParameters): Promise<XingGetAccessTokenResponse>;

/**
 * Parameters required to refresh an access token.
 *
 * @example
 * const params: RefreshAccessTokenParameters = {
 *   clientId: "your-client-id",
 *   clientSecret: "your-client-secret",
 *   refreshToken: "your-refresh-token"
 * };
 */
interface XingRefreshAccessTokenParameters {
    /**
     * The client ID provided by Xing during application registration.
     * @example "your-client-id"
     */
    client_id: string;
    /**
     * The client secret obtained during application registration, corresponding to the client ID.
     * @example "your-client-secret"
     */
    client_secret: string;
    /**
     * The refresh token issued by Xing, used to obtain a new access token.
     * @example "your-refresh-token"
     */
    refresh_token: string;
}

/**
 * Interface representing the response received after refreshing an access token.
 * Extends the XingGetAccessTokenResponse interface to inherit properties and methods
 * that are relevant for access token operations.
 *
 * @example
 * const response: XingRefreshAccessTokenResponse = {
 *   access_token: "newAccessToken12345",
 *   refresh_token: "newRefreshToken67890",
 *   expires_in: 3600,
 *   token_type: "bearer",
 *   user_id: "12345678"
 * };
 */
interface XingRefreshAccessTokenResponse extends XingGetAccessTokenResponse {
}

/**
 * Refreshes an access token from the Xing API using the provided parameters.
 *
 * @param {XingRefreshAccessTokenParameters} parameters - An object containing the necessary parameters to refresh
 *      the access token.
 * @param {string} parameters.client_id - The client ID issued when the application was registered.
 * @param {string} parameters.client_secret - The client secret issued when the application was registered.
 * @param {string} parameters.refresh_token - The refresh token issued by Xing, used to obtain a new access token.
 *
 * @return {Promise<XingRefreshAccessTokenResponse>} A promise that resolves with the refreshed access token response.
 *
 * @example
 * // Using .then() and .catch()
 * const parameters: XingRefreshAccessTokenParameters = {
 *   client_id: 'your-client-id',
 *   client_secret: 'your-client-secret',
 *   refresh_token: 'your-refresh-token',
 * };
 *
 * refreshAccessToken(parameters)
 *   .then(response => {
 *     console.log('Access token:', response.access_token);
 *     console.log('Refresh token:', response.refresh_token);
 *   })
 *   .catch(error => {
 *     console.error('Error refreshing access token:', error);
 *   });
 *
 * @example
 * // Using async/await
 * async function updateAccessToken() {
 *   try {
 *     const parameters: XingRefreshAccessTokenParameters = {
 *       client_id: 'your-client-id',
 *       client_secret: 'your-client-secret',
 *       refresh_token: 'your-refresh-token',
 *     };
 *     const response = await refreshAccessToken(parameters);
 *     console.log('Access token:', response.access_token);
 *     console.log('Refresh token:', response.refresh_token);
 *   } catch (error) {
 *     console.error('Error refreshing access token:', error);
 *   }
 * }
 */
declare function refreshAccessToken(parameters: XingRefreshAccessTokenParameters): Promise<XingRefreshAccessTokenResponse>;

export { type XingGetAccessTokenParameters, type XingGetAccessTokenResponse, type XingGetAuthorizationUrlParameters, type XingRefreshAccessTokenParameters, type XingRefreshAccessTokenResponse, getAccessToken, getAuthorizationUrl, refreshAccessToken };