Journal des ruptures et digest matinal

I want a small web app that keeps a log of every menu item that goes out of stock at my restaurant, and sends a short digest to Slack every morning. storekit tells the app about stock-outs by webhook. The app must never lose an event, never count the same event twice, and never make storekit wait.

Build it with a database so the log survives restarts, an always-on public HTTPS URL, and a scheduled job for the digest.

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 EVENT THIS APP USES: item.out_of_stock

Ignore the order example above; this app only cares about item.out_of_stock, which looks like this:

{
  "event": "item.out_of_stock",
  "data": {
    "venue": { "id": 1234, "name": "My Restaurant" },
    "item": { "id": 5678, "name": "Margherita Pizza", "plu": "PLU-001", "posId": "pos_item_42", "sku": "SKU-MARG-001" },
    "reason": "snoozed",
    "source": "manual",
    "details": { "snoozeEnd": "2024-01-15T18:00:00Z" }
  }
}

- reason is one of: snoozed (temporarily hidden by staff), inventory_depleted (sold out through inventory counts), disabled (switched off).
- source is one of: manual (someone in the dashboard), order (a customer order used the last one), deliverect, lightspeed, zonal, pos_sync (pushed from a till or integration).
- details.snoozeEnd is only present for reason snoozed and can be null, meaning snoozed indefinitely.
- plu, posId and sku can be null.
- There is no "back in stock" event. The app records when things went out; it cannot know when they came back.

WHAT TO BUILD

1. POST /webhooks/storekit — verify the Svix signature with the official svix library and STOREKIT_WEBHOOK_SECRET against the raw request body; 400 on failure. Save the event and return 200 immediately. Ignore any svix-id already saved. Handle item.out_of_stock; save and acknowledge any other event type but do nothing with it.
2. A log table with: received time (store UTC, display in TIMEZONE), venue name, item name, item id, plu, sku, reason, source, snoozeEnd. Record the event's time as the time the webhook arrived.
3. GET / — protected by HTTP basic auth with ADMIN_PASSWORD. Three things on one page:
   a. "Yesterday and today": a list of stock-outs since the start of yesterday in TIMEZONE, newest first, showing time, item, reason and source in plain words ("Snoozed by staff until 18:00", "Sold out through inventory after an order", "Switched off from Zonal").
   b. "Most sold out, last 30 days": items ranked by number of stock-outs, with the count and the most common hour of day it happens.
   c. Filters for venue (if I have more than one), reason and a date range, and a Download CSV button that exports whatever is filtered with the columns from point 2.
4. A daily digest posted to Slack via SLACK_WEBHOOK_URL at DIGEST_TIME (HH:MM in TIMEZONE, default 07:30). Content, in Slack mrkdwn:
   *Sold out yesterday — <venue name>, <date>*
   One line per item, in time order: "14:20  Margherita Pizza — sold out (inventory)" or "18:05  Sea Bass — snoozed by staff until 21:00". Group by venue if there is more than one.
   Then a blank line and "*Most sold out this month*" followed by the top five items with counts.
   If nothing sold out yesterday, post "Nothing sold out yesterday." — still post, so I know the app is alive.
   Post the digest once per day even if the app restarts: record the date of the last digest sent and skip if it has already been sent for that date.
5. A "Send digest now" button on the page for testing, which posts the digest for yesterday regardless of whether it was already sent.
6. GET /health that returns 200 and { "ok": true } and nothing else.

Use TIMEZONE for every day boundary and displayed time. Do not guess a default: if TIMEZONE is unset, refuse to start and log a clear message.

DEFINITION OF DONE

- [ ] A signed item.out_of_stock event appears in the log within a second and the endpoint returned 200.
- [ ] The same event delivered twice creates one row.
- [ ] A bad signature returns 400 and logs nothing.
- [ ] The example payload above shows as "Margherita Pizza — snoozed by staff until 18:00".
- [ ] The digest posts at DIGEST_TIME and not again that day, including after a restart.
- [ ] "Send digest now" posts to Slack immediately.
- [ ] The CSV download opens in a spreadsheet with one row per event and the columns listed.
- [ ] Restarting the app loses nothing.

WHAT TO GIVE ME WHEN YOU ARE DONE

1. The public webhook URL (…/webhooks/storekit) and the page URL.
2. The environment variables to set (STOREKIT_WEBHOOK_SECRET, ADMIN_PASSWORD, SLACK_WEBHOOK_URL, TIMEZONE, DIGEST_TIME) and where to set them on this platform.
3. Confirmation that the app stays up 24 hours a day and that the scheduled job runs when nobody has the page open.