Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 113 additions & 72 deletions README.md

Large diffs are not rendered by default.

19 changes: 19 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Documentation

Start with the [README](../README.md) for the short version. This directory has the rest.

| Doc | What's in it |
|---|---|
| [install.md](install.md) | Requirements, install and enable, the settings that matter, first steps, phones |
| [usage.md](usage.md) | The Inventory view tab by tab, and every flow: scanning, labels, put away, pricing, drafts, sales, packing |
| [how-it-works.md](how-it-works.md) | The data model, money in cents, the audit trail, the agent turns the plugin starts, labels and their public links |
| [configuration.md](configuration.md) | Every setting under **Settings → Plugins → Inventory**, with its default |
| [tools.md](tools.md) | Every agent tool |
| [api.md](api.md) | Every HTTP route: the bearer-gated operator surface and the public routes |
| [design-decisions.md](design-decisions.md) | The reasoning behind the main design choices |
| [development.md](development.md) | Layout, tests, the view harness, releasing |
| [upgrading.md](upgrading.md) | Version notes that change behavior |
| [design/](design/) | The Inventory view redesign spec |

ADRs cited in these pages are protoAgent's, and live in
[protoAgent's `docs/adr/`](https://github.com/protoLabsAI/protoAgent/tree/main/docs/adr).
136 changes: 136 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# HTTP API reference

Every route here is real and comes from `api.py` and `view.py`. `tests/test_docs_reference.py` fails if a
route is added, removed or renamed without this page changing. Money is in dollars in requests and
responses.

There are two surfaces with different authentication, on purpose.

## Operator surface: bearer token

Mounted under `/api/plugins/inventory`. The console view and anything you script use these. They need the
instance's operator bearer token, which the view gets from the console's handshake:

```bash
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7870/api/plugins/inventory/summary
```

Through a fleet hub, prefix the path with `/agents/<agent-id>`.

### Lots, items and prices

| Method | Path | What it does |
|---|---|---|
| `GET` | `/summary` | The P&L per lot and in total: cost, remaining at low/target/high, realized gross and net, projected net |
| `GET` | `/lots` | Every lot |
| `PUT` | `/lots/{lot_id}` | Create or update a lot. Only the fields sent change |
| `DELETE` | `/lots/{lot_id}` | Delete a lot. Refused while it has items unless `cascade=true`, which snapshots each removed item into the audit trail |
| `GET` | `/lots/{lot_id}/split-check` | Sealed vs split for a lot whose pieces are all still planned |
| `GET` | `/systems` | The game systems in use, for the system picker |
| `GET` | `/conditions` | The condition suggestions plus every condition in use |
| `GET` | `/items` | Items, filtered by lot, status, category, system, bin or a text search |
| `POST` | `/items` | Create an item |
| `GET` | `/items/{item_id}` | One item with its listings, sales and price observations |
| `PUT` | `/items/{item_id}` | Update an item's fields. Setting sold here is refused: record a sale instead |
| `DELETE` | `/items/{item_id}` | Delete an item and its listings, sales and observations (snapshotted into the audit trail) |
| `POST` | `/items/{item_id}/price` | Set the price band. A `basis` is required, and the comps evidence is stored with it |
| `GET` | `/stale` | Listings live longer than `listed_days` and prices older than `price_days` (default: the Stale price setting) |
| `GET` | `/aging` | Unsold items past an aging tier, oldest first, each with the basis its days count from |
| `POST` | `/items/{item_id}/snooze` | Hide an item from Aging stock for 14 days (audited) |
| `PUT` | `/items/{item_id}/shipping` | Set packed weight, box size and packaging preset |
| `GET` | `/view-config` | The settings the view needs: the stale-price days and the aging tiers |

### Selling

| Method | Path | What it does |
|---|---|---|
| `POST` | `/items/{item_id}/sold` | Record a sale (the same rules as `inventory_mark_sold`) |
| `GET` | `/sales` | Sales, optionally for one lot |
| `POST` | `/items/{item_id}/listings` | Record a live listing on a channel |
| `POST` | `/listings/{listing_id}/end` | End a listing, including one flagged `needs_end` ("I ended it") |
| `GET` | `/listings/to-end` | The double-sell guard: listings still up somewhere for items that sold elsewhere |
| `GET` | `/to-pack` | Sales not yet packed, grouped by the bin to pull from |
| `POST` | `/sales/{sale_id}/packed` | Mark a sale packed. An item with no stock left leaves its bin |
| `GET` | `/sale-pastes` | Pasted sales waiting to be checked |
| `POST` | `/sale-pastes` | Paste an order or a note. Starts one agent turn that reads it |
| `GET` | `/sale-pastes/{paste_id}` | One paste with its proposal |
| `POST` | `/sale-pastes/{paste_id}/retry` | Read a failed paste again |
| `POST` | `/sale-pastes/{paste_id}/record` | Record the checked lines, one audited sale each |
| `DELETE` | `/sale-pastes/{paste_id}` | Discard a paste (it's kept, marked discarded) |

### Listing drafts

| Method | Path | What it does |
|---|---|---|
| `GET` | `/drafts` | Every item's draft state |
| `GET` | `/items/{item_id}/draft` | One item's draft |
| `POST` | `/items/{item_id}/draft` | Ask for a draft. Starts one agent turn |
| `POST` | `/drafts/bulk` | Draft several items, one turn after another, at most 10 per request |
| `POST` | `/items/{item_id}/draft/copied` | Note that you copied the draft |
| `POST` | `/items/{item_id}/draft/sku-updated` | Note that you updated the Custom label on eBay after a bin move |
| `POST` | `/items/{item_id}/draft/live` | "I listed it": the eBay item address records a listing and marks the item listed |
| `GET` | `/items/{item_id}/photos.zip` | The item's photos in listing order, cover first |

### Scans

| Method | Path | What it does |
|---|---|---|
| `GET` | `/scans` | Open scans (or all with `open=false`) |
| `POST` | `/scans` | Start a scan: a `box` (with what you paid, which starts its lot) or a `unit` |
| `GET` | `/scans/{scan_id}` | One scan with its proposal |
| `POST` | `/scans/{scan_id}/photos` | Upload a photo (the raw image as the body, 20 MB at most). Starts identification |
| `GET` | `/scans/{scan_id}/photos/{photo_id}` | One stored photo |
| `POST` | `/scans/{scan_id}/retry` | Identify again |
| `POST` | `/scans/{scan_id}/confirm` | Confirm the name and Keep or Sell for each piece; writes the items |
| `POST` | `/scans/{scan_id}/price` | Price the sell pile. Starts one agent turn |
| `POST` | `/scans/{scan_id}/sell-sealed` | Replace the planned pieces with one sealed item at the sealed price |
| `POST` | `/scans/{scan_id}/finish` | Finish the scan |
| `DELETE` | `/scans/{scan_id}` | Discard a scan, its photos and an empty lot it started |

### Bins and labels

| Method | Path | What it does |
|---|---|---|
| `GET` | `/bins` | Every bin with its count, unsold value and when it was last checked |
| `POST` | `/bins` | Create bins |
| `PUT` | `/bins/{bin_id}` | Change a bin's label or note |
| `DELETE` | `/bins/{bin_id}` | Delete an empty bin |
| `POST` | `/bins/move` | Move items into a bin. `put_away: true` also makes a planned piece available |
| `POST` | `/bins/{bin_id}/check` | Save a bin check: strays to move in, unscanned items to flag missing |
| `POST` | `/items/{item_id}/found` | Clear an item's missing flag |
| `GET` | `/labels/base` | Where label QR codes point, and the label stocks |
| `POST` | `/labels/sheet` | Build a label sheet for bins or items, record what was printed, and return a short-lived link to it |

### Packaging

| Method | Path | What it does |
|---|---|---|
| `GET` | `/packaging` | Your packaging presets |
| `POST` | `/packaging` | Add a preset: name, length/width/height in inches, empty weight |
| `PUT` | `/packaging/{packaging_id}` | Change a preset |
| `DELETE` | `/packaging/{packaging_id}` | Delete a preset |

### Data

| Method | Path | What it does |
|---|---|---|
| `GET` | `/audit` | The audit trail, newest first, optionally for one entity |
| `POST` | `/import` | Import CSV text (items or lots). Re-import never clobbers |
| `GET` | `/export` | Export items, lots or sales as CSV |

## Public surface: no token

Mounted under `/plugins/inventory`. The console frames the view with a plain navigation, and a phone opens
labels from a printed QR, so neither can carry a bearer token. None of these routes reads inventory data.
The host exempts them because the manifest lists them under `public_paths` (the view is exempt because it's
a declared view).

| Method | Path | What it does |
|---|---|---|
| `GET` | `/view` | The console view's page. Its data comes from the operator surface |
| `GET` | `/b/{bin_id}` | A bin label's landing page. A browser signed in to this console goes straight to the bin; anyone else sees how to open it in the app. The same response for a bin that exists and one that doesn't |
| `GET` | `/i/{item_id}` | An item label's landing page, the same way |
| `GET` | `/sheet/{token}` | A label sheet by its 15-minute token, for printing in the browser. An unknown or expired token answers a short page with no data |

The landing pages and sheets are sent with `Cache-Control: no-store`, `Referrer-Policy: no-referrer` and
`X-Robots-Tag: noindex`.
Binary file added docs/assets/hero.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/phone-next.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
69 changes: 69 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Configuration

Most settings are in **Settings → Plugins → Inventory**. In YAML they sit under `inventory:` in your
agent's `config/langgraph-config.yaml`. One key, `db_path`, is YAML-only. The plugin has no secrets.

`tests/test_docs_reference.py` fails if the manifest gains or drops a key without this page changing.

```yaml
plugins:
enabled: [inventory]
inventory:
workspace_dir: /path/to/agent/workspace
weekly_review: true
review_timezone: America/Los_Angeles
```

## Where things live

| Key | Default | In Settings | What it does |
|---|---|---|---|
| `db_path` | `""` | no | Where the SQLite file lives. Blank uses the host's instance-scoped plugin store, so every agent and the dev sandbox get their own database. Set it only to point at an existing file. Scan photos are kept beside the database |
| `workspace_dir` | `""` | Workspace directory | Relative paths given to `inventory_import_csv` and `inventory_export_csv` resolve here. Blank uses the process working directory. Point it at the agent workspace |

## Weekly review

A recurring agent turn the plugin schedules on the host. It re-prices stale evidence from eBay sold comps,
reports stale listings with a recommendation (it never changes a listing itself) and ends with the per-lot
P&L. Turning the plugin off cancels it.

| Key | Default | In Settings | What it does |
|---|---|---|---|
| `weekly_review` | `false` | Weekly review | Arms the recurring turn |
| `weekly_review_cron` | `"0 9 * * 1"` | Weekly review cron | A 5-field cron, read in the review timezone. The default is Monday 09:00 |
| `review_timezone` | `""` | Review timezone | An IANA name such as `America/Los_Angeles`. Blank means UTC |
| `review_max_items` | `15` | Items re-priced per run | The most items one run re-prices. This paces eBay searches; the rest wait for the next run |
| `stale_listing_days` | `14` | Stale listing (days) | A live listing older than this is reported in the review |

## Stale prices and aging stock

| Key | Default | In Settings | What it does |
|---|---|---|---|
| `stale_price_days` | `30` | Stale price (days) | Price evidence older than this is stale. The weekly review re-checks it, the view badges it and Next ▸ Housekeeping counts it. Bounded 1 to 365 |
| `aging_days_1` | `45` | Aging: first nudge (days) | Days unsold before Next ▸ Aging stock suggests an offer to watchers or a 10% drop. Bounded 1 to 730 |
| `aging_days_2` | `90` | Aging: second nudge (days) | Days before it suggests another 10% drop or a bundle |
| `aging_days_3` | `120` | Aging: decide (days) | Days before it asks you to decide: clearance, bundle or pull it |

The three aging tiers are sorted if you set them out of order. A missing or bad value falls back to its
default.

## Labels

| Key | Default | In Settings | What it does |
|---|---|---|---|
| `label_base_url` | `""` | Bin label address | The address printed in every label's QR code, up to (not including) `/plugins/inventory`, for example `https://hub.example.ts.net/agents/<agent-id>`. Blank works it out: the agent's public URL (a fleet member's hub address), else its console. A malformed value is refused rather than guessed around |

Labels you've already printed keep the address they were printed with, so set this before your first
sheet.

## Scan intake

| Key | Default | In Settings | What it does |
|---|---|---|---|
| `scan_confidence_threshold` | `0.7` | Scan: sure enough at | 0 to 1. Below this, a scan shows "Not sure. Pick one or type it" with the agent's other guesses instead of offering Looks right |
| `scan_timeout_minutes` | `10` | Scan: give up after (minutes) | An identification that hasn't answered by then shows as failed, with Retry. Pricing gets three times as long |

## Kept in the browser, not in Settings

The label stock you last printed on is remembered per kind (bin or item) in the browser's `localStorage`,
because it's about the printer next to you, not the agent.
98 changes: 98 additions & 0 deletions docs/design-decisions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Design decisions

Why Inventory is built the way it is. What it does is in [how-it-works.md](how-it-works.md).

## One database is the record, not a spreadsheet

The inventory started as CSVs in an agent's workspace. They drifted: two copies of a sheet disagreed, a price
lost the reason it was set, and a sale typed into chat never reached the sheet. A record is only a record if
every change goes through one place with a history, so the plugin owns a SQLite file, every write is one
transaction, and every change is audited with who made it. Spreadsheets stay as import and export.

## A re-import never clobbers

Importing a sheet again fills in what's new and leaves the rest alone. A blank cell keeps the current value. A
sheet can't walk a status back from listed, pending or sold, and a sheet without ids matches rows by lot and
name. An old export dropped back in shouldn't undo a week of work.

## Money in cents, parsed strictly

Floats round wrong, and loose parsing reads `54%` as $54 and `2026-07` as $2,026. Amounts are stored as
integer cents, and anything that isn't clearly an amount is refused rather than guessed.

## A price without a reason isn't a price

The first estimates on real stock came from active asks and retail, presented as if they were sold prices.
So a target can't be set without a basis, the comps are stored with it in the same write, and a price that's
gone stale says so. When you ask why something is $54, there's an answer.

## Sold comps from a browser, not an API

eBay's sold-listings data (Marketplace Insights) is closed to new developers, and a seller account's own APIs
need developer keys and OAuth for every agent. The ebay plugin reads sold listings in a signed-in browser
instead. It's slower and it's paced, but it needs nothing but your own eBay login.

## Nothing posts for you

There's no eBay write access. A listing draft is text you paste, a pasted sale is a proposal you check, and
the weekly review reports stale listings without touching them. Listing, pricing in public and contacting
buyers stay your decisions. It also keeps a wrong guess from ever reaching a marketplace.

## Sold only through a sale record

An item can't be set to sold by editing its status. Recording a sale captures the price, shipping, fees and
postage that make the P&L true, closes the right listing, and puts the item on the pick list. Every way into
"sold" goes through that one path.

## The double-sell guard flags instead of closing

When an item sells on one channel while it's listed on another, quietly closing the other listing would leave
it live on the marketplace with nobody knowing. So the listing is flagged `needs_end` and stays on Next until
you've ended it there.

## The plugin's turns are its own, and narrow

Identifying a box, writing a draft and reading a pasted sale each run in a session of their own, never your
chat, so they can't clutter it or read it. Each has a short tool list and hard limits (no eBay where it isn't
needed, no subagents, a cap on web searches), because an early pricing session that leaned on general web
search ran to hundreds of tool calls and several dollars for a single lot.

## The agent never invents item facts

A guessed model count once made the agent doubt its own correct comps. So unknown counts stay 0, a box's
contents are what the agent can confirm, an unsure identification offers choices and a typing field, and your
correction is kept on the scan.

## Label first, then put away

Binning used to be the last step of a scan. In practice you sort pieces into bins after they're labelled, and
a piece already in a bin with no label is the one you can't find later. So a scan ends by printing labels, and
a piece goes into a bin by scanning its label and then the bin's.

## The view reads its own labels, because of iOS

iOS never hands a scanned link to a Home Screen web app: a QR read by the Camera app always opens in Safari,
which keeps its own storage and isn't signed in. So the view has **Scan label**, and the public label links
serve a page that sends a signed-in browser straight on and tells anyone else how to open it in the app.

## Labels encode the plugin's address, not the console's

A label's QR points at the plugin's own `/b/` or `/i/` route, which forwards to wherever the console opens
views today. Printed paper can't be updated, so only the plugin's stable address is ever printed.

## A live camera where it's allowed, a photo everywhere

A viewfinder that reads label after label is much faster than a photo per label, and it works where the view
shares an origin with the console. Where it doesn't, or the camera is refused, the phone's own camera and a
photo always work. QR decoding happens in the page, so photos of your shelves never leave it.

## Copy list is the operator's own format

The for-sale post was first built as Markdown with sections and bullets. The operator hand-edited it to what
a group chat actually wants: the game system as a plain header, then `Name NoS — $20` per line, nothing else.
That edit became the format, and a test pins it byte for byte.

## Settings in Settings, not on the view

Thresholds such as stale-price days, aging tiers and scan confidence are Settings, not controls on the work
view. The view stays about the work.
10 changes: 10 additions & 0 deletions docs/design/inventory-view-redesign.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Inventory view redesign: audit and spec

> **Status (0.16.2).** Shipped: the Next / Stock / Bins / Lots IA and the item drawer (0.5.0), bins
> and the pick list (0.6.0), bin labels (0.7.0), scan intake (0.8.0), listing drafts (0.9.0), item
> labels (0.10.0). **Superseded:** the scan flow's S6 bin picker (§3) was replaced in 0.11.0 by
> *label first*: the scan ends with Print labels and pieces are binned later with **Put away**, by
> scanning each piece's label and then the bin's. QR deep links (§4, open question 2) shipped in
> core as protoAgent #4712 (`sdk.view_url`, 0.227.0). Shipped after this spec: paste a sale and the
> double-sell guard (0.12.0), a live camera (0.13.0), aging stock and sealed vs split (0.14.0),
> shipping data, Check a bin and thermal labels (0.15.0), and in-app Scan label (0.16.0). How the
> view works today is in [usage.md](../usage.md); this page is kept as the design record.

Plugin `inventory` 0.4.2, shown as a merchantAgent rail view. Requested by Josh, 2026-11-02.
Status: **approved 2026-11-02.** This repo is public, so dollar figures from the real inventory are redacted to `$NN`, and the interactive preview (built on real data) is not committed.

Expand Down
Loading
Loading