Add the folders endpoints (replacing the deprecated projects endpoints)

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Added the folders endpoints: `getTeamFolders`, `getFolderFolders`, `getFolderFiles` and `getFolderMeta`
+- Added `API_VER_FOLDERS` config constant
+
+### Changed
+- Bumped the `@figma/rest-api-spec` floor to `0.42.0` (was `0.37.0`), the release that added the folders types
+
+### Deprecated
+- Marked `getTeamProjects` and `getProjectFiles` as deprecated. Figma deprecated the underlying `/v1/teams/:team_id/projects` and `/v1/projects/:project_id/files` endpoints in August 2026, and personal access tokens can no longer be granted the `files:read` scope they require, so they now fail with `403 Invalid scope`. Folder IDs are the same values as project IDs and the response shapes are unchanged.
+
+
 ## [v2.2.1-beta] - 2026-06-29
 
 ### Changed

README.md

@@ -138,8 +138,29 @@ See: https://www.figma.com/developers/api#version-history-endpoints
 
 See: https://www.figma.com/developers/api#projects-endpoints
 
-- `Api.getTeamProjects(pathParams)`
-- `Api.getProjectFiles(pathParams,queryParams)`
+> [!WARNING]
+> These endpoints were deprecated by Figma in August 2026 in favour of the folders endpoints below. Personal access tokens created now cannot be granted the `files:read` scope they require, so they return `403 Invalid scope`. Use the folders endpoints instead.
+
+- `Api.getTeamProjects(pathParams)` — deprecated, use `Api.getTeamFolders(pathParams)`
+- `Api.getProjectFiles(pathParams,queryParams)` — deprecated, use `Api.getFolderFiles(pathParams,queryParams)`
+
+#### Folders
+
+See: https://www.figma.com/developers/api#folders-endpoints
+
+These replace the projects endpoints above and require the `folders:read` scope (`folder_metadata:read` for `getFolderMeta`). Folder IDs are the same values as the old project IDs, and the responses keep the same shape, so migrating is a one-line change:
+
+```ts
+// before
+const project = await api.getProjectFiles({ project_id: '12345678' });
+// after
+const folder = await api.getFolderFiles({ folder_id: '12345678' });
+```
+
+- `Api.getTeamFolders(pathParams)`
+- `Api.getFolderFolders(pathParams)`
+- `Api.getFolderFiles(pathParams,queryParams)`
+- `Api.getFolderMeta(pathParams)`
 
 #### Components and Styles (Library Items)