n8n-nodes-caedral 0.1.0 → 0.3.0

package/README.md

@@ -1,92 +1,138 @@
 # n8n-nodes-caedral
 
-Official [n8n](https://n8n.io) community node for the [Caedral API](https://caedral.com). Send chat completions and check prepaid API usage from your workflows.
+Community node for [n8n](https://n8n.io/) that integrates with [Caedral AI](https://caedral.com) — unified access to frontier and proprietary AI models through one API.
 
 ## Installation
 
-### npm (recommended for self-hosted n8n)
+In your n8n instance:
+
+1. Go to **Settings → Community Nodes**
+2. Enter `n8n-nodes-caedral`
+3. Click **Install**
+
+Or via CLI:
 
 ```bash
-cd ~/.n8n/custom
+cd ~/.n8n
 npm install n8n-nodes-caedral
-# Restart n8n
 ```
 
-### Local development (monorepo)
+## Nodes
 
-```bash
-cd n8n-nodes-caedral
-npm install && npm run build
-npm link
-cd ~/.n8n/custom && npm link n8n-nodes-caedral
-```
+### Caedral (Main Node)
 
-## Credentials
+Full-featured node with 8 operations covering all Caedral API capabilities:
 
-Create **Caedral API** credentials in n8n:
+| Operation | Description |
+|-----------|-------------|
+| **Chat Completion** | Send messages to any Caedral model tier (Base, Titan, Olympus, Primordial) with system prompts, temperature, and max tokens |
+| **Generate Image** | Create images from text prompts using Caedral Vision (1024×1024, 1792×1024, 1024×1792) |
+| **Create Embedding** | Generate vector embeddings for text or arrays of texts using Caedral Embed |
+| **Generate Audio** | Convert text to speech with voice selection (alloy, echo, fable, onyx, nova, shimmer) |
+| **Rerank** | Semantically rerank documents by relevance to a query using Caedral Rerank |
+| **List Models** | Retrieve all available models (chat + specialized) |
+| **Get Usage** | Check pool balance, weekly usage, and overage status |
+| **Get Account Info** | View account status, plan details, and billing information |
 
-| Field | Description |
-|-------|-------------|
-| API Key | Your `cd_live_...` key from [Dashboard → API Keys](https://caedral.com/dashboard/api-keys) |
-| Base URL | `https://api.caedral.com` (production) or `http://localhost:5001` (local gateway) |
+### Caedral Chat Model (AI Sub-Node)
 
-Connection test calls `GET /v1/usage`.
+An AI Language Model node that plugs directly into n8n's native **AI Agent** and **Chain** nodes. Connect it as the language model input to instantly power your AI workflows with Caedral.
 
-## Operations
+- Select model tier (Base/Titan/Olympus/Primordial)
+- Configure temperature and max tokens
+- Compatible with all n8n AI Agent patterns
 
-### Chat Completion
+### Caedral Trigger (Polling)
 
-Send a chat completion to any Caedral model tier (`caedral-base`, `caedral-titan`, `caedral-olympus`, `caedral-primordial`).
+Automatically trigger workflows based on account conditions:
 
-Configure:
+- **Balance Below Threshold** — fires when your balance in cents drops below a configured amount
+- **Pool Usage Above Percentage** — fires when weekly pool usage exceeds a percentage threshold
 
-- **Model** — dropdown of available tiers
-- **Messages** — JSON array or individual role/content fields
-- **Temperature**, **Max Tokens** — optional generation parameters
+Polling interval configurable in n8n's trigger settings.
 
-Returns parsed `content`, `model`, `finishReason`, and `usage` fields.
+## Credentials
 
-### Get Usage
+Create a **Caedral API** credential with:
 
-Returns prepaid API balance, weekly pool (for Caedral Chat), plan info, and account status via `GET /v1/usage`.
+| Field | Description |
+|-------|-------------|
+| **API Key** | Your `cd_live_...` key from the [Caedral dashboard](https://caedral.com/dashboard/api-keys) |
+| **Base URL** | Default: `https://api.caedral.com`. Use `http://localhost:5001` for local development |
 
-## Example workflow
+The credential is validated by calling `GET /v1/usage` on save.
 
-1. **Get Usage** — check `balanceCents` before a paid-tier call
-2. **IF** — continue only if balance is sufficient
-3. **Chat Completion** — run inference with `caedral-olympus`
-4. Send output to Slack, email, or downstream nodes
+## Models
 
-See [Example n8n workflow](https://caedral.com/docs/n8n-example) in the Caedral docs.
+### Chat Models (for Chat Completion & AI Agent)
 
-## HTTP details
+| Model ID | Tier | Use Case |
+|----------|------|----------|
+| `caedral-base` | Free | Prototyping, everyday tasks |
+| `caedral-titan` | Efficient | High-volume production |
+| `caedral-olympus` | Balanced | Complex agentic applications |
+| `caedral-primordial` | Frontier | Research, mission-critical |
 
-The node calls the Caedral API gateway directly:
+### Specialized Models
 
-- `POST /v1/chat/completions` — chat completion
-- `GET /v1/usage` — usage summary
+| Model ID | Modality | Pricing |
+|----------|----------|---------|
+| `caedral-vision` | Image generation | ~$3.50/M tokens |
+| `caedral-embed` | Text embeddings | ~$0.18/M tokens |
+| `caedral-voice` | Audio/speech | ~$0.84/M tokens |
+| `caedral-rerank` | Semantic reranking | ~$0.35/request |
 
-Authentication: `Authorization: Bearer <apiKey>`.
+## Example Workflows
+
+### AI Agent with Caedral
+
+1. Add an **AI Agent** node
+2. Connect a **Caedral Chat Model** node as the Language Model input
+3. Select your preferred model tier (e.g., Olympus for balanced performance)
+4. Add tools (HTTP Request, Code, etc.) to the agent
+
+### Low Balance Alert
+
+1. Add a **Caedral Trigger** node
+2. Set condition to "Balance Below Threshold"
+3. Set threshold to 1000 (= $10.00)
+4. Connect to a Slack/Email notification node
+
+### Document Embedding Pipeline
+
+1. Trigger: new documents arrive
+2. **Caedral** node → Create Embedding operation
+3. Store embeddings in your vector database
 
 ## Development
 
 ```bash
+git clone https://github.com/caedral/n8n-nodes-caedral.git
+cd n8n-nodes-caedral
 npm install
 npm run build
 npm test
 ```
 
-Integration tests require a running local gateway on port **5001** and `DATABASE_URL` in the repo root `.env`.
-
-## Publishing
+### Project Structure
 
-See [PUBLISHING.md](./PUBLISHING.md) for npm publish and n8n Creator Portal submission steps.
+```
+├── credentials/          # API credential type
+├── nodes/
+│   ├── Caedral/          # Main multi-operation node
+│   ├── CaedralChatModel/ # AI Agent sub-node
+│   └── CaedralTrigger/   # Polling trigger node
+├── shared/               # Constants and utilities
+├── tests/                # Integration tests
+└── icons/                # Node icons (light + dark)
+```
 
 ## Links
 
-- [Caedral docs — n8n overview](https://caedral.com/docs/n8n-overview)
-- [npm package](https://www.npmjs.com/package/n8n-nodes-caedral)
-- [GitHub](https://github.com/caedral/n8n-nodes-caedral)
+- [Caedral Documentation](https://caedral.com/docs)
+- [API Reference](https://caedral.com/docs/api-reference)
+- [n8n Integration Guide](https://caedral.com/docs/n8n-overview)
+- [Report Issues](https://github.com/caedral/n8n-nodes-caedral/issues)
 
 ## License
 

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

@@ -1,36 +1,5 @@
 import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
-/**
- * n8n node exposing the Caedral API.
- *
- * Supports two operations:
- * - `chatCompletion` — send a chat completion request to a Caedral
- *   model, either with a single simple message or a full JSON
- *   messages array.
- * - `getUsage` — fetch the account's current pool, balance, and
- *   overage status.
- *
- * Requests are authenticated using the `caedralApi` credentials
- * (API key + optional base URL override).
- */
 export declare class Caedral implements INodeType {
     description: INodeTypeDescription;
-    /**
-     * Execute the node for every input item.
-     *
-     * For each item, resolves the selected `operation` and dispatches
-     * the corresponding Caedral API call. On success, the response is
-     * normalized into a flat JSON object and pushed to the output.
-     *
-     * When "Continue On Fail" is enabled, per-item errors are captured
-     * as `{ error: string }` entries in the output; otherwise the
-     * error is re-thrown (wrapped in `NodeOperationError` if it is not
-     * already a node error).
-     *
-     * @returns A single-branch array of output items, one per input.
-     * @throws {NodeApiError} If the Caedral API returns a non-2xx
-     *   status and "Continue On Fail" is disabled.
-     * @throws {NodeOperationError} For validation or unknown-operation
-     *   errors, or when wrapping an unexpected runtime error.
-     */
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }