@figma-vars/hooks 2.0.0-beta.3 → 3.0.0

package/dist/utils/errorHelpers.d.ts

@@ -0,0 +1,96 @@
+import { FigmaApiError } from '../types/figma';
+/**
+ * Type guard to check if an error is a FigmaApiError instance.
+ *
+ * @remarks
+ * Use this to safely check if an error has HTTP status code information before accessing `statusCode`.
+ *
+ * @param error - The error to check.
+ * @returns `true` if the error is a FigmaApiError, `false` otherwise.
+ *
+ * @example
+ * ```tsx
+ * import { isFigmaApiError } from '@figma-vars/hooks';
+ *
+ * try {
+ *   await mutate(payload);
+ * } catch (error) {
+ *   if (isFigmaApiError(error)) {
+ *     if (error.statusCode === 401) {
+ *       // Handle authentication error
+ *     } else if (error.statusCode === 429) {
+ *       // Handle rate limit
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isFigmaApiError(error: unknown): error is FigmaApiError;
+/**
+ * Extracts the HTTP status code from an error, if available.
+ *
+ * @remarks
+ * Returns the status code from FigmaApiError, or `null` if the error doesn't have status information.
+ *
+ * @param error - The error to extract status code from.
+ * @returns The HTTP status code, or `null` if not available.
+ *
+ * @example
+ * ```tsx
+ * import { getErrorStatus } from '@figma-vars/hooks';
+ *
+ * const status = getErrorStatus(error);
+ * if (status === 401) {
+ *   // Handle unauthorized
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getErrorStatus(error: unknown): number | null;
+/**
+ * Extracts a human-readable error message from an error.
+ *
+ * @remarks
+ * Returns the error message, falling back to a default message if the error doesn't have one.
+ *
+ * @param error - The error to extract message from.
+ * @param defaultMessage - Optional default message if error has no message. Defaults to "An error occurred".
+ * @returns The error message string.
+ *
+ * @example
+ * ```tsx
+ * import { getErrorMessage } from '@figma-vars/hooks';
+ *
+ * const message = getErrorMessage(error);
+ * toast.error(message);
+ * ```
+ *
+ * @public
+ */
+export declare function getErrorMessage(error: unknown, defaultMessage?: string): string;
+/**
+ * Checks if an error represents a specific HTTP status code.
+ *
+ * @remarks
+ * Convenience function to check if an error has a specific status code.
+ *
+ * @param error - The error to check.
+ * @param statusCode - The HTTP status code to check for.
+ * @returns `true` if the error has the specified status code, `false` otherwise.
+ *
+ * @example
+ * ```tsx
+ * import { hasErrorStatus } from '@figma-vars/hooks';
+ *
+ * if (hasErrorStatus(error, 401)) {
+ *   // Handle unauthorized
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function hasErrorStatus(error: unknown, statusCode: number): boolean;
+//# sourceMappingURL=errorHelpers.d.ts.map

package/dist/utils/errorHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/errorHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,cAAc,SAAsB,GACnC,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1E"}

package/dist/utils/index.d.ts

@@ -11,7 +11,7 @@
  *
  * @example
  * ```ts
- * import { filterVariables } from '@figma-vars/hooks/utils';
+ * import { filterVariables, isFigmaApiError } from '@figma-vars/hooks/utils';
  *
  * const filtered = filterVariables(allVariables, { resolvedType: 'COLOR' });
  * ```
@@ -19,4 +19,5 @@
  * @public
  */
 export { filterVariables } from './filterVariables';
+export { isFigmaApiError, getErrorStatus, getErrorMessage, hasErrorStatus, } from './errorHelpers';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAA"}

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "2.0.0-beta.3",
+  "version": "3.0.0",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "core": [
+        "dist/core.d.ts"
+      ]
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "scripts"
   ],
+  "bin": {
+    "figma-vars-export": "./scripts/export-variables.mjs"
+  },
   "keywords": [
     "figma",
     "figma variables",
@@ -34,14 +46,36 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "postbuild": "cp dist/index.d.ts dist/index.d.cts || copy dist/index.d.ts dist/index.d.cts && cp dist/core.d.ts dist/core.d.cts || copy dist/core.d.ts dist/core.d.cts && cp dist/core/index.d.ts dist/core/index.d.cts || copy dist/core\\index.d.ts dist/core\\index.d.cts",
+    "prepublishOnly": "pnpm build",
+    "lint": "biome format --write .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
+    "postversion": "git push && git push --tags",
+    "create:docs": "npx typedoc src/index.ts --out docs-site/api",
+    "check:publint": "publint",
+    "check:attw": "attw --pack .",
+    "check:size": "size-limit",
+    "check:release": "pnpm run build && pnpm run check:publint && pnpm run check:attw && pnpm run check:size",
+    "prepare": "husky"
+  },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,json,md}": [
       "prettier --write"
     ]
   },
   "peerDependencies": {
-    "react": "^18.3.1 || ^19.0.0",
-    "react-dom": "^18.3.1 || ^19.0.0"
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "swr": "^2.3.7"
   },
   "sideEffects": false,
   "exports": {
@@ -55,6 +89,17 @@
         "default": "./dist/index.cjs"
       },
       "default": "./dist/index.mjs"
+    },
+    "./core": {
+      "import": {
+        "types": "./dist/core/index.d.ts",
+        "default": "./dist/core.mjs"
+      },
+      "require": {
+        "types": "./dist/core/index.d.cts",
+        "default": "./dist/core.cjs"
+      },
+      "default": "./dist/core.mjs"
     }
   },
   "publishConfig": {
@@ -65,6 +110,16 @@
     "type": "github",
     "url": "https://github.com/sponsors/marklearst"
   },
+  "pnpm": {
+    "overrides": {
+      "vite": "^6.3.5"
+    },
+    "onlyBuiltDependencies": [
+      "@biomejs/biome",
+      "esbuild"
+    ]
+  },
+  "packageManager": "pnpm@10.15.0",
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.0",
     "@biomejs/biome": "^1.9.4",
@@ -72,8 +127,8 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^24.0.3",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.5.2",
     "@vitest/coverage-v8": "^2.0.5",
     "@vitest/ui": "2.1.9",
@@ -83,9 +138,10 @@
     "lint-staged": "^16.1.5",
     "prettier": "^3.6.2",
     "publint": "^0.3.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "size-limit": "^11.1.5",
+    "swr": "^2.3.7",
     "typescript": "~5.8.3",
     "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.4",
@@ -95,9 +151,7 @@
   "directories": {
     "doc": "docs"
   },
-  "dependencies": {
-    "swr": "^2.3.3"
-  },
+  "dependencies": {},
   "size-limit": [
     {
       "name": "modern ESM entry",
@@ -105,24 +159,5 @@
       "import": "{ useVariables }",
       "limit": "10 kB"
     }
-  ],
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "postbuild": "cp dist/index.d.ts dist/index.d.cts || copy dist/index.d.ts dist/index.d.cts",
-    "lint": "biome format --write .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "preview": "vite preview",
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest watch",
-    "postversion": "git push && git push --tags",
-    "create:docs": "npx typedoc src/index.ts --out docs-site/api",
-    "check:publint": "publint",
-    "check:attw": "attw --pack .",
-    "check:size": "size-limit",
-    "check:release": "pnpm run build && pnpm run check:publint && pnpm run check:attw && pnpm run check:size"
-  }
-}
+  ]
+}

package/scripts/export-variables.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import fs from 'fs/promises'
+import path from 'path'
+
+const FIGMA_TOKEN = process.env.FIGMA_TOKEN || process.env.FIGMA_PAT
+
+function parseArgs() {
+  const args = process.argv.slice(2)
+  const opts = {
+    fileKey: process.env.FIGMA_FILE_KEY,
+    out: 'data/figma-variables.json',
+  }
+
+  // Show help
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Export Figma Variables to JSON
+
+Usage:
+  figma-vars-export --file-key <FILE_KEY> --out <OUTPUT_PATH>
+  figma-vars-export --file-key <FILE_KEY> [--out <OUTPUT_PATH>]
+
+Options:
+  --file-key, --fileKey    Figma file key (required, or set FIGMA_FILE_KEY env var)
+  --out                     Output file path (default: data/figma-variables.json)
+  --help, -h                Show this help message
+
+Environment Variables:
+  FIGMA_TOKEN or FIGMA_PAT  Figma Personal Access Token (required)
+  FIGMA_FILE_KEY            Figma file key (optional, can use --file-key instead)
+
+Examples:
+  # Using npx (no install needed)
+  FIGMA_TOKEN=xxx npx figma-vars-export --file-key abc123 --out ./variables.json
+
+  # After installing the package
+  FIGMA_TOKEN=xxx figma-vars-export --file-key abc123 --out ./variables.json
+
+  # Using environment variables
+  export FIGMA_TOKEN=xxx
+  export FIGMA_FILE_KEY=abc123
+  figma-vars-export --out ./variables.json
+
+Note: Requires Figma Enterprise account for live API access.
+`)
+    process.exit(0)
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--file-key' || arg === '--fileKey') {
+      opts.fileKey = args[i + 1]
+      i += 1
+    } else if (arg === '--out') {
+      opts.out = args[i + 1]
+      i += 1
+    }
+  }
+  return opts
+}
+
+async function main() {
+  const { fileKey, out } = parseArgs()
+  if (!FIGMA_TOKEN) {
+    console.error('FIGMA_TOKEN (or FIGMA_PAT) is required')
+    process.exit(1)
+  }
+  if (!fileKey) {
+    console.error('--file-key or FIGMA_FILE_KEY is required')
+    process.exit(1)
+  }
+
+  const url = `https://api.figma.com/v1/files/${fileKey}/variables/local`
+  const res = await fetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Figma-Token': FIGMA_TOKEN,
+    },
+  })
+
+  if (!res.ok) {
+    const text = await res.text()
+    console.error(`Request failed: ${res.status} ${res.statusText}`)
+    console.error(text)
+    process.exit(1)
+  }
+
+  const json = await res.json()
+  const outputPath = path.resolve(out)
+  await fs.mkdir(path.dirname(outputPath), { recursive: true })
+  await fs.writeFile(outputPath, JSON.stringify(json, null, 2), 'utf8')
+  console.log(`Saved variables to ${outputPath}`)
+  if (json?.meta?.variables) {
+    console.log(`Variables count: ${Object.keys(json.meta.variables).length}`)
+  }
+}
+
+main().catch(err => {
+  console.error(err)
+  process.exit(1)
+})

package/dist/index.d.mts

@@ -1,2 +0,0 @@
-export * from './index'
-export {}