trendsagi 0.0.0-stage → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [TrendsAGI]
+
+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

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# trendsagi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TrendsAGI command line: what is trending on social platforms right now, with measured volume, velocity and growth, AI insights on why each topic is moving, evidence-backed recommendations, crisis events, your watchlist and read-only SQL, from a terminal or a shell script. No dependencies; Node.js 18 or later.
+
+```bash
+npx trendsagi login              # paste an API key from app.trendsagi.com > Profile > API Keys
+npx trendsagi trends list --category Technology --sort velocity --limit 10
+```
+
+Or install it once:
+
+```bash
+npm install -g trendsagi
+trendsagi --help
+```
+
+## Examples
+
+```bash
+trendsagi trends list --sort velocity --limit 10          # fastest-moving topics
+trendsagi trends analytics 123 --period 7d                # one trend's readings over time
+trendsagi trends dossier 123                               # source-backed story, timeline and channels
+trendsagi trends enrich 123 --module search_demand         # on-demand Deep Dive (can reserve credits)
+trendsagi trends social-evidence get 123                   # stored post-level evidence
+trendsagi trends social-evidence run 123 --module posts    # refresh it (reserves one credit)
+trendsagi credits social-evidence                          # balance and one-time packs
+trendsagi insights get 123                                # audience, sentiment and marketing angles
+trendsagi insights generate 123 --wait                    # build fresh insights, then print them
+trendsagi recommendations list --priority high            # prioritised actions with their evidence
+trendsagi crisis list --status active
+trendsagi watchlist add "oat milk" --threshold 50000 --email
+trendsagi schema                                          # tables the sql command can read
+trendsagi sql "SELECT category, count(*) FROM trends GROUP BY 1 ORDER BY 2 DESC"
+trendsagi webhooks create --url https://example.com/hooks/trends --trigger trend_velocity --threshold 50
+trendsagi ads preview meta_ads --trend 123 --level ad_group
+trendsagi stream --follow "AI,#SaaS"                      # live updates as JSON lines (Node.js 22+)
+trendsagi api /api/integrations/delivery/health -q lookback_hours=24   # any endpoint
+```
+
+| Commands | What they do |
+| --- | --- |
+| `login`, `logout`, `whoami` | Save, forget and check the API key |
+| `trends` | Trending topics: `list`, `get`, `analytics`, `categories`, `autocomplete`, `dossier`, `discoveries`, `enrich`, `search-demand`, `brand-momentum`, `creators`, `ask`, `social-evidence get\|run` |
+| `credits` | `social-evidence` balance, `buy-social-evidence` checkout |
+| `insights` | AI insights: `get`, `generate`, `status`, `search` |
+| `recommendations` (`recs`) | `list`, `action`, `feedback` |
+| `crisis` | `list`, `action` (acknowledge, archive, reopen) |
+| `watchlist` | `list`, `add`, `remove` |
+| `sql`, `schema` | One read-only PostgreSQL SELECT over your data, and the tables it can read |
+| `tools`, `find` | The agent tools (`list`, `call`), and whether TrendsAGI can do a task |
+| `webhooks`, `exports` | Create, change, test and run webhooks and data exports |
+| `ads` | Connected ad platforms: `providers`, `resources`, `preview`, `apply`, `streams`, `report`, `report-export` |
+| `integrations` | `availability`, `status`, `health`, `value` |
+| `stream` | Live trend updates |
+| `usage`, `status`, `api` | API usage, service status, and any endpoint without its own command |
+
+## How it behaves
+
+- **Key:** `--api-key`, then `TRENDSAGI_API_KEY`, then the key `trendsagi login` saved to `~/.config/trendsagi/config.json` (`%APPDATA%\trendsagi` on Windows). The Python CLI (`pip install trendsagi`) reads the same file.
+- **Output:** lists print as tables in a terminal, and as JSON when piped or with `--json`: `trendsagi trends list | jq '.trends[].name'`.
+- **Safety:** commands that delete something or change live ads ask first; pass `--yes` in scripts.
+- **Exit codes:** 0 success, 1 API or request error, 2 invalid usage, 4 missing or rejected API key.
+- **Usage:** each command is the API request it makes and counts against your plan's daily limit.
+
+Run `trendsagi <command> --help` for every option. Guide: [trendsagi.com/api-docs/integrations/cli](https://trendsagi.com/api-docs/integrations/cli). API reference: [trendsagi.com/api-docs/reference](https://trendsagi.com/api-docs/reference).
+
+## Also from TrendsAGI
+
+- Python client, agent tools and a local MCP server: `pip install trendsagi`
+- Hosted MCP server for Claude, ChatGPT, Grok and Cursor: `https://api.trendsagi.com/mcp` ([setup](https://trendsagi.com/mcp))
+
+Source: [github.com/TrendsAGI/TrendsAGI](https://github.com/TrendsAGI/TrendsAGI/tree/main/npm). MIT licensed.

package/bin/trendsagi.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+process.exitCode = await main();