n8n-nodes-cala 0.4.15 → 0.4.16

package/README.md

@@ -28,14 +28,15 @@ You need a Cala API key to use this node:
 
 ## Operations
 
-The node exposes a **Knowledge** resource with four operations:
+The node exposes a **Knowledge** resource with five operations:
 
 | Operation | Description |
 |-----------|-------------|
 | **Search** | Answer natural language questions with sourced, researched content |
 | **Query** | Filter entities by attributes using structured dot-notation syntax |
-| **Search Entities** | Find entities by name with fuzzy matching |
-| **Get Entity** | Get the full profile of an entity by its numeric ID |
+| **Search Entities** | Find entities by name with fuzzy matching, optionally filtered by type |
+| **Get Entity** | Get the full profile of an entity by its UUID, with optional field selection |
+| **Get Entity Fields** | Discover which properties, relationships, and observations are available for an entity |
 
 ### Search
 
@@ -106,6 +107,11 @@ Filter entities by attributes using dot-notation syntax.
 
 Find entities by name (supports fuzzy matching). Returns a list of matches with IDs.
 
+**Parameters:**
+- `Name` (required) — entity name to search for
+- `Entity Types` (optional) — filter by one or more types: Company, Person, GPE, Country, Organization, and more
+- `Limit` (optional, default 20) — max results, up to 100
+
 **Input:** `"OpenAI"` with limit `3`
 
 **Output:**
@@ -119,27 +125,55 @@ Find entities by name (supports fuzzy matching). Returns a list of matches with
 }
 ```
 
+### Get Entity Fields
+
+Discover which properties, relationships, and numerical observations are available for a specific entity before querying it. Run this first, then use the results to fill in the **Get Entity** optional fields.
+
+**Input:** Entity UUID `"c6772802-bdbc-4778-91e9-cd3d27d008d5"`
+
+**Output:**
+```json
+{
+  "properties": ["name", "aliases", "legal_name", "employee_count", "founding_date", "headquarters_address"],
+  "relationships": {
+    "outgoing": ["IS_REGISTERED_IN", "HAS_HEADQUARTERS_IN", "OPERATES_IN_INDUSTRY"],
+    "incoming": ["IS_CEO_OF", "IS_CFO_OF", "IS_BOARD_MEMBER_OF", "IS_SUBSIDIARY_OF"]
+  },
+  "numerical_observations": {
+    "FinancialMetric": [
+      { "id": "1d3eae40-0ba8-5baf-9907-6a4823b067bb", "name": "Cash and Cash Equivalents", "unit": "USD" }
+    ]
+  }
+}
+```
+
 ### Get Entity
 
-Get the full profile of an entity by its ID (from Search or Search Entities results).
+Get the full profile of an entity by its UUID. By default returns a standard set of properties. Use the optional **Additional Fields** to select exactly which properties, relationships, and numerical observations to include — run **Get Entity Fields** first to discover what's available.
 
-**Input:** `"932ba22a-5310-4b21-bbb7-6b91741c8bb3"`
+**Parameters:**
+- `Entity ID` (required) — UUID from Search Entities, Search, or Query results
+- `Additional Fields > Properties` — list of property names to return (e.g. `name`, `employee_count`, `founding_date`)
+- `Additional Fields > Relationships` — relationships to include, each with direction (Outgoing/Incoming), type name, and optional limit/offset
+- `Additional Fields > Numerical Observations` — JSON object mapping observation type to UUID array (e.g. `{"FinancialMetric": ["uuid1"]}`)
+
+**Input:** Entity UUID `"c6772802-bdbc-4778-91e9-cd3d27d008d5"` with properties `["name", "employee_count"]` and incoming relationship `IS_CEO_OF`
 
 **Output:**
 ```json
 {
+  "id": "c6772802-bdbc-4778-91e9-cd3d27d008d5",
+  "name": "Apple Inc",
+  "entity_type": "Company",
   "properties": {
-    "name": {
-      "value": "Hydnum Steel",
-      "sources": [{ "name": "Cala AI", "document": "", "date": "2026-03-05" }]
-    },
-    "registered_address": {
-      "value": "Calle Serrano North 45, Madrid, Spain",
-      "sources": [{ "name": "CB Insights", "document": "https://www.cbinsights.com/company/hydnum-steel", "date": "2026-03-02" }]
+    "name": { "value": "APPLE INC", "sources": [{ "name": "SEC", "date": "2026-02-26" }] },
+    "employee_count": { "value": 164000, "sources": [{ "name": "Macrotrends", "date": "2026-03-01" }] }
+  },
+  "relationships": {
+    "incoming": {
+      "IS_CEO_OF": [{ "id": "...", "name": "Tim Cook", "entity_type": "Person" }]
     }
   },
-  "id": { "value": "932ba22a-5310-4b21-bbb7-6b91741c8bb3", "sources": [] },
-  "relationships": { "outgoing": {}, "incoming": {} },
   "numerical_observations": []
 }
 ```

package/dist/credentials/CalaApi.credentials.js

@@ -31,7 +31,7 @@ class CalaApi {
         this.test = {
             request: {
                 baseURL: 'https://api.cala.ai',
-                url: '/v1/knowledge/entities',
+                url: '/v1/entities',
                 method: 'GET',
                 qs: {
                     name: 'test',

package/dist/nodes/Cala/Cala.node.js

@@ -54,7 +54,13 @@ class Cala {
                             name: 'Get Entity',
                             value: 'getEntity',
                             action: 'Get knowledge entity',
-                            description: 'Get the full profile of an entity by its numeric ID.',
+                            description: 'Get the full profile of an entity by its UUID.',
+                        },
+                        {
+                            name: 'Get Entity Fields',
+                            value: 'getEntityFields',
+                            action: 'Get knowledge entity fields',
+                            description: 'Get available properties, relationships, and numerical observations for an entity.',
                         },
                         {
                             name: 'Query',
@@ -116,6 +122,35 @@ class Cala {
                         show: { resource: ['knowledge'], operation: ['searchEntities'] },
                     },
                 },
+                {
+                    displayName: 'Entity Types',
+                    name: 'entity_types',
+                    type: 'multiOptions',
+                    default: [],
+                    description: 'Filter results by entity type. Leave empty to return all types.',
+                    options: [
+                        { name: 'Company', value: 'Company' },
+                        { name: 'Corporate Event', value: 'CorporateEvent' },
+                        { name: 'Country', value: 'Country' },
+                        { name: 'Country Region', value: 'CountryRegion' },
+                        { name: 'Educational Institution', value: 'EducationalInstitution' },
+                        { name: 'Entity', value: 'Entity' },
+                        { name: 'Facility', value: 'Facility' },
+                        { name: 'Financial Metric', value: 'FinancialMetric' },
+                        { name: 'GPE', value: 'GPE' },
+                        { name: 'Industry', value: 'Industry' },
+                        { name: 'Language', value: 'Language' },
+                        { name: 'Law', value: 'Law' },
+                        { name: 'Location', value: 'Location' },
+                        { name: 'Organization', value: 'Organization' },
+                        { name: 'Person', value: 'Person' },
+                        { name: 'Product', value: 'Product' },
+                        { name: 'Work of Art', value: 'WorkOfArt' },
+                    ],
+                    displayOptions: {
+                        show: { resource: ['knowledge'], operation: ['searchEntities'] },
+                    },
+                },
                 {
                     displayName: 'Limit',
                     name: 'limit',
@@ -127,30 +162,111 @@ class Cala {
                         show: { resource: ['knowledge'], operation: ['searchEntities'] },
                     },
                 },
-                // ── Knowledge › Get Entity ──────────────────────────────────────────
+                // ── Knowledge › Get Entity / Get Entity Fields ──────────────────────
                 {
                     displayName: 'Entity ID',
                     name: 'entityId',
-                    type: 'number',
+                    type: 'string',
                     required: true,
-                    default: 0,
-                    description: 'Numeric ID of the entity to retrieve.',
+                    default: '',
+                    placeholder: 'e.g. c6772802-bdbc-4778-91e9-cd3d27d008d5',
+                    description: 'UUID of the entity.',
+                    displayOptions: {
+                        show: { resource: ['knowledge'], operation: ['getEntity', 'getEntityFields'] },
+                    },
+                },
+                {
+                    displayName: 'Additional Fields',
+                    name: 'additionalFields',
+                    type: 'collection',
+                    placeholder: 'Add Field',
+                    default: {},
                     displayOptions: {
                         show: { resource: ['knowledge'], operation: ['getEntity'] },
                     },
+                    options: [
+                        {
+                            displayName: 'Properties',
+                            name: 'properties',
+                            type: 'string',
+                            typeOptions: { multipleValues: true },
+                            default: [],
+                            placeholder: 'e.g. name',
+                            description: 'List of property names to return (e.g. name, employee_count, founding_date). Run Get Entity Fields first to discover available properties.',
+                        },
+                        {
+                            displayName: 'Relationships',
+                            name: 'relationships',
+                            type: 'fixedCollection',
+                            typeOptions: { multipleValues: true },
+                            default: {},
+                            description: 'Relationships to include in the response. Run Get Entity Fields first to discover available relationship types.',
+                            options: [
+                                {
+                                    name: 'items',
+                                    displayName: 'Relationship',
+                                    values: [
+                                        {
+                                            displayName: 'Direction',
+                                            name: 'direction',
+                                            type: 'options',
+                                            default: 'outgoing',
+                                            options: [
+                                                { name: 'Outgoing', value: 'outgoing' },
+                                                { name: 'Incoming', value: 'incoming' },
+                                            ],
+                                        },
+                                        {
+                                            displayName: 'Relationship Type',
+                                            name: 'relationshipType',
+                                            type: 'string',
+                                            default: '',
+                                            placeholder: 'e.g. IS_CEO_OF',
+                                            description: 'Relationship type name as returned by Get Entity Fields.',
+                                        },
+                                        {
+                                            displayName: 'Limit',
+                                            name: 'limit',
+                                            type: 'number',
+                                            default: 10,
+                                            typeOptions: { minValue: 1 },
+                                            description: 'Maximum number of related entities to return.',
+                                        },
+                                        {
+                                            displayName: 'Offset',
+                                            name: 'offset',
+                                            type: 'number',
+                                            default: 0,
+                                            typeOptions: { minValue: 0 },
+                                            description: 'Number of related entities to skip (for pagination).',
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                        {
+                            displayName: 'Numerical Observations',
+                            name: 'numericalObservations',
+                            type: 'string',
+                            default: '',
+                            placeholder: '{"FinancialMetric": ["uuid1", "uuid2"]}',
+                            description: 'JSON object mapping observation type names to arrays of observation UUIDs. Run Get Entity Fields first to discover available types and UUIDs.',
+                        },
+                    ],
                 },
             ],
         };
     }
     async execute() {
+        var _a, _b, _c, _d;
         const items = this.getInputData();
         const returnData = [];
         const resource = this.getNodeParameter('resource', 0);
-        const operation = this.getNodeParameter('operation', 0);
         for (let i = 0; i < items.length; i++) {
             try {
                 let response;
                 if (resource === 'knowledge') {
+                    const operation = this.getNodeParameter('operation', i);
                     if (operation === 'search') {
                         const query = this.getNodeParameter('query', i);
                         response = await this.helpers.httpRequestWithAuthentication.call(this, 'calaApi', {
@@ -172,18 +288,66 @@ class Cala {
                     else if (operation === 'searchEntities') {
                         const name = this.getNodeParameter('name', i);
                         const limit = this.getNodeParameter('limit', i);
+                        const entityTypes = this.getNodeParameter('entity_types', i);
                         response = await this.helpers.httpRequestWithAuthentication.call(this, 'calaApi', {
                             method: 'GET',
-                            url: `${BASE_URL}/v1/knowledge/entities`,
-                            qs: { name, limit },
+                            url: `${BASE_URL}/v1/entities`,
+                            qs: {
+                                name,
+                                limit,
+                                ...(entityTypes.length ? { entity_types: entityTypes } : {}),
+                            },
                             json: true,
                         });
                     }
                     else if (operation === 'getEntity') {
+                        const entityId = this.getNodeParameter('entityId', i);
+                        const additionalFields = this.getNodeParameter('additionalFields', i);
+                        const body = {};
+                        if ((_a = additionalFields.properties) === null || _a === void 0 ? void 0 : _a.length) {
+                            body.properties = additionalFields.properties;
+                        }
+                        const relationshipItems = (_c = (_b = additionalFields.relationships) === null || _b === void 0 ? void 0 : _b.items) !== null && _c !== void 0 ? _c : [];
+                        if (relationshipItems.length) {
+                            const outgoing = {};
+                            const incoming = {};
+                            for (const item of relationshipItems) {
+                                if (!((_d = item.relationshipType) === null || _d === void 0 ? void 0 : _d.trim()))
+                                    continue;
+                                const rel = {};
+                                if (item.limit != null)
+                                    rel.limit = item.limit;
+                                if (item.offset != null)
+                                    rel.offset = item.offset;
+                                (item.direction === 'outgoing' ? outgoing : incoming)[item.relationshipType] = rel;
+                            }
+                            const rel = {};
+                            if (Object.keys(outgoing).length)
+                                rel.outgoing = outgoing;
+                            if (Object.keys(incoming).length)
+                                rel.incoming = incoming;
+                            body.relationships = rel;
+                        }
+                        if (additionalFields.numericalObservations) {
+                            try {
+                                body.numerical_observations = JSON.parse(additionalFields.numericalObservations);
+                            }
+                            catch {
+                                throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Numerical Observations must be a valid JSON object (e.g. {"FinancialMetric": ["uuid1"]})', { itemIndex: i });
+                            }
+                        }
+                        response = await this.helpers.httpRequestWithAuthentication.call(this, 'calaApi', {
+                            method: 'POST',
+                            url: `${BASE_URL}/v1/entities/${entityId}`,
+                            body,
+                            json: true,
+                        });
+                    }
+                    else if (operation === 'getEntityFields') {
                         const entityId = this.getNodeParameter('entityId', i);
                         response = await this.helpers.httpRequestWithAuthentication.call(this, 'calaApi', {
                             method: 'GET',
-                            url: `${BASE_URL}/v1/knowledge/entities/${entityId}`,
+                            url: `${BASE_URL}/v1/entities/${entityId}/introspection`,
                             json: true,
                         });
                     }
@@ -200,6 +364,8 @@ class Cala {
                 });
             }
             catch (error) {
+                if (error instanceof n8n_workflow_1.NodeOperationError)
+                    throw error;
                 if (this.continueOnFail()) {
                     returnData.push({
                         json: { error: new n8n_workflow_1.NodeApiError(this.getNode(), error).message },
@@ -207,7 +373,7 @@ class Cala {
                     });
                     continue;
                 }
-                throw new n8n_workflow_1.NodeApiError(this.getNode(), error);
+                throw new n8n_workflow_1.NodeApiError(this.getNode(), error, { itemIndex: i });
             }
         }
         return [returnData];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-cala",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "n8n nodes for Cala AI knowledge search",
   "keywords": [
     "n8n-community-node-package",