webflow-api 1.2.2 → 1.3.0

package/.eslintrc

@@ -0,0 +1,31 @@
+{
+  "env": {
+    "es2021": true,
+    "browser": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 12,
+    "project": "tsconfig.eslint.json"
+  },
+  "plugins": ["@typescript-eslint", "prettier"],
+  "rules": {
+    "prefer-const": "error",
+    "prettier/prettier": "error",
+    "@typescript-eslint/no-unused-vars": "off",
+    "@typescript-eslint/no-unused-params": "off",
+    "@typescript-eslint/no-unsafe-argument": "warn",
+    "@typescript-eslint/no-unsafe-assignment": "warn"
+  },
+  "overrides": [
+    {
+      "env": { "jest": true, "node": true },
+      "files": ["tests/**/*.ts"]
+    }
+  ]
+}

package/.github/workflows/code-quality.yml

@@ -0,0 +1,102 @@
+name: Code Quality
+
+on: push
+
+jobs:
+  build:
+    name: TypeScript Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+
+      - name: yarn install
+        run: yarn install
+
+      - run: yarn build
+        name: yarn build
+
+  typecheck:
+    name: TypeScript Typecheck
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+
+      - name: yarn install
+        run: yarn install
+
+      - run: yarn typecheck
+        name: yarn typecheck
+
+  test:
+    name: Jest CI Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+
+      - name: yarn install
+        run: yarn install
+
+      - name: yarn build
+        run: yarn build
+
+      - run: yarn test:ci
+        name: yarn test:ci
+
+  prettier:
+    name: Prettier Formatting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+
+      - name: yarn install
+        run: yarn install
+
+      - run: yarn format:check
+        name: yarn format:check
+
+  lint:
+    name: ESLint Linting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+
+      - name: yarn install
+        run: yarn install
+
+      - run: yarn lint
+        name: yarn lint

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,21 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+      - run: |
+          yarn install
+          yarn test
+          yarn publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/semgrep.yml

@@ -0,0 +1,24 @@
+on:
+  workflow_dispatch: {}
+  pull_request: {}
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - .github/workflows/semgrep.yml
+  schedule:
+    # random HH:MM to avoid a load spike on GitHub Actions at 00:00
+    - cron: 34 11 * * *
+name: Semgrep
+jobs:
+  semgrep:
+    name: semgrep/ci
+    runs-on: ubuntu-20.04
+    env:
+      SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+    container:
+      image: returntocorp/semgrep
+    steps:
+      - uses: actions/checkout@v3
+      - run: semgrep ci

package/.prettierignore

@@ -0,0 +1,5 @@
+dist
+temp
+*.json
+coverage
+.DS_Store

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "useTabs": false,
+  "printWidth": 100,
+  "trailingComma": "all"
+}

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/jest.config.js

@@ -0,0 +1,17 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  // A preset that is used as a base for Jest's configuration
+  preset: "ts-jest",
+
+  // The test environment that will be used for testing
+  testEnvironment: "node",
+
+  // A map from regular expressions to paths to transformers
+  transform: { "^.+\\.ts?$": "ts-jest" },
+
+  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
+  transformIgnorePatterns: ["<rootDir>/node_modules/"],
+
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+};

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.0",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "contributors": [
+    "Rodney Urquhart (https://github.com/rodneyu215)",
     "John Agan (https://github.com/johnagan)"
   ],
   "repository": {
@@ -12,12 +13,6 @@
     "type": "git"
   },
   "license": "MIT",
-  "files": [
-    "dist",
-    "src",
-    "LICENSE",
-    "yarn.lock"
-  ],
   "scripts": {
     "test": "yarn build && jest",
     "build": "yarn clean && tsc",

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({