docs: update CHANGELOG and README for v4.0.0 release #17

marklearst · 2025-12-30T01:17:11Z

BREAKING CHANGE: useFigmaToken changed from default to named export

CHANGELOG 4.0.0:

Breaking: useFigmaToken is now a named export
New: withRetry() utility for automatic retry with exponential backoff
New: redactToken() utility for safe token logging
New: baseUrl option for fetcher/mutator
New: caseInsensitive option for filterVariables()
Fix: SWR cache keys correctly separate fallback and live data
Fix: Improved error parsing for non-JSON API responses
Docs: Comprehensive mutation return type documentation

README updates:

Reorganized badges into clean 3-column table (Package/Quality/Activity)
Added npm version, bundle size, node version badges
Updated 'Why 4.0.0' section highlighting new features
Added migration guide section (3.x → 4.0)
Updated API cheat sheet with new utilities
Added withRetry example to rate limits section
Added redactToken example to security section
Updated release checklist for 4.0.0

Also added 3.1.1 changelog entry for minor doc update

BREAKING CHANGE: useFigmaToken changed from default to named export CHANGELOG 4.0.0: - Breaking: useFigmaToken is now a named export - New: withRetry() utility for automatic retry with exponential backoff - New: redactToken() utility for safe token logging - New: baseUrl option for fetcher/mutator - New: caseInsensitive option for filterVariables() - Fix: SWR cache keys correctly separate fallback and live data - Fix: Improved error parsing for non-JSON API responses - Docs: Comprehensive mutation return type documentation README updates: - Reorganized badges into clean 3-column table (Package/Quality/Activity) - Added npm version, bundle size, node version badges - Updated 'Why 4.0.0' section highlighting new features - Added migration guide section (3.x → 4.0) - Updated API cheat sheet with new utilities - Added withRetry example to rate limits section - Added redactToken example to security section - Updated release checklist for 4.0.0 Also added 3.1.1 changelog entry for minor doc update

codecov · 2025-12-30T01:18:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.37%. Comparing base (85fb384) to head (7f011d2).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #17   +/-   ##
=======================================
  Coverage   91.37%   91.37%           
=======================================
  Files          36       36           
  Lines         986      986           
  Branches      284      284           
=======================================
  Hits          901      901           
  Misses         84       84           
  Partials        1        1

Flag	Coverage Δ
unittests	`91.37% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This PR prepares the documentation for the v4.0.0 release, introducing new utilities for retry logic and token redaction, along with API flexibility improvements. The documentation updates include a reorganized badge table, comprehensive CHANGELOG entry, migration guide, and updated examples throughout the README.

Key changes:

Breaking change documentation for useFigmaToken export change (default → named)
New utilities: withRetry(), redactToken(), caseInsensitive filtering, and baseUrl API option
Enhanced error handling documentation and SWR caching bug fix notes

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 13 comments.

File	Description
CHANGELOG.md	Added comprehensive 4.0.0 release notes with breaking changes, new features, bug fixes, and migration guide; added 3.1.1 entry
README.md	Reorganized badges into 3-column table, updated version references to 4.0.0, added new utility examples, updated API cheat sheet, and added migration guide section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-30T01:22:35Z

README.md

+- Use `withRetry()` utility for automatic retry with exponential backoff on 429 errors:
+
+```ts
+import { withRetry, fetcher } from '@figma-vars/hooks'


The import import { withRetry, fetcher } from '@figma-vars/hooks' will fail. withRetry is not exported from the main package entry point (src/index.ts), and fetcher is only available from '@figma-vars/hooks/core'. The correct import should be import { fetcher } from '@figma-vars/hooks/core' and import { withRetry } from '@figma-vars/hooks/utils' (or add these to main exports).

Suggested change

import { withRetry, fetcher } from '@figma-vars/hooks'

import { fetcher } from '@figma-vars/hooks/core'

import { withRetry } from '@figma-vars/hooks/utils'

Copilot · 2025-12-30T01:22:35Z

CHANGELOG.md

+redactToken('figd_abc123xyz789secret')
+// Returns: 'figd_***...***cret'


The example output is incorrect. According to the actual implementation in src/utils/redactToken.ts, redactToken('figd_abc123xyz789secret') would return 'figd_***...ret' (showing 5 chars at start and 3 at end by default), not 'figd_...***cret' (4 chars at end). The default visibleEnd is 3, not 4.

Copilot · 2025-12-30T01:22:35Z

CHANGELOG.md

+**Options:**
+
+- `prefixLength` - Characters to show at start (default: 5)
+- `suffixLength` - Characters to show at end (default: 5)
+- `redactionString` - Replacement string (default: `'***...***'`)


The parameter names are incorrect. According to the actual implementation in src/utils/redactToken.ts, the options are named visibleStart and visibleEnd, not prefixLength and suffixLength. Also, there is no redactionString option in the actual implementation.

Copilot · 2025-12-30T01:22:36Z

CHANGELOG.md

+**Options:**
+
+- `prefixLength` - Characters to show at start (default: 5)
+- `suffixLength` - Characters to show at end (default: 5)


The default value for suffixLength is incorrect. According to the actual implementation in src/utils/redactToken.ts, the default visibleEnd is 3, not 5. The documentation should say "Characters to show at end (default: 3)".

Suggested change

- `suffixLength` - Characters to show at end (default: 5)

- `suffixLength` - Characters to show at end (default: 3)

Copilot · 2025-12-30T01:22:36Z

README.md

+const fetchWithRetry = withRetry(() => myApiCall(), { maxRetries: 3 })
+
+// Safe token logging
+console.log('Token:', redactToken(token)) // "figd_***...***cret"


The example output is incorrect. According to the actual implementation in src/utils/redactToken.ts, redactToken would return 'figd_***...ret' (showing 5 chars at start and 3 at end by default), not 'figd_...***cret' (4 chars at end). The default visibleEnd is 3, not 4.

Suggested change

console.log('Token:', redactToken(token)) // "figd_***...***cret"

console.log('Token:', redactToken(token)) // "figd_***...***ret"

Copilot · 2025-12-30T01:22:37Z

README.md

+
+// Safe logging
+console.log('Using token:', redactToken(token))
+// Output: "Using token: figd_***...***cret"


The example output is incorrect. According to the actual implementation in src/utils/redactToken.ts, redactToken would return 'figd_***...ret' (showing 5 chars at start and 3 at end by default), not 'figd_...***cret' (4 chars at end). The default visibleEnd is 3, not 4.

Suggested change

// Output: "Using token: figd_***...***cret"

// Output: "Using token: figd_***...***ret"

Copilot · 2025-12-30T01:22:37Z

CHANGELOG.md

+// Returns: 'figd_***...***cret'
+
+redactToken('short', { prefixLength: 2, suffixLength: 2 })
+// Returns: '***...***' (too short, fully redacted)


The example is misleading. The token 'short' (5 characters) with prefixLength: 2, suffixLength: 2 would require 5 characters minimum (2+2+1), so it would be fully masked as '' (5 asterisks), not '...*'. The actual implementation masks short tokens with asterisks matching the token length, not using the redaction string.

Suggested change

// Returns: '***...***' (too short, fully redacted)

// Returns: '*****' (too short, fully redacted)

Copilot · 2025-12-30T01:22:37Z

README.md

+```tsx
+// Before (3.x) - NO LONGER WORKS
+import useFigmaToken from '@figma-vars/hooks'
+
+// After (4.0) - USE THIS
+import { useFigmaToken } from '@figma-vars/hooks'
+```


The migration guide assumes useFigmaToken is exported from the main package, but it's not present in src/index.ts. Users following this guide will get an import error. Either add useFigmaToken to the exports in src/index.ts line 57-67, or clarify in the documentation that this hook is not part of the public API.

Copilot · 2025-12-30T01:22:38Z

README.md

+- **Filtering**: `filterVariables` (filter by type, name, with optional `caseInsensitive` matching)
+- **Retry**: `withRetry` (automatic retry with exponential backoff for rate limits)
+- **Security**: `redactToken` (safely redact tokens for logging/display)
+- **Error Handling**: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`, `isRateLimited`, `getRetryAfter`


The new error handling utilities isRateLimited and getRetryAfter are documented in the API cheat sheet but are not exported from the main package entry point (src/index.ts). These should be added to the exports at lines 86-92 for users to access them.

Suggested change

- **Error Handling**: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`, `isRateLimited`, `getRetryAfter`

- **Error Handling**: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`

Copilot · 2025-12-30T01:22:38Z

README.md

+### New Utilities (opt-in)
+
+```ts
+import { withRetry, redactToken, filterVariables } from '@figma-vars/hooks'


The import statement import { withRetry, redactToken, filterVariables } from '@figma-vars/hooks' will fail because withRetry and redactToken are not exported from the main package entry point (src/index.ts). Users need to either import from '@figma-vars/hooks/utils' or these utilities need to be added to the main exports.

Suggested change

import { withRetry, redactToken, filterVariables } from '@figma-vars/hooks'

import { filterVariables } from '@figma-vars/hooks'

import { withRetry, redactToken } from '@figma-vars/hooks/utils'

Copilot AI review requested due to automatic review settings December 30, 2025 01:17

Copilot started reviewing on behalf of marklearst December 30, 2025 01:17 View session

marklearst merged commit ab12009 into main Dec 30, 2025
8 checks passed

Copilot AI reviewed Dec 30, 2025

View reviewed changes

	import { withRetry, fetcher } from '@figma-vars/hooks'
	import { fetcher } from '@figma-vars/hooks/core'
	import { withRetry } from '@figma-vars/hooks/utils'

		redactToken('figd_abc123xyz789secret')
		// Returns: 'figd_*...*cret'

	- `suffixLength` - Characters to show at end (default: 5)
	- `suffixLength` - Characters to show at end (default: 3)

	console.log('Token:', redactToken(token)) // "figd_*...*cret"
	console.log('Token:', redactToken(token)) // "figd_*...*ret"

	// Output: "Using token: figd_*...*cret"
	// Output: "Using token: figd_*...*ret"

	// Returns: '*...*' (too short, fully redacted)
	// Returns: '*****' (too short, fully redacted)

	- Error Handling: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`, `isRateLimited`, `getRetryAfter`
	- Error Handling: `isFigmaApiError`, `getErrorStatus`, `getErrorMessage`, `hasErrorStatus`

	import { withRetry, redactToken, filterVariables } from '@figma-vars/hooks'
	import { filterVariables } from '@figma-vars/hooks'
	import { withRetry, redactToken } from '@figma-vars/hooks/utils'

Uh oh!

docs: update CHANGELOG and README for v4.0.0 release #17

docs: update CHANGELOG and README for v4.0.0 release #17

Uh oh!

Conversation

marklearst commented Dec 30, 2025

Uh oh!

codecov bot commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 30, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

codecov bot commented Dec 30, 2025 •

edited

Loading