webflow-api 1.3.0 → 2.0.0-beta

package/Client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as environments from "./environments";
+import * as core from "./core";
+import { Token } from "./api/resources/token/client/Client";
+import { Sites } from "./api/resources/sites/client/Client";
+import { Collections } from "./api/resources/collections/client/Client";
+import { Pages } from "./api/resources/pages/client/Client";
+import { Scripts } from "./api/resources/scripts/client/Client";
+import { Webhooks } from "./api/resources/webhooks/client/Client";
+import { Assets } from "./api/resources/assets/client/Client";
+import { Forms } from "./api/resources/forms/client/Client";
+import { Users } from "./api/resources/users/client/Client";
+import { AccessGroups } from "./api/resources/accessGroups/client/Client";
+import { Products } from "./api/resources/products/client/Client";
+import { Orders } from "./api/resources/orders/client/Client";
+import { Inventory } from "./api/resources/inventory/client/Client";
+import { Ecommerce } from "./api/resources/ecommerce/client/Client";
+export declare namespace WebflowClient {
+    interface Options {
+        environment?: core.Supplier<environments.WebflowEnvironment | string>;
+        accessToken: core.Supplier<core.BearerToken>;
+    }
+    interface RequestOptions {
+        timeoutInSeconds?: number;
+        maxRetries?: number;
+    }
+}
+export declare class WebflowClient {
+    protected readonly _options: WebflowClient.Options;
+    constructor(_options: WebflowClient.Options);
+    protected _token: Token | undefined;
+    get token(): Token;
+    protected _sites: Sites | undefined;
+    get sites(): Sites;
+    protected _collections: Collections | undefined;
+    get collections(): Collections;
+    protected _pages: Pages | undefined;
+    get pages(): Pages;
+    protected _scripts: Scripts | undefined;
+    get scripts(): Scripts;
+    protected _webhooks: Webhooks | undefined;
+    get webhooks(): Webhooks;
+    protected _assets: Assets | undefined;
+    get assets(): Assets;
+    protected _forms: Forms | undefined;
+    get forms(): Forms;
+    protected _users: Users | undefined;
+    get users(): Users;
+    protected _accessGroups: AccessGroups | undefined;
+    get accessGroups(): AccessGroups;
+    protected _products: Products | undefined;
+    get products(): Products;
+    protected _orders: Orders | undefined;
+    get orders(): Orders;
+    protected _inventory: Inventory | undefined;
+    get inventory(): Inventory;
+    protected _ecommerce: Ecommerce | undefined;
+    get ecommerce(): Ecommerce;
+}

package/Client.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebflowClient = void 0;
+const Client_1 = require("./api/resources/token/client/Client");
+const Client_2 = require("./api/resources/sites/client/Client");
+const Client_3 = require("./api/resources/collections/client/Client");
+const Client_4 = require("./api/resources/pages/client/Client");
+const Client_5 = require("./api/resources/scripts/client/Client");
+const Client_6 = require("./api/resources/webhooks/client/Client");
+const Client_7 = require("./api/resources/assets/client/Client");
+const Client_8 = require("./api/resources/forms/client/Client");
+const Client_9 = require("./api/resources/users/client/Client");
+const Client_10 = require("./api/resources/accessGroups/client/Client");
+const Client_11 = require("./api/resources/products/client/Client");
+const Client_12 = require("./api/resources/orders/client/Client");
+const Client_13 = require("./api/resources/inventory/client/Client");
+const Client_14 = require("./api/resources/ecommerce/client/Client");
+class WebflowClient {
+    constructor(_options) {
+        this._options = _options;
+    }
+    get token() {
+        var _a;
+        return ((_a = this._token) !== null && _a !== void 0 ? _a : (this._token = new Client_1.Token(this._options)));
+    }
+    get sites() {
+        var _a;
+        return ((_a = this._sites) !== null && _a !== void 0 ? _a : (this._sites = new Client_2.Sites(this._options)));
+    }
+    get collections() {
+        var _a;
+        return ((_a = this._collections) !== null && _a !== void 0 ? _a : (this._collections = new Client_3.Collections(this._options)));
+    }
+    get pages() {
+        var _a;
+        return ((_a = this._pages) !== null && _a !== void 0 ? _a : (this._pages = new Client_4.Pages(this._options)));
+    }
+    get scripts() {
+        var _a;
+        return ((_a = this._scripts) !== null && _a !== void 0 ? _a : (this._scripts = new Client_5.Scripts(this._options)));
+    }
+    get webhooks() {
+        var _a;
+        return ((_a = this._webhooks) !== null && _a !== void 0 ? _a : (this._webhooks = new Client_6.Webhooks(this._options)));
+    }
+    get assets() {
+        var _a;
+        return ((_a = this._assets) !== null && _a !== void 0 ? _a : (this._assets = new Client_7.Assets(this._options)));
+    }
+    get forms() {
+        var _a;
+        return ((_a = this._forms) !== null && _a !== void 0 ? _a : (this._forms = new Client_8.Forms(this._options)));
+    }
+    get users() {
+        var _a;
+        return ((_a = this._users) !== null && _a !== void 0 ? _a : (this._users = new Client_9.Users(this._options)));
+    }
+    get accessGroups() {
+        var _a;
+        return ((_a = this._accessGroups) !== null && _a !== void 0 ? _a : (this._accessGroups = new Client_10.AccessGroups(this._options)));
+    }
+    get products() {
+        var _a;
+        return ((_a = this._products) !== null && _a !== void 0 ? _a : (this._products = new Client_11.Products(this._options)));
+    }
+    get orders() {
+        var _a;
+        return ((_a = this._orders) !== null && _a !== void 0 ? _a : (this._orders = new Client_12.Orders(this._options)));
+    }
+    get inventory() {
+        var _a;
+        return ((_a = this._inventory) !== null && _a !== void 0 ? _a : (this._inventory = new Client_13.Inventory(this._options)));
+    }
+    get ecommerce() {
+        var _a;
+        return ((_a = this._ecommerce) !== null && _a !== void 0 ? _a : (this._ecommerce = new Client_14.Ecommerce(this._options)));
+    }
+}
+exports.WebflowClient = WebflowClient;

package/README.md

@@ -1,7 +1,18 @@
-# Webflow Data API SDK
+# Webflow JS SDK
+
+The Webflow JavaScript SDK provides convenient access to the [Webflow Data API](https://developers.webflow.com/reference/rest-introduction) from
+applications written in JS.
+
+The SDK contains typings and request builders for the Webflow Data API.
+
+## Documentation
+
+Explore the API reference documentation [here](https://developers.webflow.com/reference/rest-introduction).
 
 ## Installation
 
+Add this dependency to your project's package.json file:
+
 Using npm:
 
 ```shell
@@ -16,317 +27,129 @@ $ yarn add webflow-api
 
 ## Usage
 
-The constructor takes in a few optional parameters to initialize the API client
-
-- `token` - the access token to use
-- `headers` - additional headers to add to the request
-- `version` - the version of the API you wish to use
-
-```javascript
-const Webflow = require("webflow-api");
-
-// initialize the client with the access token
-const webflow = new Webflow({ token: "[ACCESS TOKEN]" });
-
-// fully loaded
-const webflow = new Webflow({
-  token: "[ACCESS TOKEN]",
-  version: "1.0.0",
-  headers: {
-    "User-Agent": "My Webflow App / 1.0",
-  },
-});
-```
-
-## 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
-
-You can retrieve child resources by chaining calls on the parent object.
-
-```javascript
-// get the first site
-const [site] = await webflow.sites();
-
-// get the first collection in the site
-const [collection] = await site.collections();
-
-// get the first item in the collection
-const [item] = await collection.items();
-
-// get one item from the collection
-const item = await collection.items({ itemId: "[ITEM ID]" });
-```
-
-### Pagination
-
-To paginate results, pass in the `limit` and `offset` options.
-
-```javascript
-// Get the first page of results
-const page1 = await collection.items({ limit: 20 });
-
-// Get the second page of results
-const page2 = await collection.items({ limit: 20, offset: 20 });
-```
-
-### Rate Limit
-
-Check rate limit status on each call by checking the `_meta` property.
-
-```javascript
-// make an api call
-const site = await webflow.site({ siteId: "[SITE ID]" });
-
-// check rate limit
-const { rateLimit } = site._meta; // { limit: 60, remaining: 56 }
-```
-
-### Update Token
-
-If you need to update the access token, you can set the `token` property at any time.
+Simply import `Webflow` and start making calls to our API.
 
 ```javascript
-// token is unset
-const webflow = new Webflow();
-
-// set token
-webflow.token = "[ACCESS TOKEN]";
+import { WebflowClient } from "webflow-api";
 
-// remove the token
-webflow.clearToken();
-```
-
-### Calling APIs Directly
-
-All Webflow API endpoints can be called directly using the `get`, `post`, `put`, and `delete` methods.
+const webflow = new WebflowClient({ accessToken });
 
-```javascript
-// call the sites endpoint directly
-const sites = await webflow.get("/sites");
-
-// post to an endpoint directly
-const result = await webflow.post("/sites/[SITE ID]/publish", {
-  domains: ["hello-webflow.com"],
-});
+const site = await webflow.sites.get("site-id");
 ```
 
 ## OAuth
 
-To implement OAuth, you'll need a Webflow App registered and a webserver running, that is publicly facing.
+To implement OAuth, you'll need to [register a Webflow App in your Workspace](https://developers.webflow.com/reference/authorization)
 
-### Authorize
+### Step 1: Authorize URL
 
-The first step in OAuth is to generate an authorization url to redirect the user to.
+The first step in OAuth is to generate an Authorization URL. Use this URL
+to fetch your Authorization Code. See the [docs](https://docs.developers.webflow.com/v1.0.0/docs/oauth#user-authorization)
+for more details.
 
 ```javascript
-// Get the authorization url to redirect users to
-const url = webflow.authorizeUrl({
-  client_id: "[CLIENT ID]",
-  state: "1234567890", // optional
-  redirect_uri: "https://my.server.com/oauth/callback", // optional
-});
-
-// redirect user from your server route
-res.redirect(url);
-```
+import { WebflowClient } from "webflow-api";
 
-### 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"],
+const authorizeUrl = WebflowClient.authorizeURL({
+    state: "your_state",
+    scope: "sites:read",
+    clientId: "your_client_id",
+    redirctUri: "your_redirect_uri",
 });
-```
-
-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.
-
-```javascript
-const auth = await webflow.accessToken({
-  client_id,
-  client_secret,
-  code,
-  redirect_uri, // optional - required if used in the authorize step
-});
-
-// you now have the user's access token to make API requests with
-const userWF = new Webflow({ token: auth.access_token });
-
-// pull information for the user
-const authenticatedUser = await userWF.authenticatedUser();
+console.log(authorizeUrl);
 ```
 
-### Revoke Token
+### Step 2: Retrieve your access token
 
-If the user decides to disconnect from your server, you should call revoke token to remove the authorization.
+Use the `getAccessToken` function and pass in your `client_id`,
+`client_secret`, and `authorization_code`.
 
 ```javascript
-const result = await webflow.revokeToken({
-  client_id,
-  client_secret,
-  access_token,
-});
+import { WebflowClient } from "webflow-api";
 
-// ensure it went through
-result.didRevoke === true;
+const accessToken = WebflowClient.getAccessToken({
+  clientId: "your_client_id", 
+  clientSecret: "your_client_secret",
+  code: "your_authorization_code"
+});
 ```
 
-## Examples
-
-### Sites
+### Step 3: Instantiate the client
 
-Get all sites available or lookup by site id.
+Instantiate the client using your `access_token`.
 
 ```javascript
-// List all sites
-const sites = await webflow.sites();
+import { WebflowClient } from "webflow-api";
 
-// Get a single site
-const site = await webflow.site({ siteId: "[SITE ID]" });
+const webflow = WebflowClient({ accessToken });
 ```
 
-### Collections
-
-Get all collections available for a site or lookup by collection id.
+## Webflow Types
 
-```javascript
-// Get a site's collection from the site
-const collections = await site.collections();
-
-// Get a site's collection by passing in a site id
-const collections = await webflow.collections({ siteId: "[SITE ID]" });
-
-// Get a single collection
-const collection = await webflow.collection({ collectionId: "[COLLECTION ID]" });
-```
+All of the types are nested within the `Webflow` namespace. Let IntelliSense
+guide you!
 
-### Collection Items
+## Exception Handling
 
-Get all collection items available for a collection or lookup by item id.
+All errors thrown by the SDK will be subclasses of [`WebflowError`](./src/errors/WebflowError.ts).
 
 ```javascript
-// Get the items from a collection
-const items = await collection.items();
-
-// Get a subset of items
-const items = await collection.items({ limit: 10, offset: 2 });
+import { WebflowClient, Webflow } from 'webflow';
+const webflow = new WebflowClient({ accessToken: 'your_access_token' });
 
-// Get a single item
-const item = await webflow.item({ collectionId: "[COLLECTION ID]", itemId: "[ITEM ID]" });
+try {
+  const sites = await webflow.sites.get(...);
+} catch (e) {
+  if (e instanceof Webflow.ForbiddenError) {
+    console.log(e.body.message);
+  } else if (e instanceof Webflow.BadRequestError) {
+    console.log(e.body.message);
+  } else {
+    throw e;
+  }
+}
 ```
 
-### Update an Item
+## Advanced
 
-```javascript
-// Set the fields to update
-const fields = {
-  name: "New Name",
-  _archived: false,
-  _draft: false,
-  slug: "new-name",
-};
-
-// call update
-const updatedItem = await webflow.updateItem({
-  collectionId: "[COLLECTION ID]",
-  itemId: "[ITEM ID]",
-  fields,
-});
-```
+### Timeouts
 
-### Memberships
+By default, requests time out after 60 seconds. You can configure the timeout and # of max retries
 
 ```javascript
-// Get a site's users from the site
-const users = await site.users();
-
-// Get a site's users with a site id
-const users = await webflow.users({
-  siteId: "[SITE ID]",
-});
+import { WebflowClient } from 'webflow';
 
-// Get a single user
-const user = await site.user({
-  siteId: "[SITE ID]",
-  userId: "[USER ID]",
-});
-
-// Get a site's access groups
-const accessGroups = await site.accessGroups();
-
-// Get a site's access groups with a site id
-const accessGroups = await webflow.accessGroups({
-  siteId: "[SITE ID]",
+const sites = await webflow.sites.get(..., {
+  timeoutInSeconds: 30 // override the timeout
 });
 ```
 
-### Webhooks
+### Retries
+The SDK will automatically retry failures with exponential backoff. 
+You can configure the retries by setting maxRetries.
 
 ```javascript
-// get webhooks for a site
-const webhooks = await site.webhooks();
+import { WebflowClient } from 'webflow';
 
-// create a webhook
-const webhook = await site.createWebhook({
-  triggerType: "form_submission",
-  url: "https://webhook.site",
+const sites = await webflow.sites.get(..., {
+  maxRetries: 10 // override the reries
 });
 ```
 
-### Authenticated User
+## Beta Status
 
-```javascript
-// pull information for the authenticated user
-const authenticatedUser = await webflow.authenticatedUser();
-```
+This SDK is in **Preview**, and there may be breaking changes between versions without a major
+version update.
 
-## Contributing
+To ensure a reproducible environment (and minimize risk of breaking changes), we recommend pinning a specific package version.
 
-Contributions are welcome - feel free to open an issue or pull request.
+## Contributing
 
-## License
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
 
-The MIT license - see `LICENSE`.
+On the other hand, contributions to the README are always very welcome!

package/api/errors/BadRequestError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as errors from "../../errors";
+export declare class BadRequestError extends errors.WebflowError {
+    constructor(body?: unknown);
+}

package/api/errors/BadRequestError.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BadRequestError = void 0;
+const errors = __importStar(require("../../errors"));
+class BadRequestError extends errors.WebflowError {
+    constructor(body) {
+        super({
+            message: "BadRequestError",
+            statusCode: 400,
+            body: body,
+        });
+        Object.setPrototypeOf(this, BadRequestError.prototype);
+    }
+}
+exports.BadRequestError = BadRequestError;

package/api/errors/ConflictError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as errors from "../../errors";
+export declare class ConflictError extends errors.WebflowError {
+    constructor(body?: unknown);
+}

package/api/errors/ConflictError.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConflictError = void 0;
+const errors = __importStar(require("../../errors"));
+class ConflictError extends errors.WebflowError {
+    constructor(body) {
+        super({
+            message: "ConflictError",
+            statusCode: 409,
+            body: body,
+        });
+        Object.setPrototypeOf(this, ConflictError.prototype);
+    }
+}
+exports.ConflictError = ConflictError;

package/api/errors/ForbiddenError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as errors from "../../errors";
+export declare class ForbiddenError extends errors.WebflowError {
+    constructor(body?: unknown);
+}