@canva/n8n-nodes-canva 0.1.0

package/README.md

@@ -0,0 +1,217 @@
+# n8n-nodes-canva
+
+![Banner](./.github/assets/github-banner.jpg)
+
+An n8n community node for connecting Canva to n8n using the [Canva Connect API](https://www.canva.dev/docs/connect/). Create and export designs, bulk-generate from brand templates, manage assets and folders, import external files, and connect Canva to the rest of your stack.
+
+- [Installation](#installation)
+- [Running n8n locally](#running-n8n-locally)
+- [Credentials](#credentials)
+- [Operations](#operations)
+- [Usage notes](#usage-notes)
+- [Resources](#resources)
+
+## Installation
+
+> This section is for people who already have an n8n instance running (cloud or self-hosted). If you want to test this node on your own machine first, see [Running n8n locally](#running-n8n-locally) below.
+
+Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
+
+## Running n8n locally
+
+> This section is for developers who want to run and test this node locally.
+
+**Prerequisites:** Node.js 24+, npm.
+
+1. Install dependencies and start n8n in dev mode:
+
+   ```bash
+   npm install
+   npm run dev
+   ```
+
+   This builds the node, links it to a local n8n instance, and starts n8n at [http://127.0.0.1:5678](http://127.0.0.1:5678) with hot reload enabled. The **Canva** node will appear in the node picker under _Community Nodes_.
+
+2. Follow the [Credentials](#credentials) section below to connect your Canva account.
+
+   > **Note:** When running locally, use `http://127.0.0.1:5678/rest/oauth2-credential/callback` as the redirect URI in the Canva Developer Portal. Canva does not accept `localhost` — you must use the IP address.
+
+### Troubleshooting
+
+#### `npm run dev` fails with `EACCES: permission denied, rename ...` inside `~/.npm/_cacache`
+
+`npm run dev` starts n8n via `npx n8n@latest`, which downloads n8n through your machine's shared npm cache (`~/.npm`). If that cache contains files owned by another user — usually root, left behind by running npm with `sudo` at some point — the download fails with `EACCES`/`EEXIST` rename errors. Reclaim ownership of the cache and retry:
+
+```bash
+sudo chown -R $(id -u):$(id -g) ~/.npm
+npm run dev
+```
+
+## Credentials
+
+This node uses **OAuth2 with PKCE** to authenticate with Canva.
+
+### 1. Create a Canva integration
+
+Go to the [Canva Developer Portal](https://www.canva.com/developers/integrations/connect-api) and create a new private integration. After creation, the integration's settings page will automatically open.
+
+- In the **Credentials** section, click on **Generate secret** to generate a new secret.
+- Copy and paste both the **Client ID** and **Client secret** to a secure file.
+- In the **Authentication** tab, add either of the following to the **URL 1** field of the **Authorized redirects**:
+  - **Cloud or self-hosted n8n:** `https://your-n8n-instance.com/rest/oauth2-credential/callback`
+  - **Local n8n:** `http://127.0.0.1:5678/rest/oauth2-credential/callback`
+
+- In the **Scopes** tab, enable the following scopes:
+
+| Scope                                                                                    | Used by                                           |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `asset:read` / `asset:write`                                                             | Asset resource                                    |
+| `brandtemplate:content:read` / `brandtemplate:content:write` / `brandtemplate:meta:read` | Brand Template resource                           |
+| `comment:read` / `comment:write`                                                         | Comment resource (Preview)                        |
+| `design:content:read` / `design:content:write` / `design:meta:read`                      | Design, Autofill, Export, Merge, Resize resources |
+| `folder:read` / `folder:write`                                                           | Folder resource                                   |
+| `profile:read`                                                                           | User resource                                     |
+
+Your integration's **Scopes** settings should look like this:
+
+<!-- markdownlint-disable-next-line MD033 -->
+<img src="./.github/assets/app-scopes.png" alt="Your app's scopes" width="50%" />
+
+### 2. Add your integration's credentials to the Canva node in n8n
+
+1. In n8n, open **Credentials → New → Canva OAuth2 API**.
+2. Enter the **Client ID** and **Client secret** that you saved earlier.
+3. Click **Connect my account** and complete the OAuth flow.
+
+## Operations
+
+### Asset
+
+| Operation                   | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| Delete                      | Delete an asset                                                   |
+| Get                         | Get metadata for an asset                                         |
+| Update                      | Update an asset's name or tags                                    |
+| Upload From URL _(Preview)_ | Upload an asset from a public URL and wait for completion (async) |
+
+### Autofill
+
+> 💎 The Autofill API can only be used on behalf of users who are members of a Canva Enterprise organization.
+
+| Operation | Description                                                                   |
+| --------- | ----------------------------------------------------------------------------- |
+| Create    | Populate a brand template with data and wait for the resulting design (async) |
+
+### Brand Template
+
+> 💎 The Brand Template APIs require a Canva plan with premium features (such as Canva Pro).
+
+| Operation           | Description                                     |
+| ------------------- | ----------------------------------------------- |
+| Get                 | Get metadata for a brand template               |
+| Get Dataset         | Get the autofill dataset for a brand template   |
+| Get Many            | Get many brand templates accessible to the user |
+| Publish _(Preview)_ | Publish a design as a brand template            |
+
+### Comment _(Preview API)_
+
+> ⚠️ All Comment operations use a Preview API that may have unannounced breaking changes and cannot be used in public integrations submitted for Canva review.
+
+| Operation     | Description                                |
+| ------------- | ------------------------------------------ |
+| Create Reply  | Reply to a comment thread on a design      |
+| Create Thread | Create a new comment thread on a design    |
+| Get Reply     | Get a specific reply from a comment thread |
+| Get Thread    | Get metadata for a comment thread          |
+| List Replies  | List all replies in a comment thread       |
+
+### Design
+
+| Operation               | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| Create                  | Create a new design                           |
+| Get                     | Get metadata for a design                     |
+| Get Dataset _(Preview)_ | Get the autofill dataset for a design         |
+| Get Export Formats      | Get the available export formats for a design |
+| Get Many                | Get many designs from the user's projects     |
+| Get Pages _(Preview)_   | Get metadata for pages in a design            |
+
+### Design Import
+
+| Operation       | Description                                                                                    |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| Import From URL | Import an external file (e.g. PPTX, PDF) into Canva from a URL and wait for completion (async) |
+
+### Export
+
+| Operation     | Description                                                            |
+| ------------- | ---------------------------------------------------------------------- |
+| Export Design | Export a design to a file format and wait for the download URL (async) |
+
+### Folder
+
+| Operation  | Description                                           |
+| ---------- | ----------------------------------------------------- |
+| Create     | Create a new folder                                   |
+| Delete     | Delete a folder                                       |
+| Get        | Get metadata for a folder                             |
+| List Items | List items inside a folder                            |
+| Move Item  | Move a design, asset, or folder to a different folder |
+| Update     | Rename a folder                                       |
+
+### Merge _(Preview API)_
+
+> ⚠️ All Merge operations use a Preview API that may have unannounced breaking changes and cannot be used in public integrations submitted for Canva review.
+
+| Operation        | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| Create Merge Job | Merge design pages by applying page operations to create or modify a design (async) |
+
+### Resize
+
+> 💎 The Resize API requires a Canva plan with premium features (such as Canva Pro). Users on the Canva Free plan have access to a limited trial.
+
+| Operation         | Description                                                                       |
+| ----------------- | --------------------------------------------------------------------------------- |
+| Create Resize Job | Create a resized copy of a design in new dimensions or a different format (async) |
+
+### User
+
+| Operation        | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| Get Capabilities | Get the API capabilities available to the current user account |
+| Get Me           | Get the User ID and Team ID of the authenticated user          |
+| Get Profile      | Get the display name of the authenticated user                 |
+
+## Usage notes
+
+### Async operations
+
+Several operations — **Asset Upload From URL**, **Autofill**, **Design Import**, **Export**, **Merge**, and **Resize** — create background jobs in Canva. This node automatically polls for completion and returns the final result once the job succeeds.
+
+You can tune polling behaviour with two optional parameters available on each async operation:
+
+- **Poll Interval** (default 2–3 s depending on the operation) — how often to check for job completion
+- **Max Wait** (default 60 s, or 120 s for Design Import) — maximum time to wait before throwing a timeout error
+
+If a job fails, the node throws an error with the Canva error details.
+
+### Preview APIs
+
+Operations marked _(Preview)_ use endpoints that are still in preview on the Canva platform. They may change without notice and **cannot be used in integrations submitted to Canva's public integration review**. Use them only for internal or development workflows.
+
+### Moving items
+
+The **Folder → Move Item** operation accepts any item ID (design, asset, or folder). To move an item to the top-level Projects folder, use `root` as the **To Folder ID**.
+
+### Autofill dataset format
+
+The **Autofill → Create** operation requires a `data` object whose keys must match the dataset fields returned by **Brand Template → Get Dataset**. Use the Get Dataset operation first to discover the correct field names.
+
+## Resources
+
+- [Ready-to-import example workflows](./examples/)
+- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
+- [Canva Connect API reference](https://www.canva.dev/docs/connect/api-reference/)
+- [Canva Developer Portal](https://www.canva.com/developers)
+- [Canva Developer Documentation](https://www.canva.dev/)

package/dist/credentials/CanvaOAuth2Api.credentials.d.ts

@@ -0,0 +1,9 @@
+import type { ICredentialType, INodeProperties, Icon } from 'n8n-workflow';
+export declare class CanvaOAuth2Api implements ICredentialType {
+    name: string;
+    extends: string[];
+    displayName: string;
+    documentationUrl: string;
+    icon: Icon;
+    properties: INodeProperties[];
+}

package/dist/credentials/CanvaOAuth2Api.credentials.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanvaOAuth2Api = void 0;
+class CanvaOAuth2Api {
+    constructor() {
+        this.name = 'canvaOAuth2Api';
+        this.extends = ['oAuth2Api'];
+        this.displayName = 'Canva OAuth2 API';
+        this.documentationUrl = 'https://github.com/canva-sdks/n8n-nodes-canva/tree/main#credentials';
+        this.icon = {
+            light: 'file:../nodes/Canva/icons/canva.svg',
+            dark: 'file:../nodes/Canva/icons/canva.dark.svg',
+        };
+        this.properties = [
+            {
+                displayName: 'Grant Type',
+                name: 'grantType',
+                type: 'hidden',
+                default: 'pkce',
+            },
+            {
+                displayName: 'Authorization URL',
+                name: 'authUrl',
+                type: 'hidden',
+                default: 'https://www.canva.com/api/oauth/authorize',
+            },
+            {
+                displayName: 'Access Token URL',
+                name: 'accessTokenUrl',
+                type: 'hidden',
+                default: 'https://api.canva.com/rest/v1/oauth/token',
+            },
+            {
+                displayName: 'Auth URI Query Parameters',
+                name: 'authQueryParameters',
+                type: 'hidden',
+                default: '',
+            },
+            {
+                displayName: 'Scope',
+                name: 'scope',
+                type: 'hidden',
+                default: 'asset:read asset:write brandtemplate:content:read brandtemplate:content:write brandtemplate:meta:read comment:read comment:write design:content:read design:content:write design:meta:read folder:read folder:write profile:read',
+            },
+            {
+                displayName: 'Authentication',
+                name: 'authentication',
+                type: 'hidden',
+                default: 'header',
+            },
+        ];
+    }
+}
+exports.CanvaOAuth2Api = CanvaOAuth2Api;
+//# sourceMappingURL=CanvaOAuth2Api.credentials.js.map

package/dist/credentials/CanvaOAuth2Api.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvaOAuth2Api.credentials.js","sourceRoot":"","sources":["../../credentials/CanvaOAuth2Api.credentials.ts"],"names":[],"mappings":";;;AAEA,MAAa,cAAc;IAA3B;QACC,SAAI,GAAG,gBAAgB,CAAC;QAExB,YAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QAExB,gBAAW,GAAG,kBAAkB,CAAC;QAEjC,qBAAgB,GAAG,qEAAqE,CAAC;QAEzF,SAAI,GAAS;YACZ,KAAK,EAAE,qCAAqC;YAC5C,IAAI,EAAE,0CAA0C;SAChD,CAAC;QAEF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,MAAM;aACf;YACD;gBACC,WAAW,EAAE,mBAAmB;gBAChC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,2CAA2C;aACpD;YACD;gBACC,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,2CAA2C;aACpD;YACD;gBACC,WAAW,EAAE,2BAA2B;gBACxC,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,OAAO;gBACpB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,OAAO,EACN,kOAAkO;aACnO;YACD;gBACC,WAAW,EAAE,gBAAgB;gBAC7B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,QAAQ;aACjB;SACD,CAAC;IACH,CAAC;CAAA;AArDD,wCAqDC"}

package/dist/nodes/Canva/Canva.node.d.ts

@@ -0,0 +1,5 @@
+import { type IExecuteFunctions, type INodeExecutionData, type INodeType, type INodeTypeDescription } from 'n8n-workflow';
+export declare class Canva implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}