flowcvcli 0.2.0__py3-none-any.whl

flowcvcli/__init__.py

@@ -0,0 +1,8 @@
+"""flowcvcli — control a FlowCV resume from Python or the command line."""
+from .api import FlowCV
+from .config import Config
+from .content import SECTION_META, label_of
+from .markup import html_to_text, md_to_html
+
+__all__ = ["FlowCV", "Config", "SECTION_META", "label_of", "md_to_html", "html_to_text"]
+__version__ = "0.2.0"

flowcvcli/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m flowcvcli …` (same as the `flowcv` console command)."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

flowcvcli/api.py

@@ -0,0 +1,29 @@
+"""FlowCV — the high-level client, composed from the Client core + feature mixins.
+
+LLM / library use:
+    from flowcvcli import FlowCV
+    fc = FlowCV()                      # auth + resume id from .env / env vars
+    fc = FlowCV(resume_id="...")       # target a specific resume
+    fc.add_entry("work", sets={"jobTitle": "Engineer", "employer": "Acme",
+                               "startDateNew": "01/2022", "endDateNew": "Present"},
+                 md="- Did a measurable thing.")
+    fc.set_personal_field("fullName", "Jane Doe")
+    fc.set_link("orcid", "ORCID", "https://orcid.org/0000-0000-0000-0000")
+    fc.set("font.fontFamily", "Source Sans Pro")     # a customization delta
+    fc.save_pdf("resume.pdf")                          # render + view
+"""
+from .client import Client
+from .content import ContentMixin
+from .customization import CustomizationMixin
+from .personal import PersonalMixin
+from .photo import PhotoMixin
+from .resume import ResumeMixin
+
+
+class FlowCV(Client, ResumeMixin, ContentMixin, PersonalMixin,
+             CustomizationMixin, PhotoMixin):
+    """One object that controls a FlowCV resume end to end."""
+
+    # convenience: toggle the header photo/avatar on or off (a customization delta)
+    def set_avatar_visible(self, visible):
+        return self.set("header.photo.show", bool(visible))

flowcvcli/cli.py

@@ -0,0 +1,335 @@
+"""Command-line interface over the FlowCV client.
+
+Run `python3 flowcv.py --help`. Auth comes from .env / env vars
+(FLOWCV_COOKIE, or FLOWCV_EMAIL+FLOWCV_PASSWORD). The resume id is optional:
+with a single resume the tool auto-selects it; with several, set FLOWCV_RESUME_ID
+or pass `--resume-id <id>` (any command accepts it).
+"""
+import argparse
+import json
+import os
+import sys
+
+from .api import FlowCV
+from .client import login as do_login, _write_session, _jar_header
+from .content import SECTION_META, label_of
+from .markup import html_to_text, md_to_html
+
+ALIASES = {"title": "jobTitle", "company": "employer", "start": "startDateNew",
+           "end": "endDateNew", "link": "employerLink"}
+TEXT_FIELDS = ("description", "infoHtml", "text")
+
+
+def _read(file=None, text=None):
+    if file:
+        with open(file) as f:
+            return f.read().strip()
+    return text
+
+
+def _coerce(s):
+    """Parse a CLI value as JSON (true/false/number/quoted), else keep as string."""
+    try:
+        return json.loads(s)
+    except (ValueError, TypeError):
+        return s
+
+
+def _result(env, label):
+    ok = env.get("success") if isinstance(env, dict) else env
+    print(f"{label} -> success={ok}")
+    if isinstance(env, dict) and not ok:
+        print("  !", json.dumps(env)[:200])
+
+
+def _fc(a):
+    return FlowCV(resume_id=getattr(a, "resume_id_override", None))
+
+
+# ------------------------------------------------------------------ commands
+def cmd_login(a):
+    fc = _fc(a)
+    if not (fc.cfg.email and fc.cfg.password):
+        sys.exit("Set FLOWCV_EMAIL and FLOWCV_PASSWORD in .env to use `login`.")
+    _write_session(_jar_header(do_login(fc.cfg.email, fc.cfg.password)))
+    print("login ok -> session cached to .flowcv_session")
+
+
+def cmd_resumes(a):
+    for r in _fc(a).list_resumes():
+        live = "live" if r.get("webResumeLive") else "private"
+        print(f"  {r.get('id','(no id)')}  {(r.get('title') or '(untitled)'):20}  web:{r.get('webToken','-')} [{live}]")
+
+
+def cmd_new(a):
+    new_id = _fc(a).create_resume(a.title)
+    print(f"created new resume -> {new_id}")
+
+
+def cmd_duplicate(a):
+    new_id = _fc(a).duplicate_resume(a.title)
+    print(f"duplicated -> {new_id}")
+
+
+def cmd_rename(a):
+    _result(_fc(a).rename_resume(a.title), f"rename resume -> {a.title!r}")
+
+
+def cmd_delete_resume(a):
+    fc = _fc(a)
+    rid = fc.resume_id
+    if not a.yes:
+        sys.exit(f"refusing to delete resume {rid} without --yes (this is permanent).")
+    _result(fc.delete_resume(rid), f"delete resume {rid[:8]}")
+
+
+def cmd_show(a):
+    resume = _fc(a).get_resume()
+    for sec, obj in (resume.get("content") or {}).items():
+        if a.section and sec != a.section:
+            continue
+        print(f"[{sec}] '{obj.get('displayName')}' ({len(obj.get('entries') or [])} entries)")
+        for e in obj.get("entries") or []:
+            d = f"  {e.get('startDateNew','')}–{e.get('endDateNew','')}" if e.get("startDateNew") or e.get("endDateNew") else ""
+            print(f"   {e.get('id','(no id)')}  {label_of(e)}{d}")
+
+
+def cmd_dump(a):
+    fc = _fc(a)
+    e = fc.find_entry(fc.get_resume(), a.section, a.entry)
+    for k, v in e.items():
+        if k in TEXT_FIELDS:
+            print(f"  {k} (text): {html_to_text(v)}")
+            print(f"  {k} (html): {v}")
+        else:
+            print(f"  {k}: {v!r}")
+
+
+def cmd_add(a):
+    sets = {}
+    for kv in a.set or []:
+        if "=" not in kv:
+            sys.exit(f"--set expects key=value, got {kv!r}")
+        k, _, v = kv.partition("=")
+        sets[ALIASES.get(k, k)] = v
+    new_id = _fc(a).add_entry(a.section, sets=sets, md=_read(a.file, a.text))
+    print(f"added {a.section} entry -> {new_id}")
+
+
+def cmd_rm(a):
+    _result(_fc(a).delete_entry(a.section, a.entry), f"rm {a.section}/{a.entry[:8]}")
+
+
+def cmd_reorder(a):
+    _result(_fc(a).reorder_entries(a.section, a.ids), f"reorder {a.section} ({len(a.ids)} entries)")
+
+
+def cmd_hide(a):
+    _result(_fc(a).hide_entry(a.section, a.entry, hidden=True), f"hide {a.section}/{a.entry[:8]}")
+
+
+def cmd_show_entry(a):
+    _result(_fc(a).hide_entry(a.section, a.entry, hidden=False), f"show {a.section}/{a.entry[:8]}")
+
+
+def cmd_rename_section(a):
+    _result(_fc(a).rename_section(a.section, a.name), f"rename-section {a.section}")
+
+
+def cmd_section_icon(a):
+    _result(_fc(a).set_section_icon(a.section, a.icon), f"section-icon {a.section}={a.icon}")
+
+
+def cmd_rm_section(a):
+    fc = _fc(a)
+    if not a.yes:
+        sys.exit(f"refusing to delete section {a.section!r} and all its entries without --yes.")
+    _result(fc.delete_section(a.section), f"rm-section {a.section}")
+
+
+def cmd_reorder_sections(a):
+    _result(_fc(a).reorder_sections(a.ids, layout=a.layout), f"reorder-sections ({a.layout})")
+
+
+def cmd_field(a):
+    _result(_fc(a).set_field(a.section, a.entry, a.field, _read(a.file, a.text)),
+            f"{a.section}/{a.entry[:8]}.{a.field}")
+
+
+def cmd_desc(a):
+    _result(_fc(a).set_description(a.section, a.entry, _read(a.file, a.text), field=a.field),
+            f"{a.section}/{a.entry[:8]}.{a.field}")
+
+
+def cmd_pd(a):
+    _result(_fc(a).set_personal_field(a.field, _read(a.file, a.text)), f"personalDetails.{a.field}")
+
+
+def cmd_links(a):
+    for k, display, link, shown in _fc(a).list_links():
+        print(f"  {k}: {display} -> {link} [{'shown' if shown else 'hidden'}]")
+
+
+def cmd_link(a):
+    _result(_fc(a).set_link(a.key, a.display, a.url), f"link {a.key}")
+
+
+def cmd_unlink(a):
+    _result(_fc(a).remove_link(a.key), f"unlink {a.key}")
+
+
+def cmd_customize(a):
+    _result(_fc(a).set(a.path, _coerce(a.value)), f"customize {a.path}={a.value}")
+
+
+def cmd_avatar(a):
+    fc = _fc(a)
+    if a.action in ("on", "off"):
+        _result(fc.set_avatar_visible(a.action == "on"), f"avatar {a.action}")
+    elif a.action == "set":
+        if not a.src:
+            sys.exit("avatar set needs a URL or file path: `avatar set <url|file>`")
+        _result(fc.set_photo(a.src), f"avatar set {a.src[:40]}")
+    elif a.action == "remove":
+        _result(fc.remove_photo(), "avatar remove")
+
+
+def _tname(t):
+    return t.get("title") or t.get("metaTitle") or t.get("slug") or "(unnamed)"
+
+
+def cmd_templates(a):
+    free = paid = 0
+    for t in _fc(a).list_templates():
+        if not isinstance(t, dict):
+            continue
+        premium = bool(t.get("isPremium"))
+        paid += premium; free += not premium
+        print(f"  {t.get('id') or t.get('templateId')}  [{'PAID' if premium else 'free'}]  {_tname(t)}")
+    print(f"\n{free} free, {paid} paid (PAID templates need a FlowCV subscription to apply).")
+
+
+def cmd_apply_template(a):
+    # apply_template refuses a paid template unless --force (it would corrupt a free resume)
+    _result(_fc(a).apply_template(a.template_id, force=a.force), f"apply-template {a.template_id[:8]}")
+
+
+def cmd_download(a):
+    fc = _fc(a)
+    if a.token:                                  # public download of any shared resume
+        data = fc.download_public(a.token)
+        out = a.output or f"{a.token}.pdf"
+        with open(out, "wb") as f:
+            f.write(data)
+        print(f"saved {out} ({len(data)} bytes)")
+    else:
+        path = fc.save_pdf(a.output or "resume.pdf")
+        print(f"saved {path} ({os.path.getsize(path)} bytes)")
+
+
+def cmd_publish(a):
+    fc = _fc(a)
+    _result(fc.publish(), "publish")
+    print(f"  {fc.share_url()}")
+
+
+def cmd_unpublish(a):
+    _result(_fc(a).unpublish(), "unpublish")
+
+
+def cmd_share(a):
+    st = _fc(a).web_status()
+    print(f"web resume: {'LIVE' if st['live'] else 'disabled'}\nshare url : {st['url'] or '(none)'}")
+
+
+def cmd_md2html(a):
+    print(md_to_html(_read(a.file, a.text)))
+
+
+# -------------------------------------------------------------------- parser
+def build_parser():
+    # --resume-id on a shared parent so it works BEFORE or AFTER the subcommand
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--resume-id", dest="resume_id_override", help="target a specific resume")
+    p = argparse.ArgumentParser(prog="flowcv", description=__doc__, parents=[common],
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add(name, **kw):
+        return sub.add_parser(name, parents=[common], **kw)
+
+    add("login").set_defaults(fn=cmd_login)
+    add("resumes").set_defaults(fn=cmd_resumes)
+
+    s = add("new"); s.add_argument("title"); s.set_defaults(fn=cmd_new)
+    s = add("duplicate"); s.add_argument("title", nargs="?"); s.set_defaults(fn=cmd_duplicate)
+    s = add("rename"); s.add_argument("title"); s.set_defaults(fn=cmd_rename)
+    s = add("delete-resume"); s.add_argument("--yes", action="store_true", help="confirm permanent deletion")
+    s.set_defaults(fn=cmd_delete_resume)
+
+    s = add("show"); s.add_argument("section", nargs="?"); s.set_defaults(fn=cmd_show)
+    s = add("dump"); s.add_argument("section"); s.add_argument("entry"); s.set_defaults(fn=cmd_dump)
+
+    s = add("add"); s.add_argument("section")
+    s.add_argument("--set", action="append", help="field=value (aliases: title,company,start,end,link)")
+    g = s.add_mutually_exclusive_group(); g.add_argument("--file"); g.add_argument("--text")
+    s.set_defaults(fn=cmd_add)
+
+    s = add("rm"); s.add_argument("section"); s.add_argument("entry"); s.set_defaults(fn=cmd_rm)
+
+    s = add("reorder"); s.add_argument("section")
+    s.add_argument("ids", nargs="+", help="entry ids in the desired order (all of the section's ids)")
+    s.set_defaults(fn=cmd_reorder)
+    s = add("hide"); s.add_argument("section"); s.add_argument("entry"); s.set_defaults(fn=cmd_hide)
+    s = add("show-entry"); s.add_argument("section"); s.add_argument("entry"); s.set_defaults(fn=cmd_show_entry)
+    s = add("rename-section"); s.add_argument("section"); s.add_argument("name"); s.set_defaults(fn=cmd_rename_section)
+    s = add("section-icon"); s.add_argument("section"); s.add_argument("icon", help="icon key, e.g. briefcase")
+    s.set_defaults(fn=cmd_section_icon)
+    s = add("rm-section"); s.add_argument("section")
+    s.add_argument("--yes", action="store_true", help="confirm deleting the section + its entries")
+    s.set_defaults(fn=cmd_rm_section)
+    s = add("reorder-sections"); s.add_argument("ids", nargs="+", help="section ids in the desired order")
+    s.add_argument("--layout", default="one", help="column layout to reorder (one|two|mix; default one)")
+    s.set_defaults(fn=cmd_reorder_sections)
+
+    s = add("field"); s.add_argument("section"); s.add_argument("entry"); s.add_argument("field")
+    g = s.add_mutually_exclusive_group(required=True); g.add_argument("--text"); g.add_argument("--file")
+    s.set_defaults(fn=cmd_field)
+
+    s = add("desc"); s.add_argument("section"); s.add_argument("entry")
+    s.add_argument("--field", default="description")
+    g = s.add_mutually_exclusive_group(required=True); g.add_argument("--file"); g.add_argument("--text")
+    s.set_defaults(fn=cmd_desc)
+
+    s = add("pd"); s.add_argument("field")
+    g = s.add_mutually_exclusive_group(required=True); g.add_argument("--text"); g.add_argument("--file")
+    s.set_defaults(fn=cmd_pd)
+
+    add("links").set_defaults(fn=cmd_links)
+    s = add("link"); s.add_argument("key"); s.add_argument("display"); s.add_argument("url"); s.set_defaults(fn=cmd_link)
+    s = add("unlink"); s.add_argument("key"); s.set_defaults(fn=cmd_unlink)
+
+    s = add("customize"); s.add_argument("path"); s.add_argument("value"); s.set_defaults(fn=cmd_customize)
+    s = add("avatar"); s.add_argument("action", choices=["on", "off", "set", "remove"])
+    s.add_argument("src", nargs="?", help="URL or file path (for `avatar set`)"); s.set_defaults(fn=cmd_avatar)
+    add("templates").set_defaults(fn=cmd_templates)
+    s = add("apply-template"); s.add_argument("template_id")
+    s.add_argument("--force", action="store_true", help="apply even a paid template (needs a subscription)")
+    s.set_defaults(fn=cmd_apply_template)
+
+    s = add("download"); s.add_argument("-o", "--output")
+    s.add_argument("--token", help="download a public resume by its share token (no auth)")
+    s.set_defaults(fn=cmd_download)
+    add("publish").set_defaults(fn=cmd_publish)
+    add("unpublish").set_defaults(fn=cmd_unpublish)
+    add("share").set_defaults(fn=cmd_share)
+
+    s = add("md2html")
+    g = s.add_mutually_exclusive_group(required=True); g.add_argument("--file"); g.add_argument("--text")
+    s.set_defaults(fn=cmd_md2html)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    args.fn(args)

flowcvcli/client.py

@@ -0,0 +1,300 @@
+"""Core HTTP client: auth, session cookie jar, JSON envelope, re-login retry.
+
+Feature mixins build on this interface:
+  self.cfg                      -> Config
+  self.resume_id                -> str (raises if unset)
+  self.request(path, method="GET", body=None, query=None) -> dict envelope
+  self.request_raw(path, query=None) -> (status:int, bytes)
+  self.get_resume()             -> dict (data.resume), raises on failure
+  self.now_iso()                -> ISO-8601 millisecond UTC timestamp string
+
+`path` is relative to https://app.flowcv.com/api (e.g. "resumes/save_entry",
+"auth/login"), or an absolute http(s) URL (e.g. the /pubcache template catalog).
+
+Session handling: every request goes through a single `http.cookiejar.CookieJar`
+behind an opener, so the client (a) sends *all* cookies the login set — not just
+`flowcvsidapp` — and (b) automatically captures any `Set-Cookie` the server
+returns mid-session (rotation). The full cookie set is persisted to
+`.flowcv_session` (0o600). FlowCV rate-limits login (~100/day) and returns HTTP
+429 when hammered; we surface that clearly rather than retrying into the wall.
+"""
+import datetime
+import http.cookiejar
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+from .config import Config, SESSION_FILE
+
+API = "https://app.flowcv.com/api"
+ORIGIN = "https://app.flowcv.com"
+COOKIE_DOMAIN = "app.flowcv.com"
+UA = ("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) "
+      "Chrome/149.0.0.0 Safari/537.36")
+
+
+def now_iso():
+    n = datetime.datetime.now(datetime.timezone.utc)
+    return n.strftime("%Y-%m-%dT%H:%M:%S.") + f"{n.microsecond // 1000:03d}Z"
+
+
+def _multipart(fields):
+    boundary = "----flowcvcli" + uuid.uuid4().hex
+    out = []
+    for k, v in fields.items():
+        out += [f"--{boundary}", f'Content-Disposition: form-data; name="{k}"', "", v]
+    out += [f"--{boundary}--", ""]
+    return boundary, "\r\n".join(out).encode()
+
+
+def _make_cookie(name, value):
+    """Build a session cookie scoped to the FlowCV app domain."""
+    return http.cookiejar.Cookie(
+        version=0, name=name, value=value, port=None, port_specified=False,
+        domain=COOKIE_DOMAIN, domain_specified=True, domain_initial_dot=False,
+        path="/", path_specified=True, secure=True, expires=None, discard=False,
+        comment=None, comment_url=None, rest={})
+
+
+def _seed_jar(jar, cookie_str):
+    """Load cookies from a 'name=value; name2=value2' header string into `jar`."""
+    for part in cookie_str.split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        name, _, value = part.partition("=")   # split on first '=' (values may contain '=')
+        name, value = name.strip(), value.strip()
+        if name:
+            jar.set_cookie(_make_cookie(name, value))
+
+
+def _jar_header(jar):
+    """Render a cookie jar as a 'name=value; …' Cookie header string."""
+    return "; ".join(f"{c.name}={c.value}" for c in jar)
+
+
+def _rate_limit_msg(method, path):
+    return (f"{method} {path} -> HTTP 429 (rate limited by FlowCV). Too many "
+            "requests in a short window — wait a while before retrying, and reuse "
+            "the cached session (.flowcv_session / FLOWCV_COOKIE) instead of "
+            "logging in repeatedly (login is capped at ~100/day).")
+
+
+def login(email, password, jar=None):
+    """POST /auth/login (multipart email+password) into a cookie jar.
+
+    Seeds an anonymous session (init_user) then logs in on the *same* jar, so the
+    jar ends up holding the full authenticated cookie set. Returns the jar
+    (creating a fresh one if not supplied). Raises SystemExit with a clear message
+    on a 429 rate-limit or a failed login.
+    """
+    if jar is None:
+        jar = http.cookiejar.CookieJar()
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(jar))
+    base = {"user-agent": UA, "origin": ORIGIN, "accept": "application/json, text/plain, */*"}
+
+    # Seed an anonymous session like the web app does — but login also works
+    # standalone (the browser's curl skips this), so a throttled/failed init_user
+    # must NOT abort a login that would otherwise succeed. Best-effort only.
+    try:
+        opener.open(urllib.request.Request(f"{API}/auth/init_user", headers=base), timeout=30).read()
+    except urllib.error.HTTPError:
+        pass
+    except urllib.error.URLError as e:
+        raise SystemExit(f"login (init_user) -> network error: {e.reason}")
+
+    boundary, body = _multipart({"email": email, "password": password,
+                                 "resumeData": "undefined", "letterData": "undefined",
+                                 "resumeImg": "", "letterImg": ""})
+    h = dict(base, **{"content-type": f"multipart/form-data; boundary={boundary}"})
+    try:
+        resp = opener.open(
+            urllib.request.Request(f"{API}/auth/login", data=body, headers=h, method="POST"), timeout=30)
+    except urllib.error.HTTPError as e:
+        if e.code == 429:
+            raise SystemExit(_rate_limit_msg("POST", "auth/login"))
+        raise SystemExit(f"login failed: HTTP {e.code} {e.read()[:200]!r}")
+    except urllib.error.URLError as e:
+        raise SystemExit(f"login -> network error: {e.reason}")
+    data = json.loads(resp.read().decode())
+    if not data.get("success"):
+        # whitelist error/code only — the raw envelope can echo the account email
+        raise SystemExit(f"login failed (code {data.get('code')}): {data.get('error') or 'check email/password'}")
+    if not any(c.name == "flowcvsidapp" for c in jar):
+        raise SystemExit("login succeeded but no session cookie was set")
+    return jar
+
+
+def _write_session(cookie):
+    """Persist the session cookie header with owner-only perms (0o600) — it's a credential."""
+    parent = os.path.dirname(SESSION_FILE)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    fd = os.open(SESSION_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(cookie)
+
+
+class Client:
+    def __init__(self, config=None, resume_id=None):
+        self.cfg = config or Config.load()
+        if resume_id:
+            self.cfg.resume_id = resume_id
+        self._jar = http.cookiejar.CookieJar()
+        self._opener = urllib.request.build_opener(
+            urllib.request.HTTPCookieProcessor(self._jar))
+        self._authed = False      # has the jar been seeded yet?
+        self._persisted = None    # last cookie header written to .flowcv_session
+
+    # ---- auth -------------------------------------------------------------
+    def _ensure_auth(self):
+        """Seed the cookie jar once, in priority order: FLOWCV_COOKIE (env) ->
+        cached .flowcv_session -> a fresh login(). Idempotent."""
+        if self._authed:
+            return
+        if self.cfg.cookie:
+            _seed_jar(self._jar, self.cfg.cookie)
+            self._authed = True
+            return
+        if os.path.exists(SESSION_FILE):
+            with open(SESSION_FILE) as f:
+                cached = f.read().strip()
+            if cached:
+                _seed_jar(self._jar, cached)
+                self._persisted = cached
+                self._authed = True
+                return
+        if self.cfg.email and self.cfg.password:
+            login(self.cfg.email, self.cfg.password, self._jar)
+            self._persist()
+            self._authed = True
+            return
+        raise SystemExit("No auth. Set FLOWCV_COOKIE, or FLOWCV_EMAIL + "
+                         "FLOWCV_PASSWORD, in .env.")
+
+    def cookie(self):
+        """Current Cookie header (all session cookies). For multipart uploads that
+        build their own request instead of going through `_send`."""
+        self._ensure_auth()
+        return _jar_header(self._jar)
+
+    def _persist(self):
+        header = _jar_header(self._jar)
+        _write_session(header)
+        self._persisted = header
+
+    def _maybe_persist(self):
+        """Re-persist if the server rotated the session (Set-Cookie changed the
+        jar). Never shadow an authoritative env cookie with a session file."""
+        if self.cfg.cookie:
+            return
+        header = _jar_header(self._jar)
+        if header and header != self._persisted:
+            _write_session(header)
+            self._persisted = header
+
+    def relogin(self):
+        """Discard the current session and log in fresh (only if we have creds).
+
+        Clears the jar first so a stale/duplicate cookie can't shadow the new
+        session — "a fresh login() session" the way the web app starts one.
+        """
+        if not (self.cfg.email and self.cfg.password):
+            return False
+        try:
+            os.remove(SESSION_FILE)
+        except OSError:
+            pass
+        self._jar.clear()
+        login(self.cfg.email, self.cfg.password, self._jar)
+        self._persist()
+        self._authed = True
+        return True
+
+    @property
+    def resume_id(self):
+        """The target resume id. If none was configured, auto-use the account's
+        only resume; if there are several, require an explicit choice."""
+        if self.cfg.resume_id:
+            return self.cfg.resume_id
+        env = self.request("resumes/all")
+        resumes = (env.get("data") or {}).get("resumes") if env.get("success") else None
+        if resumes is None:
+            raise SystemExit("Could not list resumes to auto-select one — set "
+                             "FLOWCV_RESUME_ID or pass --resume-id.")
+        if not resumes:
+            raise SystemExit("This account has no resumes yet.")
+        if len(resumes) == 1:
+            self.cfg.resume_id = resumes[0].get("id")   # cache for the rest of the run
+            return self.cfg.resume_id
+        listing = "\n".join(f"  {r.get('id')}  {r.get('title') or '(untitled)'}" for r in resumes)
+        raise SystemExit("You have multiple resumes — choose one with --resume-id <id> "
+                         "or FLOWCV_RESUME_ID:\n" + listing)
+
+    def now_iso(self):
+        return now_iso()
+
+    # ---- http -------------------------------------------------------------
+    def _url(self, path):
+        return path if path.startswith("http") else f"{API}/{path}"
+
+    def _send(self, path, method, body, query, timeout):
+        self._ensure_auth()                       # jar carries the cookies; opener attaches them
+        url = self._url(path)
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {"accept": "application/json, text/plain, */*", "user-agent": UA,
+                   "origin": ORIGIN}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["content-type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with self._opener.open(req, timeout=timeout) as r:
+                return r.status, r.read()
+        except urllib.error.HTTPError as e:
+            return e.code, e.read()
+        except urllib.error.URLError as e:   # DNS/conn/TLS/timeout
+            raise SystemExit(f"{method} {url} -> network error: {e.reason}")
+
+    def request(self, path, method="GET", body=None, query=None, timeout=30):
+        """Return the parsed JSON envelope dict. Retries once after re-login on 401/403."""
+        status, raw = self._send(path, method, body, query, timeout)
+        if status in (401, 403) and self.relogin():
+            status, raw = self._send(path, method, body, query, timeout)
+        if status == 429:
+            raise SystemExit(_rate_limit_msg(method, path))
+        self._maybe_persist()
+        try:
+            return json.loads(raw.decode())
+        except ValueError:
+            raise SystemExit(f"{method} {path} -> HTTP {status}: {raw[:200]!r}")
+
+    def request_raw(self, path, query=None, timeout=120):
+        """Return (status, bytes). For binary endpoints (PDF download)."""
+        status, raw = self._send(path, "GET", None, query, timeout)
+        if status in (401, 403) and self.relogin():
+            status, raw = self._send(path, "GET", None, query, timeout)
+        if status == 429:
+            raise SystemExit(_rate_limit_msg("GET", path))
+        self._maybe_persist()
+        return status, raw
+
+    # ---- resume fetch -----------------------------------------------------
+    def get_resume(self):
+        """Return the full resume object (data.resume). Raises on failure.
+
+        A freshly minted session can return `400 reloadClient:true` on its first
+        heavy read and then succeed; retry once on that signal before giving up.
+        """
+        env = self.request(f"resumes/{self.resume_id}")
+        if not env.get("success") and env.get("reloadClient"):
+            env = self.request(f"resumes/{self.resume_id}")   # session-warmup retry
+        if not env.get("success"):
+            raise SystemExit(f"get resume failed (code {env.get('code')}): {env.get('error') or ''} "
+                             "(session expired? refresh FLOWCV_COOKIE or re-login)")
+        return env["data"]["resume"]