jemgold / figma-js Goto Github PK

View Code? Open in Web Editor NEW

487.0 10.0 47.0 829 KB

Little wrapper (+ types) for the Figma API

Home Page: https://jongold.github.io/figma-js/

License: MIT License

TypeScript 100.00%

figma-js's Introduction

Figma.js

A simple wrapper for the Figma API.

Cool projects using this:

Usage

Full documentation is available on the web and most everything is typed with TypeScript.

Creating a client

Quickest start is to grab a personal access token from your Figma account settings page

import * as Figma from 'figma-js';

const token = '12345';

const client = Figma.Client({
  personalAccessToken: token
});

Or if you're building an app with OAuth authentication, after you get back the OAuth access token…

import * as Figma from 'figma-js';

const token = '12345';

const client = Figma.Client({
  accessToken: token
});

Doing cool things

Once you have instantiated a client, have fun!

client.file('file-id').then(({ data }) => {
  console.log(data);
});

Just reusing types

All of the types in the Figma file format / API are exported.

import * as Figma from 'figma-js';

const textNode: Figma.Text = {
  // … this should autocomplete if your editor is set up for it!
};

Contributing

We used the typescript-starter repo for this - refer to its README for more detailed instructions.

Helpful development commands:

yarn watch
yarn docs
yarn docs:publish

Contributions welcomed

Committing

yarn global add commitizen

# instead of git commit

git cz

Contributors

@jemgold (Airbnb)
@chrisdrackett

figma-js's People

Contributors

Stargazers

Watchers

figma-js's Issues

File Nodes type not fully implemented

I'm submitting a ...
[*] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

Currently the types are, (notice only 3 props)

export interface FileNodesParams {
    /** A list of node IDs to retrieve and convert */
    readonly ids: ReadonlyArray<string>;
    /**
     * A specific version ID to get. Omitting this will get the current version of the file
     */
    readonly version?: string;
    /**
     * Set to "paths" to export vector data
     */
    readonly geometry?: string;
}

It seems that it's not the only place.

While official Figma docs state

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Maybe it could be fixed by renewing the types

Duplicate types for Vector

I can't believe my eyes and tslint missed this one.

We export 2 things called Vector
https://figma.com/developers/docs#vector-props
https://figma.com/developers/docs#vector-type

This is breaking the postComment call, which uses client_meta: Vector (the type, not the node).

I think perhaps a smart renaming strategy is in order - perhaps renaming all of the node types to VectorNode, LineNode etc etc? Maybe?

This is a high priority bug inasmuch as I'm having to cast to any to post comments rn :D

Support for Variables

I'm submitting a ...
[ ] bug report
[X] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
It would be nice to add support for the Variable beta endpoints: https://www.figma.com/developers/api#variables
Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Any updates?

Are you still here?
Doesn't your type know about new Figma Api scheme?

Update axios to allow users to upgrade past CVE-2020-28168

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

The following CVE is patched in 0.21.1 of axios:

GHSA-4w2v-q235-vp99

package.json uses a caret range to define figma-js' dependency on axios:

https://github.com/jongold/figma-js/blob/3fbe4f390f7d67a2d4c6742cd46bed871fde23cb/package.json#L56-L58

The caret allows any updates as long as they do not modify the left-most non-zero digit:

https://docs.npmjs.com/cli/v6/using-npm/semver#caret-ranges-123-025-004

For users that eg depend on figma-js in a monorepo, this prevents an update to a version of axios that is not vulnerable to CVE-2020-28168.

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Hopefully, relaxing the dependency range (perhaps with >=) would be safe for this project. A quick skim of recent axios release notes suggests that there are no breaking/material changes between 0.19 and 0.21.

https://github.com/axios/axios/releases

Call for maintainers

Hi y'all - I totally missed a ton of issues & PRs, I didn't think ppl were using this!

Would love to add some more people as maintainers - lmk if you're interested <3

Add absoluteRenderBounds

There is absoluteRenderBounds in the Figma answer API for elements extends FrameBase and VectorBase

{
  "id": "52:309",
  "name": "listText",
  "type": "TEXT",
  "scrollBehavior": "SCROLLS",
  "blendMode": "PASS_THROUGH",
  "absoluteBoundingBox": {
    "x": -104.83568572998047,
    "y": 330.29559326171875,
    "width": 158.5352325439453,
    "height": 18.87322998046875
  },
  "absoluteRenderBounds": {
    "x": -104.0505599975586,
    "y": 332.3878479003906,
    "width": 121.72467803955078,
    "height": 14.819244384765625
  },
  "constraints": {
    "vertical": "TOP",
    "horizontal": "LEFT"
  },
  "layoutVersion": 3,
  "/* --- */"
}

Add tests

The test harness is ready, I just don't know what to test.

Re-export axios types

Since figma-js returns axios types, a project needs to add axios as a dependency, even if it isn't directly depending on it. Re-exporting those types would probably be cleaner.

Types for style and file style responses do not match reality

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

The types for the GET file styles endpoint response say it returns an object with a root array property of styles containing style definitions, extending an object with a meta property with a key-value map of style definitions :

export interface FileStylesResponse extends StyleResponse {
  readonly styles: ReadonlyArray<FullStyleMetadata>;
}

export interface StyleResponse {
  readonly meta: {
    readonly err: string | null;
    readonly status: number;
    readonly [key: string]: FullStyleMetadata;
  };
}

This does not match the API:

https://www.figma.com/developers/api#get-file-styles-endpoint

The example response is:

{
  "status": Number,
  "error": Boolean,
  "meta": { 
    "styles": [
      {
       "key": String,
       "file_key": String,
       "node_id": String,
       "style_type": StyleType,
       "thumbnail_url": String,
       "name": String,
       "description": String,
       "updated_at": String,
       "created_at": String,
       "sort_position": String,
       "user": User, 
       },
      ...
    ],
   }, 
}

There is no root styles property containing style metadata.
The meta property has a single property, styles which maps to an array of style metadata.

The GET style endpoint is typed to return the StyleResponse object above. This does not match the API:

https://www.figma.com/developers/api#get-style-endpoint

The example response is:

{
  "status": Number,
  "error": Boolean,
  "meta": { 
     "key": String,
     "file_key": String,
     "node_id": String,
     "style_type": StyleType,
     "thumbnail_url": String,
     "name": String,
     "description": String,
     "updated_at": String,
     "created_at": String,
     "sort_position": String,
     "user": User, 
   }, 
}

The style definition object is not keyed within the meta property, it is the meta property.

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

COMPONENT_SET is missing from NodeType declaration

I'm submitting a ...
[ ] bug report
[x] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
COMPONENT_SET is listed in Figma's API documentation, but is not present in this package's NodeType declaration
Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)*
Similar to this issue

Update axios to support PROXY env vars

I'm submitting a ...
[ ] bug report
[X] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

Please update the axios dependency to support usage of HTTP_PROXY and HTTPS_PROXY environment variables.

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Related issue on @figma-export/cli : marcomontalbano/figma-export#152

client.file Cannot read property 'join' of undefined

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
If params are not passed when fetching a file, the method will throw since ids is undefined. The change that causes this issue was introduced here: https://github.com/jongold/figma-js/pull/39/files#diff-f41e9d04a45c83f3b6f6e630f10117feR309
Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Suggested fix:

    file: (fileId, params = {}) =>
      client.get(`files/${fileId}`, {
        params: {
          ...params,
          ids: params.ids ? params.ids.join(',') : '',
        },
      }),

Work around:

//before
client.file(fildId).then(() => {})

//after
client.file(fildId, { ids: [] }).then(() => {})

Site link doesn't work

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
jongold.github.io/figma-js/ link doesn't show the site.
Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Missing 'plugin_data' query params

I'm submitting a ...
[ ] bug report
[X] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

Hey! Nice work here. Im just posting an issue to track that the figma api now supports fetching PluginData.

https://www.figma.com/developers/api#authentication

No rush on this!

Thanks,
Colin

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Generate types automatically

I wrote all the types out by hand which was some pretty intense type 2 fun.

Would be excellent if someone (at Figma?) could figure out how to generate them automatically.

Add variants support

Feature Request to integrate Figma's new variants feature

Add types and endpoints for:

These features mirror the existing functionality for fetching team components, file components, and component. Therefore the updates required are minor.

Duplicate types for Rectangle

The Rectangle node type and the Rectangle primitive have the same name.

Potential nesting limits; failed node render

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

Heya figma-js team. I'm running into an issue with fetching a frame at a certain nested level. Debatable design file hygiene aside, I wanted to touch base with y'all to see if this behavior's been encountered.

From the "Copy link" menu in Figma, I grab the URL,

https://www.figma.com/file/hash/project?node-id=4316%3A10002

and then pass the node ID into the .fileImages call,

const figma = Figma.Client({
	personalAccessToken: FIGMA_TOKEN,
});

const response = await figma.fileImages(key, {
	// passing in the IDs from the above link
	ids: ['4316:10002'],
});

and get a response with,

// response.data
{
    err: null,
    images:
    {
        '4316:10002':  null  // instead of the expected S3 URL 
    }
}

Here's an image of the limits:

Checking the docs, the closest hunch I have to what's happening is:

Important: the image map may contain values that are null. This indicates that rendering of that specific node has failed. This may be due to the node id not existing, or other reasons such has the node having no renderable components.

https://www.figma.com/developers/api#get-images-endpoint

So perhaps the Frame I'm copying doesn't have any renderable components? If that's the case, apologies for the ticket and my blatant misuse :-)

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

Love this project! Huge kudos to the authors and maintainers.

Node.Type = 'BOOLEAN_OPERATION'

I'm submitting a ...
[ ] bug report
[x] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary

there isn't BOOLEAN_OPERATION in NodeType.

Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

figma docs BooleanOperationNode

thumbnail_urlString property in SharedElement interface is incorrectly named

I'm submitting a ...
[x] bug report
[ ] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
The thumbnail_urlString property currently defined in the SharedElement interface should be thumbnail_url (see https://www.figma.com/developers/api#library-items-types).
Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. StackOverflow, personal fork, etc.)

interface SharedElement extends ComponentMetadata {
  ...
  readonly thumbnail_urlString: string;
 ...
}

should instead be

interface SharedElement extends ComponentMetadata {
  ...
  readonly thumbnail_url: string;
 ...
}

Is this project still relevant?

I'm submitting a ...
[ ] bug report
[ ] feature request
[x] question about the decisions made in the repository
[ ] question about how to use this project

With https://github.com/figma/rest-api-spec, is this project still relevant? They include all the typescript types, and if you need a client, you can use something like https://github.com/hey-api/openapi-ts to generate a client for you based on their openapi.yaml.

switch default branch from `master` to `main`

I added the branch, but I don't have permissions to actually do the switch in github.

Geometry and version options

I'm submitting a ...
[ ] bug report
[X] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
Get:file exposes no geometry or version options, but it very much should.

I'm submitting a ...
[ ] bug report
[x] feature request
[ ] question about the decisions made in the repository
[ ] question about how to use this project
Summary
Add first-class support for working with webhooks. It is still in beta so I understand if this should wait. I'd be happy to start a PR for this just let me know :)

@jongold / @chrisdrackett maybe you can take a look?

jemgold / figma-js Goto Github PK

figma-js's Introduction

Figma.js

Usage

Creating a client

Doing cool things

Just reusing types

Contributing

Contributions welcomed

Committing

Contributors

figma-js's People

Contributors

Stargazers

Watchers

Forkers

figma-js's Issues

Recommend Projects

Recommend Topics

Recommend Org