matheus23 / elm-figma-api / Figma

This module provides endpoints for the Figma web API.

Authentication


type AuthenticationToken

personalToken : String -> AuthenticationToken

Create a token to be used with the Personal Access Token authentication method. Read more.

oauth2Token : String -> AuthenticationToken

Create a token to be used with the OAuth 2 authentication method. Read more.

Document file and versions


type alias FileKey =
String

A file key which univocally identifies Figma document on the server.

Note: The file key can be extracted from any Figma file URL: https://www.figma.com/file/:key/:title, or via the [getFiles][#getFiles] function.


type alias File =
{ schemaVersion : Basics.Int
, thumbnailUrl : String
, document : Document.Tree
, components : Dict Document.NodeId ComponentMeta 
}

The file data returned by the server. In particular:

getFile : AuthenticationToken -> FileKey -> (Result Http.Error File -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to return the latest version of the file referred by key and store it into a File record.

import Http
import Figma as F

F.getFile ( F.personalToken "your-token" ) "your-file-key"
    |> Http.send FileReceived

Alternatively getFile can be chained together with another request (or any other task) resulting in a single command.

F.getFile ( F.personalToken "your-token" ) "your-file-key"
    |> Http.toTask
    |> Task.andThen
        (\file ->
            let
                options =
                    { format = Document.JpegFormat
                    , scale = 1.0
                    }

                nodeIds =
                    -- Extract your node ID's from file.document here
            in
                F.exportNodesWithOptions authToken fileKey options nodeIds
                    |> Http.toTask
        )
    |> Task.attempt NodesExported


type alias ComponentMeta =
{ name : String
, description : String 
}

Metadata for a master component. Component data is stored in a Document.Component record.


type alias VersionId =
String

Unique identifier for file version.


type alias Version =
{ id : String
, createdAt : Time.Posix
, label : String
, description : String
, user : User 
}

A version of a file.

getVersions : AuthenticationToken -> FileKey -> (Result Http.Error (List Version) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to list 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.

getFileWithVersion : AuthenticationToken -> FileKey -> VersionId -> (Result Http.Error File -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to return specific file version.

Comments


type Comment
    = Comment CommentData
    | Reply ReplyData

A comment is either a "top comment" or a reply to it.


type alias CommentData =
{ id : String
, message : String
, fileKey : FileKey
, position : Geometry.Position
, user : User
, createdAt : Time.Posix
, resolvedAt : Maybe Time.Posix
, orderId : String 
}

A comment left by a user.


type alias ReplyData =
{ id : String
, message : String
, fileKey : FileKey
, parentId : String
, user : User
, createdAt : Time.Posix
, resolvedAt : Maybe Time.Posix 
}

A reply to a comment.

getComments : AuthenticationToken -> FileKey -> (Result Http.Error (List Comment) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to return a list of comments left on the document.

postComment : AuthenticationToken -> FileKey -> { message : String, position : Geometry.Position } -> (Result Http.Error Comment -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to add a new comment to the document. Return the Comment that was successfully posted.

Export document nodes

exportNodesAsPng : AuthenticationToken -> FileKey -> List Document.NodeId -> (Result Http.Error (List ExportedImage) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to export a list of document nodes into PNG files at 1x resolution.

If you need to specify a different scale value use exportNodesWithOptions.

exportNodesAsJpeg : AuthenticationToken -> FileKey -> List Document.NodeId -> (Result Http.Error (List ExportedImage) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to export a list of document nodes into JPEG files at 1x resolution.

If you need to specify a different scale value use exportNodesWithOptions.

exportNodesAsSvg : AuthenticationToken -> FileKey -> List Document.NodeId -> (Result Http.Error (List ExportedImage) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to export a list of document nodes into SVG files at 1x resolution.

If you need to specify a different scale value use exportNodesWithOptions.

exportNodesWithOptions : AuthenticationToken -> FileKey -> { format : Document.ExportFormat, scale : Basics.Float } -> List Document.NodeId -> (Result Http.Error (List ExportedImage) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to export a list of document nodes into the given format files using the given scale factor automatically clamped within the 0.01–4 range.


type alias ExportedImage =
( Document.NodeId
, Maybe String 
)

A tuple made of the node ID and the image URL of its rendered representation.

A Nothing value indicates that rendering of the 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.

Team projects and files


type alias TeamId =
String

A value which uniquely identifies a team.


type alias ProjectId =
Basics.Int

A value which uniquely identifies a project.


type alias Project =
{ id : ProjectId
, name : String 
}

A single team project.

getProjects : AuthenticationToken -> TeamId -> (Result Http.Error (List Project) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request and return the list of projects of the given team.

Note that this will only return projects visible to the authenticated user or owner of the developer token.

getFiles : AuthenticationToken -> ProjectId -> (Result Http.Error (List FileMeta) -> msg) -> Platform.Cmd.Cmd msg

Construct a web request to return the list of files of the given project.


type alias FileMeta =
{ key : FileKey
, name : String
, thumbnailUrl : String
, lastModified : Time.Posix 
}

Metadata for a project file.

User


type alias User =
{ handle : String
, imageUrl : String 
}

A description of a user.

Decoders

fileDecoder : Json.Decode.Decoder File