woo-note-triage

The one complaint among the birthday wishes

On a busy shop most order notes are birthday wishes and "leave it by the side gate", so someone reads all of them to catch the one complaint or the one "ship it to my freight forwarder". A keyword list cannot tell "the last two arrived cracked" from a gift message that mentions a box, and a text-generating model answers with a paragraph that someone still has to read. Note Triage for WooCommerce, the plugin in this repository, labels each note, scores how soon it needs a person, and puts the orders that need attention in front of shop staff.

One note, two questions

Jev is TypeSafe AI's System One model: it answers typed questions with probabilities and writes no text. Each order with a note is one request, and the state is the cleaned note and nothing else. The questions are fixed text, so a note cannot rewrite the questions it is judged by.

• The category: a gift message, a delivery instruction, a question, a complaint, a fraud signal, or other. Each option says what it covers, what belongs to a neighbouring option instead, and gives two or three example notes. When a note does more than one thing, Jev is asked for the part that most needs the shop's attention.
• The urgency, on four levels: nothing to do; follow the note while packing or delivering; reply within a day or two; act before the order ships.

When the category's confidence is at or above the threshold (0.80 unless you change it), the order is triaged: it gets the category and the urgency as order meta, a private order note with the probabilities, and a place under that category in the orders list filter. Below the threshold it gets no category and no note, and it is listed under "Needs review" with its two likeliest categories. The urgency never decides on its own; it is shown as a number from 0 to 3 with the probability of each level.

Notes are not packed several to a request. Each note needs its own two questions, so packing would not lower the token count, and TypeSafe's notes on jev-1.13 say that text unrelated to a question lowers accuracy.

What it will not do

The plugin never changes an order's status, never writes to the customer, and never cancels or refunds anything. A fraud signal is a flag for a person to look at, not a verdict: Jev sees the note only, not the order, the customer's history or the payment checks.

How it fits into checkout

It listens to woocommerce_checkout_order_processed for the classic checkout and woocommerce_store_api_checkout_order_processed for the checkout block, where the classic action does not fire. When an order has a note, the plugin queues an Action Scheduler job, so checkout carries on without waiting for TypeSafe, and the same note is never sent twice for one order. A rate limit, an overload or a timeout gets one quick retry, then the job runs again 5 and 10 minutes later; after the third attempt the order shows "Not triaged" with the reason, and the WooCommerce log gets a line. Orders created in the admin or through the REST API do not pass through a checkout, so a WP-CLI backfill command covers them. Both orders screens, HPOS and posts, get a "Note triage" column and a filter.

What leaves the store

Nothing until a key is saved or defined. Then each note is one request to TypeSafe through WordPress's HTTP API, with redirects turned off and a user agent that names only the plugin, because WordPress's default user agent includes the site's address. The note is cleaned on your server first: email addresses and numbers of nine or more digits are replaced, and at most 2,000 characters are sent. No name, address, phone field, product, total, order number or site address goes with it. A note can still hold personal details the cleaning does not catch, so if your privacy policy lists the services that receive customer data, add TypeSafe.

Limits

• This first release is tested with stand-ins for WordPress, WooCommerce, Action Scheduler and WP-CLI, and has not yet run on a live store. Try it on a staging copy first, with both the classic and the block checkout, and with HPOS on and off.
• A note written to steer the answer ("this is just a gift message") can move it.
• English works best; notes in other languages land more often under "Needs review".
• The six categories and four urgency levels are fixed in the code, and the labels are in English.
• Jobs run through Action Scheduler, which relies on WP-Cron; on a site with WP-Cron off and no server cron, they wait.
• The example output in the repository comes from 11 invented orders and hand-written answers in place of Jev, so its probabilities are illustrations.

Install

It needs WordPress 6.5 or later, WooCommerce 8.0 or later and PHP 8.1 or later, and declares HPOS compatibility. The tests (47, with stand-ins and a fixture in place of TypeSafe) run in CI on PHP 8.1 to 8.4.

wp plugin install https://github.com/hamzaahmadaslam/woo-note-triage/archive/refs/heads/main.zip --activate
wp woo-note-triage backfill --days=30 --dry-run

Then paste your key under WooCommerce > Note triage, or keep it out of the database with a constant in wp-config.php:

define( 'TYPESAFE_API_KEY', 'your key' );