higherdata 0.2.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "higherdata",
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "higherdata": "dist/index.js",
+    "hd": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "15.0.0",
+    "csv-parse": "7.0.3",
+    "ink": "7.1.1",
+    "jsonc-parser": "3.3.1",
+    "libphonenumber-js": "1.13.14",
+    "react": "19.3.0",
+    "smol-toml": "1.9.0",
+    "tldts": "7.4.16",
+    "tr46": "6.0.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "exports": {
+    "./suppression": {
+      "types": "./dist/suppression.d.ts",
+      "import": "./dist/suppression.js"
+    }
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "Find, enrich and clean B2B data with HigherData.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HIGHEROPS-INC/higherdata.git",
+    "directory": "packages/cli"
+  },
+  "higherdata": {
+    "minimumServerVersion": "0.2.0"
+  }
+}

package/skills/higherdata-build-list/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: higherdata-build-list
+description: Build a HigherData company starter list from a website ICP or an existing saved ICP, with editable filters and bounded record counts.
+---
+
+Use the HigherData CLI with `--json`. Check the selected workspace and space with `higherdata --json whoami`; use `higherdata --json use SPACE` if needed. Use `higherdata --json usage` and `higherdata --json limits` to check the plan limits. Never print the API key.
+
+For a new ICP, use the customer's explicit public website. The first proposal needs a website; omitting it later uses the last accepted website in this space. Do not infer it from an email domain.
+
+```sh
+higherdata --json tools icp.propose --website https://cedar.example
+higherdata --json tools icp.create --input "$ICP_CREATE_INPUT"
+```
+
+Set `ICP_CREATE_INPUT` to a JSON object with `name`, the returned `website` and the complete returned `profile`, edited to match the user's target market. Show the proposed industries, location, size and buyer criteria with their evidence. After the user accepts that exact profile, rerun the same create command with `--execute --yes`. The AI proposal uses the workspace's configured AI mode and credit. Core cannot use Insights-only filters.
+
+For an existing ICP, read it first:
+
+```sh
+higherdata --json tools icp.get
+higherdata --json tools icp.preview --id SAVED_ICP_ID
+higherdata --json tools icp.run --id SAVED_ICP_ID --execute --yes
+```
+
+Replace ids with those returned by HigherData. Run `icp.run` for the accepted saved ICP. It creates at most 100 companies from bounded search pages. The preview count can be a baseline that excludes Insights filters; explain `isIcpBaseline` when true.
+
+Suppression applies to both the search and saved records. Report the list id, number added. If a run fails after linking a list, inspect that list instead of blindly starting another run:
+
+```sh
+higherdata --json tools lists.get --id LIST_ID
+```
+
+This skill creates a HigherData list. Sending records to a CRM is a separate task through a reviewed change set.

package/skills/higherdata-enrich-csv/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: higherdata-enrich-csv
+description: Enrich a CSV or JSONL file through HigherData with explicit mappings, a dry-run estimate, resumable job progress and a downloaded result file.
+---
+
+Run CLI commands with `--json`. Verify the selected space and limits:
+
+```sh
+higherdata --json whoami
+higherdata --json usage
+higherdata --json limits
+```
+
+Inspect the input headers locally. Choose the operation and exact target-to-column mappings with the user; do not guess ambiguous identifiers. Company enrichment can map `domain=Website`. Person enrichment can map `email=WorkEmail` or the supported LinkedIn/name and company fields. Preserve original columns. Do not add a suppression override.
+
+```sh
+higherdata --json enrich companies.csv --operation enrich.company --map domain=Website --dry-run
+```
+
+This uploads and validates the mapping without running enrichment. Read the row count and compare it with the file limit. File uploads are retained privately for up to seven days. Email operations need explicit confirmation because provider submissions use the monthly verification allowance. If the file or mapping changes, preview again.
+
+```sh
+higherdata --json enrich companies.csv --operation enrich.company --map domain=Website --wait
+```
+
+Retain the returned job id. Waiting polls that job; it does not create a second job. If interrupted, find the existing job and resume:
+
+```sh
+higherdata --json jobs list
+higherdata --json jobs wait JOB_ID
+higherdata --json jobs get JOB_ID
+higherdata --json jobs download JOB_ID --format csv --output companies-enriched.csv
+```
+
+Use an unused local output filename. The download streams CSV into the file even with `--json`; it is not a JSON report. Inspect the job JSON for completion before downloading. A failed or cancelled job is not success. Report `counts.matched`, `counts.noMatch`, `counts.suppressed`, `counts.failed` from the actual job, along with the output path. If the job is still running, report its id and status. Never reupload simply because waiting was interrupted, and never retry an uncertain start automatically.
+
+The downloaded comparisons distinguish empty, same and conflict values with provenance. Enrichment alone does not write to the customer's CRM. Any requested CRM update must become a change set for separate review.

package/skills/higherdata-suppression/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: higherdata-suppression
+description: Inspect, check or update HigherData suppression lists, including dry-run imports and the limits on owner exclusions.
+---
+
+Use CLI commands with `--json` in the intended space. Suppression is already applied to search, lookup, enrichment, list export and CRM change sets; never work around it by switching surfaces or recovering hidden records.
+
+```sh
+higherdata --json suppress list
+higherdata --json suppress check domain cedar.example
+higherdata --json suppress create Customers --kind customers --dry-run
+higherdata --json suppress import customers.csv --list LIST_ID --key-type domain --dry-run
+```
+
+Only commit an explicitly requested list or import after reviewing the preview (remove `--dry-run` on that same command). Read the import's invalid, duplicate, existing and new counts; do not silently reinterpret invalid input. Select `domain`, `email`, `email_sha256` or another supported key type deliberately. For hashed email uploads use the published normalization spec at `/docs/suppression` and the CLI's shared suppression module; hashing arbitrary email text will not enforce the intended rule.
+
+```sh
+higherdata --json suppress export --list LIST_ID --format jsonl --all
+```
+
+Export includes customer-controlled list entries only, never the global erasure list. Treat exported entries as private data.
+
+An owner can explicitly exclude one eligible list for one call using `--exclude-list LIST_ID` on commands that support it. This is not a durable disable switch. Eligible kinds are customers, open_deals, competitors, partners, employees and custom. `do_not_contact`, `opt_out` and global suppression can never be excluded. Do not introduce an exclusion to fix an empty search; ask the owner about the intended exception when the user actually requests one. API keys do not prove owner status, so a refused exclusion remains refused.
+
+Report counts and reasons returned for the keys the user supplied. A search's suppressed count does not identify the hidden records.

package/skills/higherdata-usage/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: higherdata-usage
+description: Check HigherData plan limits, email verification allowance, monthly activity and resets.
+---
+
+Use the CLI's JSON output to read actual workspace state:
+
+```sh
+higherdata --json whoami
+higherdata --json usage
+higherdata --json limits
+```
+
+All plans offer unlimited searches, lookups and enrichment under fair use. Identify the plan, effective request rate, concurrency, monthly email verification allowance, used and remaining counts, UTC reset time and monthly activity. Do not invent missing values or assume the top plan has no protective ceilings.
+
+Paid email verification submissions use the monthly allowance. Cache hits and polling do not. Core includes 2,000, Insights 10,000, and Unlimited 50,000 per UTC month; configured staff overrides can change these values. Read the actual returned allowance rather than assuming the default. AI uses the workspace's configured mode and credit separately.
+
+Limits combine protective ceilings, the plan, staff overrides and tighter customer rate or record caps. Honor reset times and returned retry delays. Never split a request across keys or spaces to evade a limit. A verification allowance refusal stops new paid submissions until reset or an authorized plan change. Search remains available. Use the returned upgrade link to open HigherTools, select the account, then Billing.
+
+Do not adjust caps or create keys under a usage-check request.

package/skills/higherdata-work-email/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: higherdata-work-email
+description: Find and verify work emails in HigherData using company pattern evidence, a preview and explicit confirmation of the verification allowance.
+---
+
+Use `--json` and the intended space. Check usage and limits before a paid request. For finding, use the person's known first and last names and a company domain or opaque company id. Do not invent an address and describe it as verified.
+
+```sh
+higherdata --json tools email.find --input '{"firstName":"Ava","lastName":"Reed","company":{"domain":"cedar.example"}}'
+higherdata --json tools email.verify --email ava@cedar.example
+```
+
+These generic commands preview by default. Read the candidates, suppression outcome and monthly verification allowance. Each candidate sent to the paid provider uses one verification; cache hits and polling are free. Confirm the request with the user, then execute the identical input with `--execute --yes`.
+
+If the result is pending, retain its `requestId`. Read it through the same tool, rather than submitting a new address search:
+
+```sh
+higherdata --json tools email.find --request-id REQUEST_ID
+higherdata --json tools email.verify --request-id REQUEST_ID
+```
+
+A preview read does not advance pending work. To continue an approved request, use its existing request id with `--execute --yes`. Honor the returned retry delay, bound waiting, and report pending status if it does not finish. Never treat a timeout as permission to restart.
+
+Report the returned `deliverable`, `undeliverable`, `risky` or `unknown` status, timestamp and verification allowance used. Suppressed records must stay hidden. Do not label risky or unknown addresses as deliverable. This skill finds data only; sending email is a separate task.