n8n-nodes-customerio 1.0.0

package/LICENSE

@@ -0,0 +1,46 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab.
+
+Licensor:
+Velocity BPA, LLC
+https://velobpa.com
+
+Licensed Work:
+This repository and all source code, documentation, and associated artifacts
+contained herein, including all n8n community nodes published by Velocity BPA.
+
+Additional Use Grant:
+You may use, modify, and run the Licensed Work free of charge for:
+- Personal use
+- Educational use
+- Research use
+- Internal business use, provided such use does not involve resale,
+  redistribution, or offering the Licensed Work as part of a commercial
+  product or service.
+
+Commercial Use Restriction:
+Commercial Use of the Licensed Work is prohibited without a valid
+Commercial License issued by the Licensor.
+
+Commercial Use includes, but is not limited to:
+- Use of the Licensed Work within any Software-as-a-Service (SaaS),
+  Platform-as-a-Service (PaaS), or hosted application that is sold,
+  licensed, or monetized in any form
+- Offering the Licensed Work as part of a managed services engagement
+- Bundling or redistributing the Licensed Work with a paid product
+- Reselling, sublicensing, or white-labeling the Licensed Work
+- Embedding the Licensed Work into any commercial automation platform,
+  integration product, or solution offering
+
+Change Date:
+January 1, 2030
+
+Change License:
+Apache License, Version 2.0
+
+For commercial licensing inquiries:
+licensing@velobpa.com
+
+Business Source License 1.1 full text:
+https://mariadb.com/bsl11/

package/README.md

@@ -0,0 +1,432 @@
+# n8n-nodes-customerio
+
+> **[Velocity BPA Licensing Notice]**
+>
+> This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).
+>
+> Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.
+>
+> For licensing information, visit https://velobpa.com/licensing or contact licensing@velobpa.com.
+
+A comprehensive n8n community node for [Customer.io](https://customer.io), the leading messaging automation platform for data-driven companies. This node provides 13 resource categories and 60+ operations for customer data management, event tracking, transactional messaging, broadcasts, campaigns, and CDP functionality.
+
+![n8n version](https://img.shields.io/badge/n8n-0.200+-blue)
+![Node version](https://img.shields.io/badge/node-18+-green)
+![License](https://img.shields.io/badge/license-BSL--1.1-blue)
+
+## Features
+
+- **Complete API Coverage**: Track API, App API, and Pipelines/CDP API
+- **13 Resource Categories**: People, Events, Segments, Customers, Campaigns, Broadcasts, Transactional, Newsletters, Messages, Activities, Exports, Objects, and Pipelines
+- **60+ Operations**: Full CRUD operations across all resources
+- **Transactional Messaging**: Send emails, push notifications, and SMS
+- **CDP Functionality**: Identify, track, page, screen, group, and alias operations
+- **B2B Support**: Object relationships for companies, accounts, and courses
+- **Webhook Triggers**: Real-time event notifications for all message types
+- **Regional Support**: US and EU data center endpoints
+
+## Installation
+
+### Community Nodes (Recommended)
+
+1. Open n8n
+2. Go to **Settings** → **Community Nodes**
+3. Click **Install a community node**
+4. Enter `n8n-nodes-customerio`
+5. Click **Install**
+
+### Manual Installation
+
+```bash
+# Navigate to your n8n installation directory
+cd ~/.n8n
+
+# Install the package
+npm install n8n-nodes-customerio
+```
+
+### Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/Velocity-BPA/n8n-nodes-customerio.git
+cd n8n-nodes-customerio
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link to n8n
+mkdir -p ~/.n8n/custom
+ln -s $(pwd) ~/.n8n/custom/n8n-nodes-customerio
+
+# Restart n8n
+```
+
+## Credentials Setup
+
+You'll need credentials from your Customer.io account:
+
+| Credential | Required | Description |
+|------------|----------|-------------|
+| Region | Yes | US or EU data center |
+| Site ID | Yes | Found in Settings → API Keys |
+| Track API Key | Yes | For data ingestion (Track API) |
+| App API Key | Yes | For management operations (App API) |
+
+### Getting Your API Keys
+
+1. Log in to your [Customer.io account](https://fly.customer.io)
+2. Go to **Settings** → **API Keys**
+3. Copy your **Site ID** and **Track API Key** from the Track API section
+4. Create an **App API Key** if you don't have one (requires Admin access)
+
+## Resources & Operations
+
+### People (Track API)
+Manage customer profiles and devices.
+
+| Operation | Description |
+|-----------|-------------|
+| Identify | Create or update a person |
+| Delete Person | Delete a person by ID |
+| Add Device | Add a mobile device token |
+| Delete Device | Remove a device token |
+| Suppress | Stop all messaging to a person |
+| Unsuppress | Resume messaging to a person |
+| Merge People | Merge two customer profiles |
+
+### Events (Track API)
+Track customer behavior and actions.
+
+| Operation | Description |
+|-----------|-------------|
+| Track | Track an event for a person |
+| Track Anonymous | Track an event without person ID |
+| Track Page View | Track a page view event |
+
+### Segments (App API)
+View and manage dynamic customer groups.
+
+| Operation | Description |
+|-----------|-------------|
+| List Segments | Get all segments |
+| Get Segment | Get segment by ID |
+| Get Segment Membership | Get people in a segment |
+
+### Customers (App API)
+Search and retrieve customer data.
+
+| Operation | Description |
+|-----------|-------------|
+| List Customers | List customers with filters |
+| Get Customer | Get customer by ID |
+| Search Customers | Search customers (Beta API) |
+| Get Customer Attributes | Get all attributes |
+| Get Customer Segments | Get customer's segments |
+| Get Customer Messages | Get messages sent to customer |
+| Get Customer Activities | Get activity history |
+| Export Customers | Export customer data |
+
+### Campaigns (App API)
+Manage automated campaign workflows.
+
+| Operation | Description |
+|-----------|-------------|
+| List Campaigns | Get all campaigns |
+| Get Campaign | Get campaign by ID |
+| Get Campaign Metrics | Get performance metrics |
+| Get Campaign Actions | Get campaign actions |
+| Get Campaign Triggers | Get trigger conditions |
+| List Campaign Messages | Get campaign messages |
+
+### Broadcasts (App API)
+Create and manage one-time broadcasts.
+
+| Operation | Description |
+|-----------|-------------|
+| List Broadcasts | Get all broadcasts |
+| Get Broadcast | Get broadcast by ID |
+| Create Broadcast | Create a new broadcast |
+| Trigger Broadcast | Trigger an API broadcast |
+| Get Broadcast Metrics | Get performance metrics |
+| Get Broadcast Actions | Get broadcast actions |
+| List Broadcast Triggers | Get triggers |
+
+### Transactional (App API)
+Send triggered individual messages.
+
+| Operation | Description |
+|-----------|-------------|
+| Send Email | Send transactional email |
+| Send Push | Send push notification |
+| Send SMS | Send SMS message |
+| Get Transactional Status | Check delivery status |
+
+### Newsletters (App API)
+Manage newsletter campaigns.
+
+| Operation | Description |
+|-----------|-------------|
+| List Newsletters | Get all newsletters |
+| Get Newsletter | Get newsletter by ID |
+| Get Newsletter Metrics | Get performance metrics |
+| Get Newsletter Contents | Get content variants |
+
+### Messages (App API)
+View sent messages and deliveries.
+
+| Operation | Description |
+|-----------|-------------|
+| List Messages | List sent messages |
+| Get Message | Get message details |
+| Get Message Templates | Get message templates |
+| Get Message Deliveries | Get delivery information |
+
+### Activities (App API)
+View activity logs and events.
+
+| Operation | Description |
+|-----------|-------------|
+| List Activities | List activities with filters |
+| Get Activity | Get activity by ID |
+
+### Exports (App API)
+Export customer and delivery data.
+
+| Operation | Description |
+|-----------|-------------|
+| List Exports | Get all exports |
+| Get Export | Get export status |
+| Create Export | Create a new export |
+| Download Export | Download completed export |
+
+### Objects (Track API)
+Manage B2B objects and relationships.
+
+| Operation | Description |
+|-----------|-------------|
+| Identify Object | Create/update an object |
+| Delete Object | Delete an object |
+| Add Relationship | Add person-object relationship |
+| Remove Relationship | Remove relationship |
+
+### Pipelines (CDP)
+Customer Data Platform operations.
+
+| Operation | Description |
+|-----------|-------------|
+| CDP Identify | Identify a user with traits |
+| CDP Track | Track an event |
+| CDP Page | Track a page view |
+| CDP Screen | Track a screen view (mobile) |
+| CDP Group | Associate user with a group |
+| CDP Alias | Create an alias to merge identities |
+
+## Trigger Node
+
+The Customer.io Trigger node receives webhook events for real-time notifications.
+
+### Supported Events
+
+| Event | Description |
+|-------|-------------|
+| Email Sent | Email was sent |
+| Email Delivered | Email was delivered |
+| Email Opened | Email was opened |
+| Email Clicked | Link in email was clicked |
+| Email Bounced | Email bounced |
+| Email Unsubscribed | Recipient unsubscribed |
+| Email Complained | Marked as spam |
+| Email Converted | Conversion tracked |
+| Push Sent | Push notification sent |
+| Push Opened | Push notification opened |
+| Push Clicked | Push notification clicked |
+| SMS Sent | SMS was sent |
+| SMS Delivered | SMS was delivered |
+| SMS Clicked | Link in SMS was clicked |
+| Webhook Sent | Webhook was sent |
+| Webhook Clicked | Webhook link was clicked |
+
+### Webhook Setup
+
+1. Add the Customer.io Trigger node to your workflow
+2. Copy the webhook URL from the node
+3. In Customer.io, go to **Data & Integrations** → **Integrations**
+4. Find **Reporting Webhooks** and add your webhook URL
+5. Select the events you want to receive
+
+## Usage Examples
+
+### Identify a Customer
+
+```json
+{
+  "resource": "people",
+  "operation": "identify",
+  "identifier": "user123",
+  "identifierType": "id",
+  "attributes": {
+    "email": "user@example.com",
+    "firstName": "John",
+    "lastName": "Doe",
+    "plan": "premium"
+  }
+}
+```
+
+### Track an Event
+
+```json
+{
+  "resource": "events",
+  "operation": "track",
+  "personId": "user123",
+  "eventName": "purchase_completed",
+  "eventData": {
+    "product": "Pro Plan",
+    "amount": 99.99,
+    "currency": "USD"
+  }
+}
+```
+
+### Send Transactional Email
+
+```json
+{
+  "resource": "transactional",
+  "operation": "sendEmail",
+  "transactionalMessageId": "1",
+  "to": "user@example.com",
+  "identifiers": {
+    "id": "user123"
+  },
+  "messageData": {
+    "orderNumber": "ORD-12345",
+    "total": "$99.99"
+  }
+}
+```
+
+### Trigger a Broadcast
+
+```json
+{
+  "resource": "broadcasts",
+  "operation": "triggerBroadcast",
+  "broadcastId": "123",
+  "recipientType": "emails",
+  "emails": ["user1@example.com", "user2@example.com"],
+  "broadcastData": {
+    "promoCode": "SAVE20"
+  }
+}
+```
+
+## Customer.io Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Person | A customer or user in your workspace |
+| ID | Primary identifier for a person |
+| Email | Can also be used as an identifier |
+| Anonymous ID | Identifier for users before they're known |
+| Event | An action or behavior you track |
+| Attributes | Properties stored on a person profile |
+| Segment | A dynamic group of people |
+| Campaign | An automated message sequence |
+| Broadcast | A one-time message to a segment |
+| Transactional | A triggered individual message |
+| Object | A non-person entity (company, course, etc.) |
+
+## API Rate Limits
+
+| API | Limit |
+|-----|-------|
+| Track API | 100 requests/second (soft limit) |
+| App API | 10 requests/second |
+| Transactional | 100 requests/second |
+| Broadcast Trigger | 1 request/10 seconds |
+
+## Error Handling
+
+The node provides detailed error messages for common issues:
+
+- **401 Unauthorized**: Invalid API credentials
+- **404 Not Found**: Resource doesn't exist
+- **429 Too Many Requests**: Rate limit exceeded
+- **500 Internal Server Error**: Customer.io server error
+
+## Security Best Practices
+
+1. **Use environment variables** for API keys in production
+2. **Enable webhook signature validation** for the trigger node
+3. **Limit API key permissions** to only what's needed
+4. **Rotate API keys** periodically
+5. **Use EU endpoints** for GDPR compliance if needed
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+```
+
+## Author
+
+**Velocity BPA**
+- Website: [velobpa.com](https://velobpa.com)
+- GitHub: [Velocity-BPA](https://github.com/Velocity-BPA)
+
+## Licensing
+
+This n8n community node is licensed under the **Business Source License 1.1**.
+
+### Free Use
+Permitted for personal, educational, research, and internal business use.
+
+### Commercial Use
+Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.
+
+For licensing inquiries:
+**licensing@velobpa.com**
+
+See [LICENSE](LICENSE), [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md), and [LICENSING_FAQ.md](LICENSING_FAQ.md) for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support
+
+- 📖 [Customer.io Documentation](https://customer.io/docs/)
+- 🐛 [Report Issues](https://github.com/Velocity-BPA/n8n-nodes-customerio/issues)
+- 💬 [n8n Community](https://community.n8n.io/)
+
+## Acknowledgments
+
+- [Customer.io](https://customer.io) for their excellent API documentation
+- [n8n](https://n8n.io) for the workflow automation platform
+- The n8n community for feedback and contributions

package/dist/credentials/CustomerIoApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class CustomerIoApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}
+//# sourceMappingURL=CustomerIoApi.credentials.d.ts.map

package/dist/credentials/CustomerIoApi.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomerIoApi.credentials.d.ts","sourceRoot":"","sources":["../../credentials/CustomerIoApi.credentials.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACX,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,MAAM,cAAc,CAAC;AAEtB,qBAAa,aAAc,YAAW,eAAe;IACpD,IAAI,SAAmB;IACvB,WAAW,SAAqB;IAChC,gBAAgB,SAAmC;IACnD,UAAU,EAAE,eAAe,EAAE,CA4C3B;IAEF,YAAY,EAAE,oBAAoB,CAGhC;IAEF,IAAI,EAAE,sBAAsB,CAU1B;CACF"}

package/dist/credentials/CustomerIoApi.credentials.js

@@ -0,0 +1,77 @@
+"use strict";
+/*
+ * Copyright (c) Velocity BPA, LLC
+ * Licensed under the Business Source License 1.1
+ * Commercial use requires a separate commercial license.
+ * See LICENSE file for details.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomerIoApi = void 0;
+class CustomerIoApi {
+    constructor() {
+        this.name = 'customerIoApi';
+        this.displayName = 'Customer.io API';
+        this.documentationUrl = 'https://customer.io/docs/api/';
+        this.properties = [
+            {
+                displayName: 'Region',
+                name: 'region',
+                type: 'options',
+                options: [
+                    {
+                        name: 'US',
+                        value: 'us',
+                    },
+                    {
+                        name: 'EU',
+                        value: 'eu',
+                    },
+                ],
+                default: 'us',
+                description: 'The region where your Customer.io account is hosted',
+            },
+            {
+                displayName: 'Site ID',
+                name: 'siteId',
+                type: 'string',
+                default: '',
+                required: true,
+                description: 'Your Customer.io Site ID (found in Settings > API Credentials)',
+            },
+            {
+                displayName: 'Track API Key',
+                name: 'trackApiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Customer.io Track API Key (found in Settings > API Credentials)',
+            },
+            {
+                displayName: 'App API Key',
+                name: 'appApiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Customer.io App API Key (found in Settings > API Credentials > App API)',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {},
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.region === "eu" ? "https://track-eu.customer.io" : "https://track.customer.io"}}',
+                url: '/auth',
+                method: 'GET',
+                headers: {
+                    Authorization: '=Basic {{Buffer.from($credentials.siteId + ":" + $credentials.trackApiKey).toString("base64")}}',
+                },
+            },
+        };
+    }
+}
+exports.CustomerIoApi = CustomerIoApi;
+//# sourceMappingURL=CustomerIoApi.credentials.js.map

package/dist/credentials/CustomerIoApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomerIoApi.credentials.js","sourceRoot":"","sources":["../../credentials/CustomerIoApi.credentials.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AASH,MAAa,aAAa;IAA1B;QACC,SAAI,GAAG,eAAe,CAAC;QACvB,gBAAW,GAAG,iBAAiB,CAAC;QAChC,qBAAgB,GAAG,+BAA+B,CAAC;QACnD,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,QAAQ;gBACrB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,IAAI;wBACV,KAAK,EAAE,IAAI;qBACX;oBACD;wBACC,IAAI,EAAE,IAAI;wBACV,KAAK,EAAE,IAAI;qBACX;iBACD;gBACD,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,qDAAqD;aAClE;YACD;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,gEAAgE;aAC7E;YACD;gBACC,WAAW,EAAE,eAAe;gBAC5B,IAAI,EAAE,aAAa;gBACnB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,sEAAsE;aACnF;YACD;gBACC,WAAW,EAAE,aAAa;gBAC1B,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,8EAA8E;aAC3F;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE,EAAE;SACd,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,kGAAkG;gBAC3G,GAAG,EAAE,OAAO;gBACZ,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACR,aAAa,EACZ,iGAAiG;iBAClG;aACD;SACD,CAAC;IACH,CAAC;CAAA;AAlED,sCAkEC"}

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

@@ -0,0 +1,6 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class CustomerIo implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+//# sourceMappingURL=CustomerIo.node.d.ts.map

package/dist/nodes/CustomerIo/CustomerIo.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomerIo.node.d.ts","sourceRoot":"","sources":["../../../nodes/CustomerIo/CustomerIo.node.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACX,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EACpB,MAAM,cAAc,CAAC;AAmBtB,qBAAa,UAAW,YAAW,SAAS;IAC3C,WAAW,EAAE,oBAAoB,CAkI/B;IAEI,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;CA4EvE"}