makea-cli 0.1.11__tar.gz → 0.1.12__tar.gz

makea_cli-0.1.12/.claude/skills/create-supplier-profile/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: create-supplier-profile
+description: >-
+  Create a new Makea supplier profile from scratch (admin), the schema-driven way:
+  first fetch the live supplier profile schema (the field taxonomy) with
+  `makea-cli get-supplier-profile-schema`, then build a valid v2 payload against
+  it, then upload with `makea-cli add-supplier`. Use this whenever you need to
+  onboard / register / create a supplier, turn raw supplier info (a website, a
+  brochure, an email, a few notes) into a structured profile, or are asked to
+  "add a supplier", "create a supplier profile", "onboard [company]". The AI does
+  the payload building — the CLI only fetches the schema and uploads. For LINKING
+  an already-registered user to an EXISTING profile use `link-supplier-user`; for
+  fixing a wrong supplier_id use `supplier-user-id-migration`.
+---
+
+# Create Supplier Profile (schema-driven)
+
+The supplier profile is described by a **v2 schema** (sections, fields, allowed
+options, required rules) served from the backend. Field names and options change
+over time, so **never hardcode the payload shape — always fetch the live schema
+first and build against it.** The CLI deliberately stays "dumb": it fetches the
+schema and uploads. *You* (the AI) do the building.
+
+Flow: **fetch schema → build payload → upload.**
+
+---
+
+## Step 0 — Auth & CLI setup
+
+You need a working, authenticated `makea-cli`. If `makea-cli list-suppliers`
+returns JSON, you're good. If it prints `尚未登录` / "not logged in" or
+`command not found`, run the **`makea-cli-setup`** skill first (install + token
+refresh + login).
+
+Quick smoke-test:
+
+```bash
+makea-cli list-suppliers 2>&1 | head -3
+```
+
+---
+
+## Step 1 — Fetch the schema (taxonomy)
+
+```bash
+makea-cli get-supplier-profile-schema
+```
+
+Returns `{success, schema}`. The `schema` object you care about:
+
+- `supplier_type_options` — the allowed values for the `type` field. Pick the
+  one that matches the supplier (e.g. `"Finished Product Manufacturer"`,
+  `"Fabric & Material Supplier"`).
+- `sections` / `sections_in_order` — each section has `key`, `label`, and a list
+  of field definitions.
+- `field_map` — every field keyed by its `key`, with: `type` (text, long_text,
+  url, email, number, single_select, multi_select, repeatable_group, file_upload,
+  file_upload_or_url), `required`, `required_when` (`{field, equals}`),
+  `options` (allowed values for selects), `options_source` (dynamic list, e.g.
+  `country_list`), `repeatable_fields`.
+- `section_visible_when` — `{section_key: {field, equals}}`. A section's fields
+  only apply when the rule matches (almost always keyed on `type`). Sections with
+  no rule are always applicable (Company & Contact, Business Scope, etc.).
+- `section_order` / `section_labels` — display ordering and human labels.
+- `option_sources.country_list` — the allowed country values for any field whose
+  `options_source` is `country_list`.
+
+> Tip: this can be a large JSON blob. Pipe it through `python3` to pull out just
+> what you need — e.g. the supplier types and the required fields for the chosen
+> type — before building.
+
+---
+
+## Step 2 — Build the payload (this is the AI's job)
+
+Decide the supplier `type` from `supplier_type_options`, then walk `field_map`:
+
+1. **Pick applicable fields.** A field applies if its section is always-visible
+   OR `section_visible_when[section]` matches your chosen `type`. Skip fields
+   whose section doesn't match.
+2. **Fill required fields.** A field is required if `required: true`, or if its
+   `required_when.{field}` equals the given value. These MUST be present and
+   non-empty or the backend rejects the payload.
+3. **Respect field types & options.**
+   - `single_select` → one string from `options`.
+   - `multi_select` → array of strings, each from `options`.
+   - `number` → a number (not a string).
+   - `email` / `url` → valid email / `http(s)://…` URL.
+   - `text` / `long_text` → string.
+   - `repeatable_group` → array of objects shaped by `repeatable_fields`.
+   - `file_upload` → array (document ids/objects); leave out if you have nothing.
+   - Fields with `options_source: country_list` → use a value from
+     `option_sources.country_list`.
+4. **"Other (please specify)".** If a select value is `"Other (please specify)"`,
+   also set the companion key `"<field_key>_other_text"` with the free text.
+5. **Only use keys that exist in `field_map`.** Unknown keys are ignored by the
+   backend. Don't invent fields.
+
+Write the result as a flat JSON object (top-level keys = field keys) to a file,
+e.g. `supplier.json`. Always include at least `name` and `type` — that's what
+makes the backend treat it as a v2 payload and validate it section-by-section:
+
+```json
+{
+  "name": "ACME Garments Ltd",
+  "type": "Finished Product Manufacturer",
+  "country_region": "China",
+  "city": "Guangzhou",
+  "contact_name": "Li Wei",
+  "contact_email": "liwei@acme.example.com"
+}
+```
+
+(Add the other applicable required + relevant optional fields from the schema.)
+
+If you only have messy raw input (website text, a brochure, an email thread),
+map it onto the schema fields yourself — that mapping is exactly what this skill
+is for. Confirm anything ambiguous with the user before uploading.
+
+---
+
+## Step 3 — Upload
+
+```bash
+makea-cli add-supplier --file supplier.json
+```
+
+The file root may be the flat supplier object (recommended) or the full envelope
+`{"supplier": {...}}` — the CLI accepts both. On success you get
+`{success: true, result: {...}}` (HTTP 201) with the stored supplier, including
+the assigned `supplier_id`.
+
+The backend re-validates the v2 payload. If it returns `success: false` with an
+`errors` array, read each `{field, code, message}`, fix the payload against the
+schema (Step 2), and re-run. Common codes: `required_missing`,
+`invalid_option`, `invalid_type`.
+
+---
+
+## Step 4 — Verify
+
+```bash
+makea-cli list-suppliers | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+search = 'acme'  # lowercase fragment of the company name
+for s in data.get('result', []):
+    if search in str(s).lower():
+        print(s['supplier_id'], s['name'], s.get('type'))
+"
+```
+
+Confirm the new `supplier_id`, name, and type look right, then summarise for the
+user.
+
+---
+
+## Notes
+
+- **Linking a user vs. creating a profile.** This skill *creates* a brand-new
+  profile. If the supplier already has a profile and just registered a login,
+  use `link-supplier-user` instead. If a profile exists under the wrong
+  `supplier_id`, use `supplier-user-id-migration`.
+- **`supplier_id` is auto-generated** when omitted. Provide one only if you need
+  it to equal a Cognito sub up front (usually you don't — link later).
+- **Documents** (catalogue, images, business_license, …) are uploaded separately
+  with `makea-cli upload-supplier-document` after the profile exists.

makea_cli-0.1.12/.claude/skills/lark-cli-setup/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: lark-cli-setup
+description: >-
+  Installs the Lark/Feishu CLI (`lark-cli`) and gets the user authenticated:
+  app-credential config, then OAuth login. Use this skill whenever the user
+  wants to install or set up lark-cli, run any lark-cli command for the first
+  time, sees "command not found: lark-cli", needs to do `config init` /
+  `auth login`, or says things like "set up lark-cli", "install the Feishu CLI",
+  "log me into lark". For permission/scope errors, identity switching (--as), or
+  re-auth on an already-installed CLI, the `lark-shared` skill is the better fit —
+  this skill is specifically the first-time install + login on-ramp.
+---
+
+# Lark CLI — Install & Login
+
+Gets `lark-cli` (飞书官方 CLI, by larksuite) installed and authenticated so
+subsequent commands work. Mirrors the README's **快速开始（AI Agent）** flow:
+install → config app credentials → OAuth login → verify.
+
+These steps are written for an AI agent driving a real terminal where some
+steps need the user to click a link in their browser. Do them in order; stop as
+soon as `auth status` reports a logged-in identity.
+
+---
+
+## Step 0 — Is it already set up?
+
+```bash
+lark-cli auth status 2>&1 | head -c 300 || echo "NOT_INSTALLED"
+```
+
+- Shows a logged-in user / valid scopes → **already set up, you're done.**
+- Runs but reports no auth / not configured → installed; skip to **Step 2**.
+- `command not found` / `NOT_INSTALLED` → go to **Step 1**.
+
+---
+
+## Step 1 — Install
+
+Requires **Node.js** (`npm` / `npx`). Pick one:
+
+**From npm (recommended):**
+
+```bash
+npx @larksuite/cli@latest install
+```
+
+**From source** (needs Go `v1.23+` and Python 3):
+
+```bash
+git clone https://github.com/larksuite/cli.git
+cd cli
+make install
+npx skills add larksuite/cli -y -g   # install the CLI SKILLs (required)
+```
+
+Verify the binary resolves:
+
+```bash
+lark-cli --help 2>&1 | head -1
+```
+
+---
+
+## Step 2 — Configure app credentials (once)
+
+This binds the CLI to a Feishu app. The command prints an authorization URL and
+blocks until the user finishes in the browser, so run it in the **background**,
+read its output, and extract the URL.
+
+```bash
+lark-cli config init --new
+```
+
+**Hand the URL to the user — do not modify it.** Treat any `verification_url`,
+`verification_uri_complete`, or `console_url` as an opaque string (no encoding,
+no reassembling query params).
+
+**Generate a QR code** for the URL and show it alongside the link (this is a
+required step, not optional):
+
+```bash
+lark-cli auth qrcode --output /tmp/lark_config_qr.png   # PNG (preferred)
+# only if the user explicitly wants ASCII: lark-cli auth qrcode --ascii
+```
+
+Send the user the link + QR together. The `config init` command exits on its own
+once they complete it.
+
+---
+
+## Step 3 — Log in (OAuth)
+
+Authorize a **user** identity. The split-flow (`--no-wait`) is preferred for an
+agent so you don't block the turn waiting on the browser:
+
+```bash
+# returns a device_code + verification_url immediately, does not block
+lark-cli auth login --recommend --no-wait --json
+```
+
+Take the `verification_url` from the output and send it (with a QR via
+`lark-cli auth qrcode`) to the user **as your final message this turn**, then
+hand control back — don't immediately poll. After the user says they've
+authorized, resume:
+
+```bash
+lark-cli auth login --device-code <DEVICE_CODE>
+```
+
+Scope notes:
+- `--recommend` auto-selects the common, auto-approvable scopes.
+- Narrower is better: `--domain calendar,task` or `--scope "calendar:calendar:read"`.
+- `auth login` must specify a range (`--recommend`, `--domain`, or `--scope`).
+  Repeated logins **accumulate** scopes (incremental authorization).
+- Never run `auth login` for a **bot** identity — bots only need scopes enabled
+  in the developer console, not OAuth.
+
+If a synchronous flow is acceptable (interactive human at the terminal), the
+simple form also works and opens a TUI / browser:
+
+```bash
+lark-cli auth login --recommend
+```
+
+---
+
+## Step 4 — Confirm & report
+
+```bash
+lark-cli auth status
+```
+
+Logged-in identity + scopes shown → tell the user **"✓ lark-cli is installed and
+logged in."** Then smoke-test a read-only command and proceed with their task:
+
+```bash
+lark-cli calendar +agenda
+```
+
+---
+
+## Reference
+
+| Command | Purpose |
+|---------|---------|
+| `npx @larksuite/cli@latest install` | install the CLI |
+| `lark-cli config init --new` | bind app credentials (first run) |
+| `lark-cli auth login --recommend` | OAuth login (user identity) |
+| `lark-cli auth login --no-wait --json` | agent split-flow: get URL without blocking |
+| `lark-cli auth login --device-code <code>` | resume split-flow after user authorizes |
+| `lark-cli auth status` | show current login + scopes |
+| `lark-cli auth logout` | log out, delete stored credentials |
+| `lark-cli auth qrcode --output <png>` | render an auth/verification URL as a QR |
+| `lark-cli update` | update CLI **and** its AI Skills (re-open the agent after) |
+
+- Identity switching: append `--as user` or `--as bot` to any command. Bots
+  can't see user resources (calendar, drive, mail).
+- Once installed, day-to-day rules (auth, permission errors, `--as`, `_notice`
+  update prompts, high-risk write confirmations) live in the `lark-shared` skill.
+- Docs: <https://github.com/larksuite/cli>

makea_cli-0.1.12/.claude/skills/makea-cli-setup/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: makea-cli-setup
+description: >-
+  Installs the Makea admin CLI (`makea-cli`) and logs the user in so subsequent
+  Makea API commands work. Use this skill whenever the user wants to set up or
+  install makea-cli, connect to the Makea platform, run any makea-cli command
+  for the first time, is hitting "尚未登录" / "not logged in" / auth errors, or
+  says things like "set up makea-cli", "log in to makea", "my makea token
+  expired", "makea-cli command not found". Also trigger when the user wants any
+  Makea admin task (users, suppliers, orders, sampling, production, documents,
+  revenue) but hasn't installed or authenticated the CLI yet.
+---
+
+# Makea CLI — Install & Login
+
+Gets `makea-cli` installed on this machine and authenticated against the live
+Makea platform (`https://api.makea.co`). Run these steps in order; stop as soon
+as a smoke-test passes.
+
+This skill assumes a normal local terminal (you can run `bash` directly and the
+user has a browser on the same machine). For sandboxed/cowork environments where
+credentials live on the user's Mac but commands run in a remote VM, see the
+bundled `makea-cli-setup.skill` archive instead.
+
+---
+
+## Step 0 — Is it already set up?
+
+Before installing anything, check whether the CLI exists and is logged in:
+
+```bash
+makea-cli version 2>&1 | head -1 || echo "NOT_INSTALLED"
+```
+
+If that prints a version, test auth with a low-cost call:
+
+```bash
+makea-cli list-suppliers 2>&1 | head -c 200
+```
+
+- JSON output → **already set up, you're done.** Skip to "Confirm & report".
+- `尚未登录` (not logged in) → installed but no valid token → go to **Step 2**.
+- `command not found` / `NOT_INSTALLED` → go to **Step 1**.
+
+---
+
+## Step 1 — Install the CLI
+
+Requires **Python 3.10+** (`python3 --version`). Pick the option that matches
+the situation:
+
+**From this repo (dev / cloned the makea-cli source):** from the repo root,
+
+```bash
+python3 -m pip install -e .
+```
+
+**From a published package (no repo clone needed):**
+
+```bash
+python3 -m pip install makea-cli        # or: pipx install makea-cli
+```
+
+If `python3` isn't found, try `python`. Common fixes if `pip install` fails:
+
+- Permission error → add `--user`
+- Externally-managed env error → `pipx install makea-cli` (preferred), or
+  `python3 -m pip install makea-cli --break-system-packages`
+- Outdated pip → `python3 -m pip install --upgrade pip` then retry
+
+Verify the command resolves:
+
+```bash
+makea-cli version
+```
+
+> Optional npm wrapper: the repo's `npm/makea-cli/` only aliases `makea-cli` to
+> `python3 -m makea_cli`. It still needs the Python package installed via pip —
+> don't use it as a substitute for Step 1.
+
+---
+
+## Step 2 — Log in
+
+`makea-cli auth` opens the company login page in the browser and saves tokens
+locally once you finish. It blocks until login completes (it runs a local
+callback server on `127.0.0.1:8250`).
+
+```bash
+makea-cli auth
+```
+
+Tell the user: **"A browser tab just opened — log in with your company account.
+Once you see 'Login successful', come back here."** When login finishes the
+command prints `登录成功，已保存在本机。` and exits.
+
+> If the browser doesn't open, the same URL is printed in the terminal — share
+> it with the user to open manually.
+>
+> To switch accounts / clear the saved token: `makea-cli auth --logout`.
+
+Connecting to a **non-production** environment? Set these before `makea-cli auth`
+(defaults live in `makea_cli/config.py`): `MAKEA_API_BASE_URL`,
+`MAKEA_COGNITO_DOMAIN`, `MAKEA_COGNITO_CLIENT_ID`, `MAKEA_REDIRECT_URI`.
+
+---
+
+## Step 3 — Confirm & report
+
+Re-run the smoke-test from Step 0:
+
+```bash
+makea-cli list-suppliers 2>&1 | head -c 200
+```
+
+JSON back → tell the user **"✓ makea-cli is installed and logged in."** and
+proceed with whatever task triggered this skill (e.g. user segmentation, order
+analysis, revenue report). Still `尚未登录` → the login didn't save; re-run
+Step 2 and confirm the browser flow completed.
+
+---
+
+## Reference
+
+| Thing | Value |
+|-------|-------|
+| API base URL | `https://api.makea.co` |
+| Credentials (macOS) | `~/Library/Application Support/makea-cli/credentials.json` |
+| Credentials (Linux) | `~/.config/makea-cli/credentials.json` |
+| Auth header | `Authorization: Bearer <id_token>` |
+| Login | `makea-cli auth` |
+| Logout | `makea-cli auth --logout` |
+
+The credentials JSON holds `id_token`, `refresh_token`, `expires_in`,
+`saved_at`. Run `makea-cli --help` for the full command list (list-users,
+list-suppliers, list-product-orders, create-quote-request, download-document,
+upload-*-document, backfill-supplier-id, …).

{makea_cli-0.1.11 → makea_cli-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: makea-cli
-Version: 0.1.11
+Version: 0.1.12
 Summary: Makea admin CLI (browser login + Makea admin HTTP API)
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27

{makea_cli-0.1.11 → makea_cli-0.1.12}/makea_cli/api_client.py

@@ -188,6 +188,11 @@ def get_all_suppliers() -> Any:
     return get_json("/admin/supplier/get_all_suppliers")
 
 
+def get_supplier_profile_schema() -> Any:
+    """GET /admin/supplier/profile/schema — supplier profile v2 schema (the field taxonomy)."""
+    return get_json("/admin/supplier/profile/schema")
+
+
 def add_supplier(body: dict[str, Any]) -> Any:
     """POST /admin/supplier/add_supplier — body must be {\"supplier\": {...}}."""
     return post_json("/admin/supplier/add_supplier", body)

{makea_cli-0.1.11 → makea_cli-0.1.12}/makea_cli/commands/supplier/cmd.py

@@ -35,6 +35,28 @@ def register(app: typer.Typer) -> None:
         """
         print_json_or_exit(console, api_client.get_all_suppliers)
 
+    @app.command(
+        "get-supplier-profile-schema",
+        help=(
+            "GET /admin/supplier/profile/schema — supplier profile v2 schema "
+            "(section/field taxonomy: sections, fields, options, required rules)."
+        ),
+    )
+    def get_supplier_profile_schema() -> None:
+        """
+        Fetch the supplier profile v2 schema (admin).
+
+        Input: none (GET /admin/supplier/profile/schema).
+
+        Output: JSON {success, schema} where schema contains: version, scope,
+        sections, section_labels, section_order, sections_in_order,
+        section_visible_when, field_map, option_sources, supplier_type_options.
+
+        This is the field taxonomy to build a supplier payload against before
+        creating one with ``add-supplier``.
+        """
+        print_json_or_exit(console, api_client.get_supplier_profile_schema)
+
     @app.command(
         "add-supplier",
         help="POST /admin/supplier/add_supplier — create supplier from JSON file (admin).",

{makea_cli-0.1.11 → makea_cli-0.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "makea-cli"
-version = "0.1.11"
+version = "0.1.12"
 description = "Makea admin CLI (browser login + Makea admin HTTP API)"
 readme = "README.md"
 requires-python = ">=3.10"