@curviate/cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,110 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
 a new command or flag is a minor; a breaking command/flag/exit-code change is a major; a fix is a patch.
 
+## [0.15.0] - 2026-07-11
+
+Full v2 API-surface parity — the coupled release with `@curviate/sdk` 0.15.0. A large
+**breaking** minor (pre-1.0): the CLI is re-pointed onto the v2-only API, drops the
+commands whose endpoint no longer exists, relocates several verbs, and adds commands for
+the new v2 methods. Every command noun kept its intent-shaped name; only the wiring,
+removed orphans, relocations, and additions changed.
+
+### Removed (BREAKING)
+
+Commands whose underlying v2 endpoint no longer exists:
+
+- **`account connect-link`**, **`account reconnect-link`**, **`account reconnect`** — the hosted-link and in-place re-auth flows. Connect a new account with `account link`; poll a hosted session with `account connect-session poll`.
+- **`company followers`**
+- **`inbox sync`**, **`inbox sync-chat`** — message history now syncs implicitly.
+- **`post list`**
+- **`recruiter sync`**, **`recruiter add-applicant`**, **`recruiter reject-applicant`**, **`recruiter job checkpoint`**
+- **`sales-nav sync`**
+- **`webhook state-diff`**
+
+Flags with no v2 request-side home — dropped entirely (not defined, parsed, or forwarded), with no replacement:
+
+- **`profile --notify`** — signal-a-view has no v2 request field.
+- **`message inmail --surface`** — the v2 send-InMail body carries no surface/type discriminator.
+- **`post create --video-thumbnail`** — v2 posts carry media only via `--attach`.
+- **`search people|companies|posts|jobs --url`** — from-URL search is now the bare `search <url>` form.
+
+### Changed (BREAKING)
+
+Renames and relocations:
+
+- **`post comment`** / **`post comments`** (and `post react --comment-id`) → the new **`comment`** group (`comment add`, `comment reply`, `comment react`, and the rest). Comment threads are first-class.
+- **`connect respond --accept` / `--decline`** → **`connect accept <id>`** / **`connect decline <id>`**; the combined `respond` is removed.
+- **`recruiter add-candidate`** → **`recruiter save-candidate <project_id> --stage-id <id> --candidate-id <id>`** (full body reshape).
+- **`recruiter project-jobs`** → **`recruiter project-job get <project_id>`** (cardinality fix — a project has at most one attached posting; single-object read, no pagination).
+- **`recruiter job applicants`** → **`recruiter applicants <project_id>`** (the applicant list is project-scoped, not job-scoped; `--channel-id` still required).
+- **`profile connections`** → **`profile relations`**.
+- **`profile endorse --skill`** → **`profile endorse --endorsement-id`** — value semantics unchanged (still the target's `endorsement_id`, obtained from their skills section via `profile <id> --sections skills`); the old flag name misleadingly suggested a skill name.
+
+CLI-visible shape changes:
+
+- **`job publish`** now requires **`--mode`** (`FREE | PROMOTED | PROMOTED_PLUS`); `PROMOTED`/`PROMOTED_PLUS` additionally require the full `--budget-*` triple.
+- **`recruiter job create`** now requires **`--project-name`** and takes the full v2 job body — `--employment-status` replaces the pre-v2 `--employment-type` on this command, alongside the company / workplace / location flags.
+- **`recruiter message new`** is now **JSON-only** (file/voice/video attachments ride the body as base64 — no multipart) and requires **`--subject`** and **`--signature`**.
+
+Dependency and request grammar:
+
+- **`@curviate/sdk` bumped to `0.15.0`.**
+- **Account-first path grammar.** Every account-scoped request now addresses the account in the URL path instead of a query/body field. This is handled entirely inside the SDK — no CLI syntax changes — but every command's underlying request moved.
+
+### Added
+
+New **`comment`** command group (the comment-thread surface):
+
+- `comment list <post_id>`, `comment add`, `comment reply`, `comment edit`, `comment delete`, `comment replies`, `comment react`, `comment reactions`, `comment unreact`, `comment user`.
+
+Job-posting management — the **`job`** family:
+
+- `job list`, `job create`, `job update`, `job budget`, `job publish`, `job close`, `job applicants`, `job applicant get`, and `job applicant resume` (binary résumé download via `-o`).
+
+Profile:
+
+- `profile update`, `profile follow`, `profile unfollow`, `profile following` (alongside `profile followers`).
+
+Posts:
+
+- `post delete`, `post unreact`, `post user-posts`, `post user-reactions`.
+
+Search and inbox:
+
+- `search <url>` (run a pasted search / saved-search / lead-list URL directly), `inbox mark-read`.
+
+Recruiter (project-centric surface):
+
+- `recruiter projects`, `recruiter project`, `recruiter project update`, `recruiter pipeline`, `recruiter project-job get|create|budget|update`, `recruiter talent-search`, `recruiter save-candidate`, `recruiter applicants`, `recruiter applicant get|resume`, plus `recruiter job close` and `recruiter search <url>`.
+
+Sales Navigator:
+
+- `sales-nav search <url>`, plus the v2 list surface: `sales-nav account-lists`, `lead-lists`, `browse-account-list`, `browse-lead-list`, `save-account`.
+
+Account:
+
+- **`account link --account-id <acc_…>`** (optional, non-breaking) — re-authenticate an existing account **in place** (reconnect): passing the id makes `account link` an in-place reconnect of that account; omit it for an ordinary fresh connect (unchanged — no `account_id` is sent). This is the reconnect path now that the hosted `account reconnect` / `account reconnect-link` commands are removed.
+
+Exit-code mapping:
+
+- **`ACCOUNT_ALREADY_LINKED`** and **`LINKEDIN_OPERATION_NOT_SUPPORTED`** are now present in `EXIT_CODE_MAP` (exit `8`, account / connection state — grouped with `ACCOUNT_RESTRICTED`/`RESOURCE_ACCESS_RESTRICTED`); previously `ACCOUNT_ALREADY_LINKED` was already a valid SDK `ErrorCode` but had no exit-code entry, and `LINKEDIN_OPERATION_NOT_SUPPORTED` is a new SDK code (a permanent LinkedIn platform limitation for the attempted operation, e.g. listing a non-self user's following list). Both were silently falling through to the default exit `1`; the exhaustiveness test now covers them.
+- **`CONNECTION_REQUEST_CONFLICT`** (exit `8`, account / connection state — the documented "already invited or already connected" contract on a `connect` retry) and **`RATE_LIMITED`** (exit `6`, rate-limited — a general/unscoped rate-limit signal alongside `RATE_LIMIT_ACCOUNT`/`RATE_LIMIT_TENANT`/`PLATFORM_RATE_LIMIT`/`LINKEDIN_RATE_LIMITED`) are new SDK error codes, both now present in `EXIT_CODE_MAP`. Picked up via the refreshed `@curviate/sdk` 0.15.0 tarball dependency (pnpm-lock.yaml integrity hash only).
+
+### Fixed
+
+- **`company <id> employees` / `company <id> posts` / `company <id> jobs` (id-first form) no longer silently returns the base company profile.** The router bound `<id>` and dropped the trailing sub-resource word, so the id-first form quietly returned the company profile with exit 0. It now routes the id-first form to the sub-resource (equivalent to `company <sub> <id>`), or exits 2 with an actionable error on a genuinely unexpected extra argument — never a silent wrong result. The guard is applied uniformly across every bare-form command group.
+- **`company employees|posts|jobs <slug>` (or a company URL) now works.** The three sub-resources previously required the numeric company id and erred on a handle; they now auto-resolve a slug/URL to the numeric id the same way the bare `company <slug>` retrieve does (a numeric id still passes straight through; a genuinely unresolvable identifier surfaces the not-found error).
+- **`profile follow <slug>` / `profile unfollow <slug>` (or a member URL) now work.** The follow endpoint accepts only a provider id, so a slug returned "not found"; both commands now resolve the identifier to the member's provider id first — the same auto-resolution `profile`, `connect`, and `message` already do.
+- **`company posts` / `search posts` slim `--json` output no longer emits a permanently-null `post_urn`/`posted_at` and silently drops the post's own id (D13).** Both endpoints share the identical v2 item schema (`{id, share_url, text, author, reaction_count, comment_count, repost_count, is_repost, attachments, reactions, permissions}`) — `post_urn` was never a real key and `posted_at` doesn't exist on this resource at all. Slim output now surfaces the real `id`; `--fields` projects the real v2 keys. `share_url`/`repost_count`/`is_repost`/`attachments`/`reactions`/`permissions`/the full `author` object remain verbose-only.
+- **`company <id>` slim `--json` output no longer emits permanently-null `employee_count`/`employee_count_range`/`followers_count`/`foundation_date`, and drops the entirely-fictitious `messaging` field.** The real v2 company-profile response nests headcount data at `insights.headcount` / `insights.headcount_range.from` (the range has no upper bound at all — documented open-ended-high, so no `to` is invented), the establishment date is a bare year at `establishment_year` (not a date string), the follower count key is singular, and there is no `messaging` field anywhere on this resource. Slim output now surfaces real `employee_count` / `employee_count_range` (`{from}` only) values; **`foundation_date` is renamed `establishment_year`** and **`followers_count` is renamed `follower_count`** (both now real, non-null); `messaging` is removed outright. `headquarters` (synthesized from `locations`) now reads the real `country_code`/`postal_code` location keys — the fictitious `country` key never existed and always projected null, and is renamed `country_code`; `postal_code` is added. `area` (region/state, e.g. "Washington") stays — it's real and often populated (verified live), even though the SDK's OpenAPI-generated types don't declare it for this endpoint.
+- **`job get` / `recruiter job get` slim `--json` output no longer emits a permanently-null `company_id`/`applicants_counter`, and `job get` (Core) no longer emits a permanently-null `published_at`.** `company_id` is synthesized from the nested `company.id` (neither shape has a top-level `company_id`); `applicants_counter` is renamed to `applications_count` (the real key on both shapes); `published_at` falls back to `created_at` on the Core shape, which has no `published_at` field at all (the Recruiter shape's own `published_at` is real and unaffected).
+- **`profile me` / `profile <id>` slim `--json` output no longer emits permanently-null `provider_id`/`network_distance`/`is_premium`/`current_position`, restores `headline` sourced from its real location, and drops the entirely-fictitious `occupation`/`organizations` fields.** Both commands are backed by the identical real v2 user-profile response — there is no top-level `provider_id` (the real identifier is `id`), no top-level `network_distance`/`is_premium` (both nested under `specifics`), and no top-level `work_experience` (the real array is `specifics.experience`, which fed the `current_position` synthesis — also permanently null until now). `provider_id` now sources from `id`; `network_distance` and `is_premium` now source from `specifics.network_distance`/`specifics.is_premium`; `current_position` is synthesized from `specifics.experience[0]`. **`profile me`'s `email` is renamed `emails`** (the real field is a plural array, not a singular string). **`headline` ← `description`** — on a v2 read, LinkedIn serves the profile headline in the `description` wire field (a separate `bio` field carries the About-section paragraph); initially assumed to have no v2 source and dropped, then restored once the real source was confirmed live (3-way evidence: a written headline read back via `description` byte-for-byte, the same result from the M3 matrix probe, and `--verbose` showing headline-shaped text in `description` across live profiles). `occupation` and `organizations` are removed outright — neither has a v2 source; the real user-profile response has no occupation-summary field and no administered-organizations field of any kind. (`profile me`'s slim output drops from 10 fields to 9; `profile <id>`'s drops from 9 to 8.)
+- **`job list --state` now re-filters returned items against their own `state` (D10).** LinkedIn's upstream state filter is best-effort — it commonly returns items whose own `state` doesn't match the request. `--json` output (and `--all` streaming) now only contains items whose own `state` actually matches (`--state OPEN` maps to the response's `LISTED`, the one value that differs between the request and response vocabularies); dropped items produce a stderr note with the count. The re-filter is page-local and never touches the pagination cursor, so `--all` still walks the same unfiltered upstream pages — it may fetch more pages than the filtered item count implies. The `--state` help text now says so.
+
+### Notes — no user action required
+
+- **`post react --as-organization`**: unchanged at the flag level; only the internal wire key was renamed, so the flag behaves exactly as before.
+
 ## [0.14.0] - 2026-07-07
 
 Webhooks surface cascade — the coupled release with `@curviate/sdk` 0.14.0. Additive minor.

package/README.md

@@ -80,14 +80,16 @@ These examples show how coding agents compose the CLI in real workflows.
 Search for matching profiles, preview the invitations, then send them once satisfied:
 
 ```bash
-# Preview first — see who would be targeted
+# Look first — a search is a read, so it just runs (no --preview on reads)
 curviate search people \
   --keywords "AI engineer" \
   --location "Berlin" \
   --limit 10 \
-  --preview
+  --json
+
+# Preview a single write before sending, then pipe IDs into connect — one request per person
+curviate connect "$SOME_ID" --note "Hi, I'd love to connect." --preview
 
-# Pipe IDs into connect — one request per person
 curviate search people --keywords "AI engineer" --location "Berlin" --all \
   | jq -r '.id' \
   | head -5 \
@@ -112,7 +114,7 @@ PROFILE_URL="https://www.linkedin.com/in/example"
 
 curviate profile "$PROFILE_URL" --posts --fields post_id --json \
   | jq -r '.[].post_id' \
-  | xargs -I{} curviate post react {} --type LIKE
+  | xargs -I{} curviate post react {} --reaction like
 ```
 
 ### 4. Check tier entitlement before a Sales Navigator sweep
@@ -193,16 +195,6 @@ curviate company posts 112013061 --limit 5 --account acc_1 --json
 curviate company jobs 112013061 --all --account acc_1 --json   # streams every page
 ```
 
-### 3. List a company's followers (page admins only)
-
-Followers are only retrievable for a company page the acting account **administers** — a
-non-administered company returns a `RESOURCE_NOT_FOUND` error (exit code `4`), the same shape as
-an unknown company.
-
-```bash
-curviate company followers 112013061 --limit 25 --account acc_1 --json
-```
-
 ## Sales Navigator
 
 Sales Navigator commands (`curviate sales-nav ...`) require an account with the Sales Navigator
@@ -297,9 +289,10 @@ curviate sales-nav save-account 112013061 --account acc_1 --list 987654
 
 Recruiter commands (`curviate recruiter ...`) require an account with the Recruiter add-on tier
 attached. A call against an account without it fails with **exit code `5`** and a `TIER_NOT_ACTIVE`
-error body naming the required tier (`recruiter`). Write commands (`add-candidate`,
-`add-applicant`, `reject-applicant`, `job create`/`publish`/`checkpoint`, `message new`) accept
-`--preview` to render the request without sending it.
+error body naming the required tier (`recruiter`). The surface is project-centric: most
+operations are scoped to a hiring project id. Write commands (`save-candidate`, `project update`,
+`project-job create`/`update`, `job create`/`publish`/`close`, `message new`) accept `--preview`
+to render the request without sending it.
 
 ### 1. List hiring projects
 
@@ -308,65 +301,62 @@ curviate recruiter projects --account acc_1 --limit 20 --json \
   | jq -r '.items[] | "\(.id)\t\(.name)"'
 ```
 
-### 2. Create a job posting draft, then publish it (with the checkpoint flow)
+### 2. Inspect a project, its pipeline, and its attached job posting
+
+`recruiter project-job get` returns the single job posting attached to a project (a
+`RESOURCE_NOT_FOUND` / exit `4` when none is attached).
+
+```bash
+curviate recruiter project "$PROJECT_ID" --account acc_1 --json
+curviate recruiter pipeline "$PROJECT_ID" --account acc_1 --json
+curviate recruiter project-job get "$PROJECT_ID" --account acc_1 --json
+```
+
+### 3. Create a job posting draft, then publish it
 
-Publishing can return a verification checkpoint instead of a published job — solve it with the
-`job_id` from the publish response, then retry:
+`recruiter job create` requires `--project-name` (the hiring project the posting opens) and takes
+the v2 job body. `recruiter job publish` is project-scoped and requires `--mode`
+(`FREE | PROMOTED | PROMOTED_PLUS`); the paid modes also require the full `--budget-*` triple.
 
 ```bash
 curviate recruiter job create \
   --account acc_1 \
+  --project-name "Backend Hiring — 2026" \
   --job-title "Senior Backend Engineer" \
   --description "Remote-first team building the core platform." \
-  --employment-type FULL_TIME \
-  --json > draft.json
-
-JOB_ID=$(jq -r '.job_id' draft.json)
+  --employment-status FULL_TIME \
+  --json
 
-curviate recruiter job publish "$JOB_ID" --account acc_1 --mode FREE --json > publish.json
-
-# If publish returns a checkpoint object instead of a published job, solve it:
-if [ "$(jq -r '.object // empty' publish.json)" = "job_posting_checkpoint" ]; then
-  curviate recruiter job checkpoint "$JOB_ID" --account acc_1 --input "123456"
-fi
+curviate recruiter job publish "$PROJECT_ID" "$JOB_ID" --account acc_1 --mode FREE --json
 ```
 
-### 3. List applicants for a job, then get one applicant's detail
+### 4. List applicants in a project, then get one applicant's detail
+
+`recruiter applicants` is project-scoped and requires `--channel-id` (the project's own
+JOB_POSTING talent-pool channel). Applicant detail and résumé are also project-scoped.
 
 ```bash
-curviate recruiter job applicants "$JOB_ID" --account acc_1 --limit 10 --json \
+curviate recruiter applicants "$PROJECT_ID" --channel-id "$CHANNEL_ID" --account acc_1 --limit 10 --json \
   | jq -r '.items[0].id' \
-  | xargs -I{} curviate recruiter applicant {} --account acc_1
+  | xargs -I{} curviate recruiter applicant "$PROJECT_ID" {} --account acc_1
 ```
 
-### 4. Download an applicant's resume
+### 5. Download an applicant's resume
 
 ```bash
-curviate recruiter applicant resume APPLICANT_ID --account acc_1 -o resume.pdf
+curviate recruiter applicant resume "$PROJECT_ID" APPLICANT_ID --account acc_1 -o resume.pdf
 ```
 
-### 5. Reject an applicant, optionally notifying them
-
-The applicant is only notified when `--message` is given; omit it to reject silently.
-`--notify-at` (a UNIX-ms timestamp to schedule the notification) requires `--message`.
+### 6. Save a candidate to a project pipeline stage
 
 ```bash
-# Silent rejection — no notification sent
-curviate recruiter reject-applicant AEM789 \
-  --account acc_1 \
-  --hiring-project-id proj_abc \
-  --reason NOT_MEET_BASIC_QUALIFICATIONS
-
-# Rejection with a notification to the applicant
-curviate recruiter reject-applicant AEM789 \
+curviate recruiter save-candidate "$PROJECT_ID" \
   --account acc_1 \
-  --hiring-project-id proj_abc \
-  --reason NOT_MEET_BASIC_QUALIFICATIONS \
-  --message "Thanks for applying — we've decided to move forward with other candidates." \
-  --preview
+  --stage-id "$STAGE_ID" \
+  --candidate-id AEM789
 ```
 
-### 6. Search Recruiter people
+### 7. Search Recruiter people
 
 ```bash
 curviate recruiter search people \
@@ -374,33 +364,14 @@ curviate recruiter search people \
   --account acc_1 \
   --limit 5 --json \
   | jq -r '.items[] | "\(.id)\t\(.full_name // .headline)"'
-```
 
-### 7. Add a candidate to a hiring project, then promote them to applicant
-
-```bash
-curviate recruiter add-candidate AEM789 \
-  --account acc_1 \
-  --hiring-project-id proj_abc \
-  --stage UNCONTACTED
-
-# Once they've applied, move them to the applicant pool:
-curviate recruiter add-applicant AEM789 \
-  --account acc_1 \
-  --hiring-project-id proj_abc \
-  --stage CONTACTED
+# A pasted Recruiter search / talent-pool URL runs directly:
+curviate recruiter search "https://www.linkedin.com/talent/search?..." --account acc_1 --json
 ```
 
-### 8. Inspect a single hiring project, then list its job postings
-
-```bash
-curviate recruiter project proj_abc --account acc_1 --json
-
-curviate recruiter jobs --account acc_1 --limit 10 --json \
-  | jq -r '.items[] | "\(.id)\t\(.title)\t\(.state)"'
-```
+### 8. Get a Recruiter-enriched profile, then start a chat with them
 
-### 9. Get a Recruiter-enriched profile, then start a chat with them
+`recruiter message new` is JSON-only and requires `--subject` and `--signature`.
 
 ```bash
 curviate recruiter profile "https://www.linkedin.com/in/example" --account acc_1 --json
@@ -408,20 +379,22 @@ curviate recruiter profile "https://www.linkedin.com/in/example" --account acc_1
 curviate recruiter message new \
   --to AEM789 \
   --account acc_1 \
+  --subject "A role you'd be a great fit for" \
+  --signature "— Alex, Talent Team" \
   "Hi — I came across your profile and think you'd be a great fit for a role we're hiring for."
 ```
 
-### 10. Get any public job posting through the Recruiter lens
+### 9. List your postings, and get any public job posting through the Recruiter lens
 
 Unlike `recruiter jobs` (which lists postings you manage), `recruiter job get` retrieves the full
 detail of *any* public LinkedIn job posting — the Recruiter-seated counterpart to the top-level
 `job get` command:
 
 ```bash
-curviate recruiter job get "https://www.linkedin.com/jobs/view/4428113858" --account acc_1 --json
+curviate recruiter jobs --account acc_1 --limit 10 --json \
+  | jq -r '.items[] | "\(.id)\t\(.title)\t\(.state)"'
 
-# Bare numeric id works identically:
-curviate recruiter job get 4428113858 --account acc_1 --verbose
+curviate recruiter job get "https://www.linkedin.com/jobs/view/4428113858" --account acc_1 --json
 ```
 
 ## Exit codes