flowcvcli 0.2.0__py3-none-any.whl

flowcvcli/config.py

@@ -0,0 +1,87 @@
+"""Configuration: resolve resume id + auth from a dotenv file and env vars.
+
+Dotenv search order (first match wins; later files fill in missing keys):
+  1. ``$FLOWCV_ENV_FILE``  — an explicit path
+  2. ``./.env``           — in the current working directory (where you run the tool)
+  3. ``<config home>/.env`` — e.g. ``~/.config/flowcvcli/.env``
+
+Real environment variables always override the dotenv file. The cached session
+cookie (a credential) is written to ``<config home>/session`` with ``0600``
+permissions, overridable via ``$FLOWCV_SESSION_FILE``. Paths are resolved from
+the user's environment, never from the install location, so the tool behaves the
+same whether it's run from source or ``pip install``-ed.
+"""
+import os
+
+APP = "flowcvcli"
+
+
+def _config_home():
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return os.path.join(base, APP)
+
+
+# Where the cached session cookie lives (override with $FLOWCV_SESSION_FILE).
+SESSION_FILE = os.environ.get("FLOWCV_SESSION_FILE") or os.path.join(_config_home(), "session")
+
+
+def _dotenv_files():
+    paths = []
+    if os.environ.get("FLOWCV_ENV_FILE"):
+        paths.append(os.environ["FLOWCV_ENV_FILE"])
+    paths.append(os.path.join(os.getcwd(), ".env"))
+    paths.append(os.path.join(_config_home(), ".env"))
+    return paths
+
+
+def _load_dotenv():
+    fv = {}
+    for path in _dotenv_files():
+        if not os.path.exists(path):
+            continue
+        with open(path) as f:
+            for line in f:
+                line = line.rstrip("\r\n").strip()    # tolerate CRLF (.env edited on Windows)
+                if line.startswith("export "):        # tolerate `export KEY=val`
+                    line = line[len("export "):]
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)          # split first '='; cookie may contain '='
+                    v = v.strip()
+                    if len(v) >= 2 and v[0] in "\"'" and v[-1] == v[0]:
+                        v = v[1:-1]                    # drop surrounding quotes
+                    fv.setdefault(k.strip(), v)        # first file wins per key
+    return fv
+
+
+def _pick(fv, *keys):
+    for k in keys:
+        v = os.environ.get(k) or fv.get(k)
+        if v:
+            return v
+    return None
+
+
+class Config:
+    """Resolved auth + target resume. resume_id may be None for resume-list ops."""
+
+    def __init__(self, resume_id=None, cookie=None, email=None, password=None):
+        self.resume_id = resume_id
+        self.cookie = cookie
+        self.email = email
+        self.password = password
+
+    @classmethod
+    def load(cls):
+        fv = _load_dotenv()
+        return cls(
+            resume_id=_pick(fv, "FLOWCV_RESUME_ID", "RESUME_ID"),
+            cookie=_pick(fv, "FLOWCV_COOKIE", "COOKIE"),
+            email=_pick(fv, "FLOWCV_EMAIL", "EMAIL"),
+            password=_pick(fv, "FLOWCV_PASSWORD", "PASSWORD"),
+        )
+
+    def require_resume_id(self):
+        if not self.resume_id:
+            raise SystemExit("No resume id. Set FLOWCV_RESUME_ID, pass resume_id=, "
+                             "or use --resume-id. Run `flowcv resumes` to list them.")
+        return self.resume_id

flowcvcli/content.py

@@ -0,0 +1,168 @@
+"""Content sections & entries: create / update / delete resume entries.
+
+A resume's `content` is a map of `sectionId -> {entries[], sectionType,
+displayName, iconKey}`. Entries are addressed by their `id`. Writes are
+read-modify-write where the API replaces the whole entry; create uses
+`save_entry` with extra section-meta so a missing section is created too.
+
+Mixes into Client; uses self.get_resume / self.request / self.resume_id.
+"""
+import uuid
+
+from .markup import md_to_html
+
+# sectionId -> (sectionType, displayName, iconKey) for creating sections.
+SECTION_META = {
+    "profile": ("profile", "Summary", "address-card"),
+    "work": ("work", "Professional Experience", "briefcase"),
+    "education": ("education", "Education", "graduation-cap"),
+    "skill": ("skill", "Skills", "head-side-brain"),
+    "publication": ("publication", "Publications", "newspaper"),
+    "organisation": ("organisation", "Organisations", "house-user"),
+    "custom1": ("custom", "Custom", "star"),
+}
+
+
+def label_of(entry):
+    """Best human label for an entry across section shapes."""
+    for k in ("jobTitle", "employer", "title", "degree", "skill",
+              "position", "publicationTitle", "organisationName"):
+        v = entry.get(k)
+        if v:
+            return v
+    return "(empty)"
+
+
+class ContentMixin:
+    # ---- lookups ----------------------------------------------------------
+    def find_section(self, resume, section):
+        """Return the section object from resume.content (or exit)."""
+        sec = (resume.get("content") or {}).get(section)
+        if sec is None:
+            raise SystemExit(f"section not found: {section}")
+        return sec
+
+    def find_entry(self, resume, section, entry_id):
+        """Return the entry dict with id == entry_id in section (or exit)."""
+        sec = self.find_section(resume, section)
+        for entry in sec.get("entries") or []:
+            if entry.get("id") == entry_id:
+                return entry
+        raise SystemExit(f"entry not found: {section}/{entry_id}")
+
+    # ---- low-level writes -------------------------------------------------
+    def save_entry(self, section, entry, extra=None):
+        """PATCH save_entry; updates the entry (or creates it with `extra`)."""
+        body = {"resumeId": self.resume_id, "sectionId": section, "entry": entry}
+        if extra:
+            body.update(extra)
+        return self.request("resumes/save_entry", method="PATCH", body=body)
+
+    def delete_entry(self, section, entry_id):
+        """DELETE delete_entry by (resumeId, sectionId, entryId)."""
+        query = {"resumeId": self.resume_id, "sectionId": section,
+                 "entryId": entry_id}
+        return self.request("resumes/delete_entry", method="DELETE", query=query)
+
+    # ---- high-level helpers ----------------------------------------------
+    def add_entry(self, section, sets=None, md=None):
+        """Create an entry (and the section if needed); return the new id.
+
+        `sets` are entry fields to populate; `md` becomes a `description`
+        HTML field. Creates the entry first (so a missing section is made),
+        then fills it with a follow-up update.
+        """
+        resume = self.get_resume()
+        existing = (resume.get("content") or {}).get(section)
+        if existing:
+            section_type = existing.get("sectionType")
+            display_name = existing.get("displayName")
+            icon_key = existing.get("iconKey")
+        elif section in SECTION_META:
+            section_type, display_name, icon_key = SECTION_META[section]
+        else:
+            raise SystemExit(f"unknown section (no meta): {section}")
+
+        new_id = str(uuid.uuid4())
+        # Create: minimal entry + section meta (also creates the section).
+        env = self.save_entry(section, {"id": new_id, "isHidden": False}, extra={
+            "sectionType": section_type,
+            "sectionDisplayName": display_name,
+            "sectionIconKey": icon_key,
+        })
+        if not env.get("success"):
+            raise SystemExit(f"could not create {section} entry: {env}")
+
+        now = self.now_iso()
+        entry = {"id": new_id, "isHidden": False, "showPlaceholder": False,
+                 "createdAt": now, "updatedAt": now}
+        entry.update(sets or {})
+        if md:
+            # rich text lives in a section-specific field (profile->text, skill->infoHtml)
+            field = {"profile": "text", "skill": "infoHtml"}.get(section, "description")
+            entry[field] = md_to_html(md)
+        env = self.save_entry(section, entry)
+        if not env.get("success"):
+            raise SystemExit(f"created {section} entry {new_id} but failed to populate it: {env}")
+        return new_id
+
+    def set_field(self, section, entry_id, field, value):
+        """Read-modify-write a single entry field; bump updatedAt if present."""
+        resume = self.get_resume()
+        entry = dict(self.find_entry(resume, section, entry_id))
+        entry[field] = value
+        if "updatedAt" in entry:
+            entry["updatedAt"] = self.now_iso()
+        return self.save_entry(section, entry)
+
+    def set_description(self, section, entry_id, md, field="description"):
+        """Set a rich-text field to md_to_html(md) on an entry."""
+        return self.set_field(section, entry_id, field, md_to_html(md))
+
+    def hide_entry(self, section, entry_id, hidden=True):
+        """Show/hide an entry (sets its `isHidden`). Hidden entries stay in the
+        resume but are omitted from the rendered output."""
+        return self.set_field(section, entry_id, "isHidden", bool(hidden))
+
+    # ---- section-level ops ------------------------------------------------
+    def reorder_entries(self, section, order):
+        """Set the order of entries in a section. `order` is the list of entry
+        ids in the desired order (must be a permutation of the section's ids).
+
+        PATCH save_entries_order with `disableAutoSort` so the manual order sticks
+        (FlowCV otherwise auto-sorts by date)."""
+        resume = self.get_resume()
+        have = [e.get("id") for e in self.find_section(resume, section).get("entries") or []]
+        order = list(order)
+        if set(order) != set(have):
+            raise SystemExit(f"reorder ids must be exactly the section's entries.\n"
+                             f"  given:   {order}\n  section: {have}")
+        return self.request("resumes/save_entries_order", method="PATCH",
+                            body={"resumeId": self.resume_id, "sectionId": section,
+                                  "newEntriesIdsOrder": order, "disableAutoSort": True})
+
+    def rename_section(self, section, display_name):
+        """PATCH save_section_name — change a section's heading text."""
+        return self.request("resumes/save_section_name", method="PATCH",
+                            body={"resumeId": self.resume_id, "sectionId": section,
+                                  "displayName": display_name})
+
+    def set_section_icon(self, section, icon_key):
+        """PATCH save_section_icon — change a section's icon (e.g. 'briefcase')."""
+        return self.request("resumes/save_section_icon", method="PATCH",
+                            body={"resumeId": self.resume_id, "sectionId": section,
+                                  "iconKey": icon_key})
+
+    def delete_section(self, section):
+        """DELETE delete_section — remove a whole section and all its entries."""
+        return self.request("resumes/delete_section", method="DELETE",
+                            query={"resumeId": self.resume_id, "sectionId": section})
+
+    def reorder_sections(self, section_ids, layout="one"):
+        """Set the section order for a column layout via the customization field
+        `sectionOrder.<layout>.sectionsSorted`. `layout` is 'one' (single column;
+        default) — two-column layouts store left/right lists separately.
+
+        Sections are ordered in `resume.customization.sectionOrder`, not in
+        `content`, so this is a `save_customization` delta."""
+        return self.set(f"sectionOrder.{layout}.sectionsSorted", list(section_ids))

flowcvcli/customization.py

@@ -0,0 +1,85 @@
+"""Customization: styling deltas & template application.
+
+FlowCV stores all design in `resume.customization` (font, colors, layout,
+spacing, headings, page format, …). Updates go through a **delta API**: each
+change is a dot-`path` into that object plus a new `value`, sent to
+`save_customization`. Templates are full customization presets pulled from a
+public catalog and applied via `apply_template`.
+"""
+
+TEMPLATE_CATALOG = "https://app.flowcv.com/pubcache/published-resume-templates"
+
+
+class CustomizationMixin:
+    """Styling & template operations (mixed into Client)."""
+
+    def customize(self, updates):
+        """Apply a batch of customization deltas. Return the envelope dict.
+
+        `updates` is a list of (path, value) tuples or {"path", "value"} dicts;
+        `path` is a dot-path into `resume.customization`
+        (e.g. "font.fontFamily", "colors.basic.single").
+        """
+        deltas = []
+        for u in updates:
+            if isinstance(u, dict):
+                deltas.append({"path": u["path"], "value": u["value"]})
+            else:
+                path, value = u
+                deltas.append({"path": path, "value": value})
+        body = {"resumeId": self.resume_id, "customizationUpdates": deltas}
+        return self.request("resumes/save_customization", method="PATCH", body=body)
+
+    def set(self, path, value):
+        """Apply a single customization delta. Return the envelope dict."""
+        return self.customize([(path, value)])
+
+    def get_customization(self):
+        """Return the current `resume.customization` object."""
+        return self.get_resume()["customization"]
+
+    def list_templates(self):
+        """Return the published template catalog as a list of template dicts.
+
+        Each template has at least an id/name and a `customization`. Defensive
+        about the response shape: the catalog may come back as a bare JSON list
+        or wrapped in a standard `{success, data}` envelope.
+        """
+        resp = self.request(TEMPLATE_CATALOG)
+        if isinstance(resp, list):
+            return resp
+        if isinstance(resp, dict):
+            data = resp.get("data", resp)
+            if isinstance(data, list):
+                return data
+            if isinstance(data, dict):
+                for key in ("templates", "items", "results"):
+                    if isinstance(data.get(key), list):
+                        return data[key]
+        return []
+
+    def apply_template(self, template_id, force=False):
+        """Apply a published template by id. Return the envelope dict.
+
+        Looks the template up in the catalog, then PATCHes `apply_template` with
+        its full `customization` and the resume's current `personalDetails`.
+        Raises SystemExit if no template matches, or if it is a paid (`isPremium`)
+        template and `force` is not set — a paid template requires a FlowCV
+        subscription (the apply request fails with 400 on a free account).
+        """
+        tpl = next((t for t in self.list_templates()
+                    if isinstance(t, dict) and (t.get("id") or t.get("templateId")) == template_id), None)
+        if tpl is None:
+            raise SystemExit(f"template not found: {template_id!r}")
+        if tpl.get("isPremium") and not force:
+            raise SystemExit(
+                f"'{tpl.get('title') or template_id}' is a PAID template — it requires a FlowCV "
+                "subscription (the apply fails with 400 on a free account). Use force=True "
+                "(CLI: --force) if your account is subscribed.")
+        body = {
+            "resumeId": self.resume_id,
+            "templateId": template_id,
+            "customization": tpl.get("customization"),
+            "personalDetails": self.get_resume()["personalDetails"],
+        }
+        return self.request("resumes/apply_template", method="PATCH", body=body)

flowcvcli/markup.py

@@ -0,0 +1,53 @@
+"""Markdown <-> FlowCV rich-text HTML.
+
+FlowCV stores rich text as justified <p> / <ul><li><p> HTML. `md_to_html`
+converts a small markdown dialect into that markup:
+
+  blank line            -> block separator
+  "## Heading"          -> bold justified paragraph (a subheader)
+  "**Whole line bold**" -> bold justified paragraph
+  "- item"              -> bullet (consecutive lines become one <ul>)
+  anything else         -> justified paragraph
+  inline **bold**       -> <strong>bold</strong> (inside paragraphs and bullets)
+"""
+import html
+import re
+
+J = ' style="text-align: justify"'
+
+
+def _esc(s):
+    """Escape text, then honor inline **bold**."""
+    return re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", html.escape(s, quote=False))
+
+
+def md_to_html(md):
+    parts, bullets = [], []
+
+    def flush():
+        if bullets:
+            lis = "".join(f"<li{J}><p{J}>{_esc(b)}</p></li>" for b in bullets)
+            parts.append(f"<ul>{lis}</ul>")
+            bullets.clear()
+
+    for raw in (md or "").splitlines():
+        line = raw.strip()
+        if not line:
+            flush()
+            continue
+        if line.startswith("- "):
+            bullets.append(line[2:].strip())
+            continue
+        flush()
+        if line.startswith("## "):
+            parts.append(f"<p{J}><strong>{html.escape(line[3:].strip(), quote=False)}</strong></p>")
+        elif len(line) > 4 and line.startswith("**") and line.endswith("**") and line.count("**") == 2:
+            parts.append(f"<p{J}><strong>{html.escape(line[2:-2].strip(), quote=False)}</strong></p>")
+        else:
+            parts.append(f"<p{J}>{_esc(line)}</p>")
+    flush()
+    return "".join(parts)
+
+
+def html_to_text(h):
+    return html.unescape(re.sub(r"\s+", " ", re.sub("<[^>]+>", " ", h or ""))).strip()

flowcvcli/personal.py

@@ -0,0 +1,66 @@
+"""Header personal details & links.
+
+`personalDetails` is a single object saved whole via PATCH
+`resumes/save_personal_details`. The API replaces the object wholesale, so every
+write follows the read-modify-write pattern: fetch the full object, change the
+target field, send it all back.
+
+Header links live in `personalDetails.social` as `{key: {display, link}}` and are
+shown in the order given by `personalDetails.detailsOrder`.
+"""
+import copy
+
+
+class PersonalMixin:
+    # ---- core read/write --------------------------------------------------
+    def _pd(self):
+        """Return a deepcopy of the resume's personalDetails object."""
+        return copy.deepcopy(self.get_resume()["personalDetails"])
+
+    def save_personal(self, pd):
+        """PATCH the full personalDetails object back. Return the envelope."""
+        return self.request("resumes/save_personal_details", method="PATCH",
+                            body={"resumeId": self.resume_id, "personalDetails": pd})
+
+    # ---- scalar fields ----------------------------------------------------
+    def set_personal_field(self, field, value):
+        """Set one scalar field on the full pd and save. Return the envelope."""
+        pd = self._pd()
+        pd[field] = value
+        return self.save_personal(pd)
+
+    # ---- header links -----------------------------------------------------
+    def set_link(self, key, display, url):
+        """Add/update a header link (pd.social[key]={display,link}).
+
+        Ensures `key` is present in pd.detailsOrder (appended if absent). Saves
+        and returns the envelope.
+        """
+        pd = self._pd()
+        social = copy.deepcopy(pd.get("social") or {})
+        social[key] = {"display": display, "link": url}
+        pd["social"] = social
+        order = pd.get("detailsOrder") or []
+        if key not in order:
+            order = order + [key]
+        pd["detailsOrder"] = order
+        return self.save_personal(pd)
+
+    def remove_link(self, key):
+        """Delete a header link and drop it from detailsOrder. SystemExit if absent."""
+        pd = self._pd()
+        social = pd.get("social") or {}
+        if key not in social:
+            raise SystemExit(f"No header link {key!r}.")
+        del social[key]
+        pd["social"] = social
+        pd["detailsOrder"] = [k for k in (pd.get("detailsOrder") or []) if k != key]
+        return self.save_personal(pd)
+
+    def list_links(self):
+        """Return [(key, display, link, shown_bool)] from pd.social/detailsOrder."""
+        pd = self.get_resume()["personalDetails"]
+        social = pd.get("social") or {}
+        order = pd.get("detailsOrder") or []
+        return [(k, v.get("display", ""), v.get("link", ""), k in order)
+                for k, v in social.items()]

flowcvcli/photo.py

@@ -0,0 +1,95 @@
+"""Header photo / avatar: upload from a URL or file, set, remove, toggle.
+
+Two-step flow:
+  1. POST resumes/upload_profile_pic (multipart: resumeId + `file`) -> {imageId}
+  2. save the imageId into personalDetails.photo (whole-image crop).
+Display is toggled via the customization delta `header.photo.show`.
+
+Depends on PersonalMixin (_pd / save_personal) and CustomizationMixin (set).
+"""
+import json
+import os
+import struct
+import urllib.error
+import urllib.request
+import uuid
+
+MAX_IMAGE_BYTES = 10 * 1024 * 1024
+
+from .client import API, ORIGIN, UA
+
+# whole-image crop (matches what FlowCV writes for an un-cropped photo)
+FULL_CROP = {"xPct": 0.0004995004995004271, "yPct": 0.0004995004995004271,
+             "widthPct": 0.9990009990009991, "heightPct": 0.9990009990009991}
+
+
+def image_size(data):
+    """Best-effort (width, height) from PNG/JPEG bytes; (0, 0) if unknown."""
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return struct.unpack(">II", data[16:24]) if len(data) >= 24 else (0, 0)
+    if data[:2] == b"\xff\xd8":  # JPEG: find a start-of-frame marker
+        i = 2
+        while i + 9 < len(data):
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+                h, w = struct.unpack(">HH", data[i + 5:i + 9])
+                return w, h
+            i += 2 + struct.unpack(">H", data[i + 2:i + 4])[0]
+    return 0, 0
+
+
+class PhotoMixin:
+    def upload_photo(self, data):
+        """Upload image bytes to upload_profile_pic; return the imageId string."""
+        self._ensure_auth()                       # opener attaches the session cookies
+        b = "----flowcvcli" + uuid.uuid4().hex
+        body = (
+            f"--{b}\r\nContent-Disposition: form-data; name=\"resumeId\"\r\n\r\n{self.resume_id}\r\n"
+            f"--{b}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"photo\"\r\n"
+            f"Content-Type: application/octet-stream\r\n\r\n"
+        ).encode() + data + f"\r\n--{b}--\r\n".encode()
+        req = urllib.request.Request(
+            f"{API}/resumes/upload_profile_pic", data=body, method="POST",
+            headers={"accept": "application/json", "user-agent": UA, "origin": ORIGIN,
+                     "content-type": f"multipart/form-data; boundary={b}"})
+        try:
+            with self._opener.open(req, timeout=60) as r:
+                env = json.loads(r.read().decode())
+        except urllib.error.HTTPError as e:
+            env = json.loads(e.read().decode())
+        if not env.get("success"):
+            raise SystemExit(f"photo upload failed: {json.dumps(env)[:200]}")
+        return env["data"]["imageId"]
+
+    def set_photo(self, src, shape="round"):
+        """Set the header photo from a local file path or an http(s) URL. Returns env."""
+        if os.path.exists(src):                       # a real file wins (e.g. http_avatar.png)
+            with open(src, "rb") as f:
+                data = f.read(MAX_IMAGE_BYTES + 1)
+        elif src.startswith(("http://", "https://")):
+            with urllib.request.urlopen(
+                    urllib.request.Request(src, headers={"user-agent": UA}), timeout=60) as r:
+                data = r.read(MAX_IMAGE_BYTES + 1)
+        else:
+            raise SystemExit(f"photo source not found (not a file or http(s) URL): {src!r}")
+        if len(data) > MAX_IMAGE_BYTES:
+            raise SystemExit("photo too large (> 10 MB)")
+        image_id = self.upload_photo(data)
+        w, h = image_size(data)
+        pd = self._pd()
+        pd["photo"] = dict(FULL_CROP, imageId=image_id, shape=shape,
+                           originalWidth=w, originalHeight=h)
+        env = self.save_personal(pd)
+        self.set("header.photo.show", True)   # make sure it displays
+        return env
+
+    def remove_photo(self):
+        """Clear the header photo and hide the photo slot."""
+        pd = self._pd()
+        pd["photo"] = {}
+        env = self.save_personal(pd)
+        self.set("header.photo.show", False)
+        return env