webflow-api 1.0.3 → 1.1.0

package/src/api/membership.ts

@@ -0,0 +1,125 @@
+import { Client, PaginatedData, QueryString, requireArgs } from "../core";
+
+/**************************************************************
+ * Interfaces
+ **************************************************************/
+export interface IUser {
+  emailVerified: boolean;
+  lastUpdated?: string;
+  createdOn: string;
+  _id: string;
+  data: any;
+}
+
+export interface IUserDelete {
+  deleted: number;
+}
+
+/**************************************************************
+ * Types
+ **************************************************************/
+export type PaginatedUsers = PaginatedData & {
+  users: IUser[];
+};
+
+export type UserIdParam = { siteId: string; userId: string };
+
+/**************************************************************
+ * Functions
+ **************************************************************/
+
+/**
+ * Get a list of Users
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.limit The number of items to return (optional)
+ * @param params.offset The number of items to skip (optional)
+ * @returns A list of Users
+ */
+export function list(
+  client: Client,
+  { siteId, limit, offset }: { siteId: string; limit?: number; offset?: number }
+) {
+  requireArgs({ siteId });
+  const params = { limit, offset };
+  const path = `/sites/${siteId}/users`;
+  return client.get<PaginatedUsers>(path, { params });
+}
+
+/**
+ * Get a single User
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.userId The user ID
+ * @returns A single User
+ */
+export function getOne(
+  client: Client,
+  { siteId, userId }: { siteId: string; userId: string }
+) {
+  requireArgs({ siteId, userId });
+  const path = `/sites/${siteId}/users/${userId}`;
+  return client.get<IUser>(path);
+}
+
+/**
+ * Update a User
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.userId The user ID
+ * @param params.data The data to update
+ * @returns The updated User
+ */
+export function update(
+  client: Client,
+  {
+    siteId,
+    userId,
+    data,
+  }: {
+    data: object;
+    siteId: string;
+    userId: string;
+  }
+) {
+  requireArgs({ siteId, userId });
+  const path = `/sites/${siteId}/users/${userId}`;
+  return client.patch<IUser>(path, data);
+}
+
+/**
+ * Invite a User to a site
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.email The email address of the user to invite
+ * @returns The newly created User
+ */
+export async function invite(
+  client: Client,
+  { siteId, email }: { siteId: string; email: string }
+) {
+  requireArgs({ siteId, email });
+  const path = `/sites/${siteId}/users/invite`;
+  return client.post<IUser>(path, { email });
+}
+
+/**
+ * Remove a User
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.userId The user ID
+ * @returns The result of the remove
+ */
+export function remove(
+  client: Client,
+  { siteId, userId }: { siteId: string; userId: string }
+) {
+  requireArgs({ siteId, userId });
+  const path = `/sites/${siteId}/users/${userId}`;
+  return client.delete<IUserDelete>(path);
+}

package/src/api/meta.ts

@@ -0,0 +1,61 @@
+import { Client } from "../core";
+
+/**************************************************************
+ * Types
+ **************************************************************/
+export type InfoApplication = {
+  description: string;
+  ownerType: string;
+  homepage: string;
+  owner: string;
+  name: string;
+  _id: string;
+};
+
+/**************************************************************
+ * Interfaces
+ **************************************************************/
+export interface IAuthenticatedUser {
+  user: {
+    firstName: string;
+    lastName: string;
+    email: string;
+    _id: string;
+  };
+}
+
+export interface IAuthentiationInfo {
+  application: InfoApplication;
+  workspaces: string[];
+  rateLimit: number;
+  createdOn: string;
+  grantType: string;
+  lastUsed: string;
+  sites: string[];
+  users: string[];
+  orgs: string[];
+  status: string;
+  _id: string;
+}
+
+/**************************************************************
+ * Functions
+ **************************************************************/
+
+/**
+ * Get the authentication info for the current token
+ * @param client The Webflow client
+ * @returns The authentication info
+ */
+export function info(client: Client) {
+  return client.get<IAuthentiationInfo>("/info");
+}
+
+/**
+ * Get the authenticated user
+ * @param client The Webflow client
+ * @returns The authenticated user
+ */
+export function user(client: Client) {
+  return client.get<IAuthenticatedUser>("/user");
+}

package/src/api/oauth.ts

@@ -0,0 +1,119 @@
+import { Client, requireArgs } from "../core";
+
+/**************************************************************
+ * Interfaces
+ **************************************************************/
+export interface IAuthorizeUrlParams {
+  state?: string;
+  scope?: string;
+  client_id: string;
+  redirect_uri?: string;
+  response_type?: string;
+}
+
+export interface IRevokeTokenParams {
+  client_secret: string;
+  access_token: string;
+  client_id: string;
+}
+
+export interface IAccessTokenParams {
+  code: string;
+  client_id: string;
+  grant_type?: string;
+  client_secret: string;
+  redirect_uri?: string;
+}
+
+export interface IAccessToken {
+  token_type: string;
+  access_token: string;
+}
+
+export interface IRevokeToken {
+  didRevoke: boolean;
+}
+
+/**************************************************************
+ * Functions
+ **************************************************************/
+
+/**
+ * Get the URL to authorize a user
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.client_id The OAuth client ID
+ * @param params.scope The scope (optional)
+ * @param params.state The state (optional)
+ * @param params.redirect_uri The redirect URI (optional)
+ * @param params.response_type The response type (default: code)
+ * @returns The URL to authorize a user
+ */
+export function authorizeUrl(
+  client: Client,
+  {
+    response_type = "code",
+    redirect_uri,
+    client_id,
+    state,
+    scope,
+  }: IAuthorizeUrlParams
+) {
+  requireArgs({ client_id });
+
+  const params = { response_type, client_id };
+  if (redirect_uri) params["redirect_uri"] = redirect_uri;
+  if (state) params["state"] = state;
+  if (scope) params["scope"] = scope;
+
+  const url = "/oauth/authorize";
+  return client.getUri({ url, method: "GET", params });
+}
+
+/**
+ * Get an access token
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.code The OAuth code
+ * @param params.client_id The OAuth client ID
+ * @param params.client_secret The OAuth client secret
+ * @param params.redirect_uri The redirect URI (optional)
+ * @param params.grant_type The grant type (default: "authorization_code")
+ * @returns An access token
+ */
+export function accessToken(
+  client: Client,
+  {
+    grant_type = "authorization_code",
+    client_secret,
+    redirect_uri,
+    client_id,
+    code,
+  }: IAccessTokenParams
+) {
+  requireArgs({ client_id, client_secret, code });
+
+  const path = "/oauth/access_token";
+  const data = { client_secret, redirect_uri, grant_type, client_id, code };
+  return client.post<IAccessToken>(path, data);
+}
+
+/**
+ * Revoke an access token
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.client_id The OAuth client ID
+ * @param params.client_secret The OAuth client secret
+ * @param params.access_token The OAuth access token
+ * @returns The result of the revoke
+ */
+export function revokeToken(
+  client: Client,
+  { client_secret, access_token, client_id }: IRevokeTokenParams
+) {
+  requireArgs({ client_id, client_secret, access_token });
+
+  const path = "/oauth/revoke_authorization";
+  const data = { client_secret, access_token, client_id };
+  return client.post<IRevokeToken>(path, data);
+}

package/src/api/site.ts

@@ -0,0 +1,86 @@
+import { Client, QueryString, requireArgs } from "../core";
+
+/**************************************************************
+ * Interfaces
+ *************************************************************/
+export interface IDomain {
+  _id: string;
+  name: string;
+}
+
+export interface ISite {
+  lastPublished: string;
+  previewUrl: string;
+  createdOn: string;
+  shortName: string;
+  timezone: string;
+  database: string;
+  name: string;
+  _id: string;
+}
+
+export interface IPublishSite {
+  queued: boolean;
+}
+
+/**************************************************************
+ * Functions
+ **************************************************************/
+
+/**
+ * Get a list of Sites
+ * @param client The Webflow client
+ * @param params The query string parameters (optional)
+ * @returns
+ */
+export function list(client: Client, params?: QueryString) {
+  const path = "/sites";
+  return client.get<ISite[]>(path, { params });
+}
+
+/**
+ * Get a single Site
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.params The query string parameters (optional)
+ * @returns A single Site
+ */
+export function getOne(
+  client: Client,
+  { siteId, params }: { siteId: string; params?: QueryString }
+) {
+  requireArgs({ siteId });
+  const path = `/sites/${siteId}`;
+  return client.get<ISite>(path, { params });
+}
+
+/**
+ * Publish a site
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.domains The domains to publish to
+ * @returns The publish result
+ */
+export function publish(
+  client: Client,
+  { siteId, domains }: { siteId: string; domains: string[] }
+) {
+  requireArgs({ siteId, domains });
+  const path = `/sites/${siteId}/publish`;
+  return client.post<IPublishSite>(path, { domains });
+}
+
+/**
+ * Get a list of domains for a site
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @returns A list of domains
+ */
+export function domains(client: Client, { siteId }: { siteId: string }) {
+  requireArgs({ siteId });
+  const path = `/sites/${siteId}/domains`;
+  return client.get<IDomain[]>(path);
+}

package/src/api/webhook.ts

@@ -0,0 +1,125 @@
+import { Client, QueryString, requireArgs } from "../core";
+
+/**************************************************************
+ * Types
+ **************************************************************/
+export type TriggerType =
+  | "form_submission"
+  | "site_publish"
+  | "ecomm_new_order"
+  | "ecomm_order_changed"
+  | "ecomm_inventory_changed"
+  | "collection_item_created"
+  | "collection_item_changed"
+  | "collection_item_deleted"
+  | string;
+
+export type Filter = {
+  name: string;
+};
+
+/**************************************************************
+ * Interfaces
+ **************************************************************/
+export interface IWebhook {
+  triggerType: TriggerType;
+  triggerId: string;
+  createdOn: string;
+  lastUsed?: string;
+  site: string;
+  _id: string;
+  filter?: {
+    name: string;
+  };
+}
+
+export interface IRemoveResult {
+  deleted: number;
+}
+
+/**************************************************************
+ * Functions
+ **************************************************************/
+
+/**
+ * Get a list of Webhooks
+ * @param client The Webflow client
+ * @param params1 The params for the request
+ * @param params1.siteId The site ID
+ * @param params The query string parameters (optional)
+ * @returns A list of Webhooks
+ */
+export function list(
+  client: Client,
+  { siteId }: { siteId: string },
+  params?: QueryString
+) {
+  requireArgs({ siteId });
+  const path = `/sites/${siteId}/webhooks`;
+  return client.get<IWebhook[]>(path, { params });
+}
+
+/**
+ * Get a single Webhook
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.webhookId The webhook ID
+ * @returns A single Webhook
+ */
+export function getOne(
+  client: Client,
+  { siteId, webhookId }: { siteId: string; webhookId: string }
+) {
+  requireArgs({ siteId, webhookId });
+  const path = `/sites/${siteId}/webhooks/${webhookId}`;
+  return client.get<IWebhook>(path);
+}
+
+/**
+ * Create a new Webhook
+ * @param client The Webflow client
+ * @param params The params for the request
+ * @param params.siteId The site ID
+ * @param params.url The URL to send the webhook to
+ * @param params.triggerType The event to trigger the webhook
+ * @param params.filter The filter to apply to the webhook (optional: form_submission only)
+ * @param params.params The query string parameters (optional)
+ * @returns The created webhook
+ */
+export function create(
+  client: Client,
+  {
+    triggerType,
+    siteId,
+    filter,
+    url,
+  }: {
+    url: string;
+    siteId: string;
+    filter?: Filter;
+    triggerType: TriggerType;
+  }
+) {
+  requireArgs({ siteId, triggerType, url });
+  const path = `/sites/${siteId}/webhooks`;
+  const data = { triggerType, url, filter };
+  return client.post<IWebhook>(path, data);
+}
+
+/**
+ * Remove a Webhook
+ * @param client The Webflow client
+ * @param params The query string parameters (optional)
+ * @param params.webhookId The Webhook ID
+ * @param params.siteId The Site ID
+ * @returns The result of the removal
+ */
+export function remove(
+  client: Client,
+  { siteId, webhookId }: { siteId: string; webhookId: string }
+) {
+  requireArgs({ siteId, webhookId });
+  const path = `/sites/${siteId}/webhooks/${webhookId}`;
+  return client.delete<IRemoveResult>(path);
+}

package/src/core/client.ts

@@ -0,0 +1,76 @@
+import { Axios } from "axios";
+import { DEFAULT_HOST, USER_AGENT, Options, RequestError } from "../core";
+
+/**************************************************************
+ * Types
+ **************************************************************/
+export type QueryString = Record<string, any>;
+export type PaginationFilter = { limit?: number; offset?: number };
+
+/**************************************************************
+ * Interfaces
+ ************************************************************* */
+export interface PaginatedData {
+  count: number;
+  limit: number;
+  offset: number;
+  total: number;
+}
+
+export interface WebflowOptions {
+  host?: string;
+  token?: string;
+  version?: string;
+  headers?: Record<string, string>;
+}
+
+/**************************************************************
+ * Classes
+ **************************************************************/
+export class Client extends Axios {
+  constructor({
+    host = DEFAULT_HOST,
+    headers = {},
+    version,
+    token,
+  }: Options = {}) {
+    super({
+      transformRequest: [(data) => JSON.stringify(data)],
+      baseURL: `https://api.${host}/`,
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+        "Accept-Version": version,
+        ...headers,
+      },
+    });
+
+    if (token) this.token = token;
+
+    // check for webflow errors
+    this.defaults.transformResponse = [this.transformResponse];
+  }
+
+  /**
+   * Transforms JSON response to an object
+   * if the response is a Webflow error, it will throw an error
+   * @param data JSON response
+   * @returns response object
+   */
+  private transformResponse(data: any = {}) {
+    // parse json if string
+    if (String(data) === data) data = JSON.parse(data);
+    if (data.err) throw new RequestError(data);
+    return data;
+  }
+
+  // set the Authorization header
+  set token(value: string) {
+    this.defaults.headers["Authorization"] = `Bearer ${value}`;
+  }
+
+  // clear the Authorization header
+  clearToken() {
+    delete this.defaults.headers["Authorization"];
+  }
+}

package/src/core/error.ts

@@ -0,0 +1,32 @@
+export interface IRequestError {
+  msg: string;
+  code: number;
+  name: string;
+  path: string;
+  err: string;
+}
+
+export class RequestError extends Error implements IRequestError {
+  msg: string;
+  code: number;
+  name: string;
+  path: string;
+  err: string;
+
+  constructor(error: IRequestError) {
+    super(error.err ? error.err : "Unknown error occured");
+    Object.assign(this, error);
+  }
+}
+
+export class ArgumentError extends Error {
+  constructor(name: string) {
+    super(`Argument '${name}' is required but was not present`);
+  }
+}
+
+export function requireArgs(args: object) {
+  for (const key in args) {
+    if (!args[key]) throw new ArgumentError(key);
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./error";
+export * from "./options";

package/src/core/options.ts

@@ -0,0 +1,9 @@
+export const DEFAULT_HOST = "webflow.com";
+export const USER_AGENT = "Webflow Javascript SDK / 1.0";
+
+export interface Options {
+  host?: string;
+  token?: string;
+  version?: string;
+  headers?: Record<string, string>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { Webflow } from "./webflow";
+
+export = Webflow;