flashrev-ai-enrich 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `flashrev-ai-enrich` are documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/), version follows [SemVer](https://semver.org/).
+
+## [1.0.0] - 2026-05-29
+
+First public release.
+
+### Highlights
+
+- CSV-first enrichment workflow with dry-run estimate, 10-row sample preview, and full-batch run.
+- 34 enrichment capabilities covering company / person / contact-unlock / verify / FlashAgent / scrape / LLM categories, kept in sync with the backend capability registry at runtime.
+- Natural-language **prompt routing** (`--prompt "..."`) that selects a capability automatically via the FlashRev `run_llm` capability (1 routing token + per-row cost).
+- Pay-on-success billing: rows that fail or come back empty are not charged; per-prompt routing is also free when the LLM call itself errors.
+- Built-in `customer_api` capability for mixing third-party HTTP APIs into the same pipeline at zero token cost.
+- AI-mode (`--ai-mode` or `FLASHREV_ENRICH_AI_MODE=1`) emits structured JSON for list commands and errors so upstream agents can parse outputs reliably.
+
+### Added
+
+- Commands: `init`, `doctor [--no-api]`, `tokens [--json]`, `token-history [--from] [--to] [--limit] [--json]`, `schema [--json]`, `dry-run`, `run`.
+- Per-row flags: `--source`, `--out`, `--capability`, `--prompt`, `--map`, `--output`, `--output-fields`, `--input`, `--job`, `--yes`, `--concurrency`, `--sample-size`, `--skip-balance-check`, `--config`.
+- Global flag: `--ai-mode` / `FLASHREV_ENRICH_AI_MODE=1` — JSON list outputs + JSON error envelope.
+- Inline single-row mode: `flashrev-ai-enrich run --capability X --input k=v --out out.csv`.
+- Job file mode: `--job enrich.job.json` for repeatable presets.
+- Routing decision block printed before estimation when `--prompt` is used (capability / inputMapping / outputMapping / reasoning / routing cost).
+- Status semantics in the output CSV: `success`, `cached`, `no_data`, `failed`.
+
+### Notes
+
+- Auth is `X-API-Key` against the FlashRev open-API gateway (`https://open-ai-api.flashlabs.ai`). Get a key at https://info.flashlabs.ai/settings/privateApps.
+- The CLI does not store the API key in any artifact. Prefer `FLASHREV_API_KEY` env var.
+- Pre-existing bug fix while wiring prompt routing: `applyRemoteConfigs` no longer overwrites local capability rules / inputs / outputs with empty arrays returned by `/configs` for some capabilities — this restores rule-validation enforcement for explicit `--capability` runs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flashlabs
+
+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

@@ -0,0 +1,334 @@
+# FlashRev AI Enrich
+
+A CSV-first CLI for FlashRev Lists Enrichment. Authenticate with your FlashRev API key, estimate token usage via dry-run, preview a 10-row sample, then enrich the rest of the CSV and write a new output file.
+
+Two ways to drive it:
+
+- **`--capability <funcName>`** — pick a capability from `schema`; deterministic, zero routing cost. Preferred for agents and scripts.
+- **`--prompt "<natural-language>"`** — describe the intent and let the FlashRev `run_llm` capability pick the funcName + column mappings. Costs 1 extra token. Convenient for ad-hoc human use.
+
+## Install
+
+```bash
+npm install -g flashrev-ai-enrich
+flashrev-ai-enrich --help
+```
+
+Or one-shot via `npx`:
+
+```bash
+npx flashrev-ai-enrich --help
+```
+
+## Quick Start
+
+> Generate a private app API key at https://info.flashlabs.ai/settings/privateApps before running the commands below.
+
+```bash
+export FLASHREV_API_KEY="your_flashrev_api_key"
+
+# 1. Self-check
+flashrev-ai-enrich doctor
+
+# 2. Browse capabilities
+flashrev-ai-enrich schema
+
+# 3. Check balance
+flashrev-ai-enrich tokens
+
+# 4. Estimate cost without spending tokens
+flashrev-ai-enrich dry-run \
+  --source examples/sample-prospects.csv \
+  --capability match_company_id \
+  --map company_linkedin=company_linkedin
+
+# 5. Real enrichment (10-row sample preview first, then the rest)
+flashrev-ai-enrich run \
+  --source examples/sample-prospects.csv \
+  --out enriched.csv \
+  --capability match_company_id \
+  --map company_linkedin=company_linkedin \
+  --output company_id=company_id \
+  --output company_name=company_name \
+  --yes
+
+# 6. Audit spend
+flashrev-ai-enrich token-history --from 2026-05-01
+```
+
+## AI-mode (for agent invocation)
+
+When `flashrev-ai-enrich` is called by an upstream agent (OpenClaw, Claude Code, etc.), turn on `--ai-mode` to get JSON for every list command and a structured JSON envelope for errors:
+
+```bash
+flashrev-ai-enrich --ai-mode tokens
+# {"remaining": 964013.01, "total": 1011000, ...}
+
+flashrev-ai-enrich --ai-mode schema
+# {"capabilities": [...]}
+
+FLASHREV_ENRICH_AI_MODE=1 flashrev-ai-enrich run --source x.csv --out y.csv --capability bad_name --yes
+# stderr: {"error":{"code":"UNKNOWN","message":"Unknown capability: bad_name. ..."}}
+```
+
+Equivalent to passing `--json` on every list command. `run` / `dry-run` keep their human-readable progress output.
+
+## Authentication
+
+```bash
+export FLASHREV_API_KEY="your_flashrev_api_key"
+flashrev-ai-enrich tokens
+```
+
+The CLI calls the FlashRev open API at `https://open-ai-api.flashlabs.ai` and sends the key in the `X-API-Key` request header (no `Bearer` prefix). API keys are read from `FLASHREV_API_KEY` by default and are never written to artifacts. If the balance is `0`, real enrichment is blocked and the user is asked to recharge.
+
+Token usage history:
+
+```bash
+flashrev-ai-enrich token-history --from 2026-05-01 --to 2026-05-27
+flashrev-ai-enrich token-history --from 2026-05-01 --limit 20 --json
+```
+
+## Worked Example
+
+Match seven LinkedIn company URLs to their FlashRev `company_id` and canonical name. The sample CSV and the enriched output are both committed under `examples/`.
+
+**Input** — `examples/sample-prospects.csv`
+
+```csv
+company_linkedin
+https://www.linkedin.com/company/microsoft
+https://www.linkedin.com/company/google
+https://www.linkedin.com/company/nvidia
+https://www.linkedin.com/company/salesforce
+https://www.linkedin.com/company/uber-com
+https://www.linkedin.com/company/openai
+https://www.linkedin.com/company/anthropicresearch
+```
+
+**Command**
+
+```bash
+export FLASHREV_API_KEY="your_flashrev_api_key"
+
+flashrev-ai-enrich run \
+  --source examples/sample-prospects.csv \
+  --out examples/sample-prospects-enriched.csv \
+  --capability match_company_id \
+  --map company_linkedin=company_linkedin \
+  --output company_id=company_id \
+  --output company_name=company_name \
+  --yes
+```
+
+Flag breakdown:
+
+- `--capability match_company_id` — capability `funcName`, taken from `flashrev-ai-enrich schema`
+- `--map <api_field>=<csv_column>` — fills the capability input field from the named CSV column (rules: at least one full rule must be satisfied per row)
+- `--output <csv_column>=<api_response_field>` — writes each named response field into a CSV column
+- `--yes` — skip the post-sample interactive confirmation (required in CI / non-TTY)
+
+**Output** — `examples/sample-prospects-enriched.csv`
+
+```csv
+company_linkedin,company_id,company_name,flashrev_enrich_status,flashrev_enrich_error
+https://www.linkedin.com/company/microsoft,569b2d141f922c03fd911a9f550fe703,Microsoft,success,
+https://www.linkedin.com/company/google,d0ae7d1e14de9efabb4f05d257310511,Google,success,
+https://www.linkedin.com/company/nvidia,c79327dc1ff953ce986cd90bad2efd85,NVIDIA,success,
+https://www.linkedin.com/company/salesforce,56aff5826708380c256230153a49b1c3,Salesforce,success,
+https://www.linkedin.com/company/uber-com,de65de0b033837eb4ade9c1b899c6391,Uber,success,
+https://www.linkedin.com/company/openai,276095f0b5dc46a45ebd9abd339d54c4,OpenAI,success,
+https://www.linkedin.com/company/anthropicresearch,7da27afb4cde929d0cd457ff1646804a,Anthropic,success,
+```
+
+**Run summary**
+
+```
+Capability:           Enrich Company -> Match Company ID
+Rows:                 7
+Unit cost:            1 token(s) / Run
+Estimated tokens:     7
+
+Summary:
+  Completed:   7
+  Failed:      0
+  Cached:      0
+  Tokens used: 7 (estimated 7)
+               (balance 964091.01 → 964084.01)
+```
+
+Rows that come back empty are marked `flashrev_enrich_status=not_found` and **not** billed — FlashRev only charges for rows that produce real data.
+
+### Inline single-row example
+
+Skip the CSV entirely. Useful for spot-checks and shell scripts:
+
+```bash
+flashrev-ai-enrich run \
+  --capability match_company_id \
+  --input company_linkedin=https://www.linkedin.com/company/openai \
+  --out /tmp/openai.csv \
+  --yes
+```
+
+### Verify Email example
+
+```bash
+flashrev-ai-enrich run \
+  --source emails.csv \
+  --out emails.verified.csv \
+  --capability verify_email \
+  --map email=email \
+  --output deliverable_email=deliverable_email \
+  --output email_type=email_type \
+  --output email_provider=email_provider \
+  --yes
+```
+
+A `deliverable_email=true / email_type=business / email_provider=Google Workspace` response confirms the address is deliverable and from a real corporate domain.
+
+## Capabilities
+
+The CLI embeds the FlashRev enrichment registry from `enrichment_config.json` and exposes 34 de-duplicated capabilities across:
+
+- `Enrich Company`
+- `Enrich Person`
+- `FlashAgent`
+
+Contact email and phone enrichment requests are handled by FlashRev backend services and billed as dedicated token actions:
+
+- `enrich_email`
+- `enrich_phone`
+
+The CLI does not call external data services directly and does not expose backend routing to users.
+
+## Data Enrichment Token Costs
+
+Dry-run estimates use the FlashRev Data Enrichment token table unless a live quote endpoint is configured.
+
+| Action | Cost | Unit |
+|---|---:|---|
+| Verify Phone Number | 1 | Run |
+| Verify Email Address | 1 | Run |
+| Enrich Prospect (General) | 1 | Run |
+| Enrich Company (General) | 1 | Run |
+| Enrich FlashAgent (General) | 1 | Run |
+| Get Company CEO | 6 | Run |
+| Get Company Executives | 6 | Run |
+| Get Location | 3 | Run |
+| Get Current Company Name | 8 | Run |
+| Get Emails | 2 | Run |
+| Get Job Title | 5 | Run |
+| Get Phones | 8 | Run |
+| Match Person Linkedin URL | 2 | Run |
+| LinkedIn All Education Experiences | 3 | Run |
+| LinkedIn All Work Experiences | 2 | Run |
+| Deep Research | 3 | Run |
+| LinkedIn Basic Info | 2 | Run |
+| Google Search | 2 | Run |
+| Custom API Request | 2 | Run |
+| Enrich Company Profile (General) | 5 | Run |
+| FlashRev Deep Research | 2 | Run |
+
+Dynamic FlashAgent capabilities such as LLM and scrape/extract may use explicit output fields:
+
+```bash
+flashrev-ai-enrich run \
+  --source leads.csv \
+  --out research.csv \
+  --capability run_llm \
+  --map prompt=prompt \
+  --output summary=summary \
+  --output confidence=confidence \
+  --yes
+```
+
+## Job Files
+
+Job files mirror the SaaS Add Enrichment model:
+
+```json
+{
+  "capability": "get_company_profile",
+  "inputMapping": {
+    "company_name": "company",
+    "company_website": "website"
+  },
+  "outputs": {
+    "flashrev_company_id": "company_id",
+    "company_industry": "industry"
+  }
+}
+```
+
+`inputMapping` maps FlashRev input fields to CSV columns. `outputs` maps output CSV column names to FlashRev response fields.
+
+## Prompt Mode
+
+Prompt mode lets a human describe the enrichment intent in plain language and let the CLI pick a capability automatically. Under the hood, the CLI sends the prompt + CSV column names + the live capability registry to FlashRev's `run_llm` capability and asks for a JSON routing decision (`funcName` / `inputMapping` / `outputMapping`). Routing costs **1 extra token** per invocation, on top of the per-row enrichment cost.
+
+```bash
+flashrev-ai-enrich run --source leads.csv --out leads.enriched.csv \
+  --prompt "fill missing business emails" --yes
+```
+
+Output before the regular dry-run summary:
+
+```
+Routing prompt via run_llm (1 token)...
+
+Routing decision:
+  capability:     enrich_email
+  inputMapping:   first_name=first_name, last_name=last_name, company_name=company
+  outputMapping:  verified_business_email=verified_business_email
+  reasoning:      User asked to fill business emails; enrich_email returns verified business emails.
+  routing cost:   1 token
+```
+
+You can override any inferred mapping with explicit `--map` / `--output` flags — those win over the LLM's choice. If `--capability` is also passed, `--prompt` is dropped with a stderr warning (explicit flag wins).
+
+If the LLM fails to pick a capability (non-JSON answer, unknown `funcName`, or `run_llm` itself returns an error), the CLI exits non-zero with the LLM's `reasoning` shown, and the user retries with explicit `--capability`. No enrichment rows run.
+
+Agents calling this CLI (OpenClaw, Claude Code, CrewAI, etc.) should usually skip `--prompt` and pass `--capability` directly — they already know which capability to use from `flashrev-ai-enrich schema`. `--prompt` is intended for ad-hoc human use.
+
+## Dry Run
+
+`dry-run` validates the CSV and job configuration, then estimates:
+
+- row count
+- estimated API calls
+- estimated token usage
+- estimate source
+
+If FlashRev exposes a quote endpoint, configure it with `init --quote-path` or in config. Otherwise the CLI uses local default per-row estimates. Dry-run does not call the unified enrichment endpoint.
+
+## API Contract Assumptions
+
+The CLI calls a unified FlashRev enrichment endpoint. Backend developers should only need to configure endpoint paths and align the payload/response envelope. The default enrichment request shape is:
+
+```json
+{
+  "mode": "prompt",
+  "prompt": "fill missing emails",
+  "capability_id": "get_company_profile",
+  "input": {
+    "company_name": "Acme"
+  },
+  "requested_outputs": ["company_id", "industry"],
+  "row_index": 1,
+  "source": "flashrev-ai-enrich"
+}
+```
+
+The response may return fields under `values`, `data.values`, `data`, `result`, `results`, `output`, or the response root. Once FlashRev provides the final OpenAPI/curl contract, backend developers should only need to update config endpoint paths or the adapter in `src/flashrev-client.js`.
+
+## Quality Gates
+
+- `flashrev-ai-enrich --help` is complete and copyable.
+- `schema --json` exposes only user-facing capability metadata.
+- `dry-run` never sends a real FlashRev enrichment request.
+- `token-history` supports date filters for auditing token deductions.
+- Real `run` blocks when FlashRev token balance is `0` and tells the user to recharge.
+- `run` writes a new CSV and never overwrites the source unless the user explicitly points `--out` there.
+- Row-level failures write `flashrev_enrich_status=failed` and `flashrev_enrich_error` without stopping the batch.
+- `npm test` and `npm pack` pass before publish.

package/bin/flashrev-ai-enrich.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  // ai-mode (set by main() based on --ai-mode flag or FLASHREV_ENRICH_AI_MODE=1) emits
+  // a structured JSON envelope to stderr so upstream agents can parse errors reliably.
+  if (process.env.__FLASHREV_AI_MODE === "1") {
+    const payload = {
+      error: {
+        code: error?.code || (error?.status ? `HTTP_${error.status}` : "UNKNOWN"),
+        message,
+        remediation: error?.hint || undefined
+      }
+    };
+    console.error(JSON.stringify(payload));
+  } else {
+    console.error(`Error: ${message}`);
+    if (error && error.hint) console.error(`Hint: ${error.hint}`);
+    if (process.env.FLASHREV_ENRICH_DEBUG && error.stack) console.error(error.stack);
+  }
+  process.exitCode = 1;
+});

package/examples/company-profile.job.json

@@ -0,0 +1,14 @@
+{
+  "capability": "get_company_profile",
+  "inputMapping": {
+    "company_name": "company",
+    "company_website": "website",
+    "company_linkedin": "linkedin"
+  },
+  "outputs": {
+    "flashrev_company_id": "company_id",
+    "company_industry": "industry",
+    "company_employees": "employees",
+    "company_linkedin_url": "company_linkedin_url"
+  }
+}

package/examples/leads.csv

@@ -0,0 +1,4 @@
+email,first_name,last_name,company,website,linkedin
+ada@example.com,Ada,Lovelace,Acme AI,https://acme.example,https://www.linkedin.com/company/acme
+ben@example.com,Ben,Stone,Beacon Robotics,https://beacon.example,https://www.linkedin.com/company/beacon
+casey@example.com,Casey,River,Northstar Data,https://northstar.example,https://www.linkedin.com/company/northstar

package/examples/person-email-unlock.job.json

@@ -0,0 +1,13 @@
+{
+  "capability": "enrich_email",
+  "inputMapping": {
+    "email": "email",
+    "first_name": "first_name",
+    "last_name": "last_name",
+    "company_name": "company"
+  },
+  "outputs": {
+    "verified_business_email": "verified_business_email",
+    "all_verified_business_emails": "all_verified_business_emails"
+  }
+}

package/examples/sample-prospects-enriched.csv

@@ -0,0 +1,8 @@
+company_linkedin,company_id,company_name,flashrev_enrich_status,flashrev_enrich_error
+https://www.linkedin.com/company/microsoft,569b2d141f922c03fd911a9f550fe703,Microsoft,success,
+https://www.linkedin.com/company/google,d0ae7d1e14de9efabb4f05d257310511,Google,success,
+https://www.linkedin.com/company/nvidia,c79327dc1ff953ce986cd90bad2efd85,NVIDIA,success,
+https://www.linkedin.com/company/salesforce,56aff5826708380c256230153a49b1c3,Salesforce,success,
+https://www.linkedin.com/company/uber-com,de65de0b033837eb4ade9c1b899c6391,Uber,success,
+https://www.linkedin.com/company/openai,276095f0b5dc46a45ebd9abd339d54c4,OpenAI,success,
+https://www.linkedin.com/company/anthropicresearch,7da27afb4cde929d0cd457ff1646804a,Anthropic,success,

package/examples/sample-prospects.csv

@@ -0,0 +1,8 @@
+company_linkedin
+https://www.linkedin.com/company/microsoft
+https://www.linkedin.com/company/google
+https://www.linkedin.com/company/nvidia
+https://www.linkedin.com/company/salesforce
+https://www.linkedin.com/company/uber-com
+https://www.linkedin.com/company/openai
+https://www.linkedin.com/company/anthropicresearch

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "flashrev-ai-enrich",
+  "version": "1.0.0",
+  "description": "FlashRev Lists Enrichment CLI for CSV-based company, person, and FlashAgent enrichment.",
+  "type": "module",
+  "bin": {
+    "flashrev-ai-enrich": "./bin/flashrev-ai-enrich.js",
+    "flashrev-enrich": "./bin/flashrev-ai-enrich.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:local": "npm pack",
+    "pack:npm": "mkdir -p dist && npm pack --pack-destination dist",
+    "pack:skill": "mkdir -p dist && tar -czf dist/flashrev-ai-enrich-skill-$npm_package_version.tgz -C skills flashrev-ai-enrich",
+    "pack:all": "npm run pack:npm && npm run pack:skill"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "flashrev",
+    "enrichment",
+    "sales",
+    "csv",
+    "cli",
+    "ai-agent"
+  ],
+  "author": "Flashlabs",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}