@design-sdk/figma-oauth/dist/index.d.mts

OAuth management for figma

interface FigmaOAuthUrlParam {
    client_id: string;
    redirect_uri: string;
    /**
     * Currently this value can only be file_read signifying
     * read-only access to the user's files.
     */
    scope?: "file_read";
    /**
     * This is a value that you should randomly generate and store.
     * When we call back to your callback endpoint,
     * you should check that the state value we pass back to you matches the state value that you initially used in your request.
     */
    state: string;
    /**
     * Currently we only support the authorization code flow for OAuth 2,
     * so the only valid value here is code.
     * We may support other values in the future.
     */
    response_type?: "code";
}
interface FigmaOAuthTokenRequestParam {
    client_id: string;
    client_secret: string;
    grant_type?: string;
    redirect_uri: string;
    code: string;
}
interface FigmaOAuthTokenRefreshParam {
    client_id: string;
    client_secret: string;
    refresh_token: string;
}
/**
 * [Authenticate users](https://www.figma.com/developers/api#auth-oauth2)
 */
interface FigmaOAuthTokenResponse {
    user_id: string;
    access_token: string;
    expires_in: number;
    refresh_token: string;
}
/**
 * [Refreshing OAuth tokens](https://www.figma.com/developers/api#refresh-oauth2)
 */
interface FigmaOAuthTokenRefreshResponse {
    access_token: string;
    expires_in: number;
}
type OAuthStage = "started" | "authorize" | "token";

/**
 * The format of the response body is:
 * ```json
 *  {
      "access_token": "<TOKEN>",
      "expires_in": "<EXPIRATION (in seconds)>",
      "refresh_token": "<REFRESH TOKEN>"
    }
 * ```
 */
declare function requestOauthToken({ client_id, client_secret, grant_type, redirect_uri, code, }: FigmaOAuthTokenRequestParam): Promise<FigmaOAuthTokenResponse>;
/**
 * [Refreshing OAuth tokens](https://www.figma.com/developers/api#refresh-oauth2)
 *
 * ```
    POST https://www.figma.com/api/oauth/refresh?
    client_id=:client_id&
    client_secret=:client_secret&
    refresh_token=:refresh_token

    {
        "access_token": <TOKEN>,
        "expires_in": <EXPIRATION (in seconds)>,
    }
 * ```
 */
declare function refreshOauthToken({ client_id, client_secret, refresh_token, }: FigmaOAuthTokenRefreshParam): Promise<FigmaOAuthTokenRefreshResponse>;
declare const request: {
    authentication: typeof requestOauthToken;
    tokenrefresh: typeof refreshOauthToken;
};

/**
 * example:
 *
 * `https://www.figma.com/api/oauth/token?`
 * - `client_id=:client_id&`
 * - `client_secret=:client_secret&`
 * - `redirect_uri=:callback&`
 * - `code=:code&`
 * - `grant_type=authorization_code`
 *
 * will return : https://accounts.grida.co/callback/figma-app-oauth?code=K3p9uhqlntNDrbLe2HMPAFgwf&state=
 */
declare function oauthBrowserUrl({ client_id, redirect_uri, state, scope, response_type, }: FigmaOAuthUrlParam): string;
/**
 *
 */
declare function oauthTokenRequestUrl({ client_id, client_secret, grant_type, redirect_uri, code, }: FigmaOAuthTokenRequestParam): string;
declare function oauthTokenRefreshUrl({ client_id, client_secret, refresh_token, }: FigmaOAuthTokenRefreshParam): string;
declare const urls: {
    oauth_token_request_url: typeof oauthTokenRequestUrl;
    oauth_token_refresh_url: typeof oauthTokenRefreshUrl;
    oauth_browser_url: typeof oauthBrowserUrl;
};

/**
 * configure figma app in a global scope.
 * if you've already loaded env variables, without explicitely calling this method,
 * still the package will work with referenced variable **`FIGMA_APP_CLIENT_ID`** and **`FIGMA_APP_CLIENT_SECRET`**
 */
declare function configure({ client_id, client_secret, redirect_uri, }: {
    client_id?: string;
    client_secret?: string;
    redirect_uri?: string;
}): void;

declare class OAuth {
    static readonly _authprocs: Map<string, OAuthState>;
    static new({ state, redirect_uri, }: {
        state?: string;
        redirect_uri?: string;
    }): OAuthState;
    static get(state: string): OAuthState;
    static resolve(state: string): void;
}
declare class OAuthState {
    private _stage;
    readonly _app_id: string;
    readonly _app_secret: string;
    readonly redirect_uri: string;
    get stage(): OAuthStage;
    readonly state: string;
    constructor({ state, redirect_uri, }: {
        state?: string;
        redirect_uri?: string;
    });
    get authUrl(): string;
    authenticate({ code }: {
        code: string;
    }): Promise<FigmaOAuthTokenResponse>;
    resolve(): void;
}

export { type FigmaOAuthTokenRefreshParam, type FigmaOAuthTokenRefreshResponse, type FigmaOAuthTokenRequestParam, type FigmaOAuthTokenResponse, type FigmaOAuthUrlParam, OAuth, type OAuthStage, OAuthState, configure, oauthBrowserUrl, oauthTokenRefreshUrl, oauthTokenRequestUrl, refreshOauthToken, request, requestOauthToken, urls };