Add the folders endpoints (replacing the deprecated projects endpoints)

[JWMarchant]

Problem

Figma deprecated the projects endpoints in August 2026 in favour of folders, and the files:read scope they require is no longer offered when creating a personal access token — the picker only exposes the granular scopes now. The result is that getProjectFiles and getTeamProjects fail for any token created today:

GET /v1/projects/{id}/files
403 {"error":true,"status":403,"message":"Invalid scope: [\"current_user:read\", \"file_comments:read\",
     \"file_comments:write\", \"file_content:read\", \"file_metadata:read\", ..., \"folders:read\", ...].
     This endpoint requires the file_read or files:read or projects:read scope."}

That token has every scope the UI offers, folders:read included. There is currently no way to list the files in a project using this library with a new token.

What this adds

Method	Endpoint	Scope
getTeamFolders	GET /v2/teams/:team_id/folders	folders:read
getFolderFolders	GET /v2/folders/:folder_id/folders	folders:read
getFolderFiles	GET /v2/folders/:folder_id/files	folders:read
getFolderMeta	GET /v2/folders/:folder_id/meta	folder_metadata:read

Folder IDs are the same values as project IDs and the response shapes are unchanged, so migrating is a rename:

// before
const project = await api.getProjectFiles({ project_id: '12345678' });
// after
const folder = await api.getFolderFiles({ folder_id: '12345678' });

Notes

• @figma/rest-api-spec floor moved to 0.42.0 (was 0.37.0). The folders types first appear in 0.42.0 — I checked 0.38–0.41 and none of them have GetFolderFilesResponse. The existing range would have resolved to a spec without them.
• The projects endpoints are deprecated, not removed. They still work for anyone holding an older token, so they're marked with a @deprecated comment and a README warning pointing at the replacements.
• API_VER_FOLDERS added to config.ts rather than inlining v2, matching how API_VER_WEBHOOKS is handled.
• lib/ is rebuilt in its own commit so the generated diff doesn't bury the source review.

Verification

tsc --noEmit clean, npm test 53/53 passing (8 new). Checked against the live API with a real token:

getFolderFiles    OK    "B&Q" 25 files, first: B&Q E1
getFolderFiles+q  OK    "Aardy" 10 files          (branch_data query param)
getFolderMeta     401   Missing credentials       (token lacks folder_metadata:read)
getProjectFiles   403   Invalid scope: [...]      (the deprecated method)

getFolderMeta's 401 is the token's missing scope, not the URL — that endpoint needs folder_metadata:read, which isn't offered alongside the others.

Commits

Bump @figma/rest-api-spec floor to 0.42.0                       package.json, package-lock.json
Add the folders endpoints                                       src/ (3), tests/ (3)
Document the folders endpoints and deprecate the projects ones  README.md, CHANGELOG.md
Re-generated library after changes                              lib/ (3)

CHANGELOG.md entry is under ## [Unreleased] — happy to move it under a version heading if you'd rather set that here.

🤖 Generated with Claude Code