webflow-api 1.2.2 → 1.3.1

package/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.
@@ -176,7 +225,7 @@ Get all sites available or lookup by site id.
 const sites = await webflow.sites();
 
 // Get a single site
-const site = await webflow.sites({ siteId: "[SITE ID]" });
+const site = await webflow.site({ siteId: "[SITE ID]" });
 ```
 
 ### Collections

package/dist/api/collection.d.ts

@@ -12,7 +12,7 @@ export declare type CollectionField = {
     name: string;
     required: boolean;
     editable: boolean;
-    validations?: Record<string, string | number | boolean | object>;
+    validations?: Record<string, any>;
 };
 /**************************************************************
  * Interfaces

package/dist/api/item.d.ts

@@ -31,7 +31,7 @@ export interface IDeletedItems {
 /**************************************************************
  * Types
  **************************************************************/
-export declare type PageinatedItems = PaginatedData & {
+export declare type PaginatedItems = PaginatedData & {
     items: IItem[];
 };
 /**************************************************************
@@ -64,7 +64,7 @@ export declare class Item extends WebflowRecord<IItem> implements IItem {
     static getOne({ collectionId, itemId }: {
         collectionId: string;
         itemId: string;
-    }, client: AxiosInstance): Promise<import("axios").AxiosResponse<PageinatedItems, any>>;
+    }, client: AxiosInstance): Promise<import("axios").AxiosResponse<PaginatedItems, any>>;
     /**
      * Get a list of Items
      * @param params The params for the request
@@ -78,7 +78,7 @@ export declare class Item extends WebflowRecord<IItem> implements IItem {
         collectionId: string;
         limit?: number;
         offset?: number;
-    }, client: AxiosInstance): Promise<import("axios").AxiosResponse<PageinatedItems, any>>;
+    }, client: AxiosInstance): Promise<import("axios").AxiosResponse<PaginatedItems, any>>;
     /**
      * Create a new Item
      * @param params The params for the request
@@ -132,7 +132,7 @@ export declare class Item extends WebflowRecord<IItem> implements IItem {
         collectionId: string;
     }, client: AxiosInstance): Promise<import("axios").AxiosResponse<IItemDelete, any>>;
     /**
-     * Unpublishes a list of Items
+     * Unpublish a list of Items
      * @param params The params for the request
      * @param params.collectionId The Collection ID
      * @param params.live Unpublish from the live site

package/dist/api/item.js

@@ -93,7 +93,7 @@ class Item extends core_1.WebflowRecord {
         return client.delete(path);
     }
     /**
-     * Unpublishes a list of Items
+     * Unpublish a list of Items
      * @param params The params for the request
      * @param params.collectionId The Collection ID
      * @param params.live Unpublish from the live site

package/dist/api/meta.d.ts

@@ -21,7 +21,7 @@ export interface IAuthenticatedUser {
         _id: string;
     };
 }
-export interface IAuthentiationInfo {
+export interface IAuthenticationInfo {
     application: InfoApplication;
     workspaces: string[];
     rateLimit: number;
@@ -43,7 +43,7 @@ export declare class Meta {
      * @param client The Axios client instance
      * @returns The authentication info
      */
-    static info(client: AxiosInstance): Promise<import("axios").AxiosResponse<IAuthentiationInfo, any>>;
+    static info(client: AxiosInstance): Promise<import("axios").AxiosResponse<IAuthenticationInfo, any>>;
     /**
      * Get the authenticated user
      * @param client The Axios client instance

package/dist/api/oauth.d.ts

@@ -1,10 +1,12 @@
 import { AxiosInstance } from "axios";
+import { SupportedScope } from "../core";
 /**************************************************************
  * Interfaces
  **************************************************************/
 export interface IAuthorizeUrlParams {
     state?: string;
     scope?: string;
+    scopes?: SupportedScope[];
     client_id: string;
     redirect_uri?: string;
     response_type?: string;
@@ -43,7 +45,7 @@ export declare class OAuth {
      * @param client The Axios client instance
      * @returns The URL to authorize a user
      */
-    static authorizeUrl({ response_type, redirect_uri, client_id, state, scope }: IAuthorizeUrlParams, client: AxiosInstance): string;
+    static authorizeUrl({ response_type, redirect_uri, client_id, state, scope, scopes }: IAuthorizeUrlParams, client: AxiosInstance): string;
     /**
      * Get an access token
      * @param params The params for the request

package/dist/api/oauth.js

@@ -17,8 +17,11 @@ class OAuth {
      * @param client The Axios client instance
      * @returns The URL to authorize a user
      */
-    static authorizeUrl({ response_type = "code", redirect_uri, client_id, state, scope }, client) {
+    static authorizeUrl({ response_type = "code", redirect_uri, client_id, state, scope, scopes }, client) {
         (0, core_1.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;
@@ -26,6 +29,8 @@ class OAuth {
             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.", "");
         return client.getUri({ baseURL, url, method: "GET", params });

package/dist/core/error.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorInterceptor = exports.requireArgs = exports.ArgumentError = exports.RequestError = void 0;
 class RequestError extends Error {
     constructor(error) {
-        super(error.err ? error.err : "Unknown error occured");
+        super(error.err ? error.err : "Unknown error occurred");
         Object.assign(this, error);
     }
 }

package/dist/core/webflow.d.ts

@@ -8,7 +8,10 @@ export interface Options {
     token?: string;
     version?: string;
     headers?: Record<string, string>;
+    beta?: boolean;
 }
+export declare const SCOPES_ARRAY: readonly ["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"];
+export declare type SupportedScope = typeof SCOPES_ARRAY[number];
 /**************************************************************
  * Class
  **************************************************************/
@@ -16,6 +19,7 @@ export declare class Webflow {
     options: Options;
     private client;
     constructor(options?: Options);
+    private removeNonBetaMethods;
     set token(value: string);
     clearToken(): void;
     get config(): AxiosRequestConfig<any>;
@@ -101,7 +105,7 @@ export declare class Webflow {
      * Get the current authorization information
      * @returns The authorization information
      */
-    info(): Promise<import("../api").IAuthentiationInfo>;
+    info(): Promise<import("../api").IAuthenticationInfo>;
     /**
      * Get the current authenticated user
      * @returns The current authenticated user
@@ -236,7 +240,7 @@ export declare class Webflow {
         collectionId: string;
     }): Promise<import("../api").IItemDelete>;
     /**
-     * Upublish a Collection Item
+     * Unpublish a Collection Item
      * @param params The Item information
      * @param params.collectionId The Collection ID
      * @param params.itemId The Item ID
@@ -374,7 +378,7 @@ export declare class Webflow {
      * @param params.siteId The Site Id
      * @param params.url The Url the Webhook should call on events
      * @param params.triggerType The type of event that should trigger the Webhook
-     * @param params.filter The filter to apply to the Webhook (form_submssion only)
+     * @param params.filter The filter to apply to the Webhook (form_submission only)
      * @returns The created webhook
      */
     createWebhook({ url, siteId, triggerType, filter, }: {

package/dist/core/webflow.js

@@ -3,12 +3,31 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Webflow = exports.USER_AGENT = exports.DEFAULT_HOST = void 0;
+exports.Webflow = exports.SCOPES_ARRAY = exports.USER_AGENT = exports.DEFAULT_HOST = void 0;
 const axios_1 = __importDefault(require("axios"));
 const core_1 = require("../core");
 const api_1 = require("../api");
 exports.DEFAULT_HOST = "webflow.com";
 exports.USER_AGENT = "Webflow Javascript SDK / 1.0";
+exports.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",
+];
 /**************************************************************
  * Class
  **************************************************************/
@@ -17,6 +36,38 @@ class Webflow {
         this.options = options;
         this.client = axios_1.default.create(this.config);
         this.client.interceptors.response.use(core_1.ErrorInterceptor);
+        if (this.options.beta) {
+            this.removeNonBetaMethods();
+        }
+    }
+    removeNonBetaMethods() {
+        const methodsToRemove = [
+            "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 () {
+                    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
     set token(value) {
@@ -28,9 +79,10 @@ class Webflow {
     }
     // The Axios configuration
     get config() {
-        const { host = exports.DEFAULT_HOST, token, version, headers } = this.options;
+        const { host = exports.DEFAULT_HOST, token, version, headers, beta = false } = this.options;
+        const effectiveHost = beta ? "webflow.com/beta" : host;
         const config = {
-            baseURL: `https://api.${host}/`,
+            baseURL: `https://api.${effectiveHost}/`,
             headers: {
                 "Content-Type": "application/json",
                 "User-Agent": exports.USER_AGENT,
@@ -43,6 +95,27 @@ class Webflow {
         // Add the Authorization header if a token is set
         if (token)
             config.headers.Authorization = `Bearer ${token}`;
+        config.paramsSerializer = {
+            serialize: (params) => {
+                if (typeof params !== "object" || params === null) {
+                    return "";
+                }
+                const parts = [];
+                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;
     }
     /**************************************************************
@@ -296,7 +369,7 @@ class Webflow {
         return res.data;
     }
     /**
-     * Upublish a Collection Item
+     * Unpublish a Collection Item
      * @param params The Item information
      * @param params.collectionId The Collection ID
      * @param params.itemId The Item ID
@@ -433,7 +506,7 @@ class Webflow {
      * @param params.siteId The Site Id
      * @param params.url The Url the Webhook should call on events
      * @param params.triggerType The type of event that should trigger the Webhook
-     * @param params.filter The filter to apply to the Webhook (form_submssion only)
+     * @param params.filter The filter to apply to the Webhook (form_submission only)
      * @returns The created webhook
      */
     async createWebhook({ url, siteId, triggerType, filter, }) {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "webflow-api",
   "description": "Webflow's official Node.js SDK for Data APIs",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "contributors": [
+    "Rodney Urquhart (https://github.com/rodneyu215)",
     "John Agan (https://github.com/johnagan)"
   ],
   "repository": {

package/src/api/collection.ts

@@ -32,7 +32,7 @@ export type CollectionField = {
   required: boolean;
   editable: boolean;
   // TODO: add a better type
-  validations?: Record<string, string | number | boolean | object>;
+  validations?: Record<string, any>;
 };
 
 /**************************************************************

package/src/api/item.ts

@@ -36,7 +36,7 @@ export interface IDeletedItems {
 /**************************************************************
  * Types
  **************************************************************/
-export type PageinatedItems = PaginatedData & {
+export type PaginatedItems = PaginatedData & {
   items: IItem[];
 };
 
@@ -77,7 +77,7 @@ export class Item extends WebflowRecord<IItem> implements IItem {
     requireArgs({ collectionId, itemId });
     const path = `/collections/${collectionId}/items/${itemId}`;
     // The API returns a paginated list with one record :(
-    return client.get<PageinatedItems>(path);
+    return client.get<PaginatedItems>(path);
   }
 
   /**
@@ -96,7 +96,7 @@ export class Item extends WebflowRecord<IItem> implements IItem {
     requireArgs({ collectionId });
     const params = { limit, offset };
     const path = `/collections/${collectionId}/items`;
-    return client.get<PageinatedItems>(path, { params });
+    return client.get<PaginatedItems>(path, { params });
   }
 
   /**
@@ -192,7 +192,7 @@ export class Item extends WebflowRecord<IItem> implements IItem {
   }
 
   /**
-   * Unpublishes a list of Items
+   * Unpublish a list of Items
    * @param params The params for the request
    * @param params.collectionId The Collection ID
    * @param params.live Unpublish from the live site

package/src/api/meta.ts

@@ -24,7 +24,7 @@ export interface IAuthenticatedUser {
   };
 }
 
-export interface IAuthentiationInfo {
+export interface IAuthenticationInfo {
   application: InfoApplication;
   workspaces: string[];
   rateLimit: number;
@@ -48,7 +48,7 @@ export class Meta {
    * @returns The authentication info
    */
   static info(client: AxiosInstance) {
-    return client.get<IAuthentiationInfo>("/info");
+    return client.get<IAuthenticationInfo>("/info");
   }
 
   /**

package/src/api/oauth.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { requireArgs } from "../core";
+import { requireArgs, SupportedScope } from "../core";
 
 /**************************************************************
  * Interfaces
@@ -7,6 +7,7 @@ import { requireArgs } from "../core";
 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.", "");

package/src/core/error.ts

@@ -16,7 +16,7 @@ export class RequestError extends Error implements IRequestError {
   err: string;
 
   constructor(error: IRequestError) {
-    super(error.err ? error.err : "Unknown error occured");
+    super(error.err ? error.err : "Unknown error occurred");
     Object.assign(this, error);
   }
 }

package/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;
   }
 
@@ -328,7 +435,7 @@ export class Webflow {
     return res.data;
   }
   /**
-   * Upublish a Collection Item
+   * Unpublish a Collection Item
    * @param params The Item information
    * @param params.collectionId The Collection ID
    * @param params.itemId The Item ID
@@ -503,7 +610,7 @@ export class Webflow {
    * @param params.siteId The Site Id
    * @param params.url The Url the Webhook should call on events
    * @param params.triggerType The type of event that should trigger the Webhook
-   * @param params.filter The filter to apply to the Webhook (form_submssion only)
+   * @param params.filter The filter to apply to the Webhook (form_submission only)
    * @returns The created webhook
    */
   async createWebhook({