@curviate/cli 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/CHANGELOG.md +138 -1
  2. package/README.md +104 -0
  3. package/dist/{account-52BUCCTZ.js → account-5KGM6EPR.js} +5 -5
  4. package/dist/{chunk-PMRQXBCP.js → chunk-2OG6M6ME.js} +22 -0
  5. package/dist/{chunk-XHVR32RW.js → chunk-5KANHEBN.js} +66 -5
  6. package/dist/{chunk-PS6QPY67.js → chunk-63X3VI3T.js} +5 -2
  7. package/dist/{chunk-RJTG5YWE.js → chunk-6P52Q2GK.js} +2 -2
  8. package/dist/{chunk-LCLYFE54.js → chunk-GHT2DLZR.js} +1 -1
  9. package/dist/{chunk-VAUKRTRG.js → chunk-LJR4LJG6.js} +2 -1
  10. package/dist/chunk-PQWDDSV7.js +65 -0
  11. package/dist/{chunk-RXIPY4O7.js → chunk-TAOXJNQN.js} +3 -3
  12. package/dist/cli.js +17 -17
  13. package/dist/{comment-XAF7AMHR.js → comment-BLG4WHST.js} +6 -6
  14. package/dist/{company-PAKHOCVR.js → company-ZT65QZ6F.js} +7 -7
  15. package/dist/{connect-5TMGM326.js → connect-57AUN33D.js} +11 -11
  16. package/dist/{exit-codes-KAVZN5BQ.js → exit-codes-U5CHA6FT.js} +1 -1
  17. package/dist/{feed-E5EQMI7T.js → feed-3AWI2URQ.js} +5 -5
  18. package/dist/{group-SNCEAWKI.js → group-DYC2NX5M.js} +5 -5
  19. package/dist/{inbox-R5OSZWTG.js → inbox-CQO2I47N.js} +25 -7
  20. package/dist/{inboxes-6XMIABRX.js → inboxes-XQ2B6X3Q.js} +5 -5
  21. package/dist/{job-3HU7KQQI.js → job-NUT4QMH2.js} +6 -6
  22. package/dist/{message-GA7D3A6Y.js → message-KMNRUD4H.js} +4 -4
  23. package/dist/{notification-B5PTNNPE.js → notification-LEM57IBY.js} +5 -5
  24. package/dist/{post-QAVRVRON.js → post-FXAANNUB.js} +6 -6
  25. package/dist/{profile-REKGQYAW.js → profile-72V55PZM.js} +41 -14
  26. package/dist/{recruiter-N36AROW7.js → recruiter-JUNB5AUR.js} +6 -6
  27. package/dist/{sales-nav-Q5RVL4PR.js → sales-nav-BALVVD35.js} +5 -5
  28. package/dist/{search-SYWHOM5J.js → search-QCXTK33P.js} +14 -14
  29. package/dist/{webhook-RE2BGX3N.js → webhook-D4QRWF7W.js} +3 -3
  30. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -6,7 +6,144 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
6
  Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
7
7
  a new command or flag is a minor; a breaking command/flag/exit-code change is a major; a fix is a patch.
8
8
 
9
- ## [Unreleased]
9
+ ## [0.27.0] - 2026-09-06
10
+
11
+ Pins `@curviate/sdk` at `0.26.0`, which is what makes the last two items of
12
+ this release possible: `inbox get` can carry the retrieval pair, and exit `14`
13
+ is reachable. No command, flag or exit code changes meaning.
14
+
15
+ ### Added
16
+
17
+ - **`--mode` and `--max-age` on the reads that can be served from a stored
18
+ copy.** `--mode auto|live|refill|cache_only` says how willing a read is to
19
+ reach LinkedIn; `--max-age <seconds>` sets the oldest stored copy it will
20
+ accept and overrides the `auto`, `live` and `refill` presets in both
21
+ directions. Available on `profile <id>`, `profile me`, `inbox get` and
22
+ `inbox messages`, the four reads the API declares them on. The activity listings on the profile
23
+ commands (`--posts`, `--comments`, `--reactions`, `--followers`) reject them
24
+ with exit `2` rather than sending a parameter their endpoints answer with a
25
+ `400`.
26
+ - **Client-side validation, before any request is sent.** An unknown `--mode`,
27
+ a `--max-age` that is not a whole number from `0` to `31536000`, or
28
+ `--mode cache_only` combined with `--max-age` is a usage error (exit `2`)
29
+ with nothing transmitted. The last of those mirrors the API: `cache_only`
30
+ never reaches LinkedIn at any age, so a freshness threshold cannot change
31
+ its answer, and the pair is refused rather than one of the two being
32
+ silently ignored.
33
+ - **Provenance on the response.** These reads carry `source` (`store` or
34
+ `live`) and `observed_at`, plus `withdrawn`/`withdrawn_at` when the platform
35
+ says the resource is gone. All of them now survive `--fields` and the slim
36
+ projection, which previously dropped them (both layers rebuild output from an
37
+ allowlist). In human mode the same facts go to stderr as a one-line
38
+ `provenance:` note, leaving stdout parseable. Under `--all`, where items
39
+ stream as raw NDJSON and never pass through the single-response renderer,
40
+ each page's note goes to stderr the same way page-scoped `notices` already
41
+ do, so the highest-volume read path is not the one that cannot say where its
42
+ data came from. A stored copy can carry less than a live one, so
43
+ `source: "store"` is the signal to re-read with `--mode live` when message
44
+ bodies or contact fields matter.
45
+ - **Exit code `14`, nothing stored.** `NOT_STORED` answers a
46
+ `--mode cache_only` read the store cannot satisfy. It is deliberately not
47
+ `4`: the resource may exist perfectly well on LinkedIn and this API simply
48
+ holds no copy, so re-checking the id is the wrong move; the fix is another
49
+ mode. A `502` under `cache_only` keeps its existing mapping, because "we
50
+ could not look" and "we hold nothing" are different answers and only one is
51
+ worth retrying.
52
+
53
+ - **The id-resolution pre-call obeys the mode too.** `profile <id> --sections`
54
+ with a slug resolves the slug to a provider id with a first read before the
55
+ enriched one. That pre-call now carries `mode`/`max_age`; previously it went
56
+ out with neither, so `--mode cache_only` reached LinkedIn once before the
57
+ read it was meant to prevent: the mode's only guarantee, broken under a
58
+ `200` with nothing to notice.
59
+
60
+ ### Changed
61
+
62
+ - **`@curviate/sdk` pinned at `0.26.0`** (was `0.25.0`), an exact pin as
63
+ always. Two things this release needed shipped there, and both were held
64
+ open by tests written to fail on the day the wait ended:
65
+ - `messaging.getChat(chatId, params?)` takes the retrieval query, so
66
+ **`inbox get` now carries `--mode`/`--max-age`** like the other three
67
+ store-served reads. The chat-id normalization still runs first, so the
68
+ pair rides the bare provider id rather than a thread URL.
69
+ - `NOT_STORED` is in the SDK's error taxonomy, so **exit `14` is now
70
+ reachable**. It previously decoded to `INTERNAL` and the binary answered
71
+ `1`; a `--mode cache_only` read the store cannot satisfy now exits `14`,
72
+ and, because the code is deliberately not retryable, on the first reply
73
+ rather than after a retry loop against an answer that cannot change.
74
+ Nothing else in the SDK bump reaches this binary: the SDK's own type-level
75
+ breaking change (`row` is `string | null` on errors and safety warnings) is
76
+ absorbed by the CLI's existing `typeof === "string"` guard, and the widened
77
+ response enums are read, never exhaustively switched.
78
+
79
+ ## [0.26.0] - 2026-09-05
80
+
81
+ ### Added
82
+
83
+ - **Exit code `13`, account-safety budget.** `BUDGET_EXHAUSTED` is a `429`,
84
+ but it is not a rate limit: it is Curviate's OWN ceiling, on a number you
85
+ configured, and nothing reached LinkedIn. Exit `6` tells a scripted caller
86
+ to back off and retry, which is the wrong action here (the reset can be a
87
+ month out, and raising the limit lifts it now), and leaving it unmapped
88
+ fell to `1`, which reads as an internal failure. `13` is a new bucket for
89
+ a genuinely new condition. Nothing that used to exit `6` changes.
90
+ - **The refusal is rendered as data, not prose.** Human mode names the row,
91
+ whether the cause was the ceiling or the activity window, when it frees (and
92
+ where no clock frees it, which of the two causes that is: the invitation
93
+ backlog, or an InMail credit pool LinkedIn regrants on its own schedule), and
94
+ the exact parameter to change. `--json` carries `budgetRow`, `resetAt`,
95
+ `safetyHint`, `safetyReason` and `blocked` through untouched.
96
+ - **A `429` naming a PAUSED row says so, and says the other rows still work.**
97
+ `PLATFORM_RATE_LIMIT` with a `budgetRow` means LinkedIn refused a recent
98
+ call on that one row. The pause is scoped to `(account, row)`, so the
99
+ recovery is to switch work rather than back off across the account.
100
+ - **`account_states` is a slim field on `account get`.** Platform conditions
101
+ the account is in right now, concurrent with and independent of `status`.
102
+ Two of the three are read on calls that SUCCEEDED (thin search results,
103
+ empty profile views), so projecting them away would hide them exactly when
104
+ they explain what you are looking at.
105
+ - **Exit code `8` for `LINKEDIN_SESSION_EVICTED`.** LinkedIn allows one
106
+ session at a time for some accounts; a person signing in elsewhere breaks
107
+ the connected one. It is the account's connection state, not your
108
+ credentials, and reconnecting does nothing while the other session is open.
109
+ It used to fall to the unmapped `1`.
110
+ - README documents exit `13` beside `6` and shows the refusal envelope.
111
+
112
+ ### Fixed
113
+
114
+ - **`FILTER_CANDIDATES_REQUIRED` now exits `2` instead of `1`.** It has been in
115
+ the SDK's taxonomy and absent from the exit-code table, so it fell to the
116
+ unmapped `1` and read as an internal failure. It is a `422` saying a
117
+ plain-string search filter matched several LinkedIn taxonomy options;
118
+ `unresolved[]` names the fields and their candidate ids, and the fix is to
119
+ re-send with a chosen id, which is the exit-2 contract exactly. Found by the
120
+ new SDK-pin gate on its first run.
121
+
122
+ ### Changed
123
+
124
+ - **`@curviate/sdk` pin bumped `0.24.3` -> `0.25.0`, which is what makes exit
125
+ `13` live.** The previous pin predated `BUDGET_EXHAUSTED`, so the wire code
126
+ decoded to `INTERNAL`, `INTERNAL` is retryable on a GET, and the binary
127
+ answered exit `1` after four requests with every payload field dropped. The
128
+ CLI's own logic was correct throughout; the dependency was the defect. The
129
+ vendored OpenAPI fixture (`test/fixtures/openapi.json`) was re-copied from
130
+ the SDK at that version and `VENDORED_FROM.json` re-recorded with it, as the
131
+ fixture-pin guard requires.
132
+
133
+ ### Removed
134
+
135
+ - **The casts that stood in for the unpublished taxonomy are gone**, on
136
+ schedule and with nothing left to remember: `["BUDGET_EXHAUSTED" as
137
+ ErrorCode]` and `["LINKEDIN_SESSION_EVICTED" as ErrorCode]` in
138
+ `src/lib/exit-codes.ts`, and the `errJson as {...}` widening plus
139
+ `(errJson.code as string)` in `src/lib/output.ts`. `CurviateErrorJSON` now
140
+ declares all six safety fields natively.
141
+ - **The hand-copied `ALL_ERROR_CODES` array in `test/lib/exit-codes.test.ts`**,
142
+ replaced by the SDK's exported `ERROR_CODES`. The copy could not fail for the
143
+ case it existed to catch: a code the SDK added and nobody copied across was
144
+ invisible to a loop that iterated the copy. The taxonomy is now derived from
145
+ the same tuple `ErrorCode` is built from, so the two cannot drift. The
146
+ SDK-pin block that made this possible remains as the pin-REGRESSION gate.
10
147
 
11
148
  ## [0.25.0] - 2026-08-29
12
149
 
package/README.md CHANGED
@@ -442,6 +442,63 @@ curviate recruiter jobs --account acc_1 --limit 10 --json \
442
442
  curviate recruiter job get "https://www.linkedin.com/jobs/view/4428113858" --account acc_1 --json
443
443
  ```
444
444
 
445
+ ## Retrieval modes
446
+
447
+ Some reads can be answered from the copy Curviate already holds instead of
448
+ calling LinkedIn. `--mode` says how willing a read is to fetch, and `--max-age`
449
+ sets the oldest stored copy it will accept.
450
+
451
+ | `--mode` | Behaviour |
452
+ |------|---------|
453
+ | `auto` | Default. Serve a stored copy while it is within the resource's freshness threshold, otherwise fetch. |
454
+ | `live` | Always fetch. Same as `--max-age 0`. |
455
+ | `refill` | Serve a stored copy at any age; fetch only when nothing is stored yet. |
456
+ | `cache_only` | Never fetch. A store miss is refused rather than fetched (see the exit-`14` note below). |
457
+
458
+ `--max-age <seconds>` is a whole number from `0` to `31536000` (one year). It
459
+ overrides the `auto`, `live` and `refill` presets in both directions. It cannot
460
+ be combined with `--mode cache_only`, whose guarantee is not a freshness
461
+ threshold: that combination is a usage error (exit `2`) before any request is
462
+ sent.
463
+
464
+ Available on the four reads that can be served from a stored copy:
465
+ `profile <id>`, `profile me`, `inbox get` and `inbox messages`. The activity
466
+ listings on the profile commands (`--posts`, `--comments`, `--reactions`,
467
+ `--followers`) do not accept them and reject them with exit `2`.
468
+
469
+ ### Telling a served copy from a fetch
470
+
471
+ Every response from these reads carries `source` (`store` or `live`) and
472
+ `observed_at`, and they survive `--fields` and the slim projection. In human
473
+ mode the same facts go to stderr as a one-line `provenance:` note, so stdout
474
+ stays parseable.
475
+
476
+ A stored copy can carry less than a live one: message bodies and contact fields
477
+ are stripped before anything is stored, so `source: "store"` is the signal to
478
+ re-read with `--mode live` when you need them.
479
+
480
+ ### Exit `14`: nothing stored
481
+
482
+ A `--mode cache_only` read the store cannot answer exits `14`. It is not
483
+ "not found" (exit `4`): the resource may exist perfectly well on LinkedIn and
484
+ this API simply holds no copy, so re-checking the id is the wrong move. It is
485
+ not a failure either. The fix is another mode, and it is never worth retrying
486
+ as sent, because the answer cannot change until you change the mode.
487
+
488
+ ```bash
489
+ # The default: a fresh stored copy if there is one, otherwise fetch
490
+ curviate profile me --account acc_1 --json
491
+
492
+ # Serve whatever is stored at any age, and fetch only if nothing is
493
+ curviate profile me --account acc_1 --mode refill --json
494
+
495
+ # Accept a stored copy up to five minutes old, otherwise fetch
496
+ curviate profile me --account acc_1 --max-age 300 --fields first_name,source,observed_at --json
497
+
498
+ # A single chat from the store, never LinkedIn. Exit 14 if nothing is stored.
499
+ curviate inbox get 2-AbCdEf== --account acc_1 --mode cache_only --json
500
+ ```
501
+
445
502
  ## Exit codes
446
503
 
447
504
  | Code | Meaning |
@@ -459,6 +516,53 @@ curviate recruiter job get "https://www.linkedin.com/jobs/view/4428113858" --acc
459
516
  | 10 | Messaging window expired or recipient unreachable |
460
517
  | 11 | Billing issue (payment required, failed, or seat cancelled) |
461
518
  | 12 | Auth action needed (a pending checkpoint; not an error) |
519
+ | 13 | Account-safety budget: Curviate's own ceiling refused the action |
520
+ | 14 | Nothing stored: a `--mode cache_only` read the store cannot answer. Retry with another mode, not with the same request |
521
+
522
+ ### 6 and 13 are both `429`, and they need different actions
523
+
524
+ Exit `6` means LinkedIn or Curviate's request limiter refused you: back off and
525
+ retry later.
526
+
527
+ Exit `13` means an account-safety ceiling YOU configured is spent, or the
528
+ account is outside the hours it works in. Nothing reached LinkedIn and nothing
529
+ was spent, so backing off is the wrong move: the reset can be a month out, and
530
+ you can lift it now. The error body names what to do, so branch on the fields
531
+ rather than parsing the message:
532
+
533
+ ```json
534
+ {
535
+ "error": {
536
+ "code": "BUDGET_EXHAUSTED",
537
+ "budgetRow": "profile_views",
538
+ "resetAt": "2026-09-06T00:00:00.000Z",
539
+ "safetyReason": "ceiling",
540
+ "safetyHint": {
541
+ "parameter": "profile_views.ceiling",
542
+ "message": "effective ceiling 15 = 100 x warm-up 0.15 (week 0, account_age)."
543
+ },
544
+ "blocked": true
545
+ }
546
+ }
547
+ ```
548
+
549
+ - `safetyReason` is `ceiling` (the row's limit is spent) or `activity_window`
550
+ (the account is outside its working hours). The fixes differ.
551
+ - `resetAt` is an absolute instant, so it stays true however long you hold it.
552
+ It is `null` in the two cases where no clock frees the account: the
553
+ invitation backlog, which falls when invitations are accepted or withdrawn
554
+ rather than at any window edge, and an InMail credit exhaustion, which
555
+ LinkedIn regrants on its own schedule. Null-check it before scheduling on it.
556
+ - `safetyHint.parameter` is addressable on the safety policy, so an agent can
557
+ choose between waiting, escalating and reconfiguring without reading prose.
558
+ - On the default posture nothing is refused at all: the action goes through and
559
+ the same payload rides the SUCCESS body under `safety_warning` with
560
+ `blocked: false`.
561
+
562
+ A `429` that carries `budgetRow` under `PLATFORM_RATE_LIMIT` is a third thing:
563
+ that row is PAUSED because LinkedIn refused a recent call on it. The pause is
564
+ scoped to that one row, so every other row on the account still works and the
565
+ recovery is to switch work, not to wait out the account.
462
566
 
463
567
  ## License
464
568
 
@@ -6,11 +6,11 @@ import {
6
6
  slimAccountGet,
7
7
  slimAccountList,
8
8
  slimAccountListItem
9
- } from "./chunk-VAUKRTRG.js";
9
+ } from "./chunk-LJR4LJG6.js";
10
10
  import {
11
11
  pageDelayFromFlags,
12
12
  streamAll
13
- } from "./chunk-PS6QPY67.js";
13
+ } from "./chunk-63X3VI3T.js";
14
14
  import {
15
15
  buildPreviewOutput
16
16
  } from "./chunk-R3VLWLVV.js";
@@ -20,7 +20,7 @@ import {
20
20
  renderSuccess,
21
21
  renderUnexpectedError,
22
22
  resolveEffectiveConfig
23
- } from "./chunk-XHVR32RW.js";
23
+ } from "./chunk-5KANHEBN.js";
24
24
  import "./chunk-KTY7R27U.js";
25
25
  import {
26
26
  GLOBAL_FLAGS,
@@ -30,7 +30,7 @@ import {
30
30
  } from "./chunk-AHYUM2XQ.js";
31
31
  import {
32
32
  AUTH_NEEDED
33
- } from "./chunk-PMRQXBCP.js";
33
+ } from "./chunk-2OG6M6ME.js";
34
34
 
35
35
  // src/commands/account.ts
36
36
  import { defineCommand } from "citty";
@@ -220,7 +220,7 @@ function resolveOutputOpts(flags) {
220
220
  async function handleError(err, outOpts, out) {
221
221
  const { CurviateError } = await import("@curviate/sdk");
222
222
  if (err instanceof CurviateError) {
223
- const { getExitCode } = await import("./exit-codes-KAVZN5BQ.js");
223
+ const { getExitCode } = await import("./exit-codes-U5CHA6FT.js");
224
224
  renderError(err, outOpts, out);
225
225
  process.exit(getExitCode(err.code));
226
226
  }
@@ -8,6 +8,14 @@ var EXIT_CODE_MAP = {
8
8
  INVALID_REQUEST: 2,
9
9
  UNSUPPORTED_MEDIA_TYPE: 2,
10
10
  PAYLOAD_TOO_LARGE: 2,
11
+ // 2, found by the SDK-pin gate at the bottom of test/lib/exit-codes.test.ts
12
+ // on its first run. It has been in the SDK's taxonomy and absent from this
13
+ // table, so it fell to the unmapped 1 and read as an internal failure. It is
14
+ // a 422 saying a plain-string search filter matched several LinkedIn
15
+ // taxonomy options: `unresolved[]` names the fields and their candidate ids,
16
+ // it is user_fixable, and it is never retryable AS SENT. Re-send with a
17
+ // chosen id, which is the exit-2 contract exactly.
18
+ FILTER_CANDIDATES_REQUIRED: 2,
11
19
  // Not found (4)
12
20
  RESOURCE_NOT_FOUND: 4,
13
21
  ACCOUNT_NOT_FOUND: 4,
@@ -29,6 +37,7 @@ var EXIT_CODE_MAP = {
29
37
  ACCOUNT_RESTRICTED: 8,
30
38
  RESOURCE_ACCESS_RESTRICTED: 8,
31
39
  LINKEDIN_AUTH_FAILED: 8,
40
+ LINKEDIN_SESSION_EVICTED: 8,
32
41
  LINKEDIN_COOKIE_INVALID: 8,
33
42
  CONNECTION_IN_PROGRESS: 8,
34
43
  ACCOUNT_ALREADY_LINKED: 8,
@@ -51,6 +60,19 @@ var EXIT_CODE_MAP = {
51
60
  PAYMENT_FAILED: 11,
52
61
  SUBSCRIPTION_BUSY: 11,
53
62
  SEAT_CANCELLED: 11,
63
+ // Account-safety budget (13), see the note above for why this is not 6
64
+ BUDGET_EXHAUSTED: 13,
65
+ // Nothing stored (14), A NEW BUCKET, and deliberately not 4.
66
+ // `NOT_STORED` is a 422 answering a `--mode cache_only` read: the resource
67
+ // may exist perfectly well on LinkedIn, and this API simply holds no copy of
68
+ // it, so it is NOT "not found" and re-checking the id is the wrong move. It
69
+ // is not 1 either: nothing failed. It is user_fixable and not retryable AS
70
+ // SENT — the fix is another mode (`refill` fetches it once, `auto` fetches
71
+ // now), which is the same shape as exit 2 but reached without a malformed
72
+ // request, so it earns its own number rather than muddying either.
73
+ // A 502 under cache_only stays 7: "we could not look" and "we hold nothing"
74
+ // are different answers and only one of them is worth retrying.
75
+ NOT_STORED: 14,
54
76
  // Internal / uncaught (1), last resort bucket
55
77
  INTERNAL: 1,
56
78
  PLATFORM_NOT_IMPLEMENTED: 1
@@ -95,13 +95,43 @@ function applyProjection(data, fields) {
95
95
  }
96
96
  return data;
97
97
  }
98
+ var isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
98
99
  function withPreservedNotices(original, rendered) {
99
- const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
100
100
  if (!isPlain(original) || !isPlain(rendered)) return rendered;
101
+ let out = rendered;
101
102
  const notices = original["notices"];
102
- if (!Array.isArray(notices) || notices.length === 0) return rendered;
103
- if (rendered["notices"] === notices) return rendered;
104
- return { ...rendered, notices };
103
+ if (Array.isArray(notices) && notices.length > 0 && rendered["notices"] !== notices) {
104
+ out = { ...out, notices };
105
+ }
106
+ return withPreservedProvenance(original, out);
107
+ }
108
+ var PROVENANCE_KEYS = ["source", "observed_at", "withdrawn", "withdrawn_at"];
109
+ function withPreservedProvenance(original, rendered) {
110
+ if (!isPlain(original) || !isPlain(rendered)) return rendered;
111
+ if (!isRetrievalSource(original["source"])) return rendered;
112
+ const carried = { ...rendered };
113
+ for (const key of PROVENANCE_KEYS) {
114
+ if (Object.prototype.hasOwnProperty.call(original, key)) carried[key] = original[key];
115
+ }
116
+ return carried;
117
+ }
118
+ function isRetrievalSource(v) {
119
+ return v === "store" || v === "live";
120
+ }
121
+ function renderProvenanceNote(data) {
122
+ if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
123
+ const d = data;
124
+ const source = d["source"];
125
+ if (!isRetrievalSource(source)) return null;
126
+ let line = `provenance: source=${source}`;
127
+ const observedAt = d["observed_at"];
128
+ if (typeof observedAt === "string" && observedAt !== "") line += ` observed_at=${observedAt}`;
129
+ if (d["withdrawn"] === true) {
130
+ const withdrawnAt = d["withdrawn_at"];
131
+ line += typeof withdrawnAt === "string" && withdrawnAt !== "" ? ` withdrawn=true withdrawn_at=${withdrawnAt}` : " withdrawn=true";
132
+ }
133
+ if (source === "store") line += " (re-read with --mode live to fetch)";
134
+ return line + "\n";
105
135
  }
106
136
  function firstProjectableItem(data) {
107
137
  const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -132,7 +162,7 @@ function renderSuccess(data, opts, out) {
132
162
  const json = isJsonMode(opts);
133
163
  const fields = opts.fields ? opts.fields.split(",").map((f) => f.trim()).filter(Boolean) : [];
134
164
  const slimmed = !opts.verbose && opts.slim ? opts.slim(data) : data;
135
- const unknownFields = detectUnknownFields(slimmed, fields);
165
+ const unknownFields = detectUnknownFields(withPreservedNotices(data, slimmed), fields);
136
166
  if (unknownFields) {
137
167
  out.stderr.write(
138
168
  `warning: --fields not present on the response: ${unknownFields.unknown.join(", ")}. Available keys: ${unknownFields.available.join(", ")}.
@@ -143,6 +173,8 @@ function renderSuccess(data, opts, out) {
143
173
  if (json) {
144
174
  out.stdout.write(JSON.stringify(projected) + "\n");
145
175
  } else {
176
+ const provenance = renderProvenanceNote(data);
177
+ if (provenance) out.stderr.write(provenance);
146
178
  out.stdout.write(renderHuman(projected) + "\n");
147
179
  }
148
180
  }
@@ -199,6 +231,34 @@ function renderError(err, opts, out) {
199
231
  msg += `
200
232
  Required tier: ${errJson.requiredTier}`;
201
233
  }
234
+ const safety = errJson;
235
+ if (safety.budgetRow) {
236
+ if (errJson.code === "BUDGET_EXHAUSTED") {
237
+ const why = safety.safetyReason === "activity_window" ? "outside its activity window" : "at its ceiling";
238
+ msg += `
239
+ Safety budget: ${safety.budgetRow} is ${why}`;
240
+ if (safety.resetAt === null) {
241
+ const frees = safety.budgetRow === "inmail" ? "when LinkedIn regrants credits" : safety.budgetRow === "pending_invites" ? "when the backlog clears" : "on its own";
242
+ msg += `
243
+ No reset instant: this frees ${frees}, not on a schedule`;
244
+ } else if (safety.resetAt) {
245
+ msg += `
246
+ Resets at: ${safety.resetAt}`;
247
+ }
248
+ if (safety.safetyHint?.parameter) {
249
+ msg += `
250
+ Change: ${safety.safetyHint.parameter}`;
251
+ }
252
+ if (safety.safetyHint?.message) {
253
+ msg += `
254
+ ${safety.safetyHint.message}`;
255
+ }
256
+ } else {
257
+ const wait = safety.retryAfterSeconds ? ` for ${safety.retryAfterSeconds}s` : "";
258
+ msg += `
259
+ Paused budget row: ${safety.budgetRow}${wait} (other rows on this account still work)`;
260
+ }
261
+ }
202
262
  if (errJson.retryAfterMs) {
203
263
  msg += `
204
264
  Retry after: ${errJson.retryAfterMs}ms`;
@@ -219,6 +279,7 @@ function renderUnexpectedError(err, out) {
219
279
  export {
220
280
  resolveEffectiveConfig,
221
281
  createClient,
282
+ renderProvenanceNote,
222
283
  renderSuccess,
223
284
  renderNotices,
224
285
  renderError,
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
- renderNotices
4
- } from "./chunk-XHVR32RW.js";
3
+ renderNotices,
4
+ renderProvenanceNote
5
+ } from "./chunk-5KANHEBN.js";
5
6
 
6
7
  // src/lib/paginate.ts
7
8
  var PaginateError = class extends Error {
@@ -56,6 +57,8 @@ async function* streamAll(fn, params, opts = {}) {
56
57
  if (opts.out) {
57
58
  const pageNotices = renderNotices(page.notices);
58
59
  if (pageNotices) opts.out.stderr.write(pageNotices + "\n");
60
+ const pageProvenance = renderProvenanceNote(page);
61
+ if (pageProvenance) opts.out.stderr.write(pageProvenance);
59
62
  }
60
63
  if (Array.isArray(items)) {
61
64
  for (const item of items) {
@@ -11,10 +11,10 @@ async function resolveMemberProviderId(ns, raw) {
11
11
  const profile = await ns.users.get(normalized, {});
12
12
  return profile.id;
13
13
  }
14
- async function resolveMemberOrMeProviderId(ns, raw) {
14
+ async function resolveMemberOrMeProviderId(ns, raw, query = {}) {
15
15
  const normalized = resolveIdentifier(raw);
16
16
  if (normalized === "me" || MEMBER_PROVIDER_ID_RE.test(normalized)) return normalized;
17
- const profile = await ns.users.get(normalized, {});
17
+ const profile = await ns.users.get(normalized, query);
18
18
  return profile.id;
19
19
  }
20
20
 
@@ -4,7 +4,7 @@ import {
4
4
  } from "./chunk-AHYUM2XQ.js";
5
5
  import {
6
6
  getExitCode
7
- } from "./chunk-PMRQXBCP.js";
7
+ } from "./chunk-2OG6M6ME.js";
8
8
 
9
9
  // src/lib/path-safety.ts
10
10
  var UNSAFE_CHARS = /[\u0000-\u0020\u007F/\\?#%]/;
@@ -216,7 +216,8 @@ function slimAccountGet(data) {
216
216
  seat_id: d["seat_id"] ?? null,
217
217
  connected_at: d["connected_at"] ?? null,
218
218
  last_checked_at: d["last_checked_at"] ?? null,
219
- quotas: d["quotas"] ?? []
219
+ quotas: d["quotas"] ?? [],
220
+ account_states: d["account_states"] ?? []
220
221
  };
221
222
  }
222
223
  function slimJob(data) {
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/lib/retrieval.ts
4
+ var RETRIEVAL_MODES = ["live", "auto", "refill", "cache_only"];
5
+ var MAX_AGE_CEILING_SECONDS = 31536e3;
6
+ var RETRIEVAL_FLAGS = {
7
+ mode: {
8
+ type: "string",
9
+ description: "How willing this read is to reach LinkedIn: auto (default, a stored copy while it is fresh), live (always fetch), refill (a stored copy at any age, fetch only when nothing is stored), cache_only (never fetch; a store miss is refused rather than fetched). Not combinable with --max-age under cache_only."
10
+ },
11
+ "max-age": {
12
+ type: "string",
13
+ description: `Maximum age in seconds of a stored copy this read will accept (integer, 0-${MAX_AGE_CEILING_SECONDS}). Overrides the auto/live/refill presets in both directions; 0 is the same as --mode live.`
14
+ }
15
+ };
16
+ var NON_NEGATIVE_INTEGER = /^\d+$/;
17
+ function hasRetrievalFlags(flags) {
18
+ return flags.mode !== void 0 || flags["max-age"] !== void 0;
19
+ }
20
+ function parseRetrievalFlags(flags) {
21
+ const query = {};
22
+ const rawMode = flags.mode;
23
+ if (rawMode !== void 0) {
24
+ if (!RETRIEVAL_MODES.includes(rawMode)) {
25
+ return {
26
+ ok: false,
27
+ error: `error: --mode must be one of: ${RETRIEVAL_MODES.join(", ")}.` + (rawMode === "" ? " Omit the flag to use the default (auto).\n" : ` Received "${rawMode}".
28
+ `)
29
+ };
30
+ }
31
+ query.mode = rawMode;
32
+ }
33
+ const rawMaxAge = flags["max-age"];
34
+ if (rawMaxAge !== void 0) {
35
+ if (query.mode === "cache_only") {
36
+ return {
37
+ ok: false,
38
+ error: "error: --mode cache_only cannot be combined with --max-age. cache_only never reaches LinkedIn at any age, so a freshness threshold cannot change its answer. Drop --max-age, or use --mode refill (stored at any age, fetch only when nothing is stored).\n"
39
+ };
40
+ }
41
+ if (!NON_NEGATIVE_INTEGER.test(rawMaxAge)) {
42
+ return {
43
+ ok: false,
44
+ error: `error: --max-age must be a whole number of seconds (0-${MAX_AGE_CEILING_SECONDS}). Received "${rawMaxAge}".
45
+ `
46
+ };
47
+ }
48
+ const seconds = Number(rawMaxAge);
49
+ if (seconds > MAX_AGE_CEILING_SECONDS) {
50
+ return {
51
+ ok: false,
52
+ error: `error: --max-age must be at most ${MAX_AGE_CEILING_SECONDS} seconds (one year). Received "${rawMaxAge}".
53
+ `
54
+ };
55
+ }
56
+ query.max_age = seconds;
57
+ }
58
+ return { ok: true, query };
59
+ }
60
+
61
+ export {
62
+ RETRIEVAL_FLAGS,
63
+ hasRetrievalFlags,
64
+ parseRetrievalFlags
65
+ };
@@ -18,7 +18,7 @@ import {
18
18
  } from "./chunk-UEAX6KUB.js";
19
19
  import {
20
20
  requireAccount
21
- } from "./chunk-LCLYFE54.js";
21
+ } from "./chunk-GHT2DLZR.js";
22
22
  import {
23
23
  buildPreviewOutput
24
24
  } from "./chunk-R3VLWLVV.js";
@@ -28,7 +28,7 @@ import {
28
28
  renderSuccess,
29
29
  renderUnexpectedError,
30
30
  resolveEffectiveConfig
31
- } from "./chunk-XHVR32RW.js";
31
+ } from "./chunk-5KANHEBN.js";
32
32
  import {
33
33
  READ_SINGLE_FLAGS,
34
34
  WRITE_FLAGS,
@@ -71,7 +71,7 @@ var MEMBER_PROVIDER_ID_RE = /^A[CDE][A-Za-z0-9_-]{4,}$/;
71
71
  async function handleSdkError(err, outOpts, out) {
72
72
  const { CurviateError } = await import("@curviate/sdk");
73
73
  if (err instanceof CurviateError) {
74
- const { getExitCode } = await import("./exit-codes-KAVZN5BQ.js");
74
+ const { getExitCode } = await import("./exit-codes-U5CHA6FT.js");
75
75
  renderError(err, outOpts, out);
76
76
  process.exit(getExitCode(err.code));
77
77
  }
package/dist/cli.js CHANGED
@@ -340,23 +340,23 @@ var main = defineCommand({
340
340
  // ---------------------------------------------------------------------------
341
341
  // Noun groups, lazy-loaded on first invocation.
342
342
  // ---------------------------------------------------------------------------
343
- profile: () => import("./profile-REKGQYAW.js").then((m) => m.profileCommand),
344
- company: () => import("./company-PAKHOCVR.js").then((m) => m.companyCommand),
345
- job: () => import("./job-3HU7KQQI.js").then((m) => m.jobCommand),
346
- connect: () => import("./connect-5TMGM326.js").then((m) => m.connectCommand),
347
- search: () => import("./search-SYWHOM5J.js").then((m) => m.searchCommand),
348
- inbox: () => import("./inbox-R5OSZWTG.js").then((m) => m.inboxCommand),
349
- inboxes: () => import("./inboxes-6XMIABRX.js").then((m) => m.inboxesCommand),
350
- message: () => import("./message-GA7D3A6Y.js").then((m) => m.messageCommand),
351
- post: () => import("./post-QAVRVRON.js").then((m) => m.postCommand),
352
- comment: () => import("./comment-XAF7AMHR.js").then((m) => m.commentCommand),
353
- account: () => import("./account-52BUCCTZ.js").then((m) => m.accountCommand),
354
- webhook: () => import("./webhook-RE2BGX3N.js").then((m) => m.webhookCommand),
355
- "sales-nav": () => import("./sales-nav-Q5RVL4PR.js").then((m) => m.salesNavCommand),
356
- recruiter: () => import("./recruiter-N36AROW7.js").then((m) => m.recruiterCommand),
357
- group: () => import("./group-SNCEAWKI.js").then((m) => m.groupCommand),
358
- feed: () => import("./feed-E5EQMI7T.js").then((m) => m.feedCommand),
359
- notification: () => import("./notification-B5PTNNPE.js").then((m) => m.notificationCommand)
343
+ profile: () => import("./profile-72V55PZM.js").then((m) => m.profileCommand),
344
+ company: () => import("./company-ZT65QZ6F.js").then((m) => m.companyCommand),
345
+ job: () => import("./job-NUT4QMH2.js").then((m) => m.jobCommand),
346
+ connect: () => import("./connect-57AUN33D.js").then((m) => m.connectCommand),
347
+ search: () => import("./search-QCXTK33P.js").then((m) => m.searchCommand),
348
+ inbox: () => import("./inbox-CQO2I47N.js").then((m) => m.inboxCommand),
349
+ inboxes: () => import("./inboxes-XQ2B6X3Q.js").then((m) => m.inboxesCommand),
350
+ message: () => import("./message-KMNRUD4H.js").then((m) => m.messageCommand),
351
+ post: () => import("./post-FXAANNUB.js").then((m) => m.postCommand),
352
+ comment: () => import("./comment-BLG4WHST.js").then((m) => m.commentCommand),
353
+ account: () => import("./account-5KGM6EPR.js").then((m) => m.accountCommand),
354
+ webhook: () => import("./webhook-D4QRWF7W.js").then((m) => m.webhookCommand),
355
+ "sales-nav": () => import("./sales-nav-BALVVD35.js").then((m) => m.salesNavCommand),
356
+ recruiter: () => import("./recruiter-JUNB5AUR.js").then((m) => m.recruiterCommand),
357
+ group: () => import("./group-DYC2NX5M.js").then((m) => m.groupCommand),
358
+ feed: () => import("./feed-3AWI2URQ.js").then((m) => m.feedCommand),
359
+ notification: () => import("./notification-LEM57IBY.js").then((m) => m.notificationCommand)
360
360
  },
361
361
  async run() {
362
362
  const { runMain } = await import("citty");