n8n-nodes-linq 3.1.2 → 4.0.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Alex
+Copyright (c) 2026 Everyday Workflows
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,150 +1,148 @@
 # n8n-nodes-linq
 
-Linq Partner API (v2) community node for n8n. This node lets you manage chats, messages (with attachments), phone numbers, webhooks, and contacts in Linq from your n8n workflows.
+Community node for the Linq Partner API v3 in n8n. Use this node to manage chats, messages, attachments, phone numbers, webhooks, and contacts from your workflows.
 
-- Package: `n8n-nodes-linq`
-- Node icon: included (SVG)
-- API version: v2
-- Auth: Integration Token (`X-LINQ-INTEGRATION-TOKEN`)
+**Ownership:** The Linq Partner API is owned and operated by Linq (https://linqapp.com/). This repository is community-maintained by Everyday Workflows.
+
+**Disclaimer:** This is a community-built integration. It is not affiliated with, endorsed by, or supported by Linq App Inc.
+
+**Acceptable use:** Users are responsible for complying with Linq’s Acceptable Use Policy and Apple’s Business Chat guidelines. Automated messaging should only be used for transactional or opted‑in communications.
+
+## Quick links
+
+- Usage guide: [docs/usage.md](docs/usage.md)
+- API reference (v3): [docs/api-reference.md](docs/api-reference.md)
+- OpenAPI spec: [V3.yaml](V3.yaml)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+- License: [LICENSE.md](LICENSE.md)
+
+## Requirements
+
+- Node.js >= 20.15
+- n8n compatible with `n8n-workflow` ^1.120.7
 
 ## Installation (in n8n)
 
 - Using the n8n UI:
-  1) Settings → Community Nodes → Install
-  2) Enter: `n8n-nodes-linq`
-  3) Restart n8n if prompted
+  1. Settings → Community Nodes → Install
+  2. Enter: `n8n-nodes-linq`
+  3. Restart n8n if prompted
 
 - Headless / environment variable:
   - Add `n8n-nodes-linq` to `N8N_COMMUNITY_PACKAGES` (or install with npm in your instance) and restart n8n.
 
 ## Credentials
 
-Create a new credential of type "Linq API" and set your Integration Token:
+Create a new credential of type **Linq API**:
 
-- Header used: `X-LINQ-INTEGRATION-TOKEN: <your token>`
-- The field is hidden in the UI (password type).
+- **API Token**: Linq Partner API token used as `Authorization: Bearer <token>`
+- **Webhook Signing Secret**: Required for Linq Trigger signature verification
+  - This is returned **only once** when a webhook subscription is created. Store it securely.
 
-Where it's defined:
-- [class LinqApi implements ICredentialType](credentials/LinqApi.credentials.ts:1)
+Where it’s defined:
+
+- [LinqApi.credentials.ts](credentials/LinqApi.credentials.ts:1)
 
 ## Node usage
 
-Add the "Linq" node to your workflow. The node provides Resources and Operations that map 1:1 to the documented Linq Partner API endpoints.
+Add the **Linq** node to your workflow. Operations map to Linq Partner API v3 endpoints.
 
-- Node implementation:
-  - [class Linq implements INodeType](nodes/Linq/Linq.node.ts:1)
-  - Icon is configured at the node-level: `icon: 'file:linq.svg'`
-  - SVG file: [linq.svg](nodes/Linq/linq.svg:1)
+- Node implementation: [Linq.node.ts](nodes/Linq/Linq.node.ts:1)
+- Icon: [linq.svg](nodes/Linq/linq.svg:1)
 
 ### Supported resources and operations
 
-The node implements all endpoints from your Linq Partner API documentation (v2):
-
-- Resource: Chat
-  - Operations:
-    - Get Many → GET `/chats` (requires `phone_number`; pagination supported)
-    - Get One → GET `/chats/:id`
-    - Find → GET `/chats/find` (requires your `phone_number` and `phone_numbers[]` of participants)
-    - Create → POST `/chats` (requires `send_from`, supports group chats via `phone_numbers[]`, optional display name, initial `message.text`)
-    - Share Contact → POST `/chats/{chat_id}/share_contact` (chat_id required; feature must be enabled by Linq)
-
-- Resource: Chat Message
-  - Operations:
-    - Get Many → GET `/chats/{chat_id}/chat_messages`
-    - Get One → GET `/chat_messages/:id`
-    - Create → POST `/chats/{chat_id}/chat_messages` (supports `text`, optional `attachment_urls[]`, optional `idempotency_key`)
-    - Delete → DELETE `/chat_messages/:id`
-    - Edit → POST `/chat_messages/:id/edit` (`text`)
-    - React → POST `/chat_messages/:id/reactions` (`reaction`)
-    - Get Reaction → GET `/chat_message_reactions/:reaction_id`
-
-- Resource: Phone Number
-  - Operations:
-    - Get Many → GET `/phone_numbers`
-    - Update → PUT `/phone_numbers/:id` (optional `forward_to`, optional `label`)
-
-- Resource: Webhook Subscription
-  - Operations:
-    - Get Many → GET `/webhook_subscriptions`
-    - Get One → GET `/webhook_subscriptions/:id`
-    - Create → POST `/webhook_subscriptions`
-    - Update → PUT `/webhook_subscriptions/:id`
-    - Delete → DELETE `/webhook_subscriptions/:id`
-
-- Resource: Contact
-  - Operations:
-    - Create → POST `/contacts`
-    - Get One → GET `/contacts/:id`
-    - Update → PUT `/contacts/:id`
-    - Delete → DELETE `/contacts/:id`
-
-### Linq Trigger Node
-
-Add the "Linq Trigger" node to automatically start workflows when Linq events occur. The node automatically registers a webhook with Linq when the workflow is activated.
-
-- Supported Events:
-  - Message Sent (`message.sent`)
-  - Message Received (`message.received`)
-  - Message Read (`message.read`)
-  - Call Completed (`call.completed`)
-  - Contact Created (`contact.created`)
-  - Contact Updated (`contact.updated`)
-  - Contact Deleted (`contact.deleted`)
-
-- Configuration:
-  1. Add the "Linq Trigger" node to your workflow
-  2. Select which events should trigger the workflow
-  3. Activate the workflow (this registers the webhook with Linq)
-  4. Linq will send events to your workflow when they occur
-
-- Security:
-  - The node verifies the signature of incoming events using HMAC-SHA256
-  - Requires the same Linq API credentials as the main node
-
-### Example workflows
-
-1) Send a group message
-- Resource: Chat
-- Operation: Create
+**Chat**
+
+- Get Many → `GET /v3/chats` (requires `from`, supports cursor/limit)
+- Get One → `GET /v3/chats/{chatId}`
+- Find → `GET /v3/chats` (with `from` + `phone_numbers[]`)
+- Create → `POST /v3/chats`
+- Share Contact → `POST /v3/chats/{chatId}/share_contact_card`
+
+**Chat Message**
+
+- Get Many → `GET /v3/chats/{chatId}/messages`
+- Get One → `GET /v3/messages/{messageId}`
+- Create → `POST /v3/chats/{chatId}/messages`
+- Delete → `DELETE /v3/messages/{messageId}`
+- React → `POST /v3/messages/{messageId}/reactions`
+
+**Phone Number**
+
+- Get Many → `GET /v3/phonenumbers`
+- Update → `PUT /v3/phonenumbers/{phoneNumberId}`
+
+**Webhook Subscription**
+
+- Get Many → `GET /v3/webhook-subscriptions`
+- Get One → `GET /v3/webhook-subscriptions/{subscriptionId}`
+- Create → `POST /v3/webhook-subscriptions`
+- Update → `PUT /v3/webhook-subscriptions/{subscriptionId}`
+- Delete → `DELETE /v3/webhook-subscriptions/{subscriptionId}`
+
+**Contact (extension)**
+
+- Create → `POST /v3/contacts`
+- Get One → `GET /v3/contacts/{contactId}`
+- Update → `PUT /v3/contacts/{contactId}`
+- Delete → `DELETE /v3/contacts/{contactId}`
+
+**Chat Message (extension)**
+
+- Edit → `POST /v3/messages/{messageId}/edit`
+- Get Reaction → `GET /v3/chat_message_reactions/{reactionId}`
+
+> **Note:** The “extension” endpoints above are currently implemented in the node but are not present in `V3.yaml`. They will be aligned once the spec is updated.
+
+## Linq Trigger Node
+
+Add the **Linq Trigger** node to start workflows when Linq events occur. The trigger automatically registers a webhook with Linq when the workflow is activated.
+
+**Supported Events**
+
+- `message.sent`
+- `message.received`
+- `message.read`
+- `call.completed`
+- `contact.created`
+- `contact.updated`
+- `contact.deleted`
+
+**Security**
+
+- The trigger verifies Linq webhooks using HMAC-SHA256
+- Uses `X-Webhook-Timestamp` + raw request body for the signature payload: `{timestamp}.{payload}`
+- Requires the **Webhook Signing Secret** from credentials
+
+## Examples
+
+### Send a group message
+
+- Resource: Chat → Create
 - Fields:
   - Send From (required): `+13175551234`
   - Display Name (optional): `Project A`
   - Phone Numbers: `+13341234567, +13347654321`
   - Message Text: `Hello from n8n!`
 
-2) Create a contact
-- Resource: Contact
-- Operation: Create
-- Fields:
-  - First Name: `John`
-  - Last Name: `Doe`
-  - Email: `john@example.com`
-  - Phone Number: `+15551234567`
-3) Manage webhook subscriptions
-- Resource: Webhook Subscription
-- Operation: Create
+### Create a webhook subscription
+
+- Resource: Webhook Subscription → Create
 - Fields:
   - Webhook URL: `https://example.com/webhooks/linq`
   - Events: `message.sent, message.received, contact.created`
-  - Version: `2`
   - Active: `true`
 
-4) Update phone number forwarding
-- Resource: Phone Number
-- Operation: Update
-- Fields:
-  - Phone Number ID: `<id>`
-  - Forward To (optional): `+15551230000`
-  - Label (optional): `Support Line`
-
 ## Development
 
 Requirements:
-- Node.js ≥ 20
-- npm or pnpm (npm commands shown below)
-- n8n local instance if testing end-to-end
+
+- Node.js >= 20
+- npm or pnpm (npm commands below)
 
 Install and build:
+
 ```bash
 cd n8n-nodes-linq
 npm install
@@ -152,7 +150,8 @@ npm run build
 npm run lint
 ```
 
-Local link for testing in a local n8n:
+Local link for testing in n8n:
+
 ```bash
 # in this folder
 npm link
@@ -162,33 +161,21 @@ npm link n8n-nodes-linq
 ```
 
 Project files of interest:
+
 - Node: [Linq.node.ts](nodes/Linq/Linq.node.ts:1)
+- Trigger: [LinqTrigger.node.ts](nodes/LinqTrigger/LinqTrigger.node.ts:1)
 - Credentials: [LinqApi.credentials.ts](credentials/LinqApi.credentials.ts:1)
-- Gulp (copies icons): [gulpfile.js](gulpfile.js:1)
+- Gulp (icons): [gulpfile.js](gulpfile.js:1)
 - TypeScript config: [tsconfig.json](tsconfig.json:1)
 - Index shim: [index.js](index.js:1)
 
 ## Publishing to npm
 
-1) Ensure metadata is correct in [package.json](package.json:1)
-   - name: `n8n-nodes-linq`
-   - version: increment for each release, e.g. `0.1.0`
-   - author: `"alexautomates"`
-   - keywords include: `n8n-community-node-package`
-   - `files: ["dist"]` to publish only built files
-   - `n8n` block lists built nodes and credentials in `dist/`
-
-2) Build and publish:
 ```bash
 npm run build
 npm publish --access public
 ```
 
-3) Users can install from the n8n UI (Community Nodes) by typing `n8n-nodes-linq`.
-
-## Icon / Branding
-
-- Icon file is included at: [nodes/Linq/linq.svg](nodes/Linq/linq.svg:1)
-- Node description references it as `icon: 'file:linq.svg'`, so it renders in the n8n UI.
-
 ## License
+
+MIT — see [LICENSE.md](LICENSE.md).

package/dist/credentials/LinqApi.credentials.js

@@ -2,30 +2,38 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LinqApi = void 0;
 class LinqApi {
-    constructor() {
-        this.name = 'linqApi';
-        this.displayName = 'Linq API';
-        this.documentationUrl = 'https://apidocs.linqapp.com/reference/';
-        this.properties = [
-            {
-                displayName: 'Integration Token',
-                name: 'integrationToken',
-                type: 'string',
-                default: '',
-                description: 'Your Linq Integration Token',
-                typeOptions: {
-                    password: true,
-                },
+    name = 'linqApi';
+    displayName = 'Linq API';
+    documentationUrl = 'https://apidocs.linqapp.com/reference/';
+    properties = [
+        {
+            displayName: 'API Token',
+            name: 'integrationToken',
+            type: 'string',
+            default: '',
+            description: 'Your Linq Partner API token (Bearer)',
+            typeOptions: {
+                password: true,
             },
-        ];
-        this.authenticate = {
-            type: 'generic',
-            properties: {
-                headers: {
-                    Authorization: 'Bearer {{$credentials.integrationToken}}',
-                },
+        },
+        {
+            displayName: 'Webhook Signing Secret',
+            name: 'webhookSigningSecret',
+            type: 'string',
+            default: '',
+            description: 'Signing secret returned when creating a webhook subscription (required for Linq Trigger)',
+            typeOptions: {
+                password: true,
             },
-        };
-    }
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                Authorization: 'Bearer {{$credentials.integrationToken}}',
+            },
+        },
+    };
 }
 exports.LinqApi = LinqApi;

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

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