n8n-nodes-orbitpage 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+## 0.1.0 - 2026-08-04
+
+- Add guided access to all 84 OrbitPage Automation REST API operations.
+- Add automatic `ETag` acquisition for revision-controlled writes.
+- Add complete direct video and protected Shop-file upload workflows.
+- Add an advanced custom API request operation.
+- Add polling triggers for workspace, publication, domain and Shop changes.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paolo Ronco
+
+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,229 @@
+# n8n-nodes-orbitpage
+
+[![CI](https://github.com/paoloronco/n8n-nodes-orbitpage/actions/workflows/ci.yml/badge.svg)](https://github.com/paoloronco/n8n-nodes-orbitpage/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/n8n-nodes-orbitpage.svg)](https://www.npmjs.com/package/n8n-nodes-orbitpage)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
+
+Community nodes for managing a hosted OrbitPage end to end from n8n. The
+package implements every operation in the OrbitPage Automation REST API, adds
+safe automatic revision handling, supports direct binary uploads, and includes
+a polling trigger for important workspace state changes.
+
+## Nodes
+
+### OrbitPage
+
+An action node with guided resources for:
+
+- workspace and complete draft;
+- page blocks, profile, theme and subpages;
+- menu, privacy, public text files and sitemap;
+- publication, version history and managed backups;
+- media, custom domains and analytics;
+- reviewed AI plan/commit flows;
+- Shop products, appearance, publishing and protected files;
+- newsletter SMTP, subscribers and campaigns;
+- team members, invitations and billing;
+- protected operator CRM, promotion, moderation and tenant operations;
+- relative custom API requests for forward-compatible access.
+
+The guided catalog contains all 84 operations in the public OpenAPI contract.
+See [the complete operation matrix](docs/OPERATIONS.md).
+
+### OrbitPage Trigger
+
+A polling trigger that starts a workflow when one of these states changes:
+
+- workspace revision;
+- publication status;
+- custom-domain status;
+- Shop state.
+
+The first production poll establishes a baseline and emits nothing unless
+**Emit Initial State** is enabled. A manual test always returns the current
+state.
+
+## Installation
+
+### n8n Community Nodes UI
+
+Open **Settings → Community Nodes**, choose **Install**, then enter:
+
+```text
+n8n-nodes-orbitpage
+```
+
+Restart self-hosted n8n if your installation requires it. Verified community
+node availability on n8n Cloud depends on the n8n review process.
+
+### Self-hosted command line
+
+From the n8n data directory:
+
+```bash
+npm install n8n-nodes-orbitpage
+```
+
+Use Node.js 22 or newer.
+
+## Credentials
+
+1. In OrbitPage, open **Dashboard → Account → Personal API tokens**.
+2. Create one token for one workflow and environment.
+3. Grant only the scopes required by the selected operations.
+4. Copy the `op_pat_...` value immediately; OrbitPage shows it only once.
+5. In n8n, create an **OrbitPage API** credential and paste the token.
+
+For `/operator` operations, create a separate 30-day token in the protected
+OrbitPage operator console and choose **Protected Operator Token** in the n8n
+credential. Never reuse an operator credential in tenant workflows.
+
+The default Base URL is `https://orbitpage.com`. Change it only when OrbitPage
+support provides a staging URL. HTTP is accepted only for localhost development.
+
+## Safe revision-controlled writes
+
+OrbitPage protects draft writes with optimistic concurrency. For block,
+profile, theme, page, settings and restore operations, the node defaults to
+**Fetch Latest Automatically**:
+
+1. it reads the related resource;
+2. captures the response `ETag` or numeric revision;
+3. sends that value as `If-Match` with the write.
+
+Choose **Enter Manually** only when an earlier node already read the state and
+you intentionally want a conflict if anything changed afterward. A `409`
+response should lead back to a new read; do not retry a stale write blindly.
+
+Profile, theme, pages and supported settings update the draft by default.
+Enable **Publish Immediately** for a single eligible mutation, or make several
+draft changes and finish with **Publication → Publish Page**. Block `PATCH` and
+`PUT` operations publish immediately by API design.
+
+## Binary uploads
+
+### Video media
+
+Choose **Media → Upload Video Binary**. The node:
+
+1. reads an MP4 or WebM binary field from the input item;
+2. reserves a temporary upload with OrbitPage;
+3. sends bytes directly to the signed storage URL without forwarding the
+   OrbitPage bearer token;
+4. finalizes and registers the asset;
+5. attempts to abort the reservation if upload or finalization fails.
+
+### Protected Shop files
+
+Choose **Shop → Upload Product File Binary**, provide the digital-product ID
+and the input binary field. The node performs the same reserve/upload/finalize
+sequence for supported protected product files.
+
+Signed upload URLs expire quickly. Keep the three steps inside this compound
+operation unless a workflow specifically needs the lower-level reserve and
+finalize actions.
+
+## AI workflows
+
+Use **AI → Plan Changes** to produce a validated preview without changing the
+page. Review the returned operations and keep its `previewToken`, then call
+**AI → Commit Changes** with that exact token. Put `"publish": true` in the
+commit body only when the workflow is authorized to make the result public.
+
+An OpenAI provider key is not an OrbitPage credential and must never be placed
+in this node.
+
+## Custom API requests
+
+**Advanced → Custom API Request** accepts a method, a path relative to
+`/api/v1`, query parameters, a JSON body and an optional `If-Match` value.
+Absolute URLs, query strings inside the path and dot segments are rejected so
+the credential cannot be redirected to a different endpoint or host.
+
+Use a guided operation whenever one exists: it documents the required scope,
+path fields and revision behavior directly in the editor.
+
+## Output and item linking
+
+Each input item produces one linked output item. The default output is the API
+response body. Enable **Include Response Headers and Status** to receive:
+
+```json
+{
+  "body": {},
+  "headers": {},
+  "statusCode": 200
+}
+```
+
+This is useful when a later node needs `ETag`, `Retry-After` or other response
+metadata. **Continue On Fail** returns an error item linked to the failing input.
+
+## Security practices
+
+- Store tokens only in n8n credentials, never workflow JSON or expressions.
+- Use one token per workflow and environment with the smallest scopes.
+- Prefer finite expiry and rotate before it is reached.
+- Do not log credentials, signed upload URLs or sensitive response bodies.
+- Respect `Retry-After`; OrbitPage currently applies per-token minute and daily
+  limits.
+- Keep operator workflows and credentials isolated.
+- Revoke a token immediately after suspected disclosure.
+
+## Documentation
+
+- [OrbitPage API guide](https://orbitpage.com/en-US/docs/api-tokens)
+- [OpenAPI 3.1 contract](https://orbitpage.com/api/openapi.json)
+- [n8n community-node installation](https://docs.n8n.io/integrations/community-nodes/installation/)
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Quality checks:
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+Importable example workflows are available in [`examples`](examples). After
+changing the typed operation catalog, rebuild and regenerate its checked-in
+reference with `npm run build && npm run docs:generate`.
+
+The package has no runtime dependencies outside the `n8n-workflow` peer. It
+uses the official `@n8n/node-cli` toolchain and publishes npm provenance through
+GitHub Actions.
+
+## Releases
+
+Releases are automated by [the publish workflow](.github/workflows/publish.yml).
+Every version tag runs the complete quality suite before publishing the public
+package with provenance.
+
+The initial `0.1.0` release can be started after adding the temporary
+package-scoped `NPM_TOKEN` repository secret:
+
+```bash
+git tag 0.1.0
+git push origin 0.1.0
+```
+
+After the first publication, configure the npm Trusted Publisher for
+`paoloronco/n8n-nodes-orbitpage` and `publish.yml`, then delete the GitHub secret
+and revoke the temporary token. Future releases can be prepared with:
+
+```bash
+npm run release
+```
+
+OIDC is the permanent release path; no long-lived npm token belongs in GitHub
+or the repository.
+
+## License
+
+MIT © Paolo Ronco

package/dist/credentials/OrbitPageApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, Icon, INodeProperties } from 'n8n-workflow';
+export declare class OrbitPageApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: Icon;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/OrbitPageApi.credentials.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrbitPageApi = void 0;
+class OrbitPageApi {
+    constructor() {
+        this.name = 'orbitPageApi';
+        this.displayName = 'OrbitPage API';
+        this.icon = {
+            light: 'file:../icons/orbitpage.svg',
+            dark: 'file:../icons/orbitpage.dark.svg',
+        };
+        this.documentationUrl = 'https://orbitpage.com/en-US/docs/api-tokens';
+        this.properties = [
+            {
+                displayName: 'Token Type',
+                name: 'credentialKind',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Personal Workspace Token',
+                        value: 'workspace',
+                    },
+                    {
+                        name: 'Protected Operator Token',
+                        value: 'operator',
+                    },
+                ],
+                default: 'workspace',
+                description: 'Personal tokens are created in Dashboard > Account. Operator tokens are created only in the protected operator console.',
+            },
+            {
+                displayName: 'Personal API Token',
+                name: 'accessToken',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                placeholder: 'op_pat_...',
+                description: 'The scoped OrbitPage bearer token. It is stored encrypted by n8n.',
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://orbitpage.com',
+                description: 'Use the production URL unless OrbitPage support supplied a dedicated staging environment',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.accessToken}}',
+                    Accept: 'application/json',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl.replace(/\\/$/, "")}}',
+                url: '={{$credentials.credentialKind === "operator" ? "/api/v1/operator/overview" : "/api/v1/workspace"}}',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.OrbitPageApi = OrbitPageApi;
+//# sourceMappingURL=OrbitPageApi.credentials.js.map

package/dist/credentials/OrbitPageApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrbitPageApi.credentials.js","sourceRoot":"","sources":["../../credentials/OrbitPageApi.credentials.ts"],"names":[],"mappings":";;;AAQA,MAAa,YAAY;IAAzB;QACC,SAAI,GAAG,cAAc,CAAC;QAEtB,gBAAW,GAAG,eAAe,CAAC;QAE9B,SAAI,GAAS;YACZ,KAAK,EAAE,6BAA6B;YACpC,IAAI,EAAE,kCAAkC;SACxC,CAAC;QAEF,qBAAgB,GAAG,6CAA6C,CAAC;QAEjE,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,0BAA0B;wBAChC,KAAK,EAAE,WAAW;qBAClB;oBACD;wBACC,IAAI,EAAE,0BAA0B;wBAChC,KAAK,EAAE,UAAU;qBACjB;iBACD;gBACD,OAAO,EAAE,WAAW;gBACpB,WAAW,EACV,yHAAyH;aAC1H;YACD;gBACC,WAAW,EAAE,oBAAoB;gBACjC,IAAI,EAAE,aAAa;gBACnB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,YAAY;gBACzB,WAAW,EAAE,mEAAmE;aAChF;YACD;gBACC,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,uBAAuB;gBAChC,WAAW,EACV,0FAA0F;aAC3F;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,aAAa,EAAE,sCAAsC;oBACrD,MAAM,EAAE,kBAAkB;iBAC1B;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,+CAA+C;gBACxD,GAAG,EAAE,qGAAqG;gBAC1G,MAAM,EAAE,KAAK;aACb;SACD,CAAC;IACH,CAAC;CAAA;AAnED,oCAmEC"}

package/dist/icons/orbitpage.dark.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">OrbitPage</title>
+  <desc id="desc">A blue page crossed by a bright orbit.</desc>
+  <defs>
+    <linearGradient id="page" x1="18" y1="15" x2="50" y2="52" gradientUnits="userSpaceOnUse"><stop stop-color="#5D82F2"/><stop offset=".58" stop-color="#29457F"/><stop offset="1" stop-color="#3B73FF"/></linearGradient>
+    <linearGradient id="fold" x1="22" y1="16" x2="42" y2="46" gradientUnits="userSpaceOnUse"><stop stop-color="#D7E2FF" stop-opacity=".34"/><stop offset="1" stop-color="#3568F4" stop-opacity="0"/></linearGradient>
+    <linearGradient id="orbit" x1="12" y1="48" x2="57" y2="16" gradientUnits="userSpaceOnUse"><stop stop-color="#5285FF"/><stop offset=".55" stop-color="#79A0FF"/><stop offset="1" stop-color="#C4D4FF"/></linearGradient>
+    <clipPath id="page-clip"><rect x="18" y="15" width="32" height="37" rx="5"/></clipPath>
+  </defs>
+  <path d="M35 14c11-5 21-2 21 8 0 9-7 20-16 26" fill="none" stroke="url(#orbit)" stroke-linecap="round" stroke-width="6"/>
+  <rect x="18" y="15" width="32" height="37" rx="5" fill="url(#page)"/>
+  <path d="M18 15h32L18 52Z" fill="url(#fold)" clip-path="url(#page-clip)"/>
+  <path d="M56 22c1 12-9 24-20 30-12 7-23 4-24-4-1-5 1-10 4-14" fill="none" stroke="url(#orbit)" stroke-linecap="round" stroke-width="6.5"/>
+  <path d="M55 20c1 9-5 19-12 26" fill="none" stroke="#fff" stroke-linecap="round" stroke-width="1.3"/>
+  <path d="M34 14c8-5 16-4 20 1" fill="none" stroke="#8CADFF" stroke-linecap="round" stroke-width="3"/>
+</svg>

package/dist/icons/orbitpage.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">OrbitPage</title>
+  <desc id="desc">A deep-blue page crossed by a bright blue orbit.</desc>
+  <defs>
+    <linearGradient id="page" x1="18" y1="15" x2="50" y2="52" gradientUnits="userSpaceOnUse"><stop stop-color="#223B70"/><stop offset=".58" stop-color="#101828"/><stop offset="1" stop-color="#2456D8"/></linearGradient>
+    <linearGradient id="fold" x1="22" y1="16" x2="42" y2="46" gradientUnits="userSpaceOnUse"><stop stop-color="#7BA2FF" stop-opacity=".28"/><stop offset="1" stop-color="#2456D8" stop-opacity="0"/></linearGradient>
+    <linearGradient id="orbit" x1="12" y1="48" x2="57" y2="16" gradientUnits="userSpaceOnUse"><stop stop-color="#2456D8"/><stop offset=".55" stop-color="#3568F4"/><stop offset="1" stop-color="#7BA2FF"/></linearGradient>
+    <clipPath id="page-clip"><rect x="18" y="15" width="32" height="37" rx="5"/></clipPath>
+  </defs>
+  <path d="M35 14c11-5 21-2 21 8 0 9-7 20-16 26" fill="none" stroke="url(#orbit)" stroke-linecap="round" stroke-width="6"/>
+  <rect x="18" y="15" width="32" height="37" rx="5" fill="url(#page)"/>
+  <path d="M18 15h32L18 52Z" fill="url(#fold)" clip-path="url(#page-clip)"/>
+  <path d="M56 22c1 12-9 24-20 30-12 7-23 4-24-4-1-5 1-10 4-14" fill="none" stroke="url(#orbit)" stroke-linecap="round" stroke-width="6.5"/>
+  <path d="M55 20c1 9-5 19-12 26" fill="none" stroke="#fff" stroke-linecap="round" stroke-width="1.3"/>
+  <path d="M34 14c8-5 16-4 20 1" fill="none" stroke="#3568F4" stroke-linecap="round" stroke-width="3"/>
+</svg>

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

@@ -0,0 +1,7 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { type PathParameter } from './operations';
+export declare class OrbitPage implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}
+export declare const pathParameters: PathParameter[];