heybash-xdpool 1.0.5 → 1.0.6
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.
- package/CHANGELOG.md +7 -0
- package/lib/bin.js +293 -11
- package/lib/client.js +60 -20
- package/lib/index.d.ts +190 -5
- package/lib/index.js +685 -37
- package/package.json +1 -1
- package/tools/sync-npmmirror.mjs +3 -3
- package/vendor/channel-pack/pack.js +41 -3
package/lib/index.d.ts
CHANGED
|
@@ -572,8 +572,17 @@ export declare class WorkBuddyUpstreamClient {
|
|
|
572
572
|
* list is missing half its entries for the rest of the session".
|
|
573
573
|
*/
|
|
574
574
|
private fetchModelsOnce;
|
|
575
|
-
/**
|
|
576
|
-
|
|
575
|
+
/**
|
|
576
|
+
* Read-only credits query, aggregated by package. Does not consume credits.
|
|
577
|
+
*
|
|
578
|
+
* `signal` is the caller's cancellation, merged with the built-in timeout
|
|
579
|
+
* rather than replacing it: the pool's background warm must give up when the
|
|
580
|
+
* host shuts down, and a caller that has already gone away must not leave a
|
|
581
|
+
* 30 s request running. `AbortSignal.any` is already the repo's way of
|
|
582
|
+
* combining these (see the pricing probe in the shim), and the timeout stays
|
|
583
|
+
* in force so a signal-less caller keeps the old behaviour exactly.
|
|
584
|
+
*/
|
|
585
|
+
fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<WorkBuddyCredits>;
|
|
577
586
|
/** Query today's check-in status without changing account state. */
|
|
578
587
|
fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
|
|
579
588
|
/** Claim today's check-in reward. The browser route guards this mutation. */
|
|
@@ -835,6 +844,41 @@ interface TokenRefresher {
|
|
|
835
844
|
domain?: string;
|
|
836
845
|
}>;
|
|
837
846
|
}
|
|
847
|
+
/**
|
|
848
|
+
* Minimal billing surface the pool needs to fill `creditExpiry` itself.
|
|
849
|
+
*
|
|
850
|
+
* Declared here for the same reason as {@link TokenRefresher}: the pool knows
|
|
851
|
+
* about accounts, not about HTTP, and importing `WorkBuddyUpstreamClient` would
|
|
852
|
+
* make the two modules circular. `fetchCredits` is OPTIONAL so every existing
|
|
853
|
+
* `TokenRefresher` — the test stubs, and any host that only wired token refresh
|
|
854
|
+
* — keeps working untouched; a client without it simply warms nothing.
|
|
855
|
+
*/
|
|
856
|
+
interface CreditReader {
|
|
857
|
+
fetchCredits(credential: WorkBuddyCredential, signal?: AbortSignal): Promise<{
|
|
858
|
+
total: number;
|
|
859
|
+
/** Absent (or undefined) when no one-off pack has a deadline. */
|
|
860
|
+
nearestExpiryMs?: number | undefined;
|
|
861
|
+
}>;
|
|
862
|
+
}
|
|
863
|
+
/**
|
|
864
|
+
* What the pool knows about one account's one-off pack deadlines.
|
|
865
|
+
*
|
|
866
|
+
* The three `state`s are the whole point of the B+ fix: "never asked", "asked,
|
|
867
|
+
* nothing has a deadline" and "asked, here is the deadline" need different
|
|
868
|
+
* handling, and collapsing them into one absent-key predicate is what made a
|
|
869
|
+
* pure monthly-pack account be re-read forever (S1 in
|
|
870
|
+
* `EXPIRY-ADVERSARIAL-20261111.md`). `stale` is orthogonal: the reading is real
|
|
871
|
+
* but older than {@link EXPIRY_READING_TTL_MS}, so it describes the past.
|
|
872
|
+
*/
|
|
873
|
+
interface ExpiryReading {
|
|
874
|
+
state: 'unread' | 'none' | 'at';
|
|
875
|
+
/** Deadline, epoch ms; present exactly when `state === 'at'`. */
|
|
876
|
+
at?: number;
|
|
877
|
+
/** When this reading was written, epoch ms; absent for `unread`. */
|
|
878
|
+
readAtMs?: number;
|
|
879
|
+
/** True when the reading is older than {@link EXPIRY_READING_TTL_MS}. */
|
|
880
|
+
stale: boolean;
|
|
881
|
+
}
|
|
838
882
|
/** Live auth file name the WorkBuddy desktop app writes. */
|
|
839
883
|
export declare const WORKBUDDY_LIVE_FILENAME = "workbuddy-desktop.info";
|
|
840
884
|
/** Snapshot files left behind by previous logins share this prefix. */
|
|
@@ -963,9 +1007,16 @@ interface AccountPoolOptions {
|
|
|
963
1007
|
*/
|
|
964
1008
|
credentialDeadCooldownMs?: number;
|
|
965
1009
|
/** Upstream client used to refresh near-expiry tokens. */
|
|
966
|
-
client?: TokenRefresher
|
|
1010
|
+
client?: TokenRefresher & Partial<CreditReader>;
|
|
967
1011
|
/** Refresh this long before actual expiry; default five minutes. */
|
|
968
1012
|
refreshMarginMs?: number;
|
|
1013
|
+
/**
|
|
1014
|
+
* How long a credit-pack deadline reading is trusted, in ms.
|
|
1015
|
+
*
|
|
1016
|
+
* Defaults to {@link EXPIRY_READING_TTL_MS}; overridable so a test can age a
|
|
1017
|
+
* reading without sleeping for an hour.
|
|
1018
|
+
*/
|
|
1019
|
+
expiryReadingTtlMs?: number;
|
|
969
1020
|
/**
|
|
970
1021
|
* How requests are spread across the pool.
|
|
971
1022
|
*
|
|
@@ -1017,6 +1068,7 @@ export declare class WorkBuddyAccountPool {
|
|
|
1017
1068
|
private credentialDeadCooldownMs;
|
|
1018
1069
|
private readonly client;
|
|
1019
1070
|
private readonly refreshMarginMs;
|
|
1071
|
+
private readonly expiryReadingTtlMs;
|
|
1020
1072
|
private accounts;
|
|
1021
1073
|
/**
|
|
1022
1074
|
* Files the last scan could not read, with the reason.
|
|
@@ -1112,10 +1164,41 @@ export declare class WorkBuddyAccountPool {
|
|
|
1112
1164
|
* their own cycle and are therefore never urgent — which is why this is
|
|
1113
1165
|
* written from the same `fetchCredits` reading that fills `creditBalances`.
|
|
1114
1166
|
*
|
|
1115
|
-
*
|
|
1116
|
-
*
|
|
1167
|
+
* A positive value is a deadline. The two other states are kept in
|
|
1168
|
+
* {@link creditExpiryNone} and {@link creditExpiryReadAt} rather than as a
|
|
1169
|
+
* missing key, because a missing key cannot tell "we never looked" from "we
|
|
1170
|
+
* looked and nothing has a deadline" — and only the first is worth reading
|
|
1171
|
+
* again. An account whose packs are all monthly reads as `none` forever, which
|
|
1172
|
+
* is exactly right: asking again cannot change the answer (S1).
|
|
1117
1173
|
*/
|
|
1118
1174
|
private creditExpiry;
|
|
1175
|
+
/**
|
|
1176
|
+
* Accounts whose last reading found NO one-off deadline (all monthly packs, or
|
|
1177
|
+
* none at all). Written instead of deleting the key, so the account stops
|
|
1178
|
+
* being a candidate for re-reading.
|
|
1179
|
+
*/
|
|
1180
|
+
private creditExpiryNone;
|
|
1181
|
+
/** When each account's deadline reading was taken, epoch ms. */
|
|
1182
|
+
private creditExpiryReadAt;
|
|
1183
|
+
/**
|
|
1184
|
+
* Accounts whose deadline reading is being fetched right now.
|
|
1185
|
+
*
|
|
1186
|
+
* Same de-duplication idea as {@link refreshInflight}, for the same reason: a
|
|
1187
|
+
* scan-triggered warm and a request-triggered top-up must not both spend a
|
|
1188
|
+
* billing round trip on the same account. A Set rather than a Map of promises
|
|
1189
|
+
* because no caller ever awaits the warm — the point is only that a second
|
|
1190
|
+
* pass skips it.
|
|
1191
|
+
*/
|
|
1192
|
+
private expiryWarmInflight;
|
|
1193
|
+
/**
|
|
1194
|
+
* Last time the pool tried to warm an account's deadline reading, epoch ms.
|
|
1195
|
+
*
|
|
1196
|
+
* The TTL is the success gate, not a retry gate: a failed read writes nothing,
|
|
1197
|
+
* so without this a permanently failing billing endpoint would be hit on every
|
|
1198
|
+
* scan and every served request. One attempt per account per minute is cheap
|
|
1199
|
+
* and still recovers quickly from a transient failure.
|
|
1200
|
+
*/
|
|
1201
|
+
private expiryWarmAttemptAt;
|
|
1119
1202
|
/**
|
|
1120
1203
|
* Last time each account served a request, epoch ms. Drives the idle term
|
|
1121
1204
|
* of the priority-mode weighting below: an account that just served loses to
|
|
@@ -1210,6 +1293,47 @@ export declare class WorkBuddyAccountPool {
|
|
|
1210
1293
|
private pruneExpiredSnapshots;
|
|
1211
1294
|
/** Rescan the auth directories and merge newly discovered accounts. */
|
|
1212
1295
|
scan(): Promise<WorkBuddyAccount[]>;
|
|
1296
|
+
/**
|
|
1297
|
+
* Warm the deadline readings that `expiry` mode sorts on.
|
|
1298
|
+
*
|
|
1299
|
+
* Fire-and-forget on purpose, from `scan()`: the pool's first request arrives
|
|
1300
|
+
* before any reading exists, and the honest answer to that is the documented
|
|
1301
|
+
* fallback plus a log line, not a stalled request. Everything about the call
|
|
1302
|
+
* is chosen to be unable to make things worse:
|
|
1303
|
+
*
|
|
1304
|
+
* - `this.client` may not exist (a host that wired only token refresh), in
|
|
1305
|
+
* which case there is nothing to read with and the pass is a no-op — the
|
|
1306
|
+
* same guard `ensureFresh` uses;
|
|
1307
|
+
* - a dead sign-in is skipped, and a successful read NEVER calls
|
|
1308
|
+
* `clearCredentialDead`. That is the difference between this and
|
|
1309
|
+
* `reviveBenched`: the billing endpoint answers 200 for a banned account
|
|
1310
|
+
* (observed on 11140), so treating a read as proof of health is what got a
|
|
1311
|
+
* banned account revived six times in a day (S2). Only a token refresh or a
|
|
1312
|
+
* fresh sign-in may clear that mark;
|
|
1313
|
+
* - accounts whose reading is fresh enough are skipped, and so are accounts
|
|
1314
|
+
* already being read (S10's de-duplication, mirroring `refreshInflight`);
|
|
1315
|
+
* - a failed read writes nothing and only warns, so the next pass tries
|
|
1316
|
+
* again without the failure being mistaken for a reading.
|
|
1317
|
+
*/
|
|
1318
|
+
private warmExpiryReadings;
|
|
1319
|
+
/** One account's warm read; see {@link warmExpiryReadings} for the rules. */
|
|
1320
|
+
private warmOneExpiryReading;
|
|
1321
|
+
/**
|
|
1322
|
+
* Top up one account's deadline reading, from wherever the pool notices it is
|
|
1323
|
+
* missing or stale.
|
|
1324
|
+
*
|
|
1325
|
+
* The request path is the second caller (after `scan()`), because a reading
|
|
1326
|
+
* ages out while the pool is busy too: the shim calls this for the account that
|
|
1327
|
+
* just served a request, which is the one whose spend is most likely to have
|
|
1328
|
+
* moved its deadline. No timer is created — the existing balance refresh is
|
|
1329
|
+
* already the natural heartbeat, and this rides on it.
|
|
1330
|
+
*
|
|
1331
|
+
* Every gate lives here rather than in the callers, so both paths obey exactly
|
|
1332
|
+
* the same rules: no client, no account, a rejected sign-in, an already-running
|
|
1333
|
+
* read, a finished "nothing expires" answer, a fresh reading, or an attempt
|
|
1334
|
+
* made within the last minute all mean "do nothing".
|
|
1335
|
+
*/
|
|
1336
|
+
warmExpiryReadingFor(accountId: string): void;
|
|
1213
1337
|
/** All accounts, cooldown state included. */
|
|
1214
1338
|
list(region?: WorkBuddyRegion): readonly WorkBuddyAccount[];
|
|
1215
1339
|
/**
|
|
@@ -1331,6 +1455,14 @@ export declare class WorkBuddyAccountPool {
|
|
|
1331
1455
|
* A pool where nobody has a known expiry therefore behaves exactly like
|
|
1332
1456
|
* priority, which is the honest degradation: without a reading there is
|
|
1333
1457
|
* nothing to sort by.
|
|
1458
|
+
*
|
|
1459
|
+
* What this method must NOT do is pretend. With only SOME readings in hand it
|
|
1460
|
+
* still has to fall back to `pool[0]`, because picking the earliest of the
|
|
1461
|
+
* accounts that happen to have answered would silently drop the account that
|
|
1462
|
+
* really dies first — the failure mode S0 in `EXPIRY-ADVERSARIAL-20261111.md`
|
|
1463
|
+
* called "worse than not fixing it", since the pick looks plausible and is
|
|
1464
|
+
* wrong. So the incomplete case is announced instead: the caller keeps the old
|
|
1465
|
+
* semantics and the log says which accounts were not read.
|
|
1334
1466
|
*/
|
|
1335
1467
|
private pickByExpiry;
|
|
1336
1468
|
/**
|
|
@@ -1423,10 +1555,50 @@ export declare class WorkBuddyAccountPool {
|
|
|
1423
1555
|
* merged: a pack that has been spent or has died disappears from the next
|
|
1424
1556
|
* reading, and keeping the stale deadline would pin the pool to an account
|
|
1425
1557
|
* whose credits are already gone — the opposite of what `expiry` mode wants.
|
|
1558
|
+
*
|
|
1559
|
+
* "Nothing expires" is a real answer, not the absence of one: it is stored as
|
|
1560
|
+
* {@link creditExpiryNone} so the account is not read again on every pass.
|
|
1426
1561
|
*/
|
|
1427
1562
|
noteCredits(accountId: string, balance: number, nearestExpiryMs?: number): void;
|
|
1563
|
+
/**
|
|
1564
|
+
* Record ONLY the deadline, never the balance.
|
|
1565
|
+
*
|
|
1566
|
+
* The scan-triggered warm exists to fill `expiry` mode's sort key. Writing the
|
|
1567
|
+
* balance as a side effect would change what the reserve floor decides — an
|
|
1568
|
+
* account could be pulled out of rotation by a background read the user never
|
|
1569
|
+
* asked for, which is a behaviour change outside this fix's scope (S7 in
|
|
1570
|
+
* `EXPIRY-ADVERSARIAL-20261111.md`; the reserve's own cold-start hole is V4,
|
|
1571
|
+
* fixed separately).
|
|
1572
|
+
*/
|
|
1573
|
+
noteExpiryOnly(accountId: string, nearestExpiryMs?: number): void;
|
|
1574
|
+
/**
|
|
1575
|
+
* The three-state writer both entry points funnel through.
|
|
1576
|
+
*
|
|
1577
|
+
* One place, so the invariant "a finished reading always leaves a state" can be
|
|
1578
|
+
* read off a single function: either a deadline is stored, or the account joins
|
|
1579
|
+
* `creditExpiryNone`. Nothing here deletes the read stamp — that is what makes
|
|
1580
|
+
* "read, found nothing" distinguishable from "never read".
|
|
1581
|
+
*/
|
|
1582
|
+
private noteExpiryReading;
|
|
1428
1583
|
/** Nearest one-off pack expiry for one account, or undefined when none known. */
|
|
1429
1584
|
creditExpiryOf(accountId: string): number | undefined;
|
|
1585
|
+
/**
|
|
1586
|
+
* The full three-state reading for one account, including staleness.
|
|
1587
|
+
*
|
|
1588
|
+
* `stale` is evaluated against {@link EXPIRY_READING_TTL_MS} here rather than
|
|
1589
|
+
* baked into the stored value, so the TTL stays a constant of the policy and
|
|
1590
|
+
* not of the data.
|
|
1591
|
+
*
|
|
1592
|
+
* Only a real deadline can go stale. "We never asked" is not a reading, and
|
|
1593
|
+
* "nothing here has a deadline" does not become less true with age: a monthly
|
|
1594
|
+
* pack does not grow an expiry date by waiting. Keeping `none` permanently
|
|
1595
|
+
* valid is what makes the S1 loop impossible — an account that answered once
|
|
1596
|
+
* is never read again by the expiry machinery, so there is no predicate that
|
|
1597
|
+
* can stay true forever and re-read it on every pass. If such an account does
|
|
1598
|
+
* gain a one-off pack later, the card refresh (which writes through
|
|
1599
|
+
* `noteCredits` on every poll) is what notices.
|
|
1600
|
+
*/
|
|
1601
|
+
expiryReadingOf(accountId: string, now?: number): ExpiryReading;
|
|
1430
1602
|
/** Last known balance for one account, or undefined when never read. */
|
|
1431
1603
|
creditsOf(accountId: string): number | undefined;
|
|
1432
1604
|
/** The credit floor the user set for one account; 0 when unset. */
|
|
@@ -3664,6 +3836,17 @@ export declare class WorkBuddyScheduler {
|
|
|
3664
3836
|
private travelHours;
|
|
3665
3837
|
private compensationHours;
|
|
3666
3838
|
private timer;
|
|
3839
|
+
/** The one-shot kick scheduled just after `start`; cleared by `stop`. */
|
|
3840
|
+
private settleTimer;
|
|
3841
|
+
/**
|
|
3842
|
+
* Deadline for the start-of-day window described in {@link dueSlot}.
|
|
3843
|
+
*
|
|
3844
|
+
* Zero until {@link start} sets it, so a manual `tick` before the loop starts
|
|
3845
|
+
* keeps the original "only past hours" behaviour.
|
|
3846
|
+
*/
|
|
3847
|
+
private startupCatchUpUntilMs;
|
|
3848
|
+
/** A startup pass is extra work; it never spends a future scheduled slot. */
|
|
3849
|
+
private readonly startupCompleted;
|
|
3667
3850
|
private running;
|
|
3668
3851
|
/** Guards against a slow run overlapping the next tick. */
|
|
3669
3852
|
private busy;
|
|
@@ -3798,6 +3981,8 @@ export declare class WorkBuddyScheduler {
|
|
|
3798
3981
|
* PASSED and its slot is still unconsumed, so a laptop that slept through
|
|
3799
3982
|
* 10:00 still runs the job when it wakes, on the same day.
|
|
3800
3983
|
*
|
|
3984
|
+
* Startup runs are handled separately in tick and do not spend a future slot.
|
|
3985
|
+
*
|
|
3801
3986
|
* The EARLIEST unconsumed candidate wins, which is what keeps a two-hour job
|
|
3802
3987
|
* (`travelHours: [9, 21]`) whole: consuming the earliest due slot leaves the
|
|
3803
3988
|
* later one for its own hour.
|