Updates for Beta: Adding scopes and removing unsupported methods (#99)

Author: RodneyU215

.github/workflows/semgrep.yml

@@ -3,13 +3,13 @@ on:
   pull_request: {}
   push:
     branches:
-    - main
-    - master
+      - main
+      - master
     paths:
-    - .github/workflows/semgrep.yml
+      - .github/workflows/semgrep.yml
   schedule:
-  # random HH:MM to avoid a load spike on GitHub Actions at 00:00
-  - cron: 34 11 * * *
+    # random HH:MM to avoid a load spike on GitHub Actions at 00:00
+    - cron: 34 11 * * *
 name: Semgrep
 jobs:
   semgrep:
@@ -20,5 +20,5 @@ jobs:
     container:
       image: returntocorp/semgrep
     steps:
-    - uses: actions/checkout@v3
-    - run: semgrep ci
+      - uses: actions/checkout@v3
+      - run: semgrep ci

README.md

@@ -38,6 +38,41 @@ const webflow = new Webflow({
 });
 ```
 
+## Transitioning to API v2
+
+We're actively working on a new version of the SDK that will fully support API v2. In the meantime, to make use of API v2 with our SDK, there are some important changes you need to be aware of:
+
+### Setting Up For API v2
+
+When initializing your client, it's crucial to set the `beta` flag to true in the client options. This ensures you're targeting the API v2 endpoints.
+
+```javascript
+const webflow = new Webflow({ beta: true, ...otherOptions });
+```
+
+Please note, when the beta flag is set, several built-in methods will not be available. These methods include, but are not limited to, info, authenticatedUser, sites, site, etc. Attempting to use these will throw an error.
+
+### Calling API v2 Endpoints
+
+To interact with API v2, you'll need to move away from using built-in methods, and instead use the provided HTTP methods directly.
+
+For instance, where you previously used `sites()`:
+
+```javascript
+// get the first site
+const [site] = await webflow.sites();
+```
+
+For API v2, you will need to use direct HTTP methods:
+
+```javascript
+// get the first site
+const sites = await webflow.get("/sites");
+const site = sites[0];
+```
+
+We understand that this is a shift in how you interact with the SDK, but rest assured, our upcoming SDK version will streamline this process and offer a more integrated experience with API v2.
+
 ## Basic Usage
 
 ### Chaining Calls
@@ -131,6 +166,20 @@ const url = webflow.authorizeUrl({
 res.redirect(url);
 ```
 
+### Using the scopes Parameter with v2 API
+
+The v2 API introduces the concept of 'scopes', providing more control over app permissions. Instead of using the scope parameter as a single string, you can define multiple permissions using the scopes array:
+
+```javascript
+const url = webflow.authorizeUrl({
+  client_id: "[CLIENT ID]",
+  redirect_uri: "https://my.server.com/oauth/callback",
+  scopes: ["read:sites", "write:items", "read:users"],
+});
+```
+
+For more information and a detailed list of available scopes, refer to our Scopes Guide.
+
 ### Access Token
 
 Once a user has authorized their Webflow resource(s), Webflow will redirect back to your server with a `code`. Use this to get an access token.

src/api/oauth.ts

@@ -1,12 +1,13 @@
 import { AxiosInstance } from "axios";
-import { requireArgs } from "../core";
+import { requireArgs, SupportedScope } from "../core";
 
 /**************************************************************
  * Interfaces
  **************************************************************/
 export interface IAuthorizeUrlParams {
   state?: string;
   scope?: string;
+  scopes?: SupportedScope[];
   client_id: string;
   redirect_uri?: string;
   response_type?: string;
@@ -52,15 +53,20 @@ export class OAuth {
    * @returns The URL to authorize a user
    */
   static authorizeUrl(
-    { response_type = "code", redirect_uri, client_id, state, scope }: IAuthorizeUrlParams,
+    { response_type = "code", redirect_uri, client_id, state, scope, scopes }: IAuthorizeUrlParams,
     client: AxiosInstance,
   ) {
     requireArgs({ client_id });
 
+    if (scope && scopes) {
+      throw new Error("Please provide either 'scope' or 'scopes', but not both.");
+    }
+
     const params = { response_type, client_id };
     if (redirect_uri) params["redirect_uri"] = redirect_uri;
     if (state) params["state"] = state;
     if (scope) params["scope"] = scope;
+    if (scopes && scopes.length > 0) params["scope"] = scopes.join("+");
 
     const url = "/oauth/authorize";
     const baseURL = client.defaults.baseURL.replace("api.", "");

src/core/webflow.ts

@@ -22,8 +22,51 @@ export interface Options {
   token?: string;
   version?: string;
   headers?: Record<string, string>;
+  beta?: boolean;
 }
 
+type MethodNames =
+  | "info"
+  | "authenticatedUser"
+  | "sites"
+  | "site"
+  | "publishSite"
+  | "domains"
+  | "collections"
+  | "collection"
+  | "items"
+  | "item"
+  | "createItem"
+  | "updateItem"
+  | "patchItem"
+  | "removeItem"
+  | "deleteItems"
+  | "publishItems";
+
+export const SCOPES_ARRAY = [
+  "assets:read",
+  "assets:write",
+  "authorized_user:read",
+  "cms:read",
+  "cms:write",
+  "custom_code:read",
+  "custom_code:write",
+  "forms:read",
+  "forms:write",
+  "pages:read",
+  "pages:write",
+  "sites:read",
+  "sites:write",
+  "users:read",
+  "users:write",
+  "ecommerce:read",
+  "ecommerce:write",
+] as const;
+
+export type SupportedScope = typeof SCOPES_ARRAY[number];
+
+type ParamValueType = string | number | boolean | null | undefined;
+
 /**************************************************************
  * Class
  **************************************************************/
@@ -32,6 +75,43 @@ export class Webflow {
   constructor(public options: Options = {}) {
     this.client = axios.create(this.config);
     this.client.interceptors.response.use(ErrorInterceptor);
+
+    if (this.options.beta) {
+      this.removeNonBetaMethods();
+    }
+  }
+
+  private removeNonBetaMethods() {
+    const methodsToRemove: MethodNames[] = [
+      "info",
+      "authenticatedUser",
+      "sites",
+      "site",
+      "publishSite",
+      "domains",
+      "collections",
+      "collection",
+      "items",
+      "item",
+      "createItem",
+      "updateItem",
+      "patchItem",
+      "removeItem",
+      "deleteItems",
+      "publishItems",
+    ];
+
+    methodsToRemove.forEach((method) => {
+      Object.defineProperty(this, method, {
+        value: function (): never {
+          throw new Error(
+            `The method '${method}()' is not available in beta mode. Please disable the beta option to use this method.`,
+          );
+        },
+        enumerable: false,
+        configurable: true,
+      });
+    });
   }
 
   // Set the Authentication token
@@ -46,10 +126,11 @@ export class Webflow {
 
   // The Axios configuration
   get config() {
-    const { host = DEFAULT_HOST, token, version, headers } = this.options;
+    const { host = DEFAULT_HOST, token, version, headers, beta = false } = this.options;
+    const effectiveHost = beta ? "webflow.com/beta" : host;
 
     const config: AxiosRequestConfig = {
-      baseURL: `https://api.${host}/`,
+      baseURL: `https://api.${effectiveHost}/`,
       headers: {
         "Content-Type": "application/json",
         "User-Agent": USER_AGENT,
@@ -63,6 +144,32 @@ export class Webflow {
     // Add the Authorization header if a token is set
     if (token) config.headers.Authorization = `Bearer ${token}`;
 
+    config.paramsSerializer = {
+      serialize: (params: Record<string, ParamValueType>): string => {
+        if (typeof params !== "object" || params === null) {
+          return "";
+        }
+
+        const parts: string[] = [];
+
+        for (const key in params) {
+          const value = params[key];
+          if (value === undefined) continue;
+
+          const safeValue =
+            typeof value === "string" || typeof value === "number" ? value : String(value);
+
+          if (key === "scope") {
+            parts.push(`${key}=${safeValue}`);
+          } else {
+            parts.push(`${key}=${encodeURIComponent(safeValue)}`);
+          }
+        }
+
+        return parts.join("&");
+      },
+    };
+
     return config;
   }
 

tests/core/webflow.test.ts

@@ -1,6 +1,6 @@
 import axios from "axios";
 import MockAdapter from "axios-mock-adapter";
-import { Webflow, RequestError } from "../../src/core";
+import { Webflow, RequestError, SupportedScope } from "../../src/core";
 import {
   MetaFixture,
   SiteFixture,
@@ -108,6 +108,24 @@ describe("Webflow", () => {
         expect(url).toBe(`https://${options.host}/oauth/authorize?${query.toString()}`);
       });
 
+      it("should generate an authorization url with valid scopes", () => {
+        const { parameters } = OAuthFixture.authorize;
+        const { client_id, state, response_type } = parameters;
+        const scopes: SupportedScope[] = ["assets:read", "cms:write"];
+
+        const url = webflow.authorizeUrl({ client_id, state, scopes });
+        const queryParts = [
+          `response_type=${response_type}`,
+          `client_id=${client_id}`,
+          `state=${state}`,
+          `scope=${scopes.join("+")}`,
+        ];
+        const query = queryParts.join("&");
+
+        expect(url).toBeDefined();
+        expect(url).toBe(`https://${options.host}/oauth/authorize?${query}`);
+      });
+
       it("should generate an access token", async () => {
         const { parameters, response, path } = OAuthFixture.access_token;