@figma-vars/hooks 3.0.0 → 3.1.0

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

@@ -1 +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"}
+{"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;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK3D"}

package/dist/utils/index.d.ts

@@ -19,5 +19,6 @@
  * @public
  */
 export { filterVariables } from './filterVariables';
-export { isFigmaApiError, getErrorStatus, getErrorMessage, hasErrorStatus, } from './errorHelpers';
+export { isFigmaApiError, getErrorStatus, getErrorMessage, hasErrorStatus, isRateLimited, getRetryAfter, } from './errorHelpers';
+export { isLocalVariablesResponse, isPublishedVariablesResponse, } from './typeGuards';
 //# 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;AACvD,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,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,EACd,aAAa,EACb,aAAa,GACd,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA"}

package/dist/utils/swrKeys.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared utilities for constructing SWR cache keys consistently across hooks.
+ *
+ * @remarks
+ * Centralizes key construction logic to prevent mismatches between fetch hooks
+ * and invalidation utilities. Ensures that invalidation keys match the keys
+ * used by useSWR in fetch hooks.
+ *
+ * @internal
+ */
+/**
+ * Parameters for constructing a published variables SWR key.
+ */
+export interface PublishedVariablesKeyParams {
+    /** Figma file key, or null if not available */
+    fileKey: string | null;
+    /** Figma Personal Access Token, or null if not available */
+    token: string | null;
+    /** Provider instance ID for fallback cache scoping */
+    providerId: string | undefined;
+    /** Whether fallback file is available */
+    hasFallback: boolean;
+}
+//# sourceMappingURL=swrKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swrKeys.d.ts","sourceRoot":"","sources":["../../src/utils/swrKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+CAA+C;IAC/C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,sDAAsD;IACtD,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAA;CACrB"}

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1,50 @@
+import { LocalVariablesResponse, PublishedVariablesResponse } from '../types/figma';
+/**
+ * Runtime type guard to check if data matches LocalVariablesResponse structure.
+ *
+ * @remarks
+ * Use this to validate fallback files or API responses at runtime before casting.
+ * Validates the essential structure: meta object with variableCollections and variables.
+ *
+ * @param data - The data to validate
+ * @returns `true` if data matches LocalVariablesResponse structure
+ *
+ * @example
+ * ```ts
+ * import { isLocalVariablesResponse } from '@figma-vars/hooks';
+ *
+ * if (isLocalVariablesResponse(fallbackData)) {
+ *   // Safe to use as LocalVariablesResponse
+ * } else {
+ *   console.error('Invalid fallback file structure');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isLocalVariablesResponse(data: unknown): data is LocalVariablesResponse;
+/**
+ * Runtime type guard to check if data matches PublishedVariablesResponse structure.
+ *
+ * @remarks
+ * Use this to validate fallback files or API responses at runtime before casting.
+ * Validates the essential structure: meta object with variableCollections and variables.
+ *
+ * @param data - The data to validate
+ * @returns `true` if data matches PublishedVariablesResponse structure
+ *
+ * @example
+ * ```ts
+ * import { isPublishedVariablesResponse } from '@figma-vars/hooks';
+ *
+ * if (isPublishedVariablesResponse(fallbackData)) {
+ *   // Safe to use as PublishedVariablesResponse
+ * } else {
+ *   console.error('Invalid fallback file structure');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isPublishedVariablesResponse(data: unknown): data is PublishedVariablesResponse;
+//# sourceMappingURL=typeGuards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,sBAAsB,CA0BhC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,0BAA0B,CA0BpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",

package/dist/index-BIUpDTdr.cjs

@@ -1 +0,0 @@
-"use strict";var O=Object.defineProperty;var f=(t,e,E)=>e in t?O(t,e,{enumerable:!0,configurable:!0,writable:!0,value:E}):t[e]=E;var L=(t,e,E)=>f(t,typeof e!="symbol"?e+"":e,E);const n="https://api.figma.com",h=`${n}/v1/files`,p=t=>`/v1/files/${t}/variables/published`,S=t=>`/v1/files/${t}/variables`,D=t=>`${h}/${t}/variables/local`,d="application/json",I="X-FIGMA-TOKEN",i="A Figma API token is required.",G=`${i} and file key are required.`,u="Failed to perform bulk update.",m="Failed to create Figma variable.",P="Failed to delete Figma variable.",N="Failed to update Figma variable.",l="An error occurred while fetching data from the Figma API.";class o extends Error{constructor(E,s){super(E);L(this,"statusCode");this.name="FigmaApiError",this.statusCode=s,Error.captureStackTrace&&Error.captureStackTrace(this,o)}}async function B(t,e){if(!e)throw new Error(i);const E=t.startsWith("http://")||t.startsWith("https://")?t:`${n}${t.startsWith("/")?"":"/"}${t}`,s=await fetch(E,{method:"GET",headers:{[I]:e,"Content-Type":d}});if(!s.ok){let A=l;const T=s.status;try{const a=s.headers.get("content-type");if(a!=null&&a.includes("application/json")){const _=await s.json();_!=null&&_.message?A=_.message:_!=null&&_.err&&(A=_.err)}}catch{}throw new o(A,T)}return s.json()}async function U(t,e,E,s){if(!e)throw new Error(i);const a={method:{CREATE:"POST",UPDATE:"PUT",DELETE:"DELETE"}[E],headers:{"Content-Type":"application/json",[I]:e}};s&&(a.body=JSON.stringify(s));const _=t.startsWith("http://")||t.startsWith("https://")?t:`${n}${t.startsWith("/")?"":"/"}${t}`,r=await fetch(_,a);if(!r.ok){const M=r.status;let R="An API error occurred";try{const c=r.headers.get("content-type");if(c!=null&&c.includes("application/json")){const F=await r.json();R=F.err||F.message||R}}catch{}throw new o(R,M)}return r.status===204||!r.body?{}:r.json()}function g(t,e){return t.filter(E=>{let s=!0;return e.resolvedType&&(s=s&&E.resolvedType===e.resolvedType),e.name&&(s=s&&E.name.includes(e.name)),s})}exports.CONTENT_TYPE_JSON=d;exports.ERROR_MSG_BULK_UPDATE_FAILED=u;exports.ERROR_MSG_CREATE_VARIABLE_FAILED=m;exports.ERROR_MSG_DELETE_VARIABLE_FAILED=P;exports.ERROR_MSG_FETCH_FIGMA_DATA_FAILED=l;exports.ERROR_MSG_TOKEN_FILE_KEY_REQUIRED=G;exports.ERROR_MSG_TOKEN_REQUIRED=i;exports.ERROR_MSG_UPDATE_VARIABLE_FAILED=N;exports.FIGMA_API_BASE_URL=n;exports.FIGMA_FILES_ENDPOINT=h;exports.FIGMA_FILE_VARIABLES_PATH=S;exports.FIGMA_LOCAL_VARIABLES_ENDPOINT=D;exports.FIGMA_PUBLISHED_VARIABLES_PATH=p;exports.FIGMA_TOKEN_HEADER=I;exports.FigmaApiError=o;exports.fetcher=B;exports.filterVariables=g;exports.mutator=U;

package/dist/index-Cd4HQQHO.js

@@ -1,94 +0,0 @@
-var I = Object.defineProperty;
-var T = (t, s, a) => s in t ? I(t, s, { enumerable: !0, configurable: !0, writable: !0, value: a }) : t[s] = a;
-var l = (t, s, a) => T(t, typeof s != "symbol" ? s + "" : s, a);
-const A = "https://api.figma.com", F = `${A}/v1/files`, M = (t) => `/v1/files/${t}/variables/published`, O = (t) => `/v1/files/${t}/variables`, S = (t) => `${F}/${t}/variables/local`, u = "application/json", p = "X-FIGMA-TOKEN", h = "A Figma API token is required.", g = `${h} and file key are required.`, D = "Failed to perform bulk update.", G = "Failed to create Figma variable.", P = "Failed to delete Figma variable.", w = "Failed to update Figma variable.", m = "An error occurred while fetching data from the Figma API.";
-class E extends Error {
-  constructor(a, e) {
-    super(a);
-    /** HTTP status code from the API response. */
-    l(this, "statusCode");
-    this.name = "FigmaApiError", this.statusCode = e, Error.captureStackTrace && Error.captureStackTrace(this, E);
-  }
-}
-async function y(t, s) {
-  if (!s)
-    throw new Error(h);
-  const a = t.startsWith("http://") || t.startsWith("https://") ? t : `${A}${t.startsWith("/") ? "" : "/"}${t}`, e = await fetch(a, {
-    method: "GET",
-    headers: {
-      [p]: s,
-      "Content-Type": u
-    }
-  });
-  if (!e.ok) {
-    let i = m;
-    const d = e.status;
-    try {
-      const n = e.headers.get("content-type");
-      if (n != null && n.includes("application/json")) {
-        const o = await e.json();
-        o != null && o.message ? i = o.message : o != null && o.err && (i = o.err);
-      }
-    } catch {
-    }
-    throw new E(i, d);
-  }
-  return e.json();
-}
-async function C(t, s, a, e) {
-  if (!s)
-    throw new Error(h);
-  const n = {
-    method: {
-      CREATE: "POST",
-      UPDATE: "PUT",
-      DELETE: "DELETE"
-    }[a],
-    headers: {
-      "Content-Type": "application/json",
-      [p]: s
-    }
-  };
-  e && (n.body = JSON.stringify(e));
-  const o = t.startsWith("http://") || t.startsWith("https://") ? t : `${A}${t.startsWith("/") ? "" : "/"}${t}`, r = await fetch(o, n);
-  if (!r.ok) {
-    const f = r.status;
-    let c = "An API error occurred";
-    try {
-      const _ = r.headers.get("content-type");
-      if (_ != null && _.includes("application/json")) {
-        const R = await r.json();
-        c = R.err || R.message || c;
-      }
-    } catch {
-    }
-    throw new E(c, f);
-  }
-  return r.status === 204 || !r.body ? {} : r.json();
-}
-function N(t, s) {
-  return t.filter((a) => {
-    let e = !0;
-    return s.resolvedType && (e = e && a.resolvedType === s.resolvedType), s.name && (e = e && a.name.includes(s.name)), e;
-  });
-}
-export {
-  u as C,
-  h as E,
-  O as F,
-  g as a,
-  M as b,
-  E as c,
-  N as d,
-  A as e,
-  y as f,
-  F as g,
-  S as h,
-  p as i,
-  D as j,
-  G as k,
-  P as l,
-  C as m,
-  w as n,
-  m as o
-};