flowcvcli 0.2.0__tar.gz

flowcvcli-0.2.0/.env.example

@@ -0,0 +1,15 @@
+# Copy to `.env` (in the dir you run `flowcv` from, or ~/.config/flowcvcli/.env)
+# and fill in. Real environment variables override this file. Secrets are gitignored.
+
+# Auth — pick ONE:
+#  (a) the session cookie: DevTools > Application > Cookies > app.flowcv.com >
+#      copy the `flowcvsidapp` value (only this cookie is needed for auth):
+FLOWCV_COOKIE=flowcvsidapp=s%3A...
+#  (b) or credentials — the tool logs in and caches the session to
+#      ~/.config/flowcvcli/session (override with $FLOWCV_SESSION_FILE):
+# FLOWCV_EMAIL=you@example.com
+# FLOWCV_PASSWORD=...
+
+# RESUME_ID is OPTIONAL: with one resume the tool auto-selects it; set this (or
+# pass --resume-id) only if your account has several. Get ids via `flowcv resumes`.
+# FLOWCV_RESUME_ID=00000000-0000-0000-0000-000000000000

flowcvcli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dannyota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowcvcli-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include .env.example
+recursive-include docs *.md
+
+# never ship local/dev artifacts or anything with personal data
+exclude flowcv.py
+prune .playwright-mcp
+global-exclude *.pyc __pycache__ .env .flowcv_env .flowcv_session *.pdf *.html

flowcvcli-0.2.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: flowcvcli
+Version: 0.2.0
+Summary: Control a FlowCV resume from the command line or Python — content, design, templates, photo, publish and PDF export — via FlowCV's private JSON API. Zero dependencies.
+Author: dannyota
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dannyota/flowcvcli
+Project-URL: Repository, https://github.com/dannyota/flowcvcli
+Project-URL: Documentation, https://github.com/dannyota/flowcvcli/blob/main/docs/API.md
+Project-URL: Issues, https://github.com/dannyota/flowcvcli/issues
+Keywords: flowcv,resume,cv,cli,resume-builder,json-api,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flowcvcli
+
+[![PyPI](https://img.shields.io/pypi/v/flowcvcli.svg)](https://pypi.org/project/flowcvcli/)
+[![Python](https://img.shields.io/pypi/pyversions/flowcvcli.svg)](https://pypi.org/project/flowcvcli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Control a [FlowCV](https://flowcv.com) resume from the **command line** or from
+**Python** — content, header & links, **customization**, **templates**,
+**avatar**, reorder/hide, multi-resume management, publish, and **PDF export**.
+It drives FlowCV's private JSON API (the same calls the web app makes), so it
+works for any FlowCV resume with your own session. **Zero dependencies** (Python
+standard library only), so it's easy to drop into scripts and LLM agents.
+
+> Unofficial and not affiliated with FlowCV. It uses FlowCV's undocumented
+> internal API and may break if that changes; use it with your own account and at
+> your own risk (mind FlowCV's Terms of Service). See [`docs/API.md`](docs/API.md)
+> for the reverse-engineered API and [`docs/RENDERING.md`](docs/RENDERING.md) for
+> how the editor renders the live preview and persists edits.
+
+## Install
+
+```bash
+pip install flowcvcli          # installs the `flowcv` command
+```
+
+Or run from source without installing:
+
+```bash
+git clone https://github.com/dannyota/flowcvcli && cd flowcvcli
+python3 flowcv.py --help       # equivalent to the `flowcv` command
+```
+
+## Configure
+
+Put a `.env` in the directory you run `flowcv` from (or in
+`~/.config/flowcvcli/.env`). Real environment variables override it.
+
+```dotenv
+# Auth — pick ONE:
+FLOWCV_COOKIE=flowcvsidapp=s%3A...     # your session cookie, OR
+# FLOWCV_EMAIL=you@example.com         # log in with credentials instead
+# FLOWCV_PASSWORD=...                  #   (session cached to ~/.config/flowcvcli/session)
+
+# FLOWCV_RESUME_ID=...                 # optional; only if your account has several resumes
+```
+
+- **Cookie**: DevTools → Application → Cookies → `app.flowcv.com` → copy the
+  `flowcvsidapp` value. That single cookie is the auth.
+- **Credentials**: with `FLOWCV_EMAIL` + `FLOWCV_PASSWORD` the tool logs in and
+  caches the session (re-login is automatic when the cookie expires). The cache
+  is written `0600` to `~/.config/flowcvcli/session` (override with
+  `$FLOWCV_SESSION_FILE`).
+- **Resume id** is optional: with one resume it's auto-selected; with several,
+  set `FLOWCV_RESUME_ID` or pass `--resume-id <id>` (run `flowcv resumes` to list).
+
+## CLI
+
+```bash
+flowcv resumes                       # list resumes (id, title, share token)
+flowcv show [section]                # sections + entries (ids, labels, dates)
+flowcv dump <section> <id>           # one entry, fields + rich text
+
+# manage resumes (multi-resume / paid plans)
+flowcv new "My Second Resume"        # new resume (same details+style, no content) -> prints id
+flowcv duplicate ["Copy title"]      # full copy of the current resume
+flowcv rename "New Title"            # rename the current resume
+flowcv delete-resume --yes           # permanent (refuses without --yes)
+
+# content (markdown mini-format below); `add` creates the section if needed
+flowcv add work --set title="Engineer" --set company="Acme" \
+       --set start=01/2022 --set end=Present --text $'- Did a measurable thing.'
+flowcv desc work <id> --file role.md
+flowcv field work <id> employer --text "Acme Corp"
+flowcv rm work <id>
+
+# reorder / hide / sections
+flowcv reorder work <id3> <id1> <id2>     # set entry order (all of the section's ids)
+flowcv hide work <id> ; flowcv show-entry work <id>
+flowcv rename-section skill "Core Skills"
+flowcv section-icon skill head-side-brain
+flowcv rm-section custom1 --yes           # delete a section + its entries
+flowcv reorder-sections profile work skill education   # one-column order
+
+# header details & links (links are social entries: orcid, googlescholar, github…)
+flowcv pd jobTitle --text "Security Leader"
+flowcv link orcid ORCID https://orcid.org/0000-0000-0000-0000
+flowcv unlink orcid ; flowcv links
+
+# avatar
+flowcv avatar set https://example.com/me.png   # upload from URL or file
+flowcv avatar on | off | remove
+
+# styling (a delta into resume.customization) and templates
+flowcv customize font.fontFamily "Source Sans Pro"
+flowcv customize colors.basic.single '"#0e374e"'
+flowcv templates                     # lists each as [free] / [PAID] (paid needs a subscription)
+flowcv apply-template <templateId>   # warns first if the template is paid
+
+# render & share
+flowcv download -o resume.pdf        # the rendered PDF
+flowcv download --token <webToken> -o out.pdf   # any PUBLIC resume by its share token (no auth)
+flowcv share | publish | unpublish
+
+flowcv login                          # refresh the cached session
+flowcv md2html --file role.md         # preview HTML (offline)
+```
+
+Any command takes `--resume-id <id>` to target a specific resume. (From source,
+replace `flowcv` with `python3 flowcv.py`.)
+
+## Library (for scripts & LLM agents)
+
+```python
+from flowcvcli import FlowCV
+
+fc = FlowCV()                                   # or FlowCV(resume_id="...")
+fc.set_personal_field("fullName", "Jane Doe")
+fc.add_entry("work", sets={"jobTitle": "Engineer", "employer": "Acme",
+                           "startDateNew": "01/2022", "endDateNew": "Present"},
+             md="- Shipped a thing with **measurable** impact.")
+fc.set("font.fontFamily", "Source Sans Pro")    # a customization delta
+fc.set_photo("https://example.com/me.png")      # avatar from URL
+fc.apply_template("a3fb6c37-...")               # a design from list_templates()
+fc.save_pdf("resume.pdf")                        # render to PDF
+
+# structure & resume management
+fc.reorder_entries("work", ["id3", "id1", "id2"])   # set entry order
+fc.rename_section("skill", "Core Skills"); fc.delete_section("custom1")
+fc.hide_entry("work", "id", hidden=True)
+new_id = fc.create_resume("Second Resume")          # or fc.duplicate_resume()
+fc.rename_resume("New Title"); fc.delete_resume()    # delete is permanent
+```
+
+### Build → render → check → improve
+
+The PDF *is* the rendered output. An agent can write content, `save_pdf(...)`,
+**open the PDF to see the actual layout**, then adjust and re-render — a closed
+feedback loop for building a resume from raw info.
+
+## Markdown mini-format (`desc` / `add`)
+
+| You write | You get |
+|---|---|
+| blank line | block separator |
+| `## Heading` / `**Whole line bold**` | bold subheader |
+| `- item` | bullet (consecutive = one list) |
+| anything else | justified paragraph |
+| `**bold**` inline | `<strong>bold</strong>` |
+
+## How it works
+
+- **Read-modify-write**: edits fetch the resume, change one part, and send it
+  back — unrelated fields are never touched.
+- New entries append to the bottom of their section; use `reorder` to change order.
+- The on-screen preview is client-side HTML; the **PDF download is a separate
+  server render** of the same data (details in [`docs/RENDERING.md`](docs/RENDERING.md)).
+
+> **Scope:** this tool covers **resumes**. The same FlowCV account also has Cover
+> Letters, Job Tracker, Email Signatures and Personal Websites (separate APIs —
+> see `docs/API.md` "Other FlowCV products"); documented but not implemented here.
+
+## Project layout
+
+```
+flowcvcli/             # the package (import flowcvcli)
+  config.py            #   resolve resume id + auth from .env / env vars
+  client.py            #   HTTP, login, cookie-jar session, retry, get_resume
+  markup.py            #   markdown <-> FlowCV rich-text HTML
+  content.py           #   sections & entries (add/edit/reorder/hide/sections)
+  personal.py          #   header details & links
+  customization.py     #   styling deltas & templates
+  photo.py             #   avatar upload / toggle
+  resume.py            #   list, create/duplicate/rename/delete, download, publish
+  api.py               #   FlowCV = Client + all mixins
+  cli.py / __main__.py #   the `flowcv` command
+docs/API.md            # reverse-engineered API reference
+docs/RENDERING.md      # how the editor renders the preview & debounces saves
+flowcv.py              # source-tree entry point (python3 flowcv.py …)
+```
+
+## License
+
+[MIT](LICENSE) © dannyota

flowcvcli-0.2.0/README.md

@@ -0,0 +1,183 @@
+# flowcvcli
+
+[![PyPI](https://img.shields.io/pypi/v/flowcvcli.svg)](https://pypi.org/project/flowcvcli/)
+[![Python](https://img.shields.io/pypi/pyversions/flowcvcli.svg)](https://pypi.org/project/flowcvcli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Control a [FlowCV](https://flowcv.com) resume from the **command line** or from
+**Python** — content, header & links, **customization**, **templates**,
+**avatar**, reorder/hide, multi-resume management, publish, and **PDF export**.
+It drives FlowCV's private JSON API (the same calls the web app makes), so it
+works for any FlowCV resume with your own session. **Zero dependencies** (Python
+standard library only), so it's easy to drop into scripts and LLM agents.
+
+> Unofficial and not affiliated with FlowCV. It uses FlowCV's undocumented
+> internal API and may break if that changes; use it with your own account and at
+> your own risk (mind FlowCV's Terms of Service). See [`docs/API.md`](docs/API.md)
+> for the reverse-engineered API and [`docs/RENDERING.md`](docs/RENDERING.md) for
+> how the editor renders the live preview and persists edits.
+
+## Install
+
+```bash
+pip install flowcvcli          # installs the `flowcv` command
+```
+
+Or run from source without installing:
+
+```bash
+git clone https://github.com/dannyota/flowcvcli && cd flowcvcli
+python3 flowcv.py --help       # equivalent to the `flowcv` command
+```
+
+## Configure
+
+Put a `.env` in the directory you run `flowcv` from (or in
+`~/.config/flowcvcli/.env`). Real environment variables override it.
+
+```dotenv
+# Auth — pick ONE:
+FLOWCV_COOKIE=flowcvsidapp=s%3A...     # your session cookie, OR
+# FLOWCV_EMAIL=you@example.com         # log in with credentials instead
+# FLOWCV_PASSWORD=...                  #   (session cached to ~/.config/flowcvcli/session)
+
+# FLOWCV_RESUME_ID=...                 # optional; only if your account has several resumes
+```
+
+- **Cookie**: DevTools → Application → Cookies → `app.flowcv.com` → copy the
+  `flowcvsidapp` value. That single cookie is the auth.
+- **Credentials**: with `FLOWCV_EMAIL` + `FLOWCV_PASSWORD` the tool logs in and
+  caches the session (re-login is automatic when the cookie expires). The cache
+  is written `0600` to `~/.config/flowcvcli/session` (override with
+  `$FLOWCV_SESSION_FILE`).
+- **Resume id** is optional: with one resume it's auto-selected; with several,
+  set `FLOWCV_RESUME_ID` or pass `--resume-id <id>` (run `flowcv resumes` to list).
+
+## CLI
+
+```bash
+flowcv resumes                       # list resumes (id, title, share token)
+flowcv show [section]                # sections + entries (ids, labels, dates)
+flowcv dump <section> <id>           # one entry, fields + rich text
+
+# manage resumes (multi-resume / paid plans)
+flowcv new "My Second Resume"        # new resume (same details+style, no content) -> prints id
+flowcv duplicate ["Copy title"]      # full copy of the current resume
+flowcv rename "New Title"            # rename the current resume
+flowcv delete-resume --yes           # permanent (refuses without --yes)
+
+# content (markdown mini-format below); `add` creates the section if needed
+flowcv add work --set title="Engineer" --set company="Acme" \
+       --set start=01/2022 --set end=Present --text $'- Did a measurable thing.'
+flowcv desc work <id> --file role.md
+flowcv field work <id> employer --text "Acme Corp"
+flowcv rm work <id>
+
+# reorder / hide / sections
+flowcv reorder work <id3> <id1> <id2>     # set entry order (all of the section's ids)
+flowcv hide work <id> ; flowcv show-entry work <id>
+flowcv rename-section skill "Core Skills"
+flowcv section-icon skill head-side-brain
+flowcv rm-section custom1 --yes           # delete a section + its entries
+flowcv reorder-sections profile work skill education   # one-column order
+
+# header details & links (links are social entries: orcid, googlescholar, github…)
+flowcv pd jobTitle --text "Security Leader"
+flowcv link orcid ORCID https://orcid.org/0000-0000-0000-0000
+flowcv unlink orcid ; flowcv links
+
+# avatar
+flowcv avatar set https://example.com/me.png   # upload from URL or file
+flowcv avatar on | off | remove
+
+# styling (a delta into resume.customization) and templates
+flowcv customize font.fontFamily "Source Sans Pro"
+flowcv customize colors.basic.single '"#0e374e"'
+flowcv templates                     # lists each as [free] / [PAID] (paid needs a subscription)
+flowcv apply-template <templateId>   # warns first if the template is paid
+
+# render & share
+flowcv download -o resume.pdf        # the rendered PDF
+flowcv download --token <webToken> -o out.pdf   # any PUBLIC resume by its share token (no auth)
+flowcv share | publish | unpublish
+
+flowcv login                          # refresh the cached session
+flowcv md2html --file role.md         # preview HTML (offline)
+```
+
+Any command takes `--resume-id <id>` to target a specific resume. (From source,
+replace `flowcv` with `python3 flowcv.py`.)
+
+## Library (for scripts & LLM agents)
+
+```python
+from flowcvcli import FlowCV
+
+fc = FlowCV()                                   # or FlowCV(resume_id="...")
+fc.set_personal_field("fullName", "Jane Doe")
+fc.add_entry("work", sets={"jobTitle": "Engineer", "employer": "Acme",
+                           "startDateNew": "01/2022", "endDateNew": "Present"},
+             md="- Shipped a thing with **measurable** impact.")
+fc.set("font.fontFamily", "Source Sans Pro")    # a customization delta
+fc.set_photo("https://example.com/me.png")      # avatar from URL
+fc.apply_template("a3fb6c37-...")               # a design from list_templates()
+fc.save_pdf("resume.pdf")                        # render to PDF
+
+# structure & resume management
+fc.reorder_entries("work", ["id3", "id1", "id2"])   # set entry order
+fc.rename_section("skill", "Core Skills"); fc.delete_section("custom1")
+fc.hide_entry("work", "id", hidden=True)
+new_id = fc.create_resume("Second Resume")          # or fc.duplicate_resume()
+fc.rename_resume("New Title"); fc.delete_resume()    # delete is permanent
+```
+
+### Build → render → check → improve
+
+The PDF *is* the rendered output. An agent can write content, `save_pdf(...)`,
+**open the PDF to see the actual layout**, then adjust and re-render — a closed
+feedback loop for building a resume from raw info.
+
+## Markdown mini-format (`desc` / `add`)
+
+| You write | You get |
+|---|---|
+| blank line | block separator |
+| `## Heading` / `**Whole line bold**` | bold subheader |
+| `- item` | bullet (consecutive = one list) |
+| anything else | justified paragraph |
+| `**bold**` inline | `<strong>bold</strong>` |
+
+## How it works
+
+- **Read-modify-write**: edits fetch the resume, change one part, and send it
+  back — unrelated fields are never touched.
+- New entries append to the bottom of their section; use `reorder` to change order.
+- The on-screen preview is client-side HTML; the **PDF download is a separate
+  server render** of the same data (details in [`docs/RENDERING.md`](docs/RENDERING.md)).
+
+> **Scope:** this tool covers **resumes**. The same FlowCV account also has Cover
+> Letters, Job Tracker, Email Signatures and Personal Websites (separate APIs —
+> see `docs/API.md` "Other FlowCV products"); documented but not implemented here.
+
+## Project layout
+
+```
+flowcvcli/             # the package (import flowcvcli)
+  config.py            #   resolve resume id + auth from .env / env vars
+  client.py            #   HTTP, login, cookie-jar session, retry, get_resume
+  markup.py            #   markdown <-> FlowCV rich-text HTML
+  content.py           #   sections & entries (add/edit/reorder/hide/sections)
+  personal.py          #   header details & links
+  customization.py     #   styling deltas & templates
+  photo.py             #   avatar upload / toggle
+  resume.py            #   list, create/duplicate/rename/delete, download, publish
+  api.py               #   FlowCV = Client + all mixins
+  cli.py / __main__.py #   the `flowcv` command
+docs/API.md            # reverse-engineered API reference
+docs/RENDERING.md      # how the editor renders the preview & debounces saves
+flowcv.py              # source-tree entry point (python3 flowcv.py …)
+```
+
+## License
+
+[MIT](LICENSE) © dannyota

flowcvcli-0.2.0/docs/API.md

@@ -0,0 +1,208 @@
+# FlowCV private API — reference
+
+Reverse-engineered from the FlowCV web app (`app.flowcv.com`). Unofficial; for
+personal use. Base: `https://app.flowcv.com/api`. All app endpoints are
+same-origin and authenticated by the **`flowcvsidapp`** session cookie alone
+(other cookies — `i18n`, `loggedin`, `appVersion` — are not needed for auth).
+
+Standard JSON envelope: `{ "success": bool, "data": ..., "error": "", "code": int }`.
+A missing endpoint returns `code:404`; an existing endpoint with a bad/empty body
+returns `code:500` (handler ran, validation failed) — useful for probing.
+
+For **how the editor renders the live preview and when it persists edits**, see
+[`RENDERING.md`](RENDERING.md). Short version: the preview is client-side React
+HTML (no PDF/canvas), edits update instantly with no network, and saves are
+debounced into the `save_entry` / `save_personal_details` / `save_customization`
+PATCHes documented below — i.e. exactly what this tool sends.
+
+**Editor boot sequence** (what the SPA fetches on load): `GET /auth/init_user`,
+`GET /resumes/all`, `GET /letters/all`, `GET /trackers/all`, `GET /signatures/all`,
+`GET /websites/all`, `GET /users/fetch_subscription_infos`,
+`GET /users/invoices/pending_review`, then `GET /resumes/{id}` for the open resume.
+
+## Auth
+
+| Method | Path | Body | Notes |
+|---|---|---|---|
+| GET | `/auth/init_user` | — | seeds an (anonymous) session cookie. The web app calls it before login, but it is **optional** — login works standalone (the browser request skips it). |
+| POST | `/auth/login` | `multipart/form-data`: `email`, `password` (+ empty `resumeData=undefined`, `letterData=undefined`, `resumeImg`, `letterImg`) | sets `flowcvsidapp` cookie on success. **Rate-limited per source IP** (≈100/day) — exhausting it on one machine doesn't affect another. |
+
+Login flow: (optionally GET `init_user` for an anonymous session) → POST `login`
+on the same cookie jar → the jar now holds the authenticated `flowcvsidapp`.
+`init_user` is best-effort; a failure there must not block the login.
+
+## Resumes (resume-level)
+
+| Method | Path | Body / Query | Returns |
+|---|---|---|---|
+| GET | `/resumes/all` | — | `data.resumes[]` (id, title, webToken, webResumeLive, order, …) |
+| GET | `/resumes/{resumeId}` | — | `data.resume` (full resume object) |
+| POST | `/resumes/create` | `{clientResume: {…full resume object…}}` | create a resume. The body must be a **complete** resume object (every NOT-NULL column), so the reliable way is to **clone a full existing resume** (`GET /resumes/{id}`), reassign `id`+`uuid`, set `title`, empty `content` (or keep it for a duplicate), and **drop** `webToken`/`feedbackToken`/`createdAt`/`updatedAt` (server regenerates). A hand-built partial body fails with Postgres `23502` (not-null). Note: the one-resume free-plan cap is **not** enforced on this endpoint. |
+| POST | `/resumes/duplicate` | `{resumeId}` | native duplicate — but returned a generic error in testing; duplicating via `create` (clone, keep `content`) is what this tool does instead. |
+| PATCH | `/resumes/rename_resume` | `{resumeId, resumeTitle}` | rename a resume |
+| DELETE | `/resumes/delete_resume?resumeId={id}` | — | **permanently delete** a resume (irreversible) |
+| PATCH | `/resumes/apply_template` | `{resumeId, templateId, customization: {…template's full customization…}, personalDetails: {…current…}}` | applies a design. `templateId` + `customization` come from the template list (below). |
+| PATCH | `/resumes/publish_web_resume` | `{publish: bool, resumeId}` | toggle the public web resume |
+| GET | `/resumes/download?resumeId={id}&previewPageCount={n}` | — | **PDF bytes** (`application/pdf`). `previewPageCount` does not truncate; any value returns the full doc. |
+| GET | `/api/public/download_resume?token={webToken}` | — | **public** PDF of any *shared* resume by its web token — no auth/ownership needed. (Only when the resume's download is enabled; otherwise 400.) |
+| DELETE | `/resumes/delete_entry?resumeId&sectionId&entryId` | — | delete a content entry (see below) |
+
+The full-resume GET also exposes `webToken` (public URL
+`https://flowcv.com/resume/{webToken}`), `webResumeLive`, `feedbackToken`. Top-level
+resume keys (for the `create` clone): `id, userId, mongoId, title, order,
+feedbackToken, webToken, uuid, feedbackEnabled, webResumeLive,
+webResumeDownloadBtn, webResumeSearchIndex, webResumeCached, personalDetails,
+content, customization, feedback, businessDetails, downloads,
+usingBusinessTemplateId, schemaVersion, lastChangeAt, createdAt, updatedAt, lng,
+tags`.
+
+## Content (sections & entries)
+
+`data.resume.content` is a map of `sectionId → { entries[], iconKey, displayName,
+sectionType }`. Known sections: `profile` (Summary), `work` (Experience),
+`education`, `skill`, `publication`, `organisation`, `custom1` (sectionType
+`custom`), plus language/certificate/interest/project/course/award/reference/
+declaration.
+
+| Method | Path | Body | Notes |
+|---|---|---|---|
+| PATCH | `/resumes/save_entry` | `{resumeId, sectionId, entry}` | **update** an existing entry (send the whole entry object). |
+| PATCH | `/resumes/save_entry` | `{resumeId, sectionId, entry:{id, isHidden:false}, sectionType, sectionDisplayName, sectionIconKey}` | **create** an entry — required extra section-meta fields. If the section doesn't exist yet, this also **creates the section**. New entries append to the bottom. Populate fields with a follow-up update call. |
+| DELETE | `/resumes/delete_entry?resumeId&sectionId&entryId` | — | delete an entry |
+| PATCH | `/resumes/save_entries_order` | `{resumeId, sectionId, newEntriesIdsOrder:[id,…], disableAutoSort:true}` | **reorder entries** within a section (the array order). `disableAutoSort` keeps the manual order (else FlowCV auto-sorts by date). |
+| PATCH | `/resumes/save_section_name` | `{resumeId, sectionId, displayName}` | **rename** a section heading |
+| PATCH | `/resumes/save_section_icon` | `{resumeId, sectionId, iconKey}` | change a section's icon |
+| DELETE | `/resumes/delete_section?resumeId&sectionId` | — | **delete a whole section** and all its entries |
+
+To **hide/show** a single entry, `save_entry` it with `entry.isHidden = true|false`
+(it stays in the resume but is omitted from output). **Reorder sections** by
+writing `customization.sectionOrder.<layout>.sectionsSorted` (a list of section
+ids) via `save_customization` — section order lives in `customization`, keyed per
+column layout (`one`, `two`, `mix`), not in `content`. (`save_section` exists too
+but 500s on every body shape tried; the granular `save_section_*` endpoints above
+are what the app actually uses. `reorder_entries`/`reorder_sections`/`rename_section`
+are all 404 — the real names are `save_entries_order`/`save_section_name`.)
+
+Section meta (`sectionType`, `displayName`, `iconKey`) for creating sections:
+`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).
+
+Rich-text fields are HTML: `<p style="text-align: justify">…</p>` for paragraphs,
+`<p…><strong>…</strong></p>` for bold subheaders, `<ul><li…><p…>…</p></li></ul>`
+for bullets. `profile` entries use a `text` field; `skill` entries use `skill`
+(title) + `infoHtml`; most others use `description`.
+
+No reorder endpoint (`reorder_entries` 404s). To reorder, reassign entry content
+across the existing array slots.
+
+## Personal details & header links
+
+| Method | Path | Body |
+|---|---|---|
+| PATCH | `/resumes/save_personal_details` | `{resumeId, personalDetails: {…full object…}}` |
+
+Always send the **full** `personalDetails` object with only the target field
+changed (it replaces the whole object). Header links live in
+`personalDetails.social` as `{platform: {display, link}}` (e.g. `linkedIn`,
+`orcid`, `googlescholar`) and are shown per `personalDetails.detailsOrder`
+(e.g. `["displayEmail","phone","address","linkedIn","orcid","googlescholar"]`).
+The legacy single link is `personalDetails.website` + `websiteLink`.
+
+## Photo / avatar
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/resumes/upload_profile_pic` | `multipart/form-data`: `resumeId` + `file` (image bytes) → `{data:{imageId:"avatar/….png"}}` |
+
+Then save the id into `personalDetails.photo` (via `save_personal_details`):
+`{imageId, shape:"round", xPct, yPct, widthPct, heightPct, originalWidth, originalHeight}`
+(use a whole-image crop: xPct≈yPct≈0.0005, widthPct≈heightPct≈0.999). Toggle
+display with the customization delta `header.photo.show` = `true|false`.
+
+## Customization (styling)
+
+| Method | Path | Body |
+|---|---|---|
+| PATCH | `/resumes/save_customization` | `{resumeId, customizationUpdates: [{path, value}, …]}` |
+
+**Delta API**: each update is a dot-`path` into `resume.customization` and a new
+`value`. Examples:
+- Columns: `layout.colsFromDetails.top|left|right` = `"one"|"two"`
+- Font: `font.fontFamily` = `"Source Sans Pro"`, `font.selected` = `"serif"|"sans"`
+- Colors: `colors.basic.single` = `"#0e374e"`, `colors.mode` = `"basic"|"advanced"`
+- Spacing: `spacing.fontSize`, `spacing.lineHeight`, `spacing.marginHorizontal`
+- Headings: `heading.style` = `"line"|"box"`, `heading.capitalization`
+- Page: `pageFormat` = `"A4"|"Letter"`
+
+The full `customization` schema is visible in `GET /resumes/{id}` (under
+`data.resume.customization`) and in the `create` default.
+
+The **Customize** panel groups (each = one or more delta paths under
+`customization`) are: **Document** (page format, date format), **Templates**
+(browse/apply, below), **Layout** (`layout.colsFromDetails…` columns one/two/mix,
+per-section placement), **Font Size**, **Spacing** (`spacing.*`), **Entry Layout**,
+**Section Headings** (`heading.style`, `heading.capitalization`, heading icons),
+**Font** — separate **body font** and **name font** — **Colors**
+(`colors.mode`/`colors.basic.single`, accent, and *Color Area*: full / page /
+header / border), **Header** (text alignment, details arrangement, icon style),
+**Photo** (`header.photo.show`), **Link Styling**, **Footer** (toggle page
+numbers / email / name), and per-**Section** customizations. "Create template"
+publishes the current design as a shareable template. The panel also has
+**undo/redo**. All of these are just `save_customization` deltas — discover exact
+paths by diffing `data.resume.customization` before/after a change in the UI.
+
+## Templates
+
+| Method | Path | Returns |
+|---|---|---|
+| GET | `/pubcache/published-resume-templates` | the full template catalog (id, title, customization, `isPremium`, …) |
+| GET | `/api/resume-templates/get_shared_template?resumeId={id}` | the template shared/applied to a resume |
+
+Each catalog entry has **`isPremium`** (bool): `false` = free, `true` = needs a
+FlowCV subscription to apply. Show this to users before they apply one.
+
+To apply a template: pick its `templateId` + `customization` from the catalog and
+PATCH `apply_template` (above).
+
+## Download & share menu (resume editor)
+
+The editor's top-right controls map to these endpoints:
+
+| UI control | Endpoint / effect |
+|---|---|
+| **Download** button | `GET /resumes/download` → PDF (server render). Shows a "✅ downloaded" modal after. |
+| ⋯ → **Download via email** | emails the PDF to the account (send-email endpoint; body not captured). |
+| ⋯ → **Get shareable link** | the **web resume**: *Enable sharing* = `publish_web_resume {publish}`; link is `https://flowcv.com/resume/{webToken}`; *Display download button* gates the public `public/download_resume?token=` PDF (off → 400). |
+
+## AI Tools (per resume, Pro plan) — `/resume/ai-tools`
+
+Gated behind the **Pro** subscription ("AI features are available on our Pro
+plan"). Two tools observed (both Beta): **Translate resume** (create a translated
+copy in another language, layout intact) and **Check spelling & grammar** (scan +
+fix suggestions). Endpoints not captured (Pro-gated on the test account).
+
+## Other FlowCV products (same account & session, separate APIs)
+
+FlowCV is more than resumes. The same `flowcvsidapp` session authenticates these
+sibling products — each with its own `…/all` list endpoint, all fetched on editor
+load. This tool currently covers **resumes only**; these are documented for
+discovery, not yet implemented:
+
+| Product | List endpoint | UI |
+|---|---|---|
+| **Cover Letters** | `GET /api/letters/all` | `/cover-letters` |
+| **Job Tracker** | `GET /api/trackers/all` | `/job-tracker` |
+| **Email Signatures** | `GET /api/signatures/all` | email-signature generator |
+| **Personal Websites** | `GET /api/websites/all` | personal-site builder |
+
+Account/billing: `GET /api/users/fetch_subscription_infos` (plan + entitlements;
+free accounts get one resume, premium templates and AI gated),
+`GET /api/users/invoices/pending_review`. The user object from `auth/login` also
+carries `paid`, `activePlans`, AB-test flags, and `numberOfLogins`.
+
+> Free vs paid recap: first resume is free forever; additional resumes, premium
+> templates (`isPremium`), AI Tools, and likely the public-download button are
+> Pro features. Show users the free/paid split before they hit a 400 or upsell.