@signal4/s4 2.2.0 → 2.5.0

package/README.md

@@ -1,24 +1,155 @@
 # @signal4/s4
 
-Media intelligence CLI and MCP server for AI agents.
+Media intelligence platform — CLI, MCP server, and TypeScript client.
 
 Search quotes, analyze discourse, track trends, and explore speakers across thousands of hours of audiovisual content.
 
-## CLI
+## Architecture
+
+This package contains three surfaces backed by one HTTP client:
+
+```
+@signal4/s4
+├── client.ts      ← Typed HTTP client (38 functions wrapping the REST API)
+├── types.ts       ← TypeScript types for all API responses
+├── config.ts      ← Config loader (~/.signal4/config)
+├── cli.ts         ← Terminal interface (s4 search, s4 speaker, ...)
+├── index.ts       ← MCP server for Claude Desktop / Cursor
+└── handlers/      ← Human-readable formatters (shared by CLI + MCP)
+```
+
+**Client** is the core — everything else is a consumer. Use it directly for programmatic access; use the CLI or MCP server for interactive use.
+
+| Surface | Entry point | Reads from | Formats with |
+|---------|-------------|------------|-------------|
+| TypeScript client | `import from '@signal4/s4/client'` | `client.ts` | — (raw typed responses) |
+| CLI | `npx @signal4/s4 search ...` | `client.ts` | `handlers/` → text |
+| MCP server | `s4 --mcp` | `client.ts` | `handlers/` → text |
+
+## TypeScript Client
+
+For applications that need typed access to the Signal4 API (frontends, agents, pipelines, scripts):
+
+```typescript
+import { searchQuotes, getSpeaker, analyze } from '@signal4/s4/client';
+import type { QuoteSearchResult, SpeakerProfile } from '@signal4/s4/types';
+
+// Search for quotes about a topic
+const results = await searchQuotes({
+  topic: 'AI regulation',
+  speaker_name: 'Tucker Carlson',
+  limit: 10,
+  start_date: '2026-05-01',
+});
+
+// Get a speaker profile
+const speaker = await getSpeaker(12345);
+
+// Run an AI analysis
+const analysis = await analyze({
+  query: 'How are podcasters talking about tariffs?',
+  workflow: 'deep_analysis',
+  days: 30,
+});
+```
+
+### Sub-path exports
+
+```typescript
+import { searchQuotes, detectTrend, ... } from '@signal4/s4/client';  // HTTP client
+import type { Quote, SpeakerProfile, ... } from '@signal4/s4/types';   // TypeScript types
+import { applyConfig } from '@signal4/s4/config';                      // Config loader
+```
+
+### Configuration
+
+The client reads from environment variables:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `SIGNAL4_API_KEY` | API key (required) | — |
+| `SIGNAL4_API_URL` | API base URL | `https://api.signal4.ca` |
+| `SIGNAL4_CLIENT_ID` | Client identifier for analytics | — |
+
+`applyConfig()` loads these from `~/.signal4/config` if not already set in the environment. The CLI and MCP server call this automatically; programmatic consumers should call it explicitly if they want the file-based fallback.
+
+### Client functions
+
+**Search**
+- `searchQuotes(params)` — Semantic/keyword search across transcripts
+- `searchClaims(params)` — Search extracted claims with stance and observation counts
+- `detectTrend(params)` — Compare recent vs baseline mention volume
+- `getTimeline(params)` — Topic mention volume over time
+
+**Entities**
+- `searchSpeakers(query, limit?)` — Autocomplete speaker search
+- `getSpeaker(id)` / `getSpeakerByName(name)` — Speaker profile
+- `getSpeakerSegments(params)` — Recent segments by speaker
+- `searchSpeakerSegments(params)` — Semantic search within a speaker's segments
+- `getChannel(id)` / `getChannelByName(name)` — Channel profile
+- `getEpisode(contentId)` — Episode details
+- `getTranscript(contentId)` — Full episode transcript
+- `getSegment(segmentId)` — Single segment with audio clip URL
+- `getSegmentThread(segmentId, n?)` — Conversation context around a segment
+
+**Analysis** (SSE streaming, handled internally)
+- `analyze(params)` — AI-powered analysis (workflows: `simple_rag`, `deep_analysis`, `speaker_compare`, `speaker_dossier`, `contradiction_check`)
+
+**Reports**
+- `getTopSpeakers(params)` / `getTopChannels(params)` — Leaderboards
+- `getSpeakerNetwork(params)` — Co-appearance network graph
+- `getTopics(params)` — Trending topic clusters
+- `getReportStats(days?)` / `getProjectStats()` — Platform statistics
+- `getDiscourseSummary(params)` — AI discourse briefing
+
+**Claims**
+- `getClaim(claimId)` — Full claim detail
+- `getClaimObservations(params)` — Observations supporting a claim
+- `getRelatedClaims(claimId)` — Similar/related claims
+
+**Ads**
+- `getAdStats(days?)` / `getAdvertisers(params)` / `getAdvertiser(id)` — Ad intelligence
+- `getAdsByChannel(channelId, days?)` / `getAdTrends(days?)` — Channel-level and trending ads
+
+**Bookmarks**
+- `createBookmark(params)` / `listBookmarks(params)` / `deleteBookmark(id)`
+
+**Auth**
+- `whoami()` — Verify key and see access scope
+
+### Error handling
+
+All functions throw on error. HTTP 502/503 are retried automatically (3 attempts with backoff). Wrap calls in try/catch:
+
+```typescript
+try {
+  const result = await searchQuotes({ topic: 'tariffs' });
+} catch (err) {
+  console.error((err as Error).message); // "HTTP 401: ..."
+}
+```
+
+### Installing as a dependency
+
+For projects within the signal4 monorepo:
 
 ```bash
-# Install globally
-npm install -g @signal4/s4
+pnpm add @signal4/s4@file:../mcp
+```
+
+For external projects (once published):
 
-# Or run directly
-npx @signal4/s4 search "tariffs" --speaker "Trudeau" --days 7
+```bash
+npm install @signal4/s4
 ```
 
-### Setup
+## CLI
 
 ```bash
-s4 setup                              # Save your API key
-s4 whoami                             # Verify access
+npm install -g @signal4/s4
+
+s4 setup          # Save your API key to ~/.signal4/config
+s4 whoami         # Verify access and see available commands
 ```
 
 ### Commands
@@ -28,6 +159,7 @@ s4 whoami                             # Verify access
 s4 search "immigration" --speaker "Tucker Carlson"
 s4 claims "AI regulation" --entity "OpenAI"
 s4 trend "tariffs"
+s4 timeline "carbon tax" --days 90
 
 # Explore
 s4 speaker "Joe Rogan"
@@ -37,8 +169,9 @@ s4 episode pod_8f1e55513f70 --transcript
 s4 segment 28553756
 s4 thread 28553756
 
-# Analyze
+# Analyze (AI-powered, slower)
 s4 analyze "carbon tax" --days 14
+s4 frames "midterm elections" --days 30
 s4 compare "tariffs" --speakers "Trump,Biden"
 s4 dossier "immigration" --speaker "Carlson"
 s4 contradictions "vaccines" --speaker "Trump"
@@ -59,7 +192,7 @@ s4 bookmarks
 s4 bookmarks add segment 12345 --note "key quote"
 ```
 
-All commands support `--json` for raw JSON output.
+All commands support `--json` for raw JSON output (bypasses the handler formatting layer and calls the client directly).
 
 ## MCP Server
 
@@ -79,14 +212,9 @@ For Claude Desktop, Cursor, or other MCP clients:
 }
 ```
 
-Tool definitions are loaded dynamically from the API based on your key's access level.
+Tool definitions are loaded dynamically from the API based on your key's access level. The MCP server uses the same handlers as the CLI for formatting responses.
 
 ## Requirements
 
 - Node.js 18+
 - A Signal4 API key ([signal4.ca](https://signal4.ca))
-
-## Links
-
-- [Signal4](https://signal4.ca)
-- [API docs](https://signal4.ca/docs/api)

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,6EAA6E;AA+vB7E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAwD1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAmkC7E,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAwD1C"}