@whatcha/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# whatcha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official command-line client for [what-are-you-do-ing](https://whatareyoudo.ing) --
+the tool an AI agent (or a script) uses instead of automating a browser.
+See `docs/proposals/2026-09-official-cli.md` for why this exists.
+
+## Install
+
+```
+npx @whatcha/cli <command>
+```
+
+or install it once:
+
+```
+npm install -g @whatcha/cli
+whatcha <command>
+```
+
+Requires Node >= 22 (fetch, `node:util`'s `parseArgs`, and the fixed
+`package.json`'s `"engines"` all assume it).
+
+## Commands
+
+### `whatcha login`
+
+```
+whatcha login [--email <email>] [--password <password>] [--token <refresh-token>] [--json]
+```
+
+Signs in and stores the session -- an OS credential store when one is
+available (macOS Keychain via `security`, Linux's Secret Service via
+`secret-tool`), otherwise a `0600` file under the OS config dir
+(`~/.config/whatcha/credentials.json` on Linux, `~/Library/.../whatcha` is
+not used on macOS since the Keychain is tried first, `%APPDATA%\whatcha` on
+Windows). Every other command reads that session and refreshes it as
+needed; there is no separate `whatcha logout` in this first version -- clear
+the credential store yourself (Keychain Access, `secret-tool clear service
+whatcha-cli account whatcha`, or delete the file) if you need to.
+
+Email and password can come from `--email`/`--password`, from
+`WHATCHA_EMAIL`/`WHATCHA_PASSWORD`, or (only when neither is set) an
+interactive prompt with the password masked. The env vars exist because an
+AI agent invoking `whatcha` as a subprocess has no TTY to answer a prompt at.
+
+**If sign-in is refused (issue #1428):** GoTrue enforces a Cloudflare
+Turnstile challenge on the password grant, and an automated/headless
+browser cannot solve it -- a real user hit exactly this ("Verification
+failed" / "Please complete the verification") trying to sign in an AI
+partner account. `POST /auth/login` also answers a captcha rejection with
+the same generic 401 as a wrong password, so `whatcha` frequently cannot
+tell you which one happened. Do not keep retrying the password in that
+case. Instead:
+
+```
+whatcha login --token <refresh-token>
+```
+
+or set `WHATCHA_TOKEN` to the same value. This calls `POST /auth/refresh`
+directly, which is **not** captcha-gated, so it works from a machine that
+can never pass Turnstile. The refresh token itself has to come from
+somewhere that *can* solve the challenge -- a browser or the mobile app,
+signed in once, with the token then handed to the headless machine out of
+band. As of this writing there is no self-service "show me my token" screen
+in the app to get one from; see this PR's description for what a real fix
+looks like on the API/product side.
+
+Advanced: if `WHATCHA_SUPABASE_URL` and `WHATCHA_SUPABASE_ANON_KEY` are both
+set, `whatcha login` talks to GoTrue directly instead of through
+`/auth/login`. This does not bypass the captcha (GoTrue enforces it either
+way) but its error responses do say explicitly when a request was rejected
+for a captcha reason, which `whatcha` then reports plainly instead of
+guessing. Nothing in this repo publishes those two values for a checkout to
+read (they are build-time secrets on the mobile/web clients), so this path
+is opt-in and unverified against a live server -- see the PR description.
+
+### `whatcha diaries`
+
+```
+whatcha diaries [--json]
+```
+
+Lists the diaries you can see (your personal shelf, same set `GET /diaries`
+without `groupId` returns -- so not diaries in a system group like Public
+Square).
+
+### `whatcha write`
+
+```
+whatcha write <diary> --text "..." [--time HH:MM] [--date YYYY-MM-DD] [--json]
+```
+
+`<diary>` is a diary id or its exact name (case-insensitive; an ambiguous
+name lists the matches and asks for the id instead). `--date`/`--time`
+default to today/now in **the diary's own timezone**, not the machine's --
+that is what decides which diary-day the API's one-entry-per-day rule
+(§11.4) puts the write on.
+
+**Appending is always safe.** If the diary-day already has an entry, this
+never sends a body it has not just read:
+
+1. No entry yet for that day -- `POST /entries` creates it with your text.
+2. An entry exists -- the entry is read first (`GET /entries/{id}`, to
+   carry its title/mood/tags/cover forward unchanged, since those fields
+   are full-replace-on-save the same as the body), then `PATCH` with
+   `appendBody: true` (fixed in #1424) appends server-side.
+3. If the server does not know `appendBody` (a 422 naming it an
+   unrecognized key), the text already read in step 2 is merged locally
+   and sent as a plain replacement of what was just read -- never blind.
+4. Either way, the entry is read back once more afterward to confirm the
+   old text is still there under the new text. If that check fails,
+   `whatcha` exits with status 2 and a loud warning instead of reporting
+   success -- see `src/lib/append-entry.ts` for why this exists (it is the
+   only defense against a server old enough to silently ignore
+   `appendBody` and just replace, which the API's own default
+   configuration would in fact do -- see the PR description).
+
+### `whatcha read`
+
+```
+whatcha read <diary> [--date YYYY-MM-DD] [--json]
+```
+
+Defaults to today (diary timezone). Prints title/tags/body; a locked (Time
+Capsule) entry is reported as locked, never shown early. `GET /entries` has
+no `?date=` filter, so this pages through the diary's entries
+newest-first (`src/lib/entry-find.ts`) until it finds that day or passes it
+-- exact, not fuzzy, but not O(1) for a very old date on a very active diary.
+
+### `whatcha profiles` / `whatcha switch`
+
+```
+whatcha profiles [--json]
+whatcha switch <@handle> [--json]
+whatcha switch --account [--json]
+```
+
+Sub-accounts (#1538): one login, more than one profile. A sub-profile is an
+ordinary user with its own `@handle`, so after a switch `write`, `read` and
+`diaries` all act as that profile -- none of them takes a flag, and none of
+them knows the feature exists. The saved session simply is that profile.
+
+`profiles` marks the current one with `*` and labels the account. Creating a
+sub-profile is done in the app; this CLI switches between the ones that
+exist.
+
+`switch --account` is how you come back. The API refuses to mint an account
+session from a sub-profile's session on purpose -- a sub-profile that could
+ask for one would be a way to take the account over -- so `switch` sets the
+account's refresh token aside in the same credential store and `--account`
+spends it. Switching from one sub-profile to a sibling carries it forward
+unchanged.
+
+Billing is the one thing a sub-profile does not have: the account's plan is
+its plan, and a sub-profile's own limits are the account's.
+
+## The `--json` contract
+
+Every command accepts `--json`. On success it prints exactly one JSON
+object to stdout: `{"ok": true, ...}`, with the fields documented per
+command above (`diaries`, `entryId`/`mode`/`verified` for `write`,
+`body`/`title`/`tags`/... for `read`). On failure it prints
+`{"ok": false, "error": {"code", "message"}}` -- still to stdout, so a
+script doing `whatcha ... --json | jq` gets parseable JSON either way,
+without also having to capture stderr.
+
+**Never included, on success or failure:** an access token, a refresh
+token, or a password. `whatcha login --json`'s output is
+`{"ok", "userId", "email", "credentialStore"}` -- the store's name, never
+its contents.
+
+## Tests
+
+```
+npm ci
+npm run typecheck
+npm test
+```
+
+Every test runs with no network: `tests/fixtures/fake-client.ts` implements
+the same `WhatchaClient` interface the real HTTP client does, so
+`src/lib/append-entry.ts`, the command parsers, and the token store are all
+exercised against an in-memory fake instead of a live API. The token-store
+tests point `WHATCHA_CONFIG_DIR` at a throwaway directory rather than
+touching a real OS keychain or the developer's own config file.

package/dist/auth/gotrue-client.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoTrueError = void 0;
+exports.signInWithPassword = signInWithPassword;
+class GoTrueError extends Error {
+    status;
+    errorCode;
+    constructor(status, errorCode, message) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.name = "GoTrueError";
+    }
+    /**
+     * GoTrue's captcha rejection is a 400 whose body names the captcha
+     * explicitly (`error_code: "captcha_failed"` on current GoTrue; older
+     * versions instead put it in `msg`, e.g. "captcha protection: request
+     * disallowed"), unlike a wrong password's "Invalid login credentials".
+     * Not verified against a live server -- see the PR description's "which
+     * paths I could verify" section.
+     */
+    looksLikeCaptchaFailure() {
+        const haystack = `${this.errorCode ?? ""} ${this.message}`.toLowerCase();
+        return haystack.includes("captcha");
+    }
+}
+exports.GoTrueError = GoTrueError;
+async function signInWithPassword(supabaseUrl, anonKey, email, password, captchaToken) {
+    let res;
+    try {
+        res = await fetch(`${supabaseUrl.replace(/\/$/, "")}/auth/v1/token?grant_type=password`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                apikey: anonKey,
+                Authorization: `Bearer ${anonKey}`,
+            },
+            body: JSON.stringify({
+                email,
+                password,
+                gotrue_meta_security: captchaToken ? { captcha_token: captchaToken } : undefined,
+            }),
+        });
+    }
+    catch (err) {
+        throw new GoTrueError(0, "network_error", `Could not reach ${supabaseUrl}: ${err.message}`);
+    }
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : undefined;
+    if (!res.ok) {
+        const body = json;
+        const message = body?.msg ?? body?.error_description ?? body?.error ?? `GoTrue answered ${res.status}`;
+        throw new GoTrueError(res.status, body?.error_code ?? body?.error, message);
+    }
+    const body = json;
+    return {
+        accessToken: body.access_token,
+        expiresIn: body.expires_in,
+        refreshToken: body.refresh_token,
+        userId: body.user.id,
+        email: body.user.email ?? email,
+    };
+}
+//# sourceMappingURL=gotrue-client.js.map

package/dist/auth/gotrue-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gotrue-client.js","sourceRoot":"","sources":["../../src/auth/gotrue-client.ts"],"names":[],"mappings":";;;AA2DA,gDA2CC;AAtED,MAAa,WAAY,SAAQ,KAAK;IACf;IAAyB;IAA9C,YAAqB,MAAc,EAAW,SAA6B,EAAE,OAAe;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAC;QADI,WAAM,GAAN,MAAM,CAAQ;QAAW,cAAS,GAAT,SAAS,CAAoB;QAEzE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,uBAAuB;QACrB,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;QACzE,OAAO,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;CACF;AAlBD,kCAkBC;AASM,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,OAAe,EACf,KAAa,EACb,QAAgB,EAChB,YAAqB;IAErB,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,oCAAoC,EAAE;YACvF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,OAAO;gBACf,aAAa,EAAE,UAAU,OAAO,EAAE;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK;gBACL,QAAQ;gBACR,oBAAoB,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,SAAS;aACjF,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CAAC,CAAC,EAAE,eAAe,EAAE,mBAAmB,WAAW,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAY,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1D,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,IAAqG,CAAC;QACnH,MAAM,OAAO,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,iBAAiB,IAAI,IAAI,EAAE,KAAK,IAAI,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC;QACvG,MAAM,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,IAAI,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,GAAG,IAA2B,CAAC;IACzC,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,YAAY;QAC9B,SAAS,EAAE,IAAI,CAAC,UAAU;QAC1B,YAAY,EAAE,IAAI,CAAC,aAAa;QAChC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;QACpB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK;KAChC,CAAC;AACJ,CAAC"}

package/dist/auth/session.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveSession = saveSession;
+exports.loadSession = loadSession;
+exports.clearSession = clearSession;
+exports.authenticatedClient = authenticatedClient;
+exports.anonymousClient = anonymousClient;
+const http_client_1 = require("../http-client");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const token_store_1 = require("./token-store");
+/** Refresh this many seconds before actual expiry, so a call in flight does not race the token dying mid-request. */
+const REFRESH_MARGIN_SECONDS = 60;
+/**
+ * Tries each candidate store in order (OS keychain first where one exists
+ * for the platform, the 0600 file always last) and uses the first one that
+ * actually accepts the write. A keychain that exists but is locked, or a
+ * Secret Service that is not running, throws on `save` rather than on
+ * `isAvailable` -- both are caught here, not just the availability check.
+ */
+async function saveSession(session, stores = (0, token_store_1.candidateStores)()) {
+    const errors = [];
+    for (const store of stores) {
+        if (!(await store.isAvailable()))
+            continue;
+        try {
+            await store.save(session);
+            return { store };
+        }
+        catch (err) {
+            errors.push(`${store.name}: ${err.message}`);
+        }
+    }
+    throw new Error(`Could not save the session to any credential store. Tried:\n${errors.join("\n")}`);
+}
+/** First candidate store that actually has a session, or null if none do. */
+async function loadSession(stores = (0, token_store_1.candidateStores)()) {
+    for (const store of stores) {
+        if (!(await store.isAvailable()))
+            continue;
+        const session = await store.load();
+        if (session)
+            return session;
+    }
+    return null;
+}
+/** Best-effort clear from every candidate, not just whichever one currently holds the session -- avoids a stale copy surviving a store switch. */
+async function clearSession(stores = (0, token_store_1.candidateStores)()) {
+    for (const store of stores) {
+        if (await store.isAvailable())
+            await store.clear();
+    }
+}
+/**
+ * A client wired to a saved session, refreshing the access token first if
+ * it is at or near expiry. Every command but `login` starts here.
+ *
+ * Throws CliUsageError (not ApiError) when there is no session or the
+ * refresh itself fails -- both are "run `whatcha login`" situations, not
+ * something a command should try to recover from.
+ */
+async function authenticatedClient(stores = (0, token_store_1.candidateStores)()) {
+    let session = await loadSession(stores);
+    if (!session) {
+        throw new errors_1.CliUsageError("Not logged in. Run `whatcha login` first.");
+    }
+    const baseUrl = session.apiBaseUrl || (0, config_1.apiBaseUrl)();
+    const nowSeconds = Date.now() / 1000;
+    if (session.expiresAt / 1000 - nowSeconds < REFRESH_MARGIN_SECONDS) {
+        const anon = new http_client_1.FetchWhatchaClient(baseUrl, async () => undefined);
+        let refreshed;
+        try {
+            refreshed = await anon.post("/auth/refresh", { refreshToken: session.refreshToken });
+        }
+        catch {
+            throw new errors_1.CliUsageError("The saved session has expired and could not be refreshed. Run `whatcha login` again.");
+        }
+        session = {
+            ...session,
+            accessToken: refreshed.accessToken,
+            refreshToken: refreshed.refreshToken,
+            expiresAt: Date.now() + refreshed.expiresIn * 1000,
+        };
+        // Best-effort: a save failure here must not fail the command that
+        // triggered the refresh -- worst case, the next command refreshes
+        // again. Whichever store answered `load()` above is where this goes
+        // back to.
+        await saveSession(session, stores).catch(() => undefined);
+    }
+    const client = new http_client_1.FetchWhatchaClient(baseUrl, async () => `Bearer ${session.accessToken}`);
+    return { client, session };
+}
+/** An unauthenticated client for `/auth/login` itself, or for `--api-url` probing. */
+function anonymousClient(baseUrl = (0, config_1.apiBaseUrl)()) {
+    return new http_client_1.FetchWhatchaClient(baseUrl, async () => undefined);
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"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"}