initial commit: n8n community node for Documenso

Documenso node with 7 resources and 35 operations using the envelopes API:
- Document: find, get, create, create and send, update, delete, duplicate, download, send, resend
- Template: find, get, create, update, delete, duplicate, use
- Recipient: create, get, update, delete
- Field: create (placeholder text + coordinate + JSON modes), get, update, delete
- File: upload, download, update, delete
- Attachment: find, create, update, delete
- Folder: find, create, update, delete

DocumensoTrigger webhook node for document signing events.

Tooling: tsdown build, biome lint/format, docker compose dev, CI + release workflows.

Author: Mythie

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Build
+        run: bun run build

.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release & Publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'rc') }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Build
+        run: bun run build
+
+      - name: Determine dist-tag
+        id: dist-tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          if [[ "$VERSION" == *"alpha"* ]]; then
+            echo "tag=alpha" >> $GITHUB_OUTPUT
+          elif [[ "$VERSION" == *"beta"* ]]; then
+            echo "tag=beta" >> $GITHUB_OUTPUT
+          elif [[ "$VERSION" == *"rc"* ]]; then
+            echo "tag=rc" >> $GITHUB_OUTPUT
+          else
+            echo "tag=latest" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public --tag ${{ steps.dist-tag.outputs.tag }}

.gitignore

@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

CLAUDE.md

@@ -0,0 +1,115 @@
+---
+description: n8n community node for Documenso document signing
+globs: "*.ts, *.json"
+alwaysApply: true
+---
+
+# @documenso/n8n-nodes-documenso
+
+n8n community node package for the Documenso open source document signing platform. Uses the `@documenso/sdk-typescript` SDK internally, exposing it through n8n's node UI.
+
+## Commands
+
+- `bun install` — install dependencies
+- `bun run build` — build with tsdown (CJS output to dist/)
+- `bun run typecheck` — type-check with tsc --noEmit
+- `bun run check` — biome check --write (lint + format)
+- `bun run lint` — biome lint only
+- `bun run format` — biome format --write only
+- `bun run dev` — docker compose up (runs n8n with the node loaded at http://localhost:5678)
+
+After changes: `bun run build && docker compose restart` to see them in n8n.
+
+## Code Style
+
+- **Formatter**: Biome — 2-space indent, double quotes
+- **Block statements**: Always use braces (`if (x) { ... }`, never `if (x) ...`)
+- **`any` types**: Allowed (biome `noExplicitAny: off`) — unavoidable with n8n's `getNodeParameter` and SDK response types
+- **Imports**: Auto-organized by biome assist
+
+## Architecture
+
+### Source layout (`src/`)
+
+```
+src/
+  index.ts                              # Package exports
+  credentials/
+    DocumensoApi.credentials.ts         # API Key + Base URL credential
+  nodes/
+    Documenso/
+      Documenso.node.ts                 # Main node — resource/operation selector
+      Documenso.node.json               # Codex metadata
+      documenso.svg                     # Node icon
+      GenericFunctions.ts               # SDK client factory + error handling
+      actions/
+        router.ts                       # Dispatches resource+operation → per-item execute
+        document/                       # 10 ops: find, get, create, createAndSend, update, delete, duplicate, download, send, resend
+        template/                       # 7 ops: find, get, create, update, delete, duplicate, use
+        recipient/                      # 4 ops: create, get, update, delete
+        field/                          # 4 ops: create, get, update, delete
+        file/                           # 4 ops: upload, download, update, delete
+        attachment/                     # 4 ops: find, create, update, delete
+        folder/                         # 4 ops: find, create, update, delete
+    DocumensoTrigger/
+      DocumensoTrigger.node.ts          # Webhook trigger node
+```
+
+### Key design decisions
+
+- **Envelopes API only**: Document and Template resources both use `client.envelopes.*` under the hood. Document passes `type: "DOCUMENT"`, Template passes `type: "TEMPLATE"`. We do NOT use the older `client.documents.*` or `client.templates.*` SDK methods.
+- **Parameter naming**: Use `documentId`/`templateId` in user-facing params, map to `envelopeId` when calling the SDK.
+- **SDK is bundled**: tsdown inlines `@documenso/sdk-typescript` into the output via `noExternal`. Only `n8n-workflow` is external (provided by n8n at runtime). This means the published package has zero runtime dependencies.
+- **CJS output**: n8n requires CommonJS. tsdown outputs `.js` (not `.cjs`) via `outExtensions`.
+
+### Adding a new operation
+
+1. Create `src/nodes/Documenso/actions/<resource>/<operation>.operation.ts`
+2. Export `description: INodeProperties[]` with `displayOptions: { show: { resource: [...], operation: [...] } }`
+3. Export `async function execute(this: IExecuteFunctions, itemIndex: number): Promise<any>`
+4. Import and register in the resource's `index.ts` (add to `descriptions` array and `operations` map)
+5. If adding a new resource, also register in `Documenso.node.ts`, `router.ts`, and the resource options list
+
+### Operation file pattern
+
+```ts
+import type { IExecuteFunctions, INodeProperties } from "n8n-workflow";
+import { getDocumensoClient, handleDocumensoError } from "../../GenericFunctions";
+
+export const description: INodeProperties[] = [
+  {
+    displayName: "Document ID",
+    name: "documentId",
+    type: "string",
+    required: true,
+    default: "",
+    displayOptions: { show: { resource: ["document"], operation: ["myOp"] } },
+  },
+];
+
+export async function execute(this: IExecuteFunctions, itemIndex: number): Promise<any> {
+  const documentId = this.getNodeParameter("documentId", itemIndex) as string;
+  try {
+    const client = await getDocumensoClient(this);
+    return await client.envelopes.someMethod({ envelopeId: documentId });
+  } catch (error) {
+    handleDocumensoError(this, error, itemIndex);
+  }
+}
+```
+
+### UX conventions
+
+- Use **fixedCollection** with `multipleValues: true` instead of JSON inputs for structured data (recipients, fields, etc.)
+- Use user-friendly operation names: "Send" not "Distribute", "Resend" not "Redistribute"
+- Coordinates are **percentages** (0–100) of page width/height, not pixels
+- Field positioning supports both **placeholder text matching** (`{{signature}}`) and coordinate modes
+- The "Create and Send" operation is the happy path — upload PDF + recipients + fields + send in one step
+
+### Build
+
+tsdown bundles entry points to `dist/`. The `copy` config in `tsdown.config.ts` handles static assets (SVG icon, codex JSON). When adding a new node, add its entry to `tsdown.config.ts` and `package.json`'s `n8n.nodes` array.
+
+### Testing locally
+
+`docker compose up` mounts `dist/` and `package.json` into n8n's custom nodes directory. The node appears in n8n's palette at http://localhost:5678.