# Playbook: retrieving email-delivered CAD (the JST email dependency)

Some manufacturers (JST since April 2025; others will follow) **email** the
CAD file instead of serving a download. chip-fetcher therefore needs a way to
**read the user's email and pull the attachment**. That capability is
**account-specific**, so it is NOT bundled into chip-fetcher — you wire up the
path that matches the user's email provider. This playbook covers both.

> Decision: **Is the user a Google/Gmail user?**
> → **Yes:** use `adom-google` (below).
> → **No:** they must build a small attachment-fetcher for their provider,
> share it on the wiki, and drop a chip-fetcher breadcrumb (below).

---

## A. Gmail / Google Workspace users → `adom-google`

`adom-google` gives programmatic read access to Gmail (CLI + OAuth, no browser
automation). Adom employees have it out of the box; other orgs self-host an
OAuth gateway or get a managed one (~$5/mo) — see the `adom-google` skill.

**First, confirm it's set up:**
```bash
adom-google status     # should show "Refresh token: present" + gmail scope
```
If not authorized, send the user through `adom-google auth` (ask safe vs full
mode first — read access only needs the default).

**Find the message, list attachments, save the file:**
```bash
# 1) find recent JST mail (NOTE: output has a leading "HTTP 200 …" line — strip it before JSON-parsing)
adom-google api "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
    -q q="JST newer_than:1d" -q maxResults=5

# 2) list attachments on a message id
adom-google gmail attachments <messageId>      # prints "<PART>.zip  <bytes>  id: <attId>"

# 3) write the attachment bytes to disk
adom-google gmail read <messageId> <attId> -o <PART>.zip
```
Gmail search operators that help: `from:`, `subject:`, `has:attachment`,
`newer_than:1h`, `filename:zip`. For a batch, request to a **plus-alias**
(`john+jst@adom.inc`) and add a Gmail **filter** that labels `JST-CAD` and
skips the inbox — the attachments are still readable by `adom-google`, but the
real inbox stays clean. (Create the filter once via the Gmail settings UI or
`adom-google api` against `…/settings/filters`.)

**Pitfall:** IGES and STEP both arrive as `<PART>.zip`. Disambiguate by the
**inner** filename (`.STEP` vs `.IGS`), and always take the **newest**
matching message (you may have requested several formats).

## B. Non-Gmail users → build it, share it, breadcrumb it

If the user is on Outlook/Microsoft 365, Fastmail, a corporate IMAP server,
etc., `adom-google` does not apply. They need a tiny equivalent that:
1. connects to their mailbox (Microsoft Graph API, IMAP, JMAP, …),
2. searches for the manufacturer mail (sender/subject/`has:attachment`), and
3. saves the `.zip` attachment to disk — the same three steps as above.

**Then share it so the next person doesn't reinvent it:**
- Publish it as a small CLI/skill on the wiki (e.g. `adompkg publish`), the way
  `adom-google` is published. Keep secrets local (0600), mirror the
  `attachments` / `read` verb shape so this playbook's steps still read true.
- **Drop a chip-fetcher breadcrumb** so it auto-surfaces from the chip-fetcher
  page: the breadcrumb announces "here's an email-attachment fetcher for
  \<provider\>" without editing chip-fetcher's page. See the
  `wiki-breadcrumbs` skill (`https://wiki.adom.inc/adom/...` breadcrumb API).
  Add a one-line pointer in the chip-fetcher wiki README's "email-delivered
  CAD" section linking to the new tool.

That way chip-fetcher stays provider-agnostic: the email-reading layer is a
pluggable, community-extensible piece, and every new provider integration is
discoverable from the chip-fetcher page via its breadcrumb.

## Where this is referenced

- [`jst.md`](jst.md) step 4 routes here for the retrieval half of the flow.
- The chip-fetcher **wiki sub-README** ("Email-delivered CAD") mirrors this for
  human readers and is where third-party provider breadcrumbs collect.