n8n-nodes-periskop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Periskop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -0,0 +1,105 @@
+# n8n-nodes-periskop
+
+An [n8n](https://n8n.io) community node for **Periskop** — product discovery for
+AI agents and workflows.
+
+Periskop turns natural-language shopping intent into structured product results:
+recommendations, ranked alternatives, merchant product URLs, price/currency when
+available, caveats, no-match results, request IDs, and machine-readable errors.
+
+> **Discovery only.** Periskop does not buy products, process payments, create
+> merchant carts or checkout, reserve stock, or place orders, and it does not
+> guarantee live price or availability. Your users complete the purchase on the
+> merchant website. Every response includes an explicit `purchase_boundary`.
+
+## Node
+
+- **Node:** `Periskop`
+- **Operation:** `Run Shopping Discovery`
+- **Endpoint:** `POST https://mcp.periskop.ai/v1/mcp/shopping/discover`
+
+### Fields
+
+| Field | Required | Notes |
+|---|---|---|
+| Prompt | yes | Natural-language shopping intent |
+| Response Format | no | `simple` (default) or `full` |
+| Country | no | ISO country code, e.g. `PT` |
+| Currency | no | ISO currency code, e.g. `EUR` |
+| Language | no | BCP 47 tag, e.g. `en` |
+| Mode | no | `auto` (default), `browse`, `recommend`, `best`, `bundle` |
+| Max Results | no | 1–50 (default `3`) |
+| Store | no | Store id or natural store hint |
+| External User ID | no | Your own analytics id |
+| Previous Result ID | no | Optional prior result id for follow-up discovery |
+| Constraints (JSON) | no | e.g. `{"max_price": 200, "optimization": "best_quality"}` |
+
+The node returns the Periskop JSON response as-is (one output item per input
+item), so you can reference `result_id`, `request_id`, `items`, `caveats`,
+`purchase_boundary`, and `errors` directly in downstream nodes.
+
+## Credential
+
+- **Name:** `Periskop API`
+- **Field:** `API Key` (your `dp_...` key — create one at
+  <https://periskop.ai/developer/keys>)
+- The node sends `Authorization: Bearer <API Key>` automatically — do **not**
+  type the word `Bearer`.
+- **Credential test:** the credential is verified against `GET /v1/mcp/stores`,
+  an auth-safe, **non-billable** endpoint — testing credentials never burns
+  credits.
+- An optional **Base URL** field defaults to `https://mcp.periskop.ai` and only
+  needs changing for sandbox/self-hosted environments.
+
+## Installation
+
+### In n8n (GUI)
+
+Install via **Settings → Community Nodes → Install** and enter
+`n8n-nodes-periskop`.
+
+### Local development
+
+```bash
+# from integrations/n8n-nodes-periskop
+npm install
+npm run build      # tsc + copies the SVG icon into dist/
+npm run lint       # eslint-plugin-n8n-nodes-base checks
+
+# link into a local n8n install for manual testing
+npm link
+cd ~/.n8n/custom    # create this folder if it does not exist
+npm link n8n-nodes-periskop
+# restart n8n; the Periskop node now appears in the node panel
+```
+
+See the n8n docs on
+[running community nodes locally](https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/)
+for the authoritative, version-specific steps.
+
+## Example workflow
+
+1. **Manual Trigger**
+2. **Periskop → Run Shopping Discovery**
+   - Prompt: `best desk chair under 60€`
+   - Response Format: `simple`
+3. Inspect the output: `result_id`, `request_id`, `items[]`, `caveats`,
+   `purchase_boundary`.
+
+## Pricing
+
+Billed per successful request in EUR. Errors, rate limits, and hard no-match
+responses are not billed. See <https://periskop.ai/developer> for current
+pricing and any introductory credits.
+
+## Known limitations
+
+- One operation (`Run Shopping Discovery`) in this first version. Additional
+  operations may be added later.
+- A genuine no-result is a `200` with `answer_type: "no_match"`, not an error;
+  infrastructure failures surface in `errors[]` and/or as HTTP `4xx/5xx` with a
+  machine-readable `code`.
+
+## License
+
+MIT

package/dist/credentials/PeriskopApi.credentials.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PeriskopApi = void 0;
+class PeriskopApi {
+    constructor() {
+        this.name = 'periskopApi';
+        this.displayName = 'Periskop API';
+        this.documentationUrl = 'https://periskop.ai/developer';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Your Periskop API key (starts with dp_). Create one at https://periskop.ai/developer/keys. The node adds the "Bearer " prefix for you.',
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://mcp.periskop.ai',
+                description: 'Periskop API base URL. Change only for sandbox/self-hosted environments.',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/v1/mcp/stores',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.PeriskopApi = PeriskopApi;

package/dist/nodes/Periskop/Periskop.node.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Periskop = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+class Periskop {
+    constructor() {
+        this.description = {
+            displayName: 'Periskop',
+            name: 'periskop',
+            icon: 'file:periskop.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{ "Run Shopping Discovery" }}',
+            description: 'Product discovery for AI agents and workflows — turn a shopping prompt into structured product results. Discovery only: no checkout, payments, or stock reservation.',
+            defaults: {
+                name: 'Periskop',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'periskopApi',
+                    required: true,
+                },
+            ],
+            requestDefaults: {
+                baseURL: '={{$credentials.baseUrl}}',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            },
+            properties: [
+                {
+                    displayName: 'Operation',
+                    name: 'operation',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: 'Run Shopping Discovery',
+                            value: 'runShoppingDiscovery',
+                            action: 'Run a shopping discovery from a prompt',
+                            description: 'Turn a natural-language shopping prompt into structured product results',
+                        },
+                    ],
+                    default: 'runShoppingDiscovery',
+                },
+                {
+                    displayName: 'Prompt',
+                    name: 'prompt',
+                    type: 'string',
+                    typeOptions: { rows: 2 },
+                    default: '',
+                    required: true,
+                    placeholder: 'best desk chair under 60€',
+                    description: 'Natural-language shopping intent. The only required field.',
+                    displayOptions: {
+                        show: { operation: ['runShoppingDiscovery'] },
+                    },
+                },
+                {
+                    displayName: 'Response Format',
+                    name: 'responseFormat',
+                    type: 'options',
+                    options: [
+                        { name: 'Simple', value: 'simple' },
+                        { name: 'Full', value: 'full' },
+                    ],
+                    default: 'simple',
+                    description: 'Simple returns a compact, easy-to-render shape (recommended). Full returns the complete contract.',
+                    displayOptions: {
+                        show: { operation: ['runShoppingDiscovery'] },
+                    },
+                },
+                {
+                    displayName: 'Additional Fields',
+                    name: 'additionalFields',
+                    type: 'collection',
+                    placeholder: 'Add Field',
+                    default: {},
+                    displayOptions: {
+                        show: { operation: ['runShoppingDiscovery'] },
+                    },
+                    options: [
+                        {
+                            displayName: 'Constraints (JSON)',
+                            name: 'constraints',
+                            type: 'json',
+                            default: '',
+                            description: 'Optional constraints, e.g. {"max_price": 200, "optimization": "best_quality"}',
+                        },
+                        {
+                            displayName: 'Country',
+                            name: 'country',
+                            type: 'string',
+                            default: '',
+                            placeholder: 'PT',
+                            description: 'ISO country code. Defaults to the account default.',
+                        },
+                        {
+                            displayName: 'Currency',
+                            name: 'currency',
+                            type: 'string',
+                            default: '',
+                            placeholder: 'EUR',
+                            description: 'ISO currency code. Defaults to the account default.',
+                        },
+                        {
+                            displayName: 'External User ID',
+                            name: 'externalUserId',
+                            type: 'string',
+                            default: '',
+                            description: 'Your end-user identifier, for your own analytics',
+                        },
+                        {
+                            displayName: 'Language',
+                            name: 'language',
+                            type: 'string',
+                            default: '',
+                            placeholder: 'en',
+                            description: 'BCP 47 language tag',
+                        },
+                        {
+                            displayName: 'Max Results',
+                            name: 'maxResults',
+                            type: 'number',
+                            typeOptions: { minValue: 1, maxValue: 50 },
+                            default: 3,
+                            description: 'Maximum number of products to return (1-50)',
+                        },
+                        {
+                            displayName: 'Mode',
+                            name: 'mode',
+                            type: 'options',
+                            options: [
+                                { name: 'Auto', value: 'auto' },
+                                { name: 'Best', value: 'best' },
+                                { name: 'Browse', value: 'browse' },
+                                { name: 'Bundle', value: 'bundle' },
+                                { name: 'Recommend', value: 'recommend' },
+                            ],
+                            default: 'auto',
+                            description: 'Discovery mode. Leave on Auto to let Periskop infer it.',
+                        },
+                        {
+                            displayName: 'Previous Result ID',
+                            name: 'previousResultId',
+                            type: 'string',
+                            default: '',
+                            description: 'Optional prior result ID for follow-up discovery',
+                        },
+                        {
+                            displayName: 'Store',
+                            name: 'store',
+                            type: 'string',
+                            default: '',
+                            description: 'Store ID or natural store hint to scope the search',
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const operation = this.getNodeParameter('operation', i);
+                if (operation !== 'runShoppingDiscovery') {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unknown operation: ${operation}`, {
+                        itemIndex: i,
+                    });
+                }
+                const prompt = this.getNodeParameter('prompt', i).trim();
+                if (!prompt) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Prompt is required.', { itemIndex: i });
+                }
+                const responseFormat = this.getNodeParameter('responseFormat', i);
+                const additional = this.getNodeParameter('additionalFields', i, {});
+                const body = {
+                    prompt,
+                    response_format: responseFormat,
+                };
+                if (additional.country)
+                    body.country = additional.country;
+                if (additional.currency)
+                    body.currency = additional.currency;
+                if (additional.language)
+                    body.language = additional.language;
+                if (additional.mode && additional.mode !== 'auto')
+                    body.mode = additional.mode;
+                if (additional.maxResults)
+                    body.max_results = additional.maxResults;
+                if (additional.store)
+                    body.store = additional.store;
+                if (additional.externalUserId)
+                    body.external_user_id = additional.externalUserId;
+                if (additional.previousResultId)
+                    body.previous_result_id = additional.previousResultId;
+                if (additional.constraints) {
+                    let constraints = additional.constraints;
+                    if (typeof constraints === 'string' && constraints.trim() !== '') {
+                        try {
+                            constraints = JSON.parse(constraints);
+                        }
+                        catch (error) {
+                            throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Constraints must be valid JSON.', { itemIndex: i });
+                        }
+                    }
+                    if (constraints && typeof constraints === 'object') {
+                        body.constraints = constraints;
+                    }
+                }
+                const options = {
+                    method: 'POST',
+                    url: '/v1/mcp/shopping/discover',
+                    body,
+                    json: true,
+                };
+                const response = await this.helpers.httpRequestWithAuthentication.call(this, 'periskopApi', options);
+                returnData.push({
+                    json: response,
+                    pairedItem: { item: i },
+                });
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: { error: error.message },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.Periskop = Periskop;

package/dist/nodes/Periskop/Periskop.node.json

@@ -0,0 +1,18 @@
+{
+	"node": "n8n-nodes-periskop.periskop",
+	"nodeVersion": "1.0",
+	"codexVersion": "1.0",
+	"categories": ["AI", "Marketing", "Miscellaneous"],
+	"resources": {
+		"credentialDocumentation": [
+			{
+				"url": "https://periskop.ai/developer"
+			}
+		],
+		"primaryDocumentation": [
+			{
+				"url": "https://periskop.ai/developer/docs"
+			}
+		]
+	}
+}

package/dist/nodes/Periskop/periskop.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#0B0B0F"/>
+  <circle cx="29" cy="29" r="14" fill="none" stroke="#6EE7F9" stroke-width="4"/>
+  <line x1="39.5" y1="39.5" x2="52" y2="52" stroke="#6EE7F9" stroke-width="5" stroke-linecap="round"/>
+  <circle cx="29" cy="29" r="5" fill="#6EE7F9"/>
+</svg>

package/index.js

@@ -0,0 +1,4 @@
+// n8n loads nodes and credentials from the paths declared in package.json's
+// "n8n" field (dist/...). This file exists only so the package has a valid
+// "main" entry; it intentionally exports nothing.
+module.exports = {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "n8n-nodes-periskop",
+  "version": "0.1.0",
+  "description": "n8n community node for Periskop — product discovery for AI agents and workflows.",
+  "keywords": [
+    "n8n-community-node-package",
+    "periskop",
+    "product-discovery",
+    "shopping",
+    "shopping-discovery",
+    "ai-agents",
+    "workflow-automation"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Periskop-ai/n8n-nodes-periskop#readme",
+  "author": {
+    "name": "Periskop",
+    "url": "https://periskop.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Periskop-ai/n8n-nodes-periskop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Periskop-ai/n8n-nodes-periskop/issues"
+  },
+  "engines": {
+    "node": ">=18.10"
+  },
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc && gulp build:icons",
+    "dev": "tsc --watch",
+    "format": "prettier nodes credentials --write",
+    "lint": "eslint nodes credentials",
+    "lintfix": "eslint nodes credentials --fix",
+    "prepublishOnly": "npm run build && npm run lint -- --quiet"
+  },
+  "files": [
+    "dist"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "credentials": [
+      "dist/credentials/PeriskopApi.credentials.js"
+    ],
+    "nodes": [
+      "dist/nodes/Periskop/Periskop.node.js"
+    ]
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-n8n-nodes-base": "^1.16.3",
+    "gulp": "^5.0.0",
+    "n8n-workflow": "*",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.4"
+  },
+  "peerDependencies": {
+    "n8n-workflow": "*"
+  }
+}