n8n-nodes-lifespace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shirui Huang
+
+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,157 @@
+# n8n-nodes-lifespace
+
+Official n8n community nodes for integrating workflows and AI agents with LifeSpace.
+
+## Status
+
+The package currently provides:
+
+- a LifeSpace Connection credential using a Connection Base URL plus an opaque `lsp_pat_*` Service API Token;
+- a LifeSpace Webhook credential for storing event-subscription signing secrets outside workflow parameters;
+- a LifeSpace node with generic Model Record operations plus an advanced connection-relative API request escape hatch;
+- discovery-driven Model, Action, Create/Update field, Query and Action Input UX against the connection's current LifeSpace authority;
+- a LifeSpace Trigger that receives signed LifeSpace domain-event webhooks;
+- the official `n8n-node` development toolchain;
+- CI for lint and build validation;
+- a GitHub Actions npm publishing path with provenance support.
+
+Domain-specific UX and AI-tool surfaces will be added only against stable upstream LifeSpace contracts/discovery metadata.
+
+## Architecture boundary
+
+LifeSpace is the source of truth for identity, authorization, domain models, contracts and events. This repository is an n8n-specific adapter and must not become a second copy of LifeSpace business contracts.
+
+LifeSpace does not depend on n8n. n8n is one optional orchestration and integration runtime that consumes LifeSpace APIs and events.
+
+## Development
+
+Requirements:
+
+- Node.js 22.22.0 or newer;
+- npm;
+- a local n8n instance for interactive node testing.
+
+Install and validate:
+
+```bash
+npm install
+npm run lint
+npm run build
+```
+
+Run the node in a local n8n development instance:
+
+```bash
+npm run dev
+```
+
+## Credentials
+
+Create and authorize the integration in LifeSpace Web first. The Web configuration owns the target Space and its granted model permissions, then exposes the values to copy into n8n:
+
+- **Connection Base URL**, for example `https://core.aisr.online/api/v1/spaces/spc_...`;
+- **Service API Token**, an opaque `lsp_pat_*` token issued for that connection.
+
+The Credential represents one already-configured LifeSpace connection. Individual LifeSpace nodes therefore do not ask for a Space ID.
+
+The Connection Base URL carries routing context only. Authorization still comes from the Service API Token plus LifeSpace credential scopes, Application × Model Access and current Space/Data Grant authority. Revoking the token or grant invalidates the connection without changing the n8n workflow.
+
+Do not store real tokens in source code, workflow examples or repository files.
+
+## LifeSpace Model Record
+
+The **Model Record** resource is a thin adapter over LifeSpace Generic Runtime routes. It supports:
+
+- Create;
+- Get;
+- List / Query;
+- Update with optimistic concurrency;
+- Delete with optimistic concurrency;
+- Execute Action for published Capability/workflow actions.
+
+The node loads its Model selector from `{Connection Base URL}/_discovery`. The list contains only models the current connection can currently use after LifeSpace applies credential scopes, Application × Model Access and current Space membership/Data Grants. The **Action** selector is then loaded dynamically from the selected model and is filtered by the same discovery authority.
+
+### Discovery-driven fields
+
+Create and Update use n8n's resource-mapper UI driven directly by the selected model's bounded Runtime Discovery metadata instead of a handwritten `Fields (JSON)` contract.
+
+- required Create fields follow LifeSpace field metadata;
+- read-only fields are excluded;
+- immutable fields are additionally excluded from Update;
+- enum fields render as options;
+- number, boolean, datetime and list fields use the corresponding n8n input types;
+- LifeSpace date-only fields intentionally remain strings so `YYYY-MM-DD` values are never converted into timezone-bearing instants;
+- automatic input-data mapping is intentionally disabled for now so unrelated incoming keys are not silently sent to LifeSpace's strict model schema.
+
+### Discovery-driven query
+
+List / Query uses bounded query metadata from LifeSpace Runtime Discovery rather than a free-form JSON request.
+
+- searchable fields enable the Search input only where the model declares search support;
+- filter fields are limited to the model's published filterable fields;
+- equality and supported range operators map to LifeSpace Generic Runtime query parameters;
+- sort fields are limited to published sortable fields;
+- pagination uses the LifeSpace `limit` and opaque `cursor` contract;
+- the node does not invent query operators or field semantics that are absent from upstream Discovery metadata.
+
+### Discovery-driven Action Input
+
+Execute Action uses a second resource-mapper driven by the selected action's bounded input metadata from LifeSpace Runtime Discovery.
+
+- Model Definition v1 workflow actions currently expose the optimistic-concurrency `version` input;
+- the `record-occurrence` Capability action exposes `version`, `occurredOn` and optional `note` according to the upstream contract;
+- required/optional status, primitive input types, date-only handling and length/range constraints come from LifeSpace metadata;
+- the node does not copy action schemas into this package or accept an unrestricted Action Input JSON object for normal use.
+
+LifeSpace Core remains authoritative for validation and authorization when an operation executes. Runtime Discovery is a dynamic UX/capability preview, not an execution-authorization proof.
+
+The node does not use the privileged `model-admin/contracts/*` surface for ordinary workflow discovery and does not copy model definitions into this repository.
+
+The **API Request** resource remains available as an advanced escape hatch for paths relative to the configured Connection Base URL.
+
+## LifeSpace Trigger
+
+LifeSpace event subscriptions are currently managed by an authenticated LifeSpace user with Space-management permission. A service token intentionally cannot create or modify subscriptions.
+
+To use the trigger:
+
+1. add a LifeSpace Trigger to an n8n workflow and activate the workflow;
+2. copy the node's production webhook URL;
+3. create a LifeSpace Webhook Endpoint for the target Space and use that URL as its destination;
+4. attach one or more LifeSpace Event Subscription filters for the required model/events to that endpoint;
+5. create a **LifeSpace Webhook API** credential and store the endpoint's one-time signing secret in that credential;
+6. attach the credential to the Trigger and optionally set expected Space/model filters as an additional local check;
+7. use LifeSpace's endpoint test action to verify delivery.
+
+The signing secret is intentionally stored as an n8n Credential rather than as a workflow parameter. Workflow exports therefore reference the credential instead of embedding the secret as ordinary node configuration.
+
+The trigger validates `X-LifeSpace-Timestamp` and `X-LifeSpace-Signature` using the upstream LifeSpace HMAC-SHA256 contract before emitting workflow data.
+
+## Publishing and verification
+
+This repository is public and is intended to remain eligible for n8n community-node verification.
+
+Publishing is performed only by `.github/workflows/publish.yml` from a version tag matching `*.*.*`. The workflow grants only `contents: read` plus `id-token: write`, so npm can attach a provenance attestation to the public package.
+
+Preferred npm authentication is Trusted Publishing through GitHub Actions. A scoped `NPM_TOKEN` is supported only as a fallback. Do not publish a verification candidate directly from a developer workstation.
+
+Before the first npm release:
+
+1. ensure the `n8n-nodes-lifespace` package is available to the publishing npm account;
+2. configure npm Trusted Publishing for `huangshirui/lifespace-n8n-nodes` and workflow `publish.yml`, or install a narrowly scoped fallback `NPM_TOKEN`;
+3. ensure CI passes on the exact release commit;
+4. create the release through the `n8n-node` release flow so the pushed version tag triggers the provenance workflow;
+5. verify the npm package links back to this public GitHub repository and exposes the MIT license and expected node metadata.
+
+The package intentionally has no runtime `dependencies`. It must not read environment variables or the local filesystem. Node UI, help text, errors, README content and examples remain English-only for n8n verification compatibility.
+
+## Planned surfaces
+
+- richer relation selectors when LifeSpace exposes an appropriate authorized lookup surface;
+- a more explicit n8n AI Tool experience for approved LifeSpace actions if the generic tool-capable node proves insufficient;
+- delegated Webhook Endpoint / Event Subscription management if LifeSpace later exposes an appropriate user-authorized integration contract;
+- OAuth `client_credentials` support where required.
+
+## License
+
+MIT

package/dist/credentials/LifeSpaceApi.credentials.d.ts

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

package/dist/credentials/LifeSpaceApi.credentials.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifeSpaceApi = void 0;
+class LifeSpaceApi {
+    constructor() {
+        this.name = 'lifeSpaceApi';
+        this.displayName = 'LifeSpace Connection API';
+        this.icon = 'file:lifespace.svg';
+        this.documentationUrl = 'https://github.com/huangshirui/LifeSpace';
+        this.properties = [
+            {
+                displayName: 'Connection Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: '',
+                placeholder: 'https://core.aisr.online/api/v1/spaces/spc_...',
+                required: true,
+                description: 'Copy the Connection Base URL from the LifeSpace Web integration configuration',
+            },
+            {
+                displayName: 'Service API Token',
+                name: 'token',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'Copy the LifeSpace Service API Token (lsp_pat_*) issued for this connection',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    Authorization: '=Bearer {{$credentials.token}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl.replace(/\\/$/, "")}}',
+                url: '/_discovery',
+                method: 'GET',
+            },
+        };
+    }
+}
+exports.LifeSpaceApi = LifeSpaceApi;
+//# sourceMappingURL=LifeSpaceApi.credentials.js.map

package/dist/credentials/LifeSpaceApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifeSpaceApi.credentials.js","sourceRoot":"","sources":["../../credentials/LifeSpaceApi.credentials.ts"],"names":[],"mappings":";;;AAOA,MAAa,YAAY;IAAzB;QACE,SAAI,GAAG,cAAc,CAAC;QAEtB,gBAAW,GAAG,0BAA0B,CAAC;QAEzC,SAAI,GAAG,oBAA6B,CAAC;QAErC,qBAAgB,GAAG,0CAA0C,CAAC;QAE9D,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,qBAAqB;gBAClC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,gDAAgD;gBAC7D,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,+EAA+E;aAC7F;YACD;gBACE,WAAW,EAAE,mBAAmB;gBAChC,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,6EAA6E;aAC3F;SACF,CAAC;QAEF,iBAAY,GAAyB;YACnC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,aAAa,EAAE,gCAAgC;iBAChD;aACF;SACF,CAAC;QAEF,SAAI,GAA2B;YAC7B,OAAO,EAAE;gBACP,OAAO,EAAE,+CAA+C;gBACxD,GAAG,EAAE,aAAa;gBAClB,MAAM,EAAE,KAAK;aACd;SACF,CAAC;IACJ,CAAC;CAAA;AA9CD,oCA8CC"}

package/dist/credentials/LifeSpaceWebhookApi.credentials.d.ts

@@ -0,0 +1,8 @@
+import type { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class LifeSpaceWebhookApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: "file:lifespace.svg";
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/LifeSpaceWebhookApi.credentials.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifeSpaceWebhookApi = void 0;
+class LifeSpaceWebhookApi {
+    constructor() {
+        this.name = 'lifeSpaceWebhookApi';
+        this.displayName = 'LifeSpace Webhook API';
+        this.icon = 'file:lifespace.svg';
+        this.documentationUrl = 'https://github.com/huangshirui/lifespace-n8n-nodes#lifespace-trigger';
+        this.properties = [
+            {
+                displayName: 'Signing Secret',
+                name: 'signingSecret',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: true,
+                description: 'One-time signing secret returned when the LifeSpace event subscription is created or rotated',
+            },
+        ];
+    }
+}
+exports.LifeSpaceWebhookApi = LifeSpaceWebhookApi;
+//# sourceMappingURL=LifeSpaceWebhookApi.credentials.js.map

package/dist/credentials/LifeSpaceWebhookApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifeSpaceWebhookApi.credentials.js","sourceRoot":"","sources":["../../credentials/LifeSpaceWebhookApi.credentials.ts"],"names":[],"mappings":";;;AAEA,MAAa,mBAAmB;IAAhC;QACE,SAAI,GAAG,qBAAqB,CAAC;QAE7B,gBAAW,GAAG,uBAAuB,CAAC;QAEtC,SAAI,GAAG,oBAA6B,CAAC;QAErC,qBAAgB,GAAG,sEAAsE,CAAC;QAE1F,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,gBAAgB;gBAC7B,IAAI,EAAE,eAAe;gBACrB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,8FAA8F;aAC5G;SACF,CAAC;IACJ,CAAC;CAAA;AApBD,kDAoBC"}

package/dist/credentials/lifespace.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="LifeSpace">
+  <defs>
+    <linearGradient id="lifespace-bg" x1="7" y1="57" x2="57" y2="7" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#075FEA"/>
+      <stop offset="0.55" stop-color="#087CF5"/>
+      <stop offset="1" stop-color="#25A8FF"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="url(#lifespace-bg)"/>
+  <g fill="none" stroke="#FFFFFF" stroke-width="5" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M29 14.5 19 20.5a5 5 0 0 0-2.5 4.3v14.4a5 5 0 0 0 2.5 4.3l10 6"/>
+    <path d="M35 14.5 45 20.5a5 5 0 0 1 2.5 4.3v14.4a5 5 0 0 1-2.5 4.3l-10 6"/>
+  </g>
+  <circle cx="32" cy="32" r="4.6" fill="#FFFFFF"/>
+</svg>

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

@@ -0,0 +1,17 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription, ResourceMapperFields } from 'n8n-workflow';
+export declare class LifeSpace implements INodeType {
+    description: INodeTypeDescription;
+    methods: {
+        loadOptions: {
+            getModels(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getActions(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getFilterableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            getSortableFields(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+        };
+        resourceMapping: {
+            getModelFields(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+            getActionInputFields(this: ILoadOptionsFunctions): Promise<ResourceMapperFields>;
+        };
+    };
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}