@astro-api/n8n-nodes-astrology 0.1.6 → 0.2.0

package/README.md

@@ -108,9 +108,52 @@ Generate SVG birth charts with **Charts → Natal**. Supports 23+ house systems
 
 Import complete workflow examples from the [`examples/`](examples/) folder:
 
+- **[AI Astrologer Assistant](examples/ai-astrologer-assistant.json)** — AI-powered chatbot with multiple Astrology tools. Demonstrates using the node with n8n AI Agent for conversational astrology queries.
 - **[Personal Horoscope Workflow](examples/personal-horoscope-workflow.json)** — Generates personalized horoscopes (day/week/month/year) by comparing natal chart with current transits. Includes AI interpretation.
 - **[Tarot Reading Workflow](examples/tarot-reading-workflow.json)** — Performs tarot card readings influenced by current planetary positions and moon phase. Supports multiple spread types.
 
+### Using with AI Agent
+
+The Astrology node supports **AI Tool mode** via n8n's `usableAsTool` feature. This allows you to connect the node to an AI Agent for conversational astrology queries.
+
+#### How It Works
+
+When `usableAsTool: true` is set, n8n automatically generates a companion Tool node:
+
+| Node Type | Purpose | Connection Type |
+|-----------|---------|-----------------|
+| `astrology` | Standard workflow node | `main` → `main` |
+| `astrologyTool` | AI Tool for Agent | `ai_tool` → `ai_tool` |
+
+#### Creating AI Workflows
+
+When building workflows with AI Agent:
+
+1. **Use the Tool version** — In workflow JSON, use type `@astro-api/n8n-nodes-astrology.astrologyTool`
+2. **Connect via `ai_tool`** — Connect nodes to AI Agent using `ai_tool` connection type
+3. **Use `$fromAI()` expressions** — Let AI extract parameters automatically
+
+**Example node configuration:**
+```json
+{
+  "parameters": {
+    "year": "={{ $fromAI('year', 'Birth year (e.g., 1990)') }}",
+    "month": "={{ $fromAI('month', 'Month 1-12') }}",
+    "city": "={{ $fromAI('city', 'City name') }}"
+  },
+  "type": "@astro-api/n8n-nodes-astrology.astrologyTool"
+}
+```
+
+**Example connection:**
+```json
+"Planetary Positions": {
+  "ai_tool": [[{"node": "AI Agent", "type": "ai_tool", "index": 0}]]
+}
+```
+
+See [AI Astrologer Assistant](examples/ai-astrologer-assistant.json) for a complete working example.
+
 ## API Documentation
 
 Full API documentation is available at:

package/dist/nodes/Astrology/Astrology.node.js

@@ -28,8 +28,9 @@ class Astrology {
             icon: "file:astrology.svg",
             group: ["transform"],
             version: 1,
+            usableAsTool: true,
             subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
-            description: "Get astrological data from Astrology API",
+            description: "Professional astrological calculations: planetary positions, house cusps, aspects, lunar metrics, horoscopes, and natal charts using Astrology API",
             defaults: {
                 name: "Astrology",
             },

package/dist/nodes/Astrology/operations/charts.operation.js

@@ -161,7 +161,7 @@ const houseSystemField = {
     },
     options: houseSystemOptions,
     default: "P",
-    description: "Astrological house calculation system",
+    description: "House calculation system. Placidus (most common), Whole Sign (traditional), Koch (time-based), Equal (simple), etc.",
 };
 /**
  * Zodiac type selector
@@ -179,16 +179,16 @@ const zodiacTypeField = {
         {
             name: "Tropical (Western)",
             value: "Tropic",
-            description: "Equinox-based zodiac used in Western astrology",
+            description: "Equinox-based zodiac used in Western astrology (signs aligned to seasons)",
         },
         {
             name: "Sidereal (Vedic)",
             value: "Sidereal",
-            description: "Constellation-based zodiac used in Vedic astrology",
+            description: "Constellation-based zodiac used in Vedic/Indian astrology (signs aligned to stars)",
         },
     ],
     default: "Tropic",
-    description: "Zodiac calculation method",
+    description: "Zodiac calculation method: Tropical (Western, season-based) or Sidereal (Vedic, star-based)",
 };
 /**
  * Active points preset selector
@@ -448,7 +448,7 @@ const simplifyField = {
         },
     },
     default: true,
-    description: "Whether to return a simplified version of the response instead of the raw data",
+    description: "Whether to return simplified response with key data only. Disable for full API response with all metadata.",
 };
 /**
  * Combined charts operations export

package/dist/nodes/Astrology/operations/data.operation.js

@@ -19,31 +19,31 @@ const dataOperationField = {
         {
             name: "Aspects",
             value: "aspects",
-            description: "Calculate angular relationships between celestial bodies",
+            description: "Calculate angular relationships (conjunctions, squares, trines, oppositions) between planets and points for astrological interpretation",
             action: "Get aspects data",
         },
         {
             name: "Current Time",
             value: "now",
-            description: "Get current UTC time data for astrological calculations",
+            description: "Get current UTC time with Julian Day number for real-time astrological calculations",
             action: "Get current time data",
         },
         {
             name: "House Cusps",
             value: "houseCusps",
-            description: "Calculate astrological house boundaries",
+            description: "Calculate the 12 astrological house boundaries (cusps) using specified house system (Placidus, Whole Sign, Koch, etc.)",
             action: "Get house cusps data",
         },
         {
             name: "Lunar Metrics",
             value: "lunarMetrics",
-            description: "Calculate moon phase cycles and illumination",
+            description: "Get current Moon phase, illumination percentage, and lunar cycle position",
             action: "Get lunar metrics data",
         },
         {
             name: "Planetary Positions",
             value: "positions",
-            description: "Calculate planetary positions with zodiac signs and degrees",
+            description: "Calculate positions of planets and points showing zodiac sign, degree, minute, retrograde status",
             action: "Get planetary positions data",
         },
     ],
@@ -69,7 +69,7 @@ const simplifyField = {
         },
     },
     default: true,
-    description: "Whether to return a simplified version of the response instead of the raw data",
+    description: "Whether to return simplified response with key data only. Disable for full API response with all metadata.",
 };
 exports.dataOperations = [
     // Operation selector

package/dist/nodes/Astrology/operations/horoscope.operation.js

@@ -178,7 +178,7 @@ exports.horoscopeOperations = [
             { name: "Virgo", value: "virgo" },
         ],
         default: "aries",
-        description: "The zodiac sign for the horoscope",
+        description: "Select the zodiac sign (Aries through Pisces) to get horoscope predictions for",
         required: true,
     },
     // Birth data fields (for personal operations and Chinese Bazi)
@@ -194,7 +194,7 @@ exports.horoscopeOperations = [
         },
         default: 1990,
         placeholder: "e.g. 1990",
-        description: "Birth year",
+        description: "Birth year in 4-digit format (e.g., 1990)",
         required: true,
     },
     {
@@ -213,7 +213,7 @@ exports.horoscopeOperations = [
             minValue: 1,
             maxValue: 12,
         },
-        description: "Birth month (1-12)",
+        description: "Birth month as number 1-12 (January=1, December=12)",
         required: true,
     },
     {
@@ -232,7 +232,7 @@ exports.horoscopeOperations = [
             minValue: 1,
             maxValue: 31,
         },
-        description: "Birth day (1-31)",
+        description: "Birth day of month (1-31)",
         required: true,
     },
     {
@@ -251,7 +251,7 @@ exports.horoscopeOperations = [
             minValue: 0,
             maxValue: 23,
         },
-        description: "Birth hour (0-23)",
+        description: "Birth hour in 24-hour format (0-23, where 0=midnight, 12=noon)",
         required: true,
     },
     {
@@ -297,7 +297,7 @@ exports.horoscopeOperations = [
             },
         ],
         default: "city",
-        description: "How to specify the birth location",
+        description: "Choose how to specify birth location: by city name (auto-detects coordinates) or exact latitude/longitude",
     },
     // City-based location
     {
@@ -313,7 +313,7 @@ exports.horoscopeOperations = [
         },
         default: "",
         placeholder: "London",
-        description: "City name",
+        description: 'Birth city name (e.g., "London", "New York", "Kyiv")',
         required: true,
     },
     {
@@ -329,7 +329,7 @@ exports.horoscopeOperations = [
         },
         default: "",
         placeholder: "GB",
-        description: "ISO 3166-1 alpha-2 country code (e.g., UA, US, GB, DE)",
+        description: "2-letter ISO country code for the birth city (e.g., US, GB, UA, DE, FR)",
         required: true,
     },
     // Coordinate-based location
@@ -350,7 +350,7 @@ exports.horoscopeOperations = [
             minValue: -90,
             maxValue: 90,
         },
-        description: "Latitude of birth place (-90 to 90)",
+        description: "Geographic latitude of birth location in decimal degrees (-90 to 90, positive=North)",
         required: true,
     },
     {
@@ -370,7 +370,7 @@ exports.horoscopeOperations = [
             minValue: -180,
             maxValue: 180,
         },
-        description: "Longitude of birth place (-180 to 180)",
+        description: "Geographic longitude of birth location in decimal degrees (-180 to 180, positive=East)",
         required: true,
     },
     // Target date (for all horoscope operations)
@@ -388,7 +388,7 @@ exports.horoscopeOperations = [
         },
         default: "",
         placeholder: "2024-01-15",
-        description: "Target date for prediction (YYYY-MM-DD). Leave empty for today.",
+        description: "Date for prediction in YYYY-MM-DD format. Leave empty for current date predictions.",
     },
     // Bazi Year (for Chinese Bazi)
     {
@@ -416,7 +416,7 @@ exports.horoscopeOperations = [
         },
         default: "en",
         placeholder: "en",
-        description: "Response language code (en, uk, ru, es, de, etc.)",
+        description: "Language code for horoscope text output (en=English, uk=Ukrainian, ru=Russian, es=Spanish, de=German)",
     },
     // Tradition (for all horoscope operations)
     {
@@ -440,7 +440,7 @@ exports.horoscopeOperations = [
             { name: "Vedic", value: "vedic" },
         ],
         default: "universal",
-        description: "Astrological tradition to use",
+        description: "Astrological tradition affecting interpretation style and emphasis",
     },
     // Text format (for text operations)
     {
@@ -461,7 +461,7 @@ exports.horoscopeOperations = [
             { name: "Structured", value: "structured" },
         ],
         default: "paragraph",
-        description: "Text output style",
+        description: "Output format for text predictions: short (1-2 sentences), paragraph (flowing text), bullets (key points), structured (categorized sections)",
     },
     // Include emoji (for text operations)
     {

package/dist/nodes/Astrology/operations/resource.options.js

@@ -14,17 +14,17 @@ exports.resourceField = {
         {
             name: "Chart",
             value: "charts",
-            description: "Generate astrological charts (natal, transit, etc.)",
+            description: "Generate natal (birth) charts with planetary positions, houses, and aspects for a given birth time and location",
         },
         {
             name: "Data",
             value: "data",
-            description: "Astrological data calculations",
+            description: "Get raw astrological calculations: planetary positions, house cusps, aspects between planets, and lunar phase data",
         },
         {
             name: "Horoscope",
             value: "horoscope",
-            description: "Daily, weekly, monthly, and yearly predictions",
+            description: "Generate horoscope predictions by zodiac sign or personalized by birth data (daily, weekly, monthly, yearly)",
         },
     ],
     default: "data",

package/dist/nodes/Astrology/shared/birthData.fields.js

@@ -30,7 +30,7 @@ function createBirthDataFields(resourceName, showForOperations, hideForOperation
             displayOptions: { ...baseDisplayOptions },
             default: 1990,
             placeholder: "e.g. 1990",
-            description: "Birth year",
+            description: "Birth year in 4-digit format (e.g., 1990)",
             required: true,
         },
         {
@@ -44,7 +44,7 @@ function createBirthDataFields(resourceName, showForOperations, hideForOperation
                 minValue: 1,
                 maxValue: 12,
             },
-            description: "Birth month (1-12)",
+            description: "Birth month as number 1-12 (January=1, December=12)",
             required: true,
         },
         {
@@ -58,7 +58,7 @@ function createBirthDataFields(resourceName, showForOperations, hideForOperation
                 minValue: 1,
                 maxValue: 31,
             },
-            description: "Birth day (1-31)",
+            description: "Birth day of month (1-31)",
             required: true,
         },
         {
@@ -72,7 +72,7 @@ function createBirthDataFields(resourceName, showForOperations, hideForOperation
                 minValue: 0,
                 maxValue: 23,
             },
-            description: "Birth hour (0-23)",
+            description: "Birth hour in 24-hour format (0-23, where 0=midnight, 12=noon)",
             required: true,
         },
         {

package/dist/nodes/Astrology/shared/location.fields.js

@@ -63,7 +63,7 @@ function createLocationFields(resourceName, showForOperations, hideForOperations
                 },
             ],
             default: "city",
-            description: "How to specify the birth location",
+            description: "Choose how to specify birth location: by city name (auto-detects coordinates) or exact latitude/longitude",
         },
         // City-based location fields
         {
@@ -73,7 +73,7 @@ function createLocationFields(resourceName, showForOperations, hideForOperations
             displayOptions: cityDisplayOptions,
             default: "",
             placeholder: "London",
-            description: "City name",
+            description: 'Birth city name (e.g., "London", "New York", "Kyiv")',
             required: true,
         },
         {
@@ -83,7 +83,7 @@ function createLocationFields(resourceName, showForOperations, hideForOperations
             displayOptions: cityDisplayOptions,
             default: "",
             placeholder: "GB",
-            description: "ISO 3166-1 alpha-2 country code (e.g., UA, US, GB, DE)",
+            description: "2-letter ISO country code for the birth city (e.g., US, GB, UA, DE, FR)",
             required: true,
         },
         // Coordinate-based location fields
@@ -98,7 +98,7 @@ function createLocationFields(resourceName, showForOperations, hideForOperations
                 minValue: -90,
                 maxValue: 90,
             },
-            description: "Latitude of birth place (-90 to 90)",
+            description: "Geographic latitude of birth location in decimal degrees (-90 to 90, positive=North)",
             required: true,
         },
         {
@@ -112,7 +112,7 @@ function createLocationFields(resourceName, showForOperations, hideForOperations
                 minValue: -180,
                 maxValue: 180,
             },
-            description: "Longitude of birth place (-180 to 180)",
+            description: "Geographic longitude of birth location in decimal degrees (-180 to 180, positive=East)",
             required: true,
         },
     ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astro-api/n8n-nodes-astrology",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "n8n community node for Astrology API - professional astrological calculations, charts, horoscopes, and interpretations",
   "main": "dist/index.js",
   "scripts": {
@@ -70,7 +70,7 @@
     ]
   },
   "peerDependencies": {
-    "n8n-workflow": "1.55.0"
+    "n8n-workflow": "1.120.7"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
@@ -81,7 +81,7 @@
     "eslint-plugin-n8n-nodes-base": "^1.16.5",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
-    "n8n-workflow": "1.55.0",
+    "n8n-workflow": "1.120.7",
     "prettier": "3.4.1",
     "typescript": "5.5.4"
   }