figma-metadata-extractor 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +128 -0
  3. package/dist/index.cjs +1462 -0
  4. package/dist/index.js +1462 -0
  5. package/package.json +69 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Figma Metadata Extractor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # Figma Metadata Extractor
2
+
3
+ A TypeScript library for extracting metadata and downloading images from Figma files programmatically, based on Figma-Context-MCP.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install figma-metadata-extractor
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```typescript
14
+ import { getFigmaMetadata, downloadFigmaImages } from 'figma-metadata-extractor';
15
+
16
+ // Extract metadata from a Figma file
17
+ const metadata = await getFigmaMetadata(
18
+ 'https://figma.com/file/ABC123/My-Design',
19
+ {
20
+ apiKey: 'your-figma-api-key',
21
+ outputFormat: 'object' // or 'json' or 'yaml'
22
+ }
23
+ );
24
+
25
+ console.log(metadata.nodes); // Array of design nodes
26
+ console.log(metadata.globalVars); // Styles, colors, etc.
27
+
28
+ // Download images from the file
29
+ const images = await downloadFigmaImages(
30
+ 'https://figma.com/file/ABC123/My-Design',
31
+ [
32
+ {
33
+ nodeId: '1234:5678',
34
+ fileName: 'icon.svg'
35
+ },
36
+ {
37
+ nodeId: '9876:5432',
38
+ fileName: 'hero-image.png'
39
+ }
40
+ ],
41
+ {
42
+ apiKey: 'your-figma-api-key',
43
+ localPath: './assets/images'
44
+ }
45
+ );
46
+
47
+ console.log(images); // Array of download results
48
+ ```
49
+
50
+ ## API Reference
51
+
52
+ ### `getFigmaMetadata(figmaUrl, options)`
53
+
54
+ Extracts comprehensive metadata from a Figma file including layout, content, visuals, and component information.
55
+
56
+ **Parameters:**
57
+ - `figmaUrl` (string): The Figma file URL
58
+ - `options` (FigmaMetadataOptions): Configuration options
59
+
60
+ **Options:**
61
+ - `apiKey?: string` - Figma API key (Personal Access Token)
62
+ - `oauthToken?: string` - Figma OAuth Bearer token
63
+ - `useOAuth?: boolean` - Whether to use OAuth instead of API key
64
+ - `outputFormat?: 'json' | 'yaml' | 'object'` - Output format (default: 'object')
65
+ - `depth?: number` - Maximum depth to traverse the node tree
66
+
67
+ **Returns:** Promise<FigmaMetadataResult | string>
68
+
69
+ ### `downloadFigmaImages(figmaUrl, nodes, options)`
70
+
71
+ Downloads SVG and PNG images from a Figma file.
72
+
73
+ **Parameters:**
74
+ - `figmaUrl` (string): The Figma file URL
75
+ - `nodes` (FigmaImageNode[]): Array of image nodes to download
76
+ - `options` (FigmaMetadataOptions & FigmaImageOptions): Configuration options
77
+
78
+ **Node Properties:**
79
+ - `nodeId: string` - The Figma node ID (format: '1234:5678')
80
+ - `fileName: string` - Local filename (must end with .png or .svg)
81
+ - `imageRef?: string` - Image reference for image fills
82
+ - `needsCropping?: boolean` - Whether image needs cropping
83
+ - `cropTransform?: number[][]` - Transform matrix for cropping
84
+ - `requiresImageDimensions?: boolean` - Whether to generate CSS variables
85
+ - `filenameSuffix?: string` - Suffix for unique filenames
86
+
87
+ **Additional Options:**
88
+ - `pngScale?: number` - Export scale for PNG images (default: 2)
89
+ - `localPath: string` - Absolute path to save images
90
+
91
+ **Returns:** Promise<FigmaImageResult[]>
92
+
93
+ ## Authentication
94
+
95
+ You need either a Figma API key or OAuth token:
96
+
97
+ ### API Key (Personal Access Token)
98
+ 1. Go to Figma → Settings → Account → Personal Access Tokens
99
+ 2. Generate a new token
100
+ 3. Use it in the `apiKey` option
101
+
102
+ ### OAuth Token
103
+ 1. Set up Figma OAuth in your application
104
+ 2. Use the bearer token in the `oauthToken` option
105
+ 3. Set `useOAuth: true`
106
+
107
+ ## Advanced Usage
108
+
109
+ The library also exports the underlying extractor system for custom processing:
110
+
111
+ ```typescript
112
+ import {
113
+ simplifyRawFigmaObject,
114
+ allExtractors,
115
+ layoutExtractor,
116
+ textExtractor
117
+ } from 'figma-metadata-extractor';
118
+
119
+ // Use specific extractors
120
+ const customResult = simplifyRawFigmaObject(
121
+ rawFigmaResponse,
122
+ [layoutExtractor, textExtractor]
123
+ );
124
+ ```
125
+
126
+ ## License
127
+
128
+ MIT