Independent build

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.

Designer and builder · E-commerce · In use

  • Etsy API
  • TypeScript
  • Express
  • Gemini

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

Architecture

Etsy listing optimizer: local data flow with owner approvalThe owner connects Etsy and triggers a manual refresh. Listings and public signals go into a local JSON cache, deterministic scoring ranks opportunities, the owner reviews them in a local dashboard, optionally requests AI advice, and approves each title and description edit before anything is written to Etsy.OwnerTriggers refreshEtsy APIOAuth, tokensencryptedLocal JSON cacheListings, signalsRule-based scoringNo AI in this stepLocal dashboardReviewOpen dataPublic-attentionsignalsAI adviceOptional, on requestOwner approvalPer listing

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

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.

Questions and next steps

Danilo Salazar · Origo Solutions