n8n-nodes-alterlab 0.13.0 → 0.14.1

package/README.md

@@ -71,15 +71,43 @@ npm install n8n-nodes-alterlab
 
 ### Connect Your Account
 
-**Option A — One-click OAuth (recommended):**
-1. Add an AlterLab node to your workflow
-2. Click the credential dropdown → **Create New → AlterLab OAuth2 API**
-3. Click **Connect** → sign in → done. No API key copy-paste needed.
-
-**Option B — API key:**
+**Option A — API key (default, works everywhere):**
 1. [Sign up free](https://app.alterlab.io/signin?redirect=/dashboard/keys&source=n8n&utm_source=n8n&utm_medium=integration&utm_campaign=community_node) and copy your API key
 2. In n8n: **Credentials → New → AlterLab API** → paste key
 
+**Option B — OAuth2 (browser sign-in, no key to copy):**
+1. Add an AlterLab node and choose **Create New → AlterLab OAuth2 API**
+2. Click **Connect my account**, sign in to AlterLab and approve access
+
+That is the whole setup on n8n Cloud and on self-hosted n8n. The credential uses OAuth 2.0 **Authorization Code with PKCE** and **Dynamic Client Registration** (RFC 7591): n8n discovers AlterLab's endpoints from `https://api.alterlab.io/.well-known/oauth-authorization-server`, registers itself for *its own* callback URL and gets a public client ID. No client secret exists, so nothing secret ships in this package and no per-instance allowlist is needed.
+
+Requirements:
+- n8n 2.10 or newer (verified on 2.10.2), which has dynamic client registration built into its OAuth2 credential. Older n8n: use Option A or the manual registration below.
+- Your n8n must be reachable over **HTTPS** at its public URL (`WEBHOOK_URL` / `N8N_EDITOR_BASE_URL`); AlterLab only accepts `https://` redirect URIs for n8n-style (web) clients, so a plain `http://` callback is rejected.
+- Access tokens are short lived (1 hour) and n8n refreshes them automatically with the refresh token; reconnect only if you revoke access in AlterLab.
+
+#### Manual client registration (if you cannot use dynamic registration)
+
+In the credential, switch **Register Client Automatically** off, then register your n8n callback once. Your callback is shown in the credential as **OAuth Redirect URL** (`https://<your-n8n>/rest/oauth2-credential/callback`):
+
+```bash
+curl -sS -X POST https://api.alterlab.io/api/v1/oauth/register \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "client_name": "My n8n",
+    "redirect_uris": ["https://n8n.example.com/rest/oauth2-credential/callback"],
+    "token_endpoint_auth_method": "none",
+    "grant_types": ["authorization_code", "refresh_token"],
+    "scope": "scrape"
+  }'
+```
+
+Paste the returned `client_id` into **Client ID** and leave **Client Secret** empty (public PKCE client). Registration is limited to 5 requests per hour per IP address.
+
+Supported scopes are `scrape` (read and write, enough for every operation of this node), `read`, `write` and `billing`.
+
+> Do not put `https://api.alterlab.io/api/v1/oauth/authorize` into an *Authorization URL* field yourself: the AlterLab credential already sets the correct browser route (`https://alterlab.io/oauth/authorize`).
+
 ## Quick Start — Scrape a Page in 30 Seconds
 
 1. Add the **AlterLab** node to any workflow
@@ -229,6 +257,7 @@ Content type, custom headers, geo-targeting (`location.country` / `location.lang
 
 | Resource | Operations |
 |---|---|
+| **Account** | Get Balance (credits, tier, auto-recharge; works with an API key or OAuth2) |
 | **Scrape** | Scrape, Estimate Cost |
 | **Crawl** | Start (polls to completion), Get Status, Cancel, Resume, Export (JSON / JSONL / CSV, one item per page), List |
 | **Search** | Web search with engine (DuckDuckGo, Google, Bing), safe search, and optional result scraping |
@@ -241,7 +270,7 @@ Scrape output also includes `jobId`, `finalUrl`, `cachedAt` / `expiresAt` / `sta
 
 ### Credential Test
 
-The **Test** button calls `GET /api/v1/auth/identity`, which validates the API key without spending credits.
+The **Test** button calls `GET /api/v1/auth/identity`, which validates the API key or OAuth access token without spending credits.
 
 ## Frequently Asked Questions
 
@@ -263,7 +292,7 @@ Yes. AlterLab handles all major e-commerce anti-bot protection including Cloudfl
 
 ### Does AlterLab work with n8n Cloud and self-hosted n8n?
 
-Yes, both. Install via **Settings → Community Nodes** on n8n Cloud, or `npm install n8n-nodes-alterlab` for self-hosted. OAuth2 authentication works on both — click Connect, sign in, done.
+Yes, both. Install via **Settings → Community Nodes** on n8n Cloud, or `npm install n8n-nodes-alterlab` for self-hosted. OAuth2 authentication works on both (see *Connect Your Account* for the HTTPS callback requirement on self-hosted n8n).
 
 ### Is there rate limiting?
 

package/dist/credentials/AlterLabOAuth2Api.credentials.d.ts

@@ -1,4 +1,32 @@
 import type { ICredentialTestRequest, ICredentialType, INodeProperties } from "n8n-workflow";
+/**
+ * AlterLab OAuth2 (Authorization Code + PKCE, public client).
+ *
+ * The credential extends n8n's built-in `oAuth2Api`, so every override below
+ * MUST use the inherited property names (`authUrl`, `accessTokenUrl`,
+ * `clientId`, ...). An override under any other name leaves the inherited
+ * field visible and blank (ALT-80 / #46).
+ *
+ * No secret is shipped in this package. Self-hosted n8n callback URLs differ
+ * per instance, so the default path uses OAuth 2.0 Dynamic Client Registration
+ * (RFC 7591): n8n reads AlterLab's discovery document, registers a public
+ * client for this instance's own callback URL and runs PKCE (S256). Users who
+ * cannot use dynamic registration switch it off and paste a client ID obtained
+ * from `POST /api/v1/oauth/register` (see README).
+ */
+export declare const ALTERLAB_API_URL = "https://api.alterlab.io";
+/** Browser-facing authorization route (a GET; the API route of the same name is POST-only on older deployments). */
+export declare const ALTERLAB_AUTHORIZE_URL = "https://alterlab.io/oauth/authorize";
+export declare const ALTERLAB_TOKEN_URL = "https://api.alterlab.io/api/v1/oauth/token";
+/** Scope vocabulary of the AlterLab authorization server (`scopes_supported`). */
+export declare const ALTERLAB_OAUTH_SCOPES: string[];
+/**
+ * `scrape` grants the read+write API permissions every node operation needs
+ * (including Account > Get Balance, which is not scope-gated). Manual
+ * registrations should request only this; dynamic registration requests the
+ * full `scopes_supported` list because n8n does so itself.
+ */
+export declare const ALTERLAB_DEFAULT_SCOPE = "scrape";
 export declare class AlterLabOAuth2Api implements ICredentialType {
     name: string;
     displayName: string;

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

@@ -1 +1 @@
-{"version":3,"file":"AlterLabOAuth2Api.credentials.d.ts","sourceRoot":"","sources":["../../credentials/AlterLabOAuth2Api.credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,eAAe,EAChB,MAAM,cAAc,CAAC;AAEtB,qBAAa,iBAAkB,YAAW,eAAe;IACvD,IAAI,SAAuB;IAC3B,WAAW,SAAyB;IACpC,gBAAgB,SACmF;IAEnG,OAAO,WAAiB;IAExB,UAAU,EAAE,eAAe,EAAE,CAiD3B;IAEF,IAAI,EAAE,sBAAsB,CAM1B;CACH"}
+{"version":3,"file":"AlterLabOAuth2Api.credentials.d.ts","sourceRoot":"","sources":["../../credentials/AlterLabOAuth2Api.credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,eAAe,EAChB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAC1D,oHAAoH;AACpH,eAAO,MAAM,sBAAsB,wCAAwC,CAAC;AAC5E,eAAO,MAAM,kBAAkB,+CAA2C,CAAC;AAC3E,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,UAAyC,CAAC;AAC5E;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,WAAW,CAAC;AAE/C,qBAAa,iBAAkB,YAAW,eAAe;IACvD,IAAI,SAAuB;IAC3B,WAAW,SAAyB;IACpC,gBAAgB,SACmF;IAEnG,OAAO,WAAiB;IAExB,UAAU,EAAE,eAAe,EAAE,CA6E3B;IAIF,IAAI,EAAE,sBAAsB,CAM1B;CACH"}

package/dist/credentials/AlterLabOAuth2Api.credentials.js

@@ -1,6 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlterLabOAuth2Api = void 0;
+exports.AlterLabOAuth2Api = exports.ALTERLAB_DEFAULT_SCOPE = exports.ALTERLAB_OAUTH_SCOPES = exports.ALTERLAB_TOKEN_URL = exports.ALTERLAB_AUTHORIZE_URL = exports.ALTERLAB_API_URL = void 0;
+/**
+ * AlterLab OAuth2 (Authorization Code + PKCE, public client).
+ *
+ * The credential extends n8n's built-in `oAuth2Api`, so every override below
+ * MUST use the inherited property names (`authUrl`, `accessTokenUrl`,
+ * `clientId`, ...). An override under any other name leaves the inherited
+ * field visible and blank (ALT-80 / #46).
+ *
+ * No secret is shipped in this package. Self-hosted n8n callback URLs differ
+ * per instance, so the default path uses OAuth 2.0 Dynamic Client Registration
+ * (RFC 7591): n8n reads AlterLab's discovery document, registers a public
+ * client for this instance's own callback URL and runs PKCE (S256). Users who
+ * cannot use dynamic registration switch it off and paste a client ID obtained
+ * from `POST /api/v1/oauth/register` (see README).
+ */
+exports.ALTERLAB_API_URL = "https://api.alterlab.io";
+/** Browser-facing authorization route (a GET; the API route of the same name is POST-only on older deployments). */
+exports.ALTERLAB_AUTHORIZE_URL = "https://alterlab.io/oauth/authorize";
+exports.ALTERLAB_TOKEN_URL = `${exports.ALTERLAB_API_URL}/api/v1/oauth/token`;
+/** Scope vocabulary of the AlterLab authorization server (`scopes_supported`). */
+exports.ALTERLAB_OAUTH_SCOPES = ["scrape", "read", "write", "billing"];
+/**
+ * `scrape` grants the read+write API permissions every node operation needs
+ * (including Account > Get Balance, which is not scope-gated). Manual
+ * registrations should request only this; dynamic registration requests the
+ * full `scopes_supported` list because n8n does so itself.
+ */
+exports.ALTERLAB_DEFAULT_SCOPE = "scrape";
 class AlterLabOAuth2Api {
     constructor() {
         this.name = "alterLabOAuth2Api";
@@ -8,41 +36,64 @@ class AlterLabOAuth2Api {
         this.documentationUrl = "https://docs.alterlab.io/api?utm_source=n8n&utm_medium=integration&utm_campaign=community_node";
         this.extends = ["oAuth2Api"];
         this.properties = [
+            {
+                displayName: "Register Client Automatically",
+                name: "useDynamicClientRegistration",
+                type: "boolean",
+                default: true,
+                description: "Whether n8n registers itself with AlterLab for this instance's callback URL (OAuth Dynamic Client Registration). Turn off only to use a client ID you registered yourself, see the package README.",
+            },
+            {
+                displayName: "Server URL",
+                name: "serverUrl",
+                type: "hidden",
+                default: exports.ALTERLAB_API_URL,
+            },
             {
                 displayName: "Grant Type",
                 name: "grantType",
                 type: "hidden",
-                default: "authorizationCode",
+                default: "pkce",
             },
             {
                 displayName: "Authorization URL",
-                name: "authorizationUrl",
+                name: "authUrl",
                 type: "hidden",
-                default: "https://app.alterlab.io/oauth/authorize",
+                default: exports.ALTERLAB_AUTHORIZE_URL,
             },
             {
                 displayName: "Access Token URL",
                 name: "accessTokenUrl",
                 type: "hidden",
-                default: "https://api.alterlab.io/api/v1/oauth/token",
+                default: exports.ALTERLAB_TOKEN_URL,
             },
             {
                 displayName: "Client ID",
                 name: "clientId",
-                type: "hidden",
-                default: "n8n-community-node",
+                type: "string",
+                default: "",
+                required: true,
+                displayOptions: {
+                    show: { useDynamicClientRegistration: [false] },
+                },
+                description: "The client_id returned by POST /api/v1/oauth/register for this n8n instance's callback URL",
             },
             {
                 displayName: "Client Secret",
                 name: "clientSecret",
-                type: "hidden",
-                default: "altrlab_n8n_Kx7mP2vQ9wR4jH6nB3cT5zY8",
+                type: "string",
+                typeOptions: { password: true },
+                default: "",
+                displayOptions: {
+                    show: { useDynamicClientRegistration: [false] },
+                },
+                description: "Leave empty. AlterLab clients registered with token_endpoint_auth_method=none are public and use PKCE instead of a secret",
             },
             {
                 displayName: "Scope",
                 name: "scope",
                 type: "hidden",
-                default: "scrape",
+                default: exports.ALTERLAB_DEFAULT_SCOPE,
             },
             {
                 displayName: "Auth URI Query Parameters",
@@ -51,15 +102,19 @@ class AlterLabOAuth2Api {
                 default: "",
             },
             {
+                // Public client: no client secret is sent, so credentials in the
+                // Authorization header (the n8n default) are never produced.
                 displayName: "Authentication",
                 name: "authentication",
                 type: "hidden",
-                default: "body",
+                default: "header",
             },
         ];
+        // GET /api/v1/auth/identity accepts X-API-Key, Bearer sk_ and Bearer alo_at_
+        // (OAuth) credentials, spends no credits and does not need a scope.
         this.test = {
             request: {
-                baseURL: "https://api.alterlab.io",
+                baseURL: exports.ALTERLAB_API_URL,
                 url: "/api/v1/auth/identity",
                 method: "GET",
             },

package/dist/credentials/AlterLabOAuth2Api.credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"AlterLabOAuth2Api.credentials.js","sourceRoot":"","sources":["../../credentials/AlterLabOAuth2Api.credentials.ts"],"names":[],"mappings":";;;AAMA,MAAa,iBAAiB;IAA9B;QACE,SAAI,GAAG,mBAAmB,CAAC;QAC3B,gBAAW,GAAG,qBAAqB,CAAC;QACpC,qBAAgB,GACd,gGAAgG,CAAC;QAEnG,YAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QAExB,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,mBAAmB;aAC7B;YACD;gBACE,WAAW,EAAE,mBAAmB;gBAChC,IAAI,EAAE,kBAAkB;gBACxB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,yCAAyC;aACnD;YACD;gBACE,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,4CAA4C;aACtD;YACD;gBACE,WAAW,EAAE,WAAW;gBACxB,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,oBAAoB;aAC9B;YACD;gBACE,WAAW,EAAE,eAAe;gBAC5B,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,sCAAsC;aAChD;YACD;gBACE,WAAW,EAAE,OAAO;gBACpB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,QAAQ;aAClB;YACD;gBACE,WAAW,EAAE,2BAA2B;gBACxC,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACZ;YACD;gBACE,WAAW,EAAE,gBAAgB;gBAC7B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,MAAM;aAChB;SACF,CAAC;QAEF,SAAI,GAA2B;YAC7B,OAAO,EAAE;gBACP,OAAO,EAAE,yBAAyB;gBAClC,GAAG,EAAE,uBAAuB;gBAC5B,MAAM,EAAE,KAAK;aACd;SACF,CAAC;IACJ,CAAC;CAAA;AAlED,8CAkEC"}
+{"version":3,"file":"AlterLabOAuth2Api.credentials.js","sourceRoot":"","sources":["../../credentials/AlterLabOAuth2Api.credentials.ts"],"names":[],"mappings":";;;AAMA;;;;;;;;;;;;;;GAcG;AAEU,QAAA,gBAAgB,GAAG,yBAAyB,CAAC;AAC1D,oHAAoH;AACvG,QAAA,sBAAsB,GAAG,qCAAqC,CAAC;AAC/D,QAAA,kBAAkB,GAAG,GAAG,wBAAgB,qBAAqB,CAAC;AAC3E,kFAAkF;AACrE,QAAA,qBAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC5E;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,QAAQ,CAAC;AAE/C,MAAa,iBAAiB;IAA9B;QACE,SAAI,GAAG,mBAAmB,CAAC;QAC3B,gBAAW,GAAG,qBAAqB,CAAC;QACpC,qBAAgB,GACd,gGAAgG,CAAC;QAEnG,YAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QAExB,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,+BAA+B;gBAC5C,IAAI,EAAE,8BAA8B;gBACpC,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI;gBACb,WAAW,EACT,oMAAoM;aACvM;YACD;gBACE,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,wBAAgB;aAC1B;YACD;gBACE,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,MAAM;aAChB;YACD;gBACE,WAAW,EAAE,mBAAmB;gBAChC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,8BAAsB;aAChC;YACD;gBACE,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,0BAAkB;aAC5B;YACD;gBACE,WAAW,EAAE,WAAW;gBACxB,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,cAAc,EAAE;oBACd,IAAI,EAAE,EAAE,4BAA4B,EAAE,CAAC,KAAK,CAAC,EAAE;iBAChD;gBACD,WAAW,EACT,4FAA4F;aAC/F;YACD;gBACE,WAAW,EAAE,eAAe;gBAC5B,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,cAAc,EAAE;oBACd,IAAI,EAAE,EAAE,4BAA4B,EAAE,CAAC,KAAK,CAAC,EAAE;iBAChD;gBACD,WAAW,EACT,2HAA2H;aAC9H;YACD;gBACE,WAAW,EAAE,OAAO;gBACpB,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,8BAAsB;aAChC;YACD;gBACE,WAAW,EAAE,2BAA2B;gBACxC,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACZ;YACD;gBACE,iEAAiE;gBACjE,6DAA6D;gBAC7D,WAAW,EAAE,gBAAgB;gBAC7B,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,QAAQ;aAClB;SACF,CAAC;QAEF,6EAA6E;QAC7E,oEAAoE;QACpE,SAAI,GAA2B;YAC7B,OAAO,EAAE;gBACP,OAAO,EAAE,wBAAgB;gBACzB,GAAG,EAAE,uBAAuB;gBAC5B,MAAM,EAAE,KAAK;aACd;SACF,CAAC;IACJ,CAAC;CAAA;AAhGD,8CAgGC"}

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

@@ -1 +1 @@
-{"version":3,"file":"AlterLab.node.d.ts","sourceRoot":"","sources":["../../../nodes/AlterLab/AlterLab.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EAEjB,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EAErB,MAAM,cAAc,CAAC;AAkCtB,qBAAa,QAAS,YAAW,SAAS;IACxC,WAAW,EAAE,oBAAoB,CA+hF/B;IAEI,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;CAgqDxE"}
+{"version":3,"file":"AlterLab.node.d.ts","sourceRoot":"","sources":["../../../nodes/AlterLab/AlterLab.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EAEjB,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EAErB,MAAM,cAAc,CAAC;AAmCtB,qBAAa,QAAS,YAAW,SAAS;IACxC,WAAW,EAAE,oBAAoB,CA6yG/B;IAEI,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;CA4rDxE"}