Kitchen ticket personalizzato su una stampante Star cloud

I want a small web service that prints a custom kitchen ticket for every order I receive on storekit, on a Star CloudPRNT receipt printer that I own. It runs unattended in a restaurant kitchen, so it has to be reliable and boring: it must never print an order twice, never lose an order if it restarts, and never make storekit wait.

Two things talk to this service: storekit (sending me orders by webhook) and my Star printer (polling for jobs). Nobody else uses it, apart from me checking an admin page occasionally.

Build it with a database so the queue and the history survive restarts and redeploys. It needs an always-on public HTTPS URL.

CONTEXT ABOUT STOREKIT

I run a hospitality business on storekit (storekit.com), an online ordering and payments platform for restaurants, cafés and bars. storekit can notify my own app about things that happen in my store by sending webhooks.

How storekit webhooks work:
- Each event is an HTTP POST with a JSON body to a URL I register in the storekit dashboard.
- The body has the shape { "event": "<event type>", "data": { ... } }. Two exceptions: the legacy order.created event (do not use it; use order.created.v2) sends the bare order object, and the order.refund.created / order.refund.succeeded / order.refund.failed events put order, customer, venue and refund next to event instead of inside data.
- Requests are signed with Svix. Every request carries the headers svix-id, svix-timestamp and svix-signature. Verify them with the official `svix` library for your language, using a secret I will provide in an environment variable called STOREKIT_WEBHOOK_SECRET. Reject anything that fails verification with HTTP 400.
- My endpoint must respond with a 2xx status within 15 seconds. Save the event to the database first, respond 200, then do the work from the saved copy.
- Once I have responded 200, storekit will not send that event again, so the work must not be lost: store each event with a status (pending, done, failed) and only mark it done after the work has actually succeeded. On startup and on a timer, pick up anything still pending or failed and retry it. Never do the work only in memory after responding.
- The same event can occasionally be delivered more than once. Use the svix-id header as the unique key for the saved event: a repeat of an event already saved is ignored, whatever its status.
- Any page or endpoint protected by a password must be served over HTTPS only; redirect or refuse plain HTTP.
- Money fields (total, tip, deliveryFee, discountTotal, item price, modifier price) are integers in minor units: 2500 means £25.00.
- orderType is one of Delivery, Pickup, InStore, Curbside, CateringDelivery, CateringPickup or Billpay.
- table is only present for in-store orders; deliveryAddress and pickUpTime only for delivery orders. When they do not apply the key is omitted, so treat a missing key the same as null. notes and items[].note can be null or empty. customer.companyName and customer.vatNumber appear only when supplied.

Example order.created.v2 payload:

{
  "event": "order.created.v2",
  "data": {
    "id": "ord_abc123",
    "code": "A1B2",
    "asap": true,
    "total": 2500,
    "tip": 250,
    "deliveryFee": 299,
    "discountTotal": 0,
    "orderType": "Delivery",
    "pickUpTime": "2024-01-15T10:45:00Z",
    "channel": "WEB",
    "poNumber": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "deliveryTime": "2024-01-15T11:00:00Z",
    "notes": "Ring doorbell",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+44123456789",
      "marketingConsent": true
    },
    "items": [
      {
        "name": "Margherita Pizza",
        "printName": "Margherita",
        "price": 1200,
        "quantity": 1,
        "plu": null,
        "posId": null,
        "taxRate": 20,
        "note": null,
        "modifiers": [
          { "name": "Extra cheese", "printName": "Cheese", "price": 150, "quantity": 1, "plu": null, "posId": null, "taxRate": 20 }
        ]
      }
    ],
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "123 Main St",
        "street2": "",
        "city": "London",
        "postCode": "W1A 1AA",
        "country": "UK",
        "companyName": "My Restaurant Ltd",
        "coordinates": { "latitude": 51.5074, "longitude": -0.1278 }
      }
    },
    "deliveryAddress": {
      "street1": "456 Oak Ave",
      "street2": "Flat 2",
      "city": "London",
      "postCode": "E1 6AN",
      "country": "UK",
      "notes": null,
      "coordinates": { "latitude": 51.5155, "longitude": -0.0722 }
    }
  }
}

The full list of event types and payloads is at https://storekit.com/docs/developers/webhooks/webhook-events

THE PRINTER: STAR CLOUDPRNT PROTOCOL

My printer is a Star Micronics printer with CloudPRNT. I will type this service's URL into the printer's configuration page, and the printer will then poll it. Implement the server side of Star's CloudPRNT HTTP protocol at the path /cloudprnt/<PRINTER_TOKEN>, where PRINTER_TOKEN is a long random secret from an environment variable. Tickets contain customer details, so any request to /cloudprnt whose token segment does not match must get 404 and nothing else. Below I write /cloudprnt for short; always include the token segment.

- The printer POSTs a small JSON status object to /cloudprnt every few seconds. Respond with JSON. When there is nothing queued respond { "jobReady": false }. When there is a job respond { "jobReady": true, "mediaTypes": ["text/plain"], "jobToken": "<id of the job>", "deleteMethod": "DELETE" } — only ever hand out the job at the front of the queue.
- The printer then GETs /cloudprnt?type=text/plain&token=<jobToken> (it may also send mac or uid query parameters; ignore them). Respond with the ticket body as plain text, Content-Type text/plain. GET must be repeatable: return the same job again if asked, do not remove it from the queue.
- After printing, the printer sends DELETE /cloudprnt?token=<jobToken>&code=<result>. The code is a URL-encoded result: "200 OK" (or a code starting with 2) means it printed — mark the job printed and remove it from the queue. Any other code means the printer could not print it — mark the job "failed" with that code, remove it from the queue so the printer is not stuck on it, and leave it in the admin page so I can reprint it. DELETE must be idempotent: a repeat for a job already confirmed is fine, respond 200.
- Never automatically re-queue a job the printer has fetched but not confirmed: the printer may have printed it and only lost the confirmation, and re-queueing would print it twice. Keep it in a "printing" state under its original token. If it has been in that state for more than 2 minutes, show it as "unconfirmed" in the admin page with a Reprint button, and let me decide.
- Keep the whole poll cycle under a second; the printer polls constantly.
- Star publishes the protocol at https://star-m.jp/products/s_print/sdk/StarCloudPRNT/manual/en/protocol-reference/index.html — follow it where it differs from my summary.

Use plain text jobs. Take the line width from a COLUMNS environment variable: 48 for an 80 mm thermal printer (TSP100IV, mC-Print3), 42 for an SP742, or 32 for a 58 mm printer (mC-Print2), in the printer's default font. Every rule below that says 48 means COLUMNS. Use only ASCII characters. End every ticket with six blank lines so the paper feeds far enough to tear off.

WHAT TO BUILD

1. POST /webhooks/storekit — the storekit endpoint. Verify the Svix signature using the official svix library and the STOREKIT_WEBHOOK_SECRET environment variable, against the raw request body. Return 400 if verification fails. Return 200 immediately once the event is saved, before rendering or printing anything. Ignore any svix-id you have already saved. Handle the event type order.created.v2; store and acknowledge any other event type but do nothing with it.
2. A renderer that turns an order.created.v2 payload into a ticket using MY TICKET LAYOUT below, and adds the ticket to the print queue.
3. The /cloudprnt endpoints described above, backed by the queue in the database.
4. GET /admin — a single page, protected by HTTP basic auth using ADMIN_PASSWORD, listing the last 50 tickets with order code, time, status (queued / printing / unconfirmed / printed / failed with the printer's code) and a Reprint button that queues the same ticket again. At the top, show when the printer last polled and a green/red indicator: red if it has not polled in the last 60 seconds. Also a Print test ticket button that queues a ticket with fake data so I can check the layout without a real order.
5. GET /health that returns 200 and { "ok": true } and nothing else; keep the queue length and last poll time on /admin only.

MY TICKET LAYOUT

Render every ticket exactly like this. Lines are COLUMNS characters wide (48 in the examples). Centre text where shown. Use rows of = and - characters as separators. Where I write UPPER CASE below I mean print it in upper case.

- Line 1: a full row of =
- Line 2: the order code (data.code) centred, printed on its own line and repeated on the next line so it stands out (my printer cannot do large fonts in plain text, so repetition is the emphasis).
- Line 3: the order type, centred, mapped exactly like this: Delivery -> "DELIVERY", CateringDelivery -> "CATERING DELIVERY", Pickup -> "PICKUP", CateringPickup -> "CATERING PICKUP", Curbside -> "CURBSIDE", InStore -> table.name in upper case (e.g. "TABLE 5") or "IN STORE" if table is null, Billpay -> "BILL PAYMENT", anything else -> the raw value in upper case. For Delivery and CateringDelivery, then print on following lines the delivery address (deliveryAddress.street1, street2 if not empty, postCode) and customer.phone.
- Line 4: "Ordered <HH:MM>" from createdAt in the venue's local time. If asap is false, add "FOR <HH:MM>" from deliveryTime on the same line, right-aligned. If asap is true, add "ASAP" instead.
- Line 5: a full row of -
- Then the items. For each item: quantity, space, item name in upper case, e.g. "2  MARGHERITA". Underneath, each modifier indented by five spaces with a leading "- " e.g. "     - Extra basil". If an item has a notes field with text in it, print it indented under its modifiers prefixed with "** ". One blank line between items.
- Then a full row of -
- If data.notes or any item's notes contains the word "allergy" or "allergic" (any case), print three lines: a row of !, then "!!  ALLERGY - SEE NOTES  !!" centred, then a row of !. Then print data.notes in full when present, wrapped to 48 characters. If data.notes is present but nothing mentions allergies, print "Notes:" followed by the wrapped notes. If there are no order notes, print nothing else here.
- Then a full row of -
- Then the customer's first name and last initial only ("Jane D."), the item count ("3 items") and the total formatted from minor units with the currency code from a CURRENCY environment variable ("Total 25.00 GBP"). Do not guess a default: if CURRENCY or TIMEZONE is unset, refuse to start and log a clear message. No email, no full surname.
- Last line: a full row of =, then six blank lines.

DEFINITION OF DONE

- [ ] A signed order.created.v2 event queues exactly one ticket, and returns 200 in under one second.
- [ ] The same event sent twice queues one ticket, not two.
- [ ] A request with a bad signature returns 400 and queues nothing.
- [ ] /cloudprnt returns jobReady false when the queue is empty and hands out one job at a time when it is not. A wrong PRINTER_TOKEN gets 404.
- [ ] A DELETE with a non-success code marks the job failed, not printed, and it can be reprinted from /admin.
- [ ] A job fetched but never confirmed is shown as unconfirmed, and is not printed again unless I click Reprint.
- [ ] Restarting the service does not lose queued or historical tickets.
- [ ] /admin shows tickets, printer status and allows reprints and a test ticket.
- [ ] The example payload in the context renders with a PICKUP line, "1  MARGHERITA PIZZA", "Notes: Ring doorbell", "John D." and "Total 25.00 GBP", and no allergy banner.
- [ ] A payload whose notes read "Severe nut allergy" renders the allergy banner.

WHAT TO GIVE ME WHEN YOU ARE DONE

1. The public URL of the service, and the exact two URLs I will paste: the storekit webhook URL (…/webhooks/storekit) and the printer URL (…/cloudprnt/<PRINTER_TOKEN>).
2. The environment variables I must set (STOREKIT_WEBHOOK_SECRET, ADMIN_PASSWORD, PRINTER_TOKEN, COLUMNS, CURRENCY, TIMEZONE for the venue's local time, and anything else you added) and where to set them on this platform.
3. How to confirm it is running always-on, not sleeping between requests.
4. A one-paragraph explanation of how to test it end to end before I connect the real printer.