@dustinnewman98/figma-api v1.3.2

figma-api

Full implementation of Figma API.

Figma api's file fully typed with TypeScript.

Both browser & nodejs supported.

All api requests uses go-result-js for smooth error solving (return tuple like error, result ).

Promises & ES6.

Install

npm i figma-api --save-exact

!go-result-js will be removed in future versions, so install using --save-exact!

or browser version:

https://raw.githubusercontent.com/Morglod/figma-api/master/lib/figma-api.js
https://raw.githubusercontent.com/Morglod/figma-api/master/lib/figma-api.min.js

All api in browser exported to global Figma object.

Usage

import * as Figma from 'figma-api';

export async function main() {
    const api = new Figma.Api({
        personalAccessToken: 'my token',
    });

    const [ err, file ] = await api.getFile('my file key');
    if (file) {
        // ... access file data ...
    }
}

or in browser:

const api = new Figma.Api({ personalAccessToken: 'my token' });

api.getFile('my file key').then(([ err, file ]) => {
    if (file) {
        // access file data
    }
});

Api

new Api ({ personalAccessToken, oAuthToken })

Creates new Api object with specified personal or oAuthToken.
Documentation on how to get tokens

Api.getFile(fileKey, opts?: { version?, geometry? })

Require file data with specified version.
Set geometry='paths' to export vector data.

Returns:

[ Error?, {
    name: string,
    document: Node<'DOCUMENT'>,
    components: { [nodeId: string]: Component },
    schemaVersion: number,
    styles: { [styleName: string]: Style }
} ]

Api.getImage(fileKey, opts?: {
    /** A comma separated list of node IDs to render */
    ids: string,
    /** A number between 0.01 and 4, the image scaling factor */
    scale: number,
    /** Image output format */
    format: 'jpg'|'png'|'svg',
    /** Whether to include id attributes for all SVG elements. `Default: false` */
    svg_include_id?: boolean,
    /** Whether to simplify inside/outside strokes and use stroke attribute if possible instead of <mask>. `Default: true` */
    svg_simplify_stroke?: boolean,
    /** A specific version ID to get. Omitting this will get the current version of the file */
    version?: string,
})

Renders images from a file.

Returns:

[ Error?, {
    err: string,
    images: { [nodeId: string]: string|null },
    status: number
} ]

Api.getVersions(fileKey)

A list of the version history of a file. The version history consists of versions, manually-saved additions to the version history of a file.
If the account is not on a paid team, version history is limited to the past 30 days. Note that version history will not include autosaved versions.

Returns:

[ Error?, {
    versions: Version[]
} ]

Api.getComments(fileKey)

List of comments left on the file.

Returns:

[ Error?, {
    comments: Comment[],
} ]

Api.postComment(fileKey: string, message: string, client_meta: Vector|FrameOffset)

Posts a new comment on the file with specified location.

Returns:

[ Error?, Comment ]

Api.getTeamProjects(team_id)

Lists the projects for a specified team. Note that this will only return projects visible to the authenticated user or owner of the developer token.

Returns:

[ Error?, {
    projects: { id: number, name: string }[],
} ]

Api.getProjectFiles(project_id)

List the files in a given project.

Returns:

[ Error?, {
    files: {
        key: string,
        name: string,
        thumbnail_url: string,
        last_modified: string,
    }[],
} ]

Api.getImageFills(fileKey)

Download links for all images present in image fills.

Returns:

[ Error?, {
    meta?: {
        images: {
            [imageRef: string]: imageUrl,
        },
    }
    images?: {
        [imageRef: string]: imageUrl,
    },
} ]

Because of great figma api docs, meta? & images? for now.

Api.appendHeaders(headers: {}): void
Populate headers with auth.

Api.request<T>(url, opts): Promise<[ Error?, T]>
Make request with auth headers.

Auth helpers

OAuth figma documentation.

function oAuthLink(
    client_id: string,
    redirect_uri: string,
    scope: 'file_read',
    state: string,
    response_type: 'code',
): string;

Returns link for OAuth auth flow.
User should open this link, allow access and he will be redirected to redirect_uri?code=<code>.
Then you should use oAuthToken method to get access token.

function oAuthToken(
    client_id: string,
    client_secret: string,
    redirect_uri: string,
    code: string,
    grant_type: 'authorization_code',
): Promise<[ Error?, {
    access_token: string,
    expires_in: number,
} ]>

Returns access token info from oauth code (see oAuthLink method).

File types

All types with description

isEffectShadow(effect: Effect): effect is EffectShadow;

Check if effect is one of shadow effects.

isEffectBlur(effect: Effect): effect is EffectBlur;

Check if effect is one of blur effects.

isPaintSolid(paint: Paint): paint is PaintSolid;
isPaintGradient(paint: Paint): paint is PaintGradient;
isPaintImage(paint: Paint): paint is PaintImage;

Check if paint is one of pain types.

isNodeType<NodeType>(node: Node): node is type of NodeType;

Check if node is type of specified node.

Development

git clone https://github.com/Morglod/figma-api.git
cd figma-api
git checkout dev
npm i
npm run build