comonyx-admin

Admin skill to sign into Cosmonyx, fetch companies, filter/export (PDF or Excel), optionally email the export, or send reminder emails to filtered companies.

# Cosmonyx Admin – Sign in, Fetch Companies, Export as PDF or Excel

This skill lets an **admin** sign in to Cosmonyx, fetch **all company records** using the same endpoints as the Cosmonyx gateway API, then choose to export those records as **PDF** or **Excel**, or send reminder emails. Email is sent by this skill’s own script (`scripts/send-email.py`); see TOOLS.md.

You must run all HTTP requests yourself (no external repos). For structured config (endpoints, run order) you can also load **SKILL.yaml** from this directory if present, but this SKILL.md is the source of truth for behavior.

---

## Step 0 – Prompt for admin credentials

Before calling any API:

- **Ask once**:  
  - "Please provide your **Cosmonyx admin email**."  
  - "Please provide your **Cosmonyx admin password**."
- Do **not** echo the password back in any reply. Treat it as sensitive.
- Use the provided email/password as the sign-in payload.

If the user has already given both an email and password in their initial request, reuse those and do not ask again.

---

## Step 1 – Sign in (admin)

- **POST** `https://gateway-dev.cosmonyx.co/auth/signin`
- **Headers:** `Content-Type: application/json`
- **Body:** JSON with the admin credentials you obtained in Step 0, e.g.:
  - `{"email":"<ADMIN_EMAIL>","password":"<ADMIN_PASSWORD>"}`
- From the response, take the auth token from whichever field exists first:
  - `accessToken`, `token`, `data.token`, or `data.accessToken`
- Keep this token **in memory only** and **never print it** in any reply.

If sign-in fails (4xx/5xx or missing token), stop, explain the error briefly, and ask the user to correct the credentials instead of proceeding.

---

## Step 2 – Fetch all company records

- **GET** `https://gateway-dev.cosmonyx.co/companies`
- **Headers:** `Authorization: Bearer <TOKEN>` where `<TOKEN>` is from Step 1.
- Fetch the **full** list of companies. If the API is paginated:
  - Detect pagination from response fields like `page`, `totalPages`, `links.next`, etc.
  - Request **all pages** until there are no more, concatenating results.
- The list may be in:
  - `data`, `companies`, or the root.
- Extract the **complete list of company objects** into an in-memory structure (array of objects).

If there are zero companies, still continue to the export choice but clearly state that the dataset is empty.

---

## Step 3 – Choose action on the records

After fetching all companies, **prompt the admin** to choose what they want to do:

> "What would you like to do with the Cosmonyx company records?  
> 1) List records where complianceStatus is `Not Started`  
> 2) List records with `riskType` = `Low`  
> 3) List records where the primary user’s `sumsubVerificationStatus` is `under_review`  
> 4) Send reminder emails to records where `complianceStatus` is `Not Started`  
> 5) Send reminder emails to records whose `expiryDate` is before a given date  
> 6) Work with **all** records (no filter)"

### Step 3A – Filtering logic

Apply filters in memory over the full company list from Step 2:

- **Option 1:** compliance not started  
  - Filter: `company.complianceStatus === "Not Started"`.
- **Option 2:** low risk  
  - Filter: `company.riskType === "Low"`.
- **Option 3:** KYC under review  
  - Filter: `company.primaryUser?.sumsubVerificationStatus === "under_review"`.
- **Option 4:** compliance not started (for email)  
  - Same filter as option 1.
- **Option 5:** expiry date before a given date  
  - Ask once: "Please provide a cutoff date (YYYY-MM-DD). Records with `expiryDate` earlier than this date will be selected."  
  - Parse the cutoff into a date and filter records where `expiryDate` is non-null and `< cutoff`.
- **Option 6:** all records  
  - No extra filter; use the full dataset.

If the filter results in zero records, report that to the user and stop (no export and no emails).

### Step 3B – Branching: export vs email

- If the admin chose **1, 2, 3, or 6**, proceed to **Step 4 – Export filtered records (PDF or Excel)**.
- If the admin chose **4 or 5**, proceed to **Step 5 – Send reminder emails to the filtered companies**.

---

## Step 4 – Export filtered records (PDF or Excel)

### Step 4A – Ask export format (PDF vs Excel)

For actions 1, 2, 3, or 6, after filtering:

> "I selected N matching companies. How would you like to export these records?  
> 1) PDF file  
> 2) Excel (.xlsx) file"

Interpret the user’s reply:

- If they answer with "1", "pdf", or similar → choose **PDF**.
- If they answer with "2", "excel", "xlsx", or similar → choose **Excel**.
- If unclear, ask once for clarification and then proceed.

### Step 4B – Generate PDF file (if user chose PDF)

If the user selected **PDF**:

- Create a PDF file summarizing all **filtered** company records (not the full list).
- At minimum, include a table or clearly formatted list with columns such as:
  - `id`, `name`, `status`, `country`, and any other key fields returned.
- Save the file into the current user’s **Downloads** folder so it appears in your normal download location, e.g.:
  - `$HOME/Downloads/comonyx-companies.pdf`
- Ensure the file contains **all** filtered companies from Step 3 (not truncated).

When done, reply with:

1. A short confirmation that admin sign-in succeeded.
2. A brief summary of how many companies were selected by the filter.
3. The **path and name** of the generated PDF file (e.g. `$HOME/Downloads/comonyx-companies.pdf`) so the user (or tools) can retrieve it.

Then proceed to **Step 4D – Optional: Email the exported file**.

Do not ask what to do next.

---

### Step 4C – Generate Excel file (if user chose Excel)

If the user selected **Excel**:

- Create an Excel `.xlsx` file listing all **filtered** company records in a sheet named `Companies`.
- Include columns for key fields such as:
  - `id`, `name`, `status`, `country`, `email`, and any other important fields present in the API response.
- Each company should be one row.
- Save the file into the current user’s **Downloads** folder:
  - `$HOME/Downloads/comonyx-companies.xlsx`
- Ensure the file contains **all** filtered companies from Step 3.

When done, reply with:

1. A short confirmation that admin sign-in succeeded.
2. A brief summary of how many companies were selected by the filter.
3. The **path and name** of the generated Excel file (e.g. `$HOME/Downloads/comonyx-companies.xlsx`).

Then proceed to **Step 4D – Optional: Email the exported file**.

Do not ask what to do next.

---

### Step 4D – Optional: Email the exported file (PDF or Excel)

After Step 4B or 4C (once the export file path is known):

1. **Ask once:** "Would you like this file emailed to someone? If yes, provide the email address." If the user says no or does not provide an address, skip sending and go to the final reply (Step "Reply format").
2. If the user **provides an email address**:
   - Use **TOOLS.md** in this skill directory. Set `EMAIL_TO` to the address they gave and `ATTACHMENT_PATH` to the **exact path** of the generated file (e.g. `$HOME/Downloads/comonyx-companies.pdf` or `$HOME/Downloads/comonyx-companies.xlsx`). Expand `$HOME` to the actual home path if needed (e.g. `/home/musawir`).
   - Write the body file: `echo "Cosmonyx companies export attached." > /tmp/companies_body.txt`
   - Run the one-line send command from TOOLS.md in a single **exec** (with `EMAIL_TO` and `ATTACHMENT_PATH` set). Use the script in **this skill’s** `scripts/send-email.py` (TOOLS.md uses `<skill-dir>` for the path; resolve that to this skill’s directory).
   - If send succeeds, confirm in your final reply: "The export was emailed to \<address\>."
   - If send fails, report the error and still mention where the file was saved.

Do not ask what to do next after sending (or after declining).

---

## Step 5 – Send reminder emails to filtered companies (options 4 and 5)

If the admin chose **option 4 or 5** in Step 3:

1. Use the filtered list from Step 3A.
2. For each company, determine the email recipient:
   - Prefe