diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6504fc8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Taskade API docs + url: https://www.taskade.com/docs + about: The public Taskade API, webhooks and authentication. + - name: Account and product help + url: https://www.taskade.com/contact + about: Questions about your Taskade account, billing or plan. Do not post them in a public issue. diff --git a/.github/ISSUE_TEMPLATE/integration-bug.yml b/.github/ISSUE_TEMPLATE/integration-bug.yml new file mode 100644 index 0000000..6661c84 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/integration-bug.yml @@ -0,0 +1,63 @@ +name: Integration bug +description: A Taskade trigger, action or search on Zapier, n8n or Make does not work as expected. +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + **This issue is public.** Everyone on the internet can read it. + Do not paste an API token, an email address, a name, or a link to a private workspace or project. + Replace them with placeholders such as `TOKEN`, `jane@example.com` and `PROJECT_ID`. + For help with your own account, use [taskade.com/contact](https://www.taskade.com/contact). + - type: checkboxes + id: privacy + attributes: + label: Privacy check + options: + - label: This issue holds no token, no email address and no link to a private workspace or project. + required: true + - type: dropdown + id: platform + attributes: + label: Platform + options: + - Zapier + - n8n + - Make + validations: + required: true + - type: input + id: operation + attributes: + label: Trigger, action or search + description: The name that you see on the platform, for example "Create Task" or "New Comment". + placeholder: Create Task + validations: + required: true + - type: textarea + id: what-happened + attributes: + label: What happened + description: Include the error message. Remove every token, email address and private link first. + validations: + required: true + - type: textarea + id: expected + attributes: + label: What you expected + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + placeholder: | + 1. Add the "Create Task" action to a Zap. + 2. Select a project. + 3. Test the action. + - type: input + id: version + attributes: + label: App version + description: For example, the Zapier app version or the n8n-nodes-taskade version. Leave it empty if you do not know. diff --git a/.github/ISSUE_TEMPLATE/new-trigger-or-action.yml b/.github/ISSUE_TEMPLATE/new-trigger-or-action.yml new file mode 100644 index 0000000..142b94a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-trigger-or-action.yml @@ -0,0 +1,51 @@ +name: New trigger or action request +description: Ask for a new Taskade trigger, action or search on Zapier, n8n or Make. +title: "[Request] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + This issue is public. Do not paste an API token, an email address or a link to a private workspace. + The integrations here use the public Taskade API. To see what the API can do today, read the [API overview](https://www.taskade.com/docs/getting-started/api-overview) and the [list of webhook events](https://www.taskade.com/docs/guides/webhooks#supported-events). + - type: dropdown + id: kind + attributes: + label: What do you need? + options: + - A trigger (an event in Taskade starts a workflow) + - An action (a workflow changes something in Taskade) + - A search (a workflow finds something in Taskade) + validations: + required: true + - type: dropdown + id: platforms + attributes: + label: Platforms + multiple: true + options: + - Zapier + - n8n + - Make + validations: + required: true + - type: textarea + id: event-or-action + attributes: + label: The event or the action + description: Which event starts the trigger, or what the action does in Taskade. + placeholder: When a task is completed in a project, start a Zap. + validations: + required: true + - type: textarea + id: use-case + attributes: + label: The use case + description: What you want to automate, and why. + validations: + required: true + - type: input + id: api-endpoint + attributes: + label: API endpoint or event, if you know it + placeholder: POST /completeTask, or the comment.created event diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7e06523 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,137 @@ +# Contributing + +Thank you for your help with the Taskade integrations. This repository holds three apps on the public Taskade API: + +| App | Folder | Language and package manager | +|---|---|---| +| Zapier | [`src/`](src) | TypeScript, Yarn 1 (`yarn.lock`) | +| n8n | [`packages/n8n-nodes-taskade`](packages/n8n-nodes-taskade) | TypeScript, npm (`package-lock.json`) | +| Make | [`packages/make-app-taskade`](packages/make-app-taskade) | Make Apps Editor files (`.iml.jsonc`), no dependencies | + +New here? Read [Build a trigger and an action](docs/build-a-trigger-and-an-action.md) first. It walks through one trigger and one action, file by file. + +## Before you start + +- To ask for a new trigger or action, or to report a bug, use the [issue forms](https://github.com/taskade/integrations/issues/new/choose). +- Check that the public API can do what you want. Refer to the [API docs](https://www.taskade.com/docs/getting-started/api-overview). A new instant trigger needs a public webhook event, and [#10](https://github.com/taskade/integrations/issues/10) tracks the events that are not public yet. +- For a large change, open an issue first, so that a maintainer can agree on the plan with you. + +## Set up + +You need Git, Node.js and Yarn 1. CI uses Node 20 for the Zapier app, Node 24 for the n8n node and Node 22 for the Make check. All the commands below also pass on Node 22. + +```bash +git clone https://github.com/taskade/integrations.git +cd integrations +``` + +### The Zapier app + +Run these commands from the root of the repository. They are the same steps as the `build-and-test` job in [`.github/workflows/ci.yml`](.github/workflows/ci.yml). + +```bash +yarn install --frozen-lockfile +yarn lint # ESLint on src/ +yarn build # tsc, from src/ to lib/ +yarn test # builds again, then runs the Jest tests in lib/test +``` + +`yarn test` also runs the Zapier schema validation on the full app definition, so a schema error fails before it reaches a deploy. + +The [Zapier CLI](https://docs.zapier.com/platform/build-cli/overview) adds a local check of the app structure. `npx` runs the CLI with no global install. Version 17.4.0 matches `zapier-platform-core` in `package.json`. + +```bash +npx --yes --package zapier-platform-cli@17.4.0 zapier validate --without-style +``` + +### Run the Zapier app against your own account + +`zapier invoke` runs one trigger, action or search on your computer, against the real Taskade API. Nothing goes to Zapier. + +1. Use a test account or a test workspace. The actions change real data. +2. Create a personal access token in Taskade under [Settings > API](https://www.taskade.com/settings/api). +3. Put the token in a `.env` file at the root of the repository. The app reads it as `authData_access_token`, the same field that holds the OAuth2 token on Zapier: + + ```bash + echo "authData_access_token='tskdp_your_token_here'" > .env + ``` + +4. Build, then invoke: + + ```bash + yarn build + npx --yes --package zapier-platform-cli@17.4.0 zapier invoke trigger get_all_spaces + npx --yes --package zapier-platform-cli@17.4.0 zapier invoke create create_task --inputData '{"project_id":"YOUR_PROJECT_ID","content":"Hello from my computer"}' + ``` + + The first command lists your workspaces and folders. The second command adds a task to a project. Use a test project. + +Git ignores `.env`. Never commit it, and never paste a token into an issue, a pull request, a test or a sample. If a token leaks, delete it in Settings > API and create a new one. + +### The n8n node + +Run these commands in the package folder. They are the same steps as the `n8n-node` job in [`.github/workflows/ci.yml`](.github/workflows/ci.yml). + +```bash +cd packages/n8n-nodes-taskade +npm ci --ignore-scripts +npm run lint +npm test # Vitest +npm run build # n8n-node build, to dist/ +``` + +CI also runs the n8n community package scanner on the source and on the packed tarball: + +```bash +npm install --no-save --ignore-scripts --prefix /tmp/n8n-scanner @n8n/scan-community-package@0.38.0 +npm run scan -- /tmp/n8n-scanner +``` + +The [package README](packages/n8n-nodes-taskade/README.md) describes the credentials, the operations and the trigger. + +### The Make app + +The Make app has no dependencies. Run the check from the root of the repository, the same step as [`.github/workflows/make-app.yml`](.github/workflows/make-app.yml): + +```bash +node packages/make-app-taskade/test/validate.mjs +``` + +The script compares every request of the app with the live Public API v2 spec. The [package README](packages/make-app-taskade/README.md) explains the layout and each check. + +## Rules + +- **One integration in each pull request.** A change to the Zapier app and a change to the n8n node go in two pull requests. +- **A key never changes.** A Zapier key (`create_task`), an n8n node name or operation value, and a Make module ID are public contracts after they ship. A saved Zap, workflow or scenario stores them. Add a new key, and never rename or remove an old one. +- **No secret and no personal data in the code.** Use made-up values in tests, fixtures and samples: `token`, `jane@example.com`, `A1b2C3d4E5f6G7h8`. Never use a real token, email address, name, or link to a private workspace. +- **Product names in full.** Write "Taskade Genesis" and "Taskade EVE", not "Genesis" or "EVE" alone. +- **Plan facts follow the API docs.** For example, webhooks need a Taskade Pro plan or higher. If an operation needs a plan, say so in its description, as the webhook triggers do. +- **Tests with each change.** A new trigger, action or search comes with a test that checks the request it sends. The [guide](docs/build-a-trigger-and-an-action.md#7-the-test) shows the pattern. +- **Commit messages** follow the history of this repository: `feat(zapier): Add ...`, `fix(n8n): ...`, `docs(readme): ...`. + +## Pull requests + +1. Create a branch from `master`. +2. Make your change, with tests. +3. Run the commands for the app that you changed (refer to [Set up](#set-up)). +4. Open a pull request. Say what changed, why, and which commands you ran. + +CI runs on every pull request. The `CI` workflow builds, lints and tests the Zapier app and the n8n node. The `Make app` workflow runs when a pull request changes `packages/make-app-taskade/`. + +## How a merged change reaches users + +A merge to `master` does not change any live integration. Each platform has its own release step. + +| App | Release | Who | +|---|---|---| +| Zapier | A maintainer bumps `version` in `package.json`, adds the notes to `CHANGELOG.md`, runs `zapier push`, tests the new version in a Zap, then runs `zapier promote` and `zapier migrate`. The steps are in the [README](README.md#release). No workflow deploys to Zapier. | Maintainer, by hand | +| n8n | A maintainer bumps `version` in `packages/n8n-nodes-taskade/package.json`, merges it, then pushes the tag `n8n-v` from `master`. [`publish-n8n.yml`](.github/workflows/publish-n8n.yml) checks that the tag matches the version and is on `master`, tests, builds, scans, and publishes to npm with provenance. n8n verification of the node is tracked in [#17](https://github.com/taskade/integrations/issues/17). | Maintainer, with a tag | +| Make | CI checks the app on each pull request and on `master`. A maintainer deploys it to Make and submits it for the Make review with the steps in [`SUBMISSION.md`](packages/make-app-taskade/SUBMISSION.md). It is not submitted yet: refer to [#33](https://github.com/taskade/integrations/issues/33). | Maintainer, by hand | + +## Questions and security + +- Product questions and account help: [taskade.com/contact](https://www.taskade.com/contact). +- API questions: [taskade.com/docs](https://www.taskade.com/docs). +- A security problem: report it through [taskade.com/contact](https://www.taskade.com/contact), not in a public issue. + +By contributing, you agree that your contribution is licensed under the [MIT License](LICENSE). diff --git a/README.md b/README.md index 872099f..90f1889 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,71 @@ # Taskade Integrations -The public source-of-truth for Taskade actions & triggers across automation platforms, starting with the official [Zapier integration](https://zapier.com/apps/taskade/integrations). It is built on the [Taskade public API](https://docs.taskade.com/), with one exception: the `task_due` trigger (see the note below). +The open source Taskade apps for Zapier, n8n and Make, built on the public Taskade API: use them, learn from them, add to them. -Building a Taskade integration for another platform (n8n, Activepieces, Make, Pipedream, or your own)? Everything here except `task_due` runs against the documented public API, so copy freely. Live OpenAPI specs: +**[Use an integration](#use-an-integration)** · **[Learn how it is built](docs/build-a-trigger-and-an-action.md)** · **[Add a trigger or an action](CONTRIBUTING.md)** -- v1 REST API: `https://www.taskade.com/api/v1` — [spec](https://www.taskade.com/api/documentation/v1/json) -- v2 Action API: `https://www.taskade.com/api/v2` — [spec](https://www.taskade.com/api/documentation/v2/json) +## Use an integration -## Status +| Platform | Where to get it | Status | +|---|---|---| +| Zapier | [Taskade on Zapier](https://zapier.com/apps/taskade/integrations) | Live. The public version (1.3.0) has every Zapier trigger, action and search in the table below. A maintainer deploys each version by hand, so the live app can lag this source. Source in [`src/`](src). | +| n8n | [`n8n-nodes-taskade` on npm](https://www.npmjs.com/package/n8n-nodes-taskade) | On npm, published from GitHub Actions with npm provenance. Self-hosted n8n installs it as a community node. Not verified by n8n yet: see [#17](https://github.com/taskade/integrations/issues/17). Source in [`packages/n8n-nodes-taskade`](packages/n8n-nodes-taskade). | +| Make | Not listed on Make yet | Source in [`packages/make-app-taskade`](packages/make-app-taskade), checked in CI. Not submitted yet: see [`SUBMISSION.md`](packages/make-app-taskade/SUBMISSION.md) and [#33](https://github.com/taskade/integrations/issues/33). | -| Platform | Status | +Two more platforms keep their own Taskade apps in their own repositories: [Taskade on Activepieces](https://www.activepieces.com/pieces/taskade) and [Taskade on Pipedream](https://pipedream.com/apps/taskade). + +## What ships today + +Every name below comes from the code in this repository. The [Zapier app reference](#zapier-app-reference) lists the Zapier keys. + +| Platform | Triggers | Actions | Searches | +|---|---|---|---| +| Zapier | Task Due, New Comment, Task Assigned, New Project, Project Assigned, Member Joined Project | Create Task, Complete Task, Update Task, Delete Task, Move Task, Set Task Due Date, Assign Task, Set Task Note, Set Task Custom Field, Create Project, Create Project From Template, Complete Project, Copy Project, Get Project Share Link, Run AI Agent, Create AI Agent, Generate AI Agent, Update AI Agent, Add Knowledge to AI Agent, Enable Public Agent Access, Run Automation, Custom API Call | Find Task, Find Project, Find AI Agent, Get Project Content | +| n8n | Taskade Trigger: Task Due, Comment Created, Task Assigned, Project Created, Project Assigned, Member Joined Project | Task: Create, Update, Complete, Reopen, Delete, Move, Assign, Set Note, Set Date, Set Custom Field. Project: Create, Create From Template, Copy, Complete, Restore, Enable Share Link. Agent: Prompt, Generate, Add Project Knowledge | Task: Get Many. Project: Get, Get Many. Agent: Get, Get Many. Workspace: Get Many. Folder: Get Many | +| Make | Watch Tasks Due, Watch New Comments, Watch Task Assignments, Watch New Projects, Watch Project Assignments, Watch New Project Members | Create a Task, Update a Task, Complete a Task, Delete a Task, Move a Task, Assign a Task, Set a Task Date, Set a Task Note, Set a Task Custom Field, Create a Project, Create a Project from a Template, Copy a Project, Get a Project, Prompt an AI Agent, Generate an AI Agent, Make an API Call | List Tasks, List Projects, List AI Agents | + +## Learn how it is built + +Start with [Build a trigger and an action](docs/build-a-trigger-and-an-action.md). It walks through one real trigger and one real action of the Zapier app, file by file, and then the same for the n8n node. + +```text +src/ the Zapier app (TypeScript) + index.ts registers every trigger, action and search by its key + authentication.ts OAuth2 with Taskade + client.ts one request helper for the v1 and v2 API + fields.ts shared dropdown fields (workspace, project, task) + triggers/ instant triggers, and hidden triggers that fill dropdowns + creates/ actions + searches/ searches + test/ Jest tests +packages/n8n-nodes-taskade/ the n8n node and the n8n trigger +packages/make-app-taskade/ the Make app +``` + +## Add a trigger or an action + +Read [CONTRIBUTING.md](CONTRIBUTING.md). It has the setup, the commands that CI runs, how to run the Zapier app against your own Taskade account, and the rules. To ask for a trigger or an action, [open a request](https://github.com/taskade/integrations/issues/new/choose). + +## What the public API offers today + +Everything in this repository uses the public Taskade API, except the Zapier `task_due` trigger. If the API can do it, an integration here can do it. + +| Area | Docs | |---|---| -| Zapier | Live: [Taskade on Zapier](https://zapier.com/apps/taskade/integrations). The public version (1.3.0) has every trigger, action and search in the table below. Deploys are manual, so the live app version can lag this source. | -| Activepieces | Live: [Taskade on Activepieces](https://www.activepieces.com/pieces/taskade) (`@activepieces/piece-taskade`). Activepieces maintains the piece in [its own repo](https://github.com/activepieces/activepieces). | -| Pipedream | Live: [Taskade on Pipedream](https://pipedream.com/apps/taskade). Pipedream maintains the components in [its own repo](https://github.com/PipedreamHQ/pipedream). | -| n8n | On npm: [`n8n-nodes-taskade`](https://www.npmjs.com/package/n8n-nodes-taskade), published from GitHub Actions with npm provenance. Self-hosted n8n installs it as a community node. Source in [`packages/n8n-nodes-taskade`](packages/n8n-nodes-taskade). Not verified by n8n yet: see [#17](https://github.com/taskade/integrations/issues/17). | -| Make | Source in [`packages/make-app-taskade`](packages/make-app-taskade) (Make Apps Editor local layout: OAuth2 and token connections, 6 instant triggers, 15 actions, 3 searches, a universal module). Not yet submitted: see [`SUBMISSION.md`](packages/make-app-taskade/SUBMISSION.md). | +| Start here: every API surface and the plans that have it | [API overview](https://www.taskade.com/docs/getting-started/api-overview) | +| Sign in with a personal access token or OAuth2 | [Authentication](https://www.taskade.com/docs/getting-started/authentication) | +| Webhook events: `task.due`, `task.assigned`, `comment.created`, `project.created`, `project.assigned`, `project.joined`. Pro plan and higher. | [Webhooks guide](https://www.taskade.com/docs/guides/webhooks) · [`POST /webhooks`](https://www.taskade.com/docs/actions/webhooks-post) | +| Tasks: create, update, complete, move, assign, dates, notes, custom fields | [Create task](https://www.taskade.com/docs/actions/create-task) · [List tasks](https://www.taskade.com/docs/actions/list-tasks) | +| Projects: create, copy, templates, share links, Markdown export | [Create project](https://www.taskade.com/docs/actions/create-project) · [Export project](https://www.taskade.com/docs/actions/export-project) | +| AI agents: create, generate, prompt, knowledge, public access | [Prompt agent](https://www.taskade.com/docs/actions/prompt-agent) · [List agents](https://www.taskade.com/docs/actions/list-agents) | +| Workspaces and folders | [List spaces](https://www.taskade.com/docs/actions/list-spaces) · [List folders](https://www.taskade.com/docs/actions/list-folders) | +| Full reference | [Action API v2](https://www.taskade.com/docs/actions) · [REST API v1](https://www.taskade.com/docs/rest) · [v2 spec](https://www.taskade.com/api/documentation/v2/json) · [v1 spec](https://www.taskade.com/api/documentation/v1/json) | + +A new instant trigger needs a new public webhook event first. [#10](https://github.com/taskade/integrations/issues/10) tracks the events that are not public yet. -## Zapier app capabilities +## Zapier app reference -All triggers are instant (webhooks). The 5 triggers on the public webhook-subscription API need a Taskade Pro plan or higher. Actions and searches do not need Pro. Run AI Agent and Generate AI Agent use AI credits, and Run Automation needs an automation with a webhook trigger, which also needs Pro. +All triggers are instant (webhooks). The triggers on the public webhook-subscription API need a Taskade Pro plan or higher. Actions and searches do not need Pro. Run AI Agent and Generate AI Agent use AI credits, and Run Automation needs an automation with a webhook trigger, which also needs Pro. | Type | Name | Key | Notes | |---|---|---|---| @@ -58,24 +104,13 @@ All triggers are instant (webhooks). The 5 triggers on the public webhook-subscr Hidden dropdown helpers (not user-facing): `get_all_spaces`, `get_all_projects`, `get_all_blocks`, `get_all_assignable_members`, `get_all_tasks`, `get_all_project_templates`, `get_all_agents`, `get_all_fields`. -Auth: OAuth2 (`www.taskade.com/oauth2/*`). The API also supports [Personal Access Tokens](https://www.taskade.com/settings/api) (`Authorization: Bearer tskdp_…`) for other platforms. +Auth: OAuth2 (`www.taskade.com/oauth2/*`). The API also accepts [personal access tokens](https://www.taskade.com/settings/api) (`Authorization: Bearer tskdp_…`), which the n8n node, the Make app and local tests use. > Note: only `task_due` still uses Taskade-internal webhook routes. The other instant triggers use the public webhook-subscription API, so other platforms can subscribe to the same events. -## Development - -Prerequisites: Node ≥ 18, Yarn, [Zapier CLI](https://docs.zapier.com/platform/build-cli/overview#quick-setup-guide). - -```bash -yarn install -yarn lint # eslint on src/ -yarn build # tsc -> lib/ -yarn test # builds, then validates the app against Zapier's official schema -``` +## Release -The test suite validates the full app definition with `zapier-platform-schema`'s `validateAppDefinition` — the same check `zapier validate` runs — so schema regressions fail in CI before they reach a deploy. - -### Release +A merged change does not reach users by itself. [CONTRIBUTING.md](CONTRIBUTING.md#how-a-merged-change-reaches-users) has the steps for each platform. For the Zapier app, a maintainer runs them: 1. Bump `version` in `package.json` to a number that `zapier versions` does not list yet 2. Add the release notes to `CHANGELOG.md` @@ -83,9 +118,7 @@ The test suite validates the full app definition with `zapier-platform-schema`'s 4. Test each new trigger, action and search in a Zap, then `zapier promote ` 5. `zapier migrate ` moves existing users to the new version. Start with a small percent and watch `zapier logs` -Deploying to the live Zapier app is a deliberate, manual step — never automatic on merge. - -### Logs +Deploying to the live Zapier app is a deliberate, manual step. It never happens on merge. ```bash zapier logs @@ -96,7 +129,7 @@ zapier logs --type=http --detailed ## Roadmap - Platform-agnostic operation manifest + per-platform codegen: the existing [n8n node](packages/n8n-nodes-taskade) and the Make app rendered from one source -- Move `task_due` to the public webhook-subscription API +- Move `task_due` to the public webhook API See the [Zapier Integration Guide](https://help.taskade.com/en/articles/8958540-zapier-integration) for end-user docs. diff --git a/docs/build-a-trigger-and-an-action.md b/docs/build-a-trigger-and-an-action.md new file mode 100644 index 0000000..2e3906b --- /dev/null +++ b/docs/build-a-trigger-and-an-action.md @@ -0,0 +1,450 @@ +# Build a trigger and an action + +This guide walks through one real trigger and one real action of the Taskade app for Zapier. Then it shows the same two parts in the n8n node. Every excerpt is copied from the files in this repository. Open the file beside the guide and read the full code there. + +When you finish, you know where each part lives, how it calls the public Taskade API, and how to test it. The last section is a checklist to add your own trigger or action. + +- [The Zapier app](#the-zapier-app) + - [1. Registration](#1-registration) + - [2. Authentication](#2-authentication) + - [3. The trigger: New Comment](#3-the-trigger-new-comment) + - [4. The action: Create Task](#4-the-action-create-task) + - [5. A dynamic dropdown](#5-a-dynamic-dropdown) + - [6. Deduplication](#6-deduplication) + - [7. The test](#7-the-test) + - [8. Run it against your own account](#8-run-it-against-your-own-account) +- [Add your own in 6 steps](#add-your-own-in-6-steps) +- [The n8n node](#the-n8n-node) + +## The Zapier app + +The Zapier app is TypeScript in [`src/`](../src). `tsc` compiles it to `lib/`, and Zapier loads `lib/index.js` through [`index.js`](../index.js). The Zapier name for an action is a "create". + +| Part | File | +|---|---| +| Registration of every trigger, create and search | [`src/index.ts`](../src/index.ts) | +| OAuth2 with Taskade | [`src/authentication.ts`](../src/authentication.ts) | +| Request helper for the v1 and v2 API | [`src/client.ts`](../src/client.ts) | +| Shared dropdown fields | [`src/fields.ts`](../src/fields.ts) | +| The trigger in this guide | [`src/triggers/publicWebhook.ts`](../src/triggers/publicWebhook.ts) | +| The action in this guide | [`src/creates/createTask.ts`](../src/creates/createTask.ts) | +| The dropdown in this guide | [`src/triggers/getAllProjects.ts`](../src/triggers/getAllProjects.ts) | +| The tests in this guide | [`src/test/triggerAndAction.test.ts`](../src/test/triggerAndAction.test.ts) | + +### 1. Registration + +[`src/index.ts`](../src/index.ts) imports each definition and puts it in `triggers`, `creates` or `searches` under its key: + +```ts + triggers: { + // hidden dropdown helpers + [GetAllBlocks.key]: GetAllBlocks, + [GetAllProjects.key]: GetAllProjects, + ... + // instant triggers + [TaskDue.key]: TaskDue, + [NewComment.key]: NewComment, + ... + }, + + creates: { + // tasks + [CreateTask.key]: CreateTask, + ... +``` + +The key is the public contract with every Zap that uses it. A Zap stores the key, so a renamed key breaks every Zap that uses the old one. Never rename or remove a key. + +### 2. Authentication + +The app uses OAuth2. [`src/authentication.ts`](../src/authentication.ts) points Zapier at the Taskade OAuth2 endpoints, and Zapier stores the token in `bundle.authData`: + +```ts +export const authentication = { + type: 'oauth2', + test: { + headers: { + accept: 'application/json', + authorization: 'bearer {{bundle.authData.access_token}}', + }, + url: 'https://www.taskade.com/oauth2/ping', + }, + oauth2Config: { + authorizeUrl: { + url: 'https://www.taskade.com/oauth2/authorize', +``` + +`CLIENT_ID` and `CLIENT_SECRET` belong to the Taskade app on Zapier. You do not need them to build or test. Each request sends the token as a bearer token. [`src/client.ts`](../src/client.ts) does this for every new trigger, action and search: + +```ts +export const request = async (z: ZObject, bundle: Bundle, opts: RequestOptions) => { + const base = opts.version === 'v2' ? BASE_V2 : BASE_V1; + const url = opts.path.startsWith('http') ? opts.path : `${base}${opts.path}`; + return z.request({ + url, + method: opts.method, + headers: { + Accept: 'application/json', + 'content-type': 'application/json', + authorization: `Bearer ${bundle.authData.access_token}`, + }, +``` + +`parseOk` in the same file turns an `{ ok: false, message }` answer from the API into a Zapier error that the user can read. + +### 3. The trigger: New Comment + +New Comment (`new_comment`) starts a Zap when someone adds a comment to a task. It is an instant trigger: Taskade sends each event to Zapier, and Zapier does not poll. + +The five public-webhook triggers share one factory, `makePublicWebhookTrigger`, in [`src/triggers/publicWebhook.ts`](../src/triggers/publicWebhook.ts). A new trigger of this kind is one call to the factory: + +```ts +export const NewComment = makePublicWebhookTrigger({ + key: 'new_comment', + noun: 'Comment', + label: 'New Comment', + description: 'Triggers when a comment is added to a task. Requires a Taskade Pro plan or higher.', + triggerType: 'comment.created', + sample: { + projectName: 'Customer Projects', + projectId: 'A1b2C3d4E5f6G7h8', + nodeId: '099630d4-267e-4b22-894b-08b69f3a4d79', + nodeText: 'Follow up with the client', + ... + }, + outputFields: [ + { key: 'projectName' }, + { key: 'projectId' }, + { key: 'nodeId', label: 'Task ID' }, + { key: 'nodeText', label: 'Task Text' }, + ... + ], +}); +``` + +- `key` is the contract with every Zap. `noun` and `label` are what users see in the Zap editor. +- `triggerType` is the name of the public webhook event. The [webhooks guide](https://www.taskade.com/docs/guides/webhooks#supported-events) lists every event. +- `sample` is the data that the Zap editor shows before the first real event. It has the same fields as a real delivery, with made-up values. +- `outputFields` gives each field a label in the Zap editor. + +The factory writes the four functions that Zapier calls for a hook trigger: + +```ts + const performSubscribe = async (z: ZObject, bundle: Bundle) => { + const response = await request(z, bundle, { + method: 'POST', + path: '/subscribeWebhook', + version: 'v2', + body: { targetUrl: bundle.targetUrl, triggerType: options.triggerType }, + }); + const data: ApiResponse = parseOk(z, response.json); + return data; // { ok: true, hookId } -> stored as bundle.subscribeData + }; + + const performUnsubscribe = async (z: ZObject, bundle: Bundle) => { + const response = await request(z, bundle, { + method: 'POST', + path: '/unsubscribeWebhook', + version: 'v2', + // @ts-ignore subscribeData is populated by Zapier with performSubscribe's result + body: { hookId: bundle.subscribeData.hookId }, + }); + return parseOk(z, response.json); + }; + + const perform = async (z: ZObject, bundle: Bundle) => [bundle.cleanedRequest]; + + // No public list endpoint exists for historical events; return the + // documented sample so users can set up their Zap before the first delivery. + const performList = async () => [options.sample]; +``` + +| Function | When Zapier calls it | What it does here | +|---|---|---| +| `performSubscribe` | The user turns the Zap on | Registers the Zap URL for the event with [`POST /subscribeWebhook`](https://www.taskade.com/docs/actions/subscribe-webhook) | +| `performUnsubscribe` | The user turns the Zap off | Removes the registration with [`POST /unsubscribeWebhook`](https://www.taskade.com/docs/actions/unsubscribe-webhook) | +| `perform` | Taskade sends an event | Returns the delivery as one trigger result | +| `performList` | The user tests the trigger in the Zap editor | Returns the sample | + +The API docs mark `subscribeWebhook` and `unsubscribeWebhook` as deprecated. Their replacement is the signed [`POST /webhooks`](https://www.taskade.com/docs/actions/webhooks-post) API. The [n8n trigger](#the-n8n-trigger) uses it. The Zapier triggers still use the older pair, and they still work. + +Webhook triggers need a Taskade Pro plan or higher. The description of each trigger says so, and a test checks it. + +### 4. The action: Create Task + +Create Task (`create_task`) adds a task to a project. Its file is [`src/creates/createTask.ts`](../src/creates/createTask.ts). + +The definition names the action and lists its input fields. Four fields are dynamic dropdowns. `content` is plain text, and the two dates use the `datetime` type: + +```ts +export default { + key: 'create_task', + noun: 'Task', + display: { + label: 'Create Task', + description: 'Creates a task in a Taskade project.', + hidden: false, + }, + operation: { + inputFields: [ + { + key: 'space_id', + label: 'Workspace or Folder', + type: 'string', + dynamic: 'get_all_spaces.id.name', + required: false, + ... + }, + { + key: 'project_id', + label: 'Project', + type: 'string', + dynamic: 'get_all_projects.id.title', + required: true, + ... + }, + ... + { + key: 'content', + label: 'Content', + type: 'string', + helpText: 'The content of the task.', + required: true, + ... + }, +``` + +`perform` reads the values from `bundle.inputData` and calls [`POST /api/v1/projects/{projectId}/tasks`](https://www.taskade.com/docs/rest/task-create): + +```ts + const createTaskResponse = await z.request({ + url: `https://www.taskade.com/api/v1/projects/${bundle.inputData.project_id}/tasks`, + method: 'POST', + headers: { + Accept: 'application/json', + 'content-type': 'application/json', + authorization: `Bearer ${bundle.authData.access_token}`, + }, + body: JSON.stringify({ + tasks: tasks, + }), + }); + + const createTaskData: CreateTasksResponse = createTaskResponse.json; + + if (!createTaskData.ok) { + throw new z.errors.Error(createTaskData.message, 'invalid_input', 400); + } +``` + +The API takes at most 2000 characters for each task, so `splitContentIntoChunks` cuts longer content into sibling tasks. If a start or end date is set, another call sets the date. If an assignee is set, another call assigns the task. The action returns the ID of the new task, and the sample has the same shape: + +```ts + sample: { + taskId: '099630d4-267e-4b22-894b-08b69f3a4d79', + }, + outputFields: [{ key: 'taskId' }], +``` + +`create_task` is older than [`src/client.ts`](../src/client.ts), so it writes its headers by hand. Newer actions use `request`, `parseOk` and the fields in [`src/fields.ts`](../src/fields.ts). [`src/creates/deleteTask.ts`](../src/creates/deleteTask.ts) is the shortest example, and a good template for a new action: + +```ts +const perform = async (z: ZObject, bundle: Bundle) => { + const response = await request(z, bundle, { + method: 'DELETE', + path: `/projects/${bundle.inputData.project_id}/tasks/${bundle.inputData.task_id}`, + }); + + parseOk(z, response.json); + + return { id: bundle.inputData.task_id as string, deleted: true }; +}; + +export default { + key: 'delete_task', + noun: 'Task', + display: { + label: 'Delete Task', + description: 'Deletes a task from a project.', + hidden: false, + }, + operation: { + inputFields: [spaceField(false), projectField(true), taskField('task_id', 'Task', true)], +``` + +### 5. A dynamic dropdown + +`dynamic: 'get_all_projects.id.title'` tells Zapier to fill the Project dropdown from the trigger with the key `get_all_projects`. Zapier uses `id` as the value and `title` as the label. That trigger is [`src/triggers/getAllProjects.ts`](../src/triggers/getAllProjects.ts). It is hidden, so users never see it as a trigger: + +```ts + key: 'get_all_projects', + noun: 'Projects', + display: { + label: 'Get All Projects', + description: "List all projects from a user's space.", + hidden: true, + }, +``` + +Zapier gives the dropdown trigger the values that the user already picked in the action. Thus the project list follows the Workspace or Folder field: + +```ts +const perform = async (z: ZObject, bundle: Bundle) => { + if (bundle.inputData.space_id == null) { + const response = await z.request({ + url: `https://www.taskade.com/api/v1/me/projects`, + ... + return data.items.map((i) => ({ id: i.id, title: i.name })); + } + + const response = await z.request({ + url: `https://www.taskade.com/api/v1/folders/${bundle.inputData.space_id}/projects`, +``` + +The trigger sets `canPaginate: true`, so Zapier can ask for more pages and passes the page number in `bundle.meta.page`. This trigger does not read `bundle.meta.page` yet, and it sends the same request for each page. + +### 6. Deduplication + +Zapier deduplicates the results of a polling trigger by the `id` field of each item. Refer to [Zapier deduplication](https://docs.zapier.com/platform/build/deduplication). The hidden dropdown triggers are polling triggers, and each item that they return has an `id`. + +The instant triggers in this app return each delivery as one result. They add no `id` and no other deduplication key. If you add a polling trigger, return an `id` on each item, or set `primary: true` on the output fields that make an item unique. + +### 7. The test + +The tests run with Jest and need no network and no Taskade account. [`src/test/triggerAndAction.test.ts`](../src/test/triggerAndAction.test.ts) tests the trigger and the action of this guide. It uses a stand-in for the Zapier `z` object that records each request and returns a fixed answer: + +```ts +const fakeZ = (json: unknown) => { + const calls: Array<{ url: string; method: string; body?: string }> = []; + const z = { + request: async (options: { url: string; method: string; body?: string }) => { + calls.push(options); + return { status: 200, json }; + }, + errors: { Error: class extends Error {} }, + } as unknown as ZObject; + return { z, calls }; +}; +``` + +A test calls `perform` and checks the request that the action sent: + +```ts + it('creates the task at the end of the project and returns its ID', async () => { + const { z, calls } = fakeZ({ ok: true, item: [{ id: 'task-1' }] }); + const result = await CreateTask.operation.perform( + z, + fakeBundle({ inputData: { project_id: 'project-1', content: 'Send the proposal' } }), + ); + expect(result).toEqual({ taskId: 'task-1' }); + expect(calls).toHaveLength(1); + expect(calls[0].url).toBe('https://www.taskade.com/api/v1/projects/project-1/tasks'); +``` + +[`src/test/app.test.ts`](../src/test/app.test.ts) checks the whole app. It runs the Zapier schema validation, checks that every key is registered, and checks the listing copy: labels in title case, trigger descriptions that start with "Triggers when", and the Pro plan notice on each webhook trigger. + +Run all tests: + +```bash +yarn test +``` + +### 8. Run it against your own account + +The Zapier CLI runs a trigger or an action on your computer with `zapier invoke`. Nothing goes to Zapier. `npx` runs the CLI with no global install. You need a Taskade account and a personal access token from [Settings > API](https://www.taskade.com/settings/api). The token works in place of the OAuth2 token, because both go in the same `Authorization: Bearer` header. + +Put the token in a `.env` file at the root of the repository. Git ignores `.env`. Never commit a token. + +```bash +echo "authData_access_token='tskdp_your_token_here'" > .env +yarn build +npx --yes --package zapier-platform-cli@17.4.0 zapier invoke trigger get_all_spaces +npx --yes --package zapier-platform-cli@17.4.0 zapier invoke create create_task --inputData '{"project_id":"YOUR_PROJECT_ID","content":"Hello from my computer"}' +``` + +The first command lists your workspaces and folders, the same list that fills the dropdown. The second command adds a task to a real project in your account. Use a test project. + +An instant trigger needs a public URL that Taskade can call, and `zapier invoke` runs on your computer. The tests in [`src/test/triggerAndAction.test.ts`](../src/test/triggerAndAction.test.ts) cover the subscribe, unsubscribe and delivery steps of an instant trigger. + +## Add your own in 6 steps + +- [ ] **1. Check the API.** Find the endpoint in the [Action API reference](https://www.taskade.com/docs/actions) or the [REST API reference](https://www.taskade.com/docs/rest). For an instant trigger, the event must be in the [list of webhook events](https://www.taskade.com/docs/guides/webhooks#supported-events). The Zapier app already uses every event in that list. A new event needs a change to the Taskade API first, so add a comment to [#10](https://github.com/taskade/integrations/issues/10). +- [ ] **2. Write one file.** Put an action in `src/creates/`, a search in `src/searches/` and a trigger in `src/triggers/`. Start from [`src/creates/deleteTask.ts`](../src/creates/deleteTask.ts). Pick a new key in `snake_case`. Write the label in title case. Start a trigger description with "Triggers when", start an action or search description with a verb that ends in "s", such as "Creates" or "Finds", and end it with a period. The tests in [`src/test/app.test.ts`](../src/test/app.test.ts) check these rules. Use `request` and `parseOk` from [`src/client.ts`](../src/client.ts) and the fields in [`src/fields.ts`](../src/fields.ts). Add a `sample` with the same keys as a real result, and `outputFields` with clear labels. +- [ ] **3. Register it.** Import the file in [`src/index.ts`](../src/index.ts) and add it to `triggers`, `creates` or `searches` under its key. +- [ ] **4. Test it.** Add a test in `src/test/` that calls `perform` with `fakeZ` and checks the request and the result. Add the key to the list in the matching "registers the expected ..." test in [`src/test/app.test.ts`](../src/test/app.test.ts). +- [ ] **5. Run the checks.** Run `yarn lint` and `yarn test`. Then run `zapier invoke` against a test project in your own account, as in [step 8](#8-run-it-against-your-own-account). +- [ ] **6. Open a pull request.** Add the new name to the tables in the [README](../README.md). Describe what you ran. A maintainer writes the release notes in `CHANGELOG.md` and releases the new version (refer to [CONTRIBUTING.md](../CONTRIBUTING.md#how-a-merged-change-reaches-users)). + +## The n8n node + +The n8n package is in [`packages/n8n-nodes-taskade`](../packages/n8n-nodes-taskade). It has two nodes: `Taskade` for actions and reads, and `Taskade Trigger` for events. Both call the Action API v2 through one helper, `taskadeApiRequest` in [`nodes/Taskade/GenericFunctions.ts`](../packages/n8n-nodes-taskade/nodes/Taskade/GenericFunctions.ts). Two credential types are in [`credentials/`](../packages/n8n-nodes-taskade/credentials): a personal access token and OAuth2. + +### One operation: Task > Create + +An n8n node describes its fields as data, and one `execute` function runs every operation. + +1. The operation is an option in [`nodes/Taskade/descriptions/TaskDescription.ts`](../packages/n8n-nodes-taskade/nodes/Taskade/descriptions/TaskDescription.ts): + + ```ts + { name: 'Create', value: 'create', action: 'Create a task', description: 'Create a task in a project' }, + ``` + +2. The Project field is a resource locator in [`nodes/Taskade/descriptions/SharedFields.ts`](../packages/n8n-nodes-taskade/nodes/Taskade/descriptions/SharedFields.ts). The user picks from a list, pastes a project URL, or types an ID. The list comes from the `searchProjects` method in [`nodes/Taskade/Taskade.node.ts`](../packages/n8n-nodes-taskade/nodes/Taskade/Taskade.node.ts), which calls `/listMyProjects`. It is the n8n form of a dynamic dropdown: + + ```ts + modes: [ + { + displayName: 'From List', + name: 'list', + type: 'list', + typeOptions: { searchListMethod: 'searchProjects', searchable: true }, + }, + ``` + +3. `executeOperation` in [`nodes/Taskade/Taskade.node.ts`](../packages/n8n-nodes-taskade/nodes/Taskade/Taskade.node.ts) sends the request to [`POST /createTask`](https://www.taskade.com/docs/actions/create-task): + + ```ts + const items = (await call('/createTask', { projectId, tasks: [task] })) + .items as IDataObject[]; + return items?.[0] ?? {}; + ``` + +4. [`test/Taskade.node.test.ts`](../packages/n8n-nodes-taskade/test/Taskade.node.test.ts) has a table with one row for each operation: the parameters, the endpoint and the body that the node must send. + + ```ts + { + name: 'task create at the project root', + params: { resource: 'task', operation: 'create', projectId: 'p1', content: 'Ship it', contentType: 'text/markdown', options: {} }, + endpoint: '/createTask', + body: { projectId: 'p1', tasks: [{ contentType: 'text/markdown', content: 'Ship it', placement: 'beforeend' }] }, + }, + ``` + +To add an operation, add the option and its fields in the description file, add a branch in `executeOperation`, and add a row to the test table. + +### The n8n trigger + +[`nodes/TaskadeTrigger/TaskadeTrigger.node.ts`](../packages/n8n-nodes-taskade/nodes/TaskadeTrigger/TaskadeTrigger.node.ts) uses the signed webhook API. When the user activates the workflow, `create` registers the n8n URL for one event with [`POST /webhooks`](https://www.taskade.com/docs/actions/webhooks-post) and keeps the signing secret: + +```ts + async create(this: IHookFunctions): Promise { + const targetUrl = this.getNodeWebhookUrl('default') as string; + const spaceIds = this.getNodeParameter('spaceIds', []) as string[]; + const response = await taskadeApiRequest.call(this, '/webhooks', { + targetUrl, + events: [this.getNodeParameter('event') as string], + spaceIds, + }); +``` + +`delete` removes the registration when the user deactivates the workflow. `webhook` runs for each delivery. It checks the `X-Taskade-Signature-V2` header with `isValidSignature` and answers HTTP 401 to a delivery with a wrong signature, or one more than 5 minutes old. [`test/TaskadeTrigger.node.test.ts`](../packages/n8n-nodes-taskade/test/TaskadeTrigger.node.test.ts) tests the signature check and each step of the webhook lifecycle. + +Run the n8n checks from the package folder: + +```bash +cd packages/n8n-nodes-taskade +npm ci --ignore-scripts +npm run lint +npm test +npm run build +``` diff --git a/src/test/triggerAndAction.test.ts b/src/test/triggerAndAction.test.ts new file mode 100644 index 0000000..a8009f7 --- /dev/null +++ b/src/test/triggerAndAction.test.ts @@ -0,0 +1,91 @@ +import { Bundle, ZObject } from 'zapier-platform-core'; + +import CreateTask from '../creates/createTask'; +import { NewComment } from '../triggers/publicWebhook'; + +// The walk-through in docs/build-a-trigger-and-an-action.md points at these tests. +// They run each perform function with a stand-in for the Zapier `z` object, so +// they need no network and no Taskade account. + +const fakeZ = (json: unknown) => { + const calls: Array<{ url: string; method: string; body?: string }> = []; + const z = { + request: async (options: { url: string; method: string; body?: string }) => { + calls.push(options); + return { status: 200, json }; + }, + errors: { Error: class extends Error {} }, + } as unknown as ZObject; + return { z, calls }; +}; + +const fakeBundle = (fields: Record) => + ({ authData: { access_token: 'token' }, inputData: {}, meta: {}, ...fields }) as unknown as Bundle; + +describe('trigger: new_comment', () => { + it('subscribes the Zap URL to the comment.created event', async () => { + const { z, calls } = fakeZ({ ok: true, hookId: 'hook-1' }); + const result = await NewComment.operation.performSubscribe( + z, + fakeBundle({ targetUrl: 'https://hooks.zapier.com/hooks/standard/1/abc/' }), + ); + expect(result).toEqual({ ok: true, hookId: 'hook-1' }); + expect(calls[0].url).toBe('https://www.taskade.com/api/v2/subscribeWebhook'); + expect(calls[0].method).toBe('POST'); + expect(JSON.parse(calls[0].body ?? '{}')).toEqual({ + targetUrl: 'https://hooks.zapier.com/hooks/standard/1/abc/', + triggerType: 'comment.created', + }); + }); + + it('unsubscribes with the hookId that the subscribe call returned', async () => { + const { z, calls } = fakeZ({ ok: true }); + await NewComment.operation.performUnsubscribe(z, fakeBundle({ subscribeData: { hookId: 'hook-1' } })); + expect(calls[0].url).toBe('https://www.taskade.com/api/v2/unsubscribeWebhook'); + expect(JSON.parse(calls[0].body ?? '{}')).toEqual({ hookId: 'hook-1' }); + }); + + it('turns one delivery into one trigger result', async () => { + const { z } = fakeZ({}); + const delivery = NewComment.operation.sample; + const result = await NewComment.operation.perform(z, fakeBundle({ cleanedRequest: delivery })); + expect(result).toEqual([delivery]); + }); + + it('has a sample for every output field', () => { + for (const { key } of NewComment.operation.outputFields) { + expect(NewComment.operation.sample).toHaveProperty(key as string); + } + }); +}); + +describe('action: create_task', () => { + it('creates the task at the end of the project and returns its ID', async () => { + const { z, calls } = fakeZ({ ok: true, item: [{ id: 'task-1' }] }); + const result = await CreateTask.operation.perform( + z, + fakeBundle({ inputData: { project_id: 'project-1', content: 'Send the proposal' } }), + ); + expect(result).toEqual({ taskId: 'task-1' }); + expect(calls).toHaveLength(1); + expect(calls[0].url).toBe('https://www.taskade.com/api/v1/projects/project-1/tasks'); + expect(JSON.parse(calls[0].body ?? '{}')).toEqual({ + tasks: [{ contentType: 'text/markdown', content: 'Send the proposal', placement: 'beforeend' }], + }); + }); + + it('splits content over 2000 characters into more than one task', async () => { + const { z, calls } = fakeZ({ ok: true, item: [{ id: 'task-1' }] }); + const content = `${'a'.repeat(1500)} ${'b'.repeat(1500)}`; + await CreateTask.operation.perform(z, fakeBundle({ inputData: { project_id: 'project-1', content } })); + const { tasks } = JSON.parse(calls[0].body ?? '{}'); + expect(tasks).toHaveLength(2); + }); + + it('shows the Taskade error message when the API refuses the request', async () => { + const { z } = fakeZ({ ok: false, message: 'Project not found' }); + await expect( + CreateTask.operation.perform(z, fakeBundle({ inputData: { project_id: 'missing', content: 'x' } })), + ).rejects.toThrow('Project not found'); + }); +});