CareMax Authentication

CRITICAL RULES

1. 1. This is a silent prerequisite for ALL caremax-* skills. Do NOT ask "do you want to authenticate?" — just execute.
2. NEVER write your own curl commands. Only use the scripts below.
3. NEVER split auth into multiple steps manually. Use ./scripts/auth-flow.sh (from this skill root) — it opens browser AND auto-polls until done.
4. BASE URL DETECTION: If the user specifies a custom URL (local dev 默认 http://localhost:8788，须与后端 wrangler [dev] 端口一致), you MUST:

- Pass it as the first argument: bash ./scripts/auth-flow.sh http://localhost:8788 (run from this skill root — see path convention below) - After auth completes, credentials.json will have base_url set to that URL - All subsequent api-call.sh, list-system-presets.sh, quick-log.sh, upload.sh, ocr-stream.sh will auto-use it - Look for URL patterns like http://localhost:XXXX, caremax(http://...), or explicit "use local" / "use localhost"

Scripts

Path convention (no ~/.claude — product-agnostic)

• - This skill (caremax-auth): run commands with current working directory = this folder (the directory that contains SKILL.md and scripts/). Invoke scripts as ./scripts/<name>.sh.
• Other caremax-* skills sit as sibling directories next to caremax-auth (e.g. skills/caremax-indicators/ and skills/caremax-auth/ in the repo, or ~/.agents/skills/<name>/ after install). From those folders, call auth as ../caremax-auth/scripts/<name>.sh.

Credentials file location is unchanged: ~/.caremax/credentials.json (not under any product’s config dir).

api-call.sh — Make authenticated API calls (PRIMARY TOOL)

This is what you should use for all API calls. It auto-checks token, auto-refreshes if expired.

CODEBLOCK0

If it returns {"error":"no_credentials",...} → run ./scripts/auth-flow.sh (see below), then retry.

list-system-presets.sh — 当前账号可快捷记录的指标列表

与 App 「快捷记一笔」 芯片一致：先看有哪些 preset_key / 显示名 / 默认单位，再调用 quick-log.sh。

CODEBLOCK1

quick-log.sh — 快捷记一笔（单条数值）

CODEBLOCK2

可选参数：--unit、--date（YYYY-MM-DD）、--member（家庭成员 UUID）。底层走 api-call.sh，自动带用户 OAuth token。

upload.sh — Upload files (images/PDFs) to CareMax

CODEBLOCK3

Returns: INLINECODE34

Use the returned id values as fileIds for ocr-stream.sh.

IMPORTANT: Do NOT use api-call.sh for file uploads — it only supports JSON body. Always use upload.sh for multipart file uploads.

download-file.sh — Download a source file from a session

CODEBLOCK4

Get file_id from session detail (source_files[].id in reports, or files[].id in session).

ocr-stream.sh — OCR with real-time SSE progress (for caremax-ocr skill)

CODEBLOCK5

Outputs one JSON per line as OCR progresses. Last line (step=done) has the full results.
Read each line and display progress to the user. See caremax-ocr skill for details.

Handles errors gracefully:

• - 409 (session already processing) → outputs INLINECODE43
• 403 (quota exceeded) → outputs INLINECODE44
• Pipeline auto-resumes from saved checkpoint on retry (no work is lost)

auth-flow.sh — One-shot full authorization (opens browser + auto-polls)

CODEBLOCK6

This script does EVERYTHING in one shot:

1. 1. Requests device code from the API
2. Opens the user's browser to the authorize page
3. Automatically polls every 5 seconds until the user approves (up to 15 min)
4. Saves token to INLINECODE45

Output when done: INLINECODE46

Run this in the background so you can tell the user what's happening while it polls:

bash ./scripts/auth-flow.sh &

Then tell the user: "I've opened the authorization page in your browser. Please log in and click Allow. I'll detect it automatically."

Wait for the background job to finish — it will output the result.

check-token.sh — Check token status (used internally by api-call.sh)

CODEBLOCK8

Output: INLINECODE47

refresh-token.sh — Refresh expired token (used internally by api-call.sh)

CODEBLOCK9

Standard Workflow

Quick vitals (快捷记一笔)

CODEBLOCK10

Query data

CODEBLOCK11

Upload + OCR (save medical reports from images)

This is a session-based multi-step workflow. One upload session groups all files + reports together.

Step 1: Upload → creates a session

bash ./scripts/upload.sh /path/to/image1.jpg /path/to/image2.jpg

Returns:

{ "session_id": "uuid", "member_id": "uuid", "files": [{ "id": "...", "original_name": "..." }] }

Save session_id — it's used for all subsequent steps.

Step 2: OCR (with real-time progress)

CODEBLOCK14

Each output line is a JSON progress event. Relay to the user:

• - step=normalize → "正在预处理文件..."
• INLINECODE50 → "正在 OCR 识别第 X/Y 页..."
• INLINECODE51 → "AI 正在分析报告结构..."
• INLINECODE52 → "正在标准化指标名称..."
• INLINECODE53 → OCR complete, data contains reports array

Step 3: Present results for user review (MANDATORY)

Do NOT call confirm automatically. Parse the step=done data and show:

CODEBLOCK15

Wait for user to say 确认/保存/OK.

Step 4: Confirm and save

CODEBLOCK16

Returns: INLINECODE56

After success: "已保存 N 份报告。"

Query sessions

CODEBLOCK17

Delete session (undo entire upload)

bash ./scripts/api-call.sh DELETE /api/skill/sessions/<session_id>

Deletes the session + all files + all reports atomically.