@notilens/notilens 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,150 @@
+# NotiLens
+
+CLI tool for sending AI agent task lifecycle notifications to [NotiLens](https://www.notilens.com).
+
+## Installation
+
+```bash
+npm install -g @notilens/notilens
+```
+
+## Setup
+
+Register your agent with its endpoint and secret from the NotiLens dashboard:
+
+```bash
+notilens add-agent <agent-name> http <endpoint> <secret>
+```
+
+**Example:**
+```bash
+notilens add-agent my-agent http https://hook.notilens.com/webhook/[TOPIC_TOKEN]/send [TOPIC_SECRET]
+```
+
+---
+
+## Usage
+
+### Task Lifecycle
+
+```bash
+# Start a task (auto-generates task ID if omitted)
+notilens task.start --agent my-agent --task task_001
+
+# Mark in progress
+notilens task.in_progress --agent my-agent --task task_001
+
+# Complete successfully
+notilens task.complete "Processed 100 records" --agent my-agent --task task_001
+
+# Report an error (non-terminal, task continues)
+notilens task.error "Step 3 flow Crashed" --agent my-agent --task task_001
+
+# Retry
+notilens task.retry --agent my-agent --task task_001
+
+# Loop iteration
+notilens task.loop "Processing step 1" --agent my-agent --task task_001
+
+# Fail (terminal)
+notilens task.fail "Worker failed" --agent my-agent --task task_001
+
+# Timeout (terminal)
+notilens task.timeout "Took more than 15 secs" --agent my-agent --task task_001
+
+# Cancel (terminal)
+notilens task.cancel "User cancelled" --agent my-agent --task task_001
+
+# Terminate (terminal)
+notilens task.terminate "Out of memory" --agent my-agent --task task_001
+```
+
+### AI Response Events
+
+```bash
+notilens ai.response.generate "Summary generated" --agent my-agent --task task_001
+notilens ai.response.fail "Model unavailable" --agent my-agent --task task_001
+```
+
+### Input Events
+
+```bash
+notilens input.required "Please confirm the output" --agent my-agent --task task_001
+notilens input.approve "User approved" --agent my-agent --task task_001
+notilens input.reject "User rejected" --agent my-agent --task task_001
+```
+
+### Metrics
+
+Track token usage and confidence after an AI call:
+
+```bash
+# set.metrics <prompt_tokens> <completion_tokens> [confidence] --agent ... --task ...
+notilens set.metrics 512 128 0.95 --agent my-agent --task task_001
+```
+
+### Generic Event
+
+Emit any custom event:
+
+```bash
+notilens emit "data.processed" "Ingested 500 rows" --agent my-agent --task task_001
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--agent <name>` | Agent name (required) |
+| `--task <id>` | Task ID (auto-generated if omitted) |
+| `--type` | Override notification type: `info` `success` `warning` `urgent` `important` |
+| `--meta key=value` | Custom metadata (repeatable) |
+| `--image_url <url>` | Attach an image |
+| `--open_url <url>` | Link to open |
+| `--download_url <url>` | Link to download |
+| `--tags "tag1,tag2"` | Comma-separated tags |
+| `--is_actionable true\|false` | Override actionable flag |
+| `--confidence <0-1>` | Confidence score |
+
+---
+
+## Notification Types
+
+Events are automatically mapped to notification types:
+
+| Type | Events |
+|------|--------|
+| `success` | `task.completed`, `response.generated`, `input.approved` |
+| `urgent` | `task.failed`, `task.timeout`, `response.failed` |
+| `important` | `task.error`, `task.terminated` |
+| `warning` | `task.retrying`, `task.cancelled`, `input.required`, `input.rejected` |
+| `info` | All others |
+
+---
+
+## Full Example
+
+```bash
+# Register agent
+notilens add-agent summarizer http https://hook.notilens.com/webhook/my_topic_token/send mysecret
+
+# Start task
+notilens task.start --agent summarizer --task job_42
+
+# Update token metrics mid-task
+notilens set.metrics 1024 256 --agent summarizer --task job_42
+
+# Add custom metadata
+notilens task.complete "Summary ready" --agent summarizer --task job_42 \
+  --meta input_file=report.pdf \
+  --meta pages=12 \
+  --open_url https://example.com/summary.pdf
+```
+
+---
+
+## License
+
+MIT — [notilens.com](https://www.notilens.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notilens/notilens",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "NotiLens CLI — send AI agent task lifecycle notifications",
   "keywords": ["notilens", "ai-agent", "notifications", "monitoring", "cli"],
   "homepage": "https://www.notilens.com",