Etsy listing optimizer: local-only review and owner-approved edits for one shop
A local app for a single shop owner: cached listing review, rule-based insights, optional AI advice, and explicit approval of each title and description before anything is written to Etsy.
Key facts
- 5Scoring factorsWeighted factors in the repository configuration
Context and problem
A shop owner needs to keep listing titles, tags and descriptions current, which is slow by hand. I built a local app that reviews listings, ranks opportunities and drafts advice, while the owner stays in control of every change. It is used by one shop owner, who agreed to this write-up. The shop stays unnamed.
Constraints
- One owner, one shop, running on a single Mac.
- Local-only persistence in app-managed files, with no cloud runtime dependency.
- Secrets and local data are excluded from version control.
Architecture
How to read it. Read left to right, then down. A manual refresh pulls listings and public signals into a local cache, and rule-based scoring ranks opportunities with no AI involved. Optional AI advice runs only when the owner asks. The highlighted box is the approval step: nothing is written to Etsy until the owner approves that listing.
The owner connects Etsy through OAuth and triggers a manual refresh. The app syncs the shop’s listings into a local JSON cache and pulls public-attention signals from open data sources. Deterministic scoring ranks opportunities from five weighted factors: product-topic relevance, event proximity, public-attention momentum, marketplace demand and competition, and tag and description staleness. The owner reviews everything in a local dashboard. The stack is Express 5 and TypeScript.
Decisions and trade-offs
- Local JSON store. The repository’s install notes say JSON was chosen to avoid native database installs, with SQLite as a later upgrade.
- Deterministic scoring, no AI. Refresh, scoring and page loads never call a model. AI runs only when the owner clicks the advice button.
- Manual refresh. Refresh is owner-triggered, with a default of one run per day.
Governance and cost
Every title and description change needs explicit per-listing approval from the owner before anything is written to Etsy, and only those two fields can be written. The write path refuses to run without the right Etsy authorization. Etsy tokens are stored encrypted on the machine. AI is optional and off by default. The advisory prompt tells the model it is read-only and must not claim an update was applied. Cost is bounded by owner-initiated calls, a default of one run per day and a default maximum of 20 recommendations per run.
Outcome
In use by one shop. The repository is public. I make no claim here about sales or ranking results.
What comes next
The next step is a persistence upgrade from the JSON file to SQLite, which the install notes already name as the intended path.