Module cloud_client 

Structs

EffectivePlan

A resolved plan plus its provenance. The plan here is only ever used for display and for gating hosted surfaces — it never gates a local capability (Local-Free Invariant; the local engine has no entitlement checks).

LinkCode

A freshly minted pairing code for login-less machine linking (GH #736).

PlanCache

The locally cached plan plus when it was last confirmed against the billing backend. The timestamp is what powers offline grace.

PublishedCard

Result of a successful Wrapped publish (POST /api/wrapped). The edit_token is returned (and must be stored to delete/claim later) only on a fresh insert; on a signed re-publish the server updates the existing card in place and omits it (the client keeps the stored one).

RegisterResult

Enums

PlanSource

Where an effective plan came from — drives the wording in billing status and the dashboard badge.

Constants

PLAN_GRACE_DAYS

Days a cached plan keeps granting its hosted entitlements while the billing backend is unreachable. Generous on purpose: a network blip or a weekend offline must never silently demote a paying user to Free.

Functions

account_email

The signed-in account’s email, for status displays.

api_url

cached_plan

The cached plan, if any. Prefers the structured plan.json; falls back to a legacy plan.txt (no timestamp → verified_at = 0, i.e. immediately past grace until the next successful refresh re-stamps it).

claim_wrapped

Bind a published card to the logged-in account so the leaderboard stacks all of the user’s machines under one entry (#488). Auth: account Bearer + the card’s edit_token (X-Edit-Token). Server: POST /api/wrapped/:id/claim. Requires being logged in.

contribute

fetch_account_cloud

GET /api/account/cloud — the Personal Cloud dashboard payload (entitlement gate, per-bucket sync footprint, buddy, usage totals). Powers lean-ctx cloud status, mirroring what leanctx.com/account/cloud shows.

fetch_leaderboard

Fetch the public community leaderboard as JSON ({ "entries": [ … ] }).

fetch_plan

forgot_password

index_bundle_status

GET /api/sync/index — hosted-bucket listing + quota usage for the account.

is_cloud_user

is_logged_in

link_wrapped_complete

Complete a login-less machine link on the second machine: join this card into the pairing code’s group. Auth: this card’s edit_token — no account. Server: POST /api/wrapped/:id/link/complete.

link_wrapped_start

Start a login-less machine link: mint a short-lived pairing code for this card. Auth: the card’s edit_token only — no account. Server: POST /api/wrapped/:id/link/start.

load_api_key

load_cloud_models

login

oauth_register_client

plan_within_grace

Pure grace check (no clock/IO) so it is unit-testable: is a plan confirmed at verified_at still within grace_days of now? Returns the age in days too.

publish_wrapped

Publish a whitelisted Wrapped payload. Accepts either a bare payload (legacy anonymous) or a signed envelope {payload_json, public_key, signature} (login-less identity → server upsert). No account auth; the server rate-limits per IP. Contract: docs/contracts/wrapped-permalink-v1.md.

pull_cloud_models

pull_index_bundle

Download, decrypt and unpack the hosted bundle for this project. Returns the bundle manifest on success.

pull_knowledge

Pull the knowledge store: vault-first (encrypted blob, decrypted locally), with a legacy plaintext fallback for accounts that never pushed a vault.

push_buddy

push_cep

push_commands

push_feedback

push_gain

push_gotchas

Push gotchas as a zero-knowledge vault (GL #467 follow-up): sealed client-side under the gotcha-vault-v1 HKDF domain — the backend stores ciphertext only and purges the account’s legacy plaintext rows on the first vault push.

push_index_bundle

Pack, encrypt and upload the project’s index bundle. Returns (project_hash, encrypted_size_bytes).

push_knowledge

Push the knowledge store as a zero-knowledge vault (GL #467): entries are sealed client-side (XChaCha20-Poly1305, domain-separated HKDF key) — the backend stores ciphertext and can never read them. The first vault push also purges the account’s legacy plaintext rows server-side.

refresh_effective_plan

Best-effort live resolve: try the backend (refreshing the cache on success), otherwise fall back to the cached-with-grace plan. Suitable for explicit commands like lean-ctx billing status where a network round-trip is fine.

register

resolve_effective_plan_cached

Resolve the effective plan from the local cache only (no network), applying the offline-grace policy. Use this on hot paths (dashboard requests); use refresh_effective_plan when a live confirmation is acceptable.

save_cloud_models

save_credentials

save_plan

start_checkout

Start a Stripe Checkout session for the logged-in account and return the hosted URL to open. plan is e.g. "pro" or "team"; interval is "monthly" or "yearly". The open backend proxies this to the private billing plane (which returns 503 when billing is not configured).

sync_stats

unpublish_wrapped

Delete a previously published card using its one-time edit_token (sent as X-Edit-Token).