Shop Mini backend
Apps/Recipes/Shop Mini backend

Build the backend for a Shop Mini

A Shop Mini runs inside the Shop app and brings its own backend. This one is a web app on Apps: buyers paste a tracking number and watch the parcel cross a 3D globe, hub by hub. The Mini itself is in the app's mini/ folder.

Web, backend onlyKind backendRecipe id parcel-globe

What you'll build

Shop Minia tracking number/api/mini/shipmentsShop token → sessionshipment.creatependingrefreshShip24 and a geocoderGlobethe route, hub by hub

What it shows: A bearer token from another platform turned into a session, a role that scopes every read to one user, courier and geocoder calls kept out of requests, an hourly schedule, and CORS for a page at localhost on any port.

Before you start

  • The CLI: npm i -g @inferencebureau/apps, then ib-apps login once.

Create the app from the recipe

One command creates the app on Inference Bureau and downloads its files into ./my-parcel-globe. Web is the default platform, so the recipe id is all it takes.

ib-apps create my-parcel-globe --recipe parcel-globe

Tour what the recipe loaded

The recipe replaces the starter, keeping the coding-agent guidance. Here's where each piece lives.

WhereWhat's there
web/lib/mini.ts, miniBuyer/, miniSession/The Mini sends Shop's temporary token as a bearer token. buyerOf verifies it with Shop once (userTokenVerify, with SHOP_MINIS_API_KEY), keeps the answer in miniSession under the token's hash until it expires, and knows the buyer by Shop's publicId.
accessControl/permissions.ib.tsThe mini-buyers role: a buyer reads and deletes only their own shipments, and create sets the buyer from the session, whatever the request named.
shipment/actions/refresh.ts, api/lib/A new shipment answers pending and queues refresh, so no request waits on Ship24. Each new event is placed with a geocoder, one call a second, and every place is kept in place, so a hub seen before costs nothing.
settings.ib.ts, api/actions/refreshShipments.tsThe hourly schedule refreshes every parcel not delivered and not checked in the last 50 minutes, and removes expired sessions. cors allows http://localhost:* on /api/mini/*.
mini/src/globe/The globe: land as instanced dots, each route a tube that draws itself with a shader, and drag, spin and turn-to-face in a few lines rather than a package Shop doesn't allow.
tests/parcel-globe.test.tsThe actions, the schedule and the session check, with Ship24, the geocoder and Shop stubbed.
// web/lib/mini.ts (excerpt): the Mini's bearer token is a temporary Shop token. Shop is asked about it once.
const hash = tokenHash(token);
const session = await api.miniSession.findFirst({ filter: { tokenHash: { equals: hash } }, select: { expiresAt: true, buyer: { select: { id: true, publicId: true, userState: true } } } });
if (session && new Date(session.expiresAt).getTime() > Date.now()) return buyerFrom(session.buyer);

const v = await verifyShopToken(token); // userTokenVerify, with the Mini's API key
if (!v) return null;
const { record: buyer } = await api.miniBuyer.upsert({ on: "publicId", values: { publicId: v.publicId, userState: v.userState, lastSeenAt: now } });
await api.miniSession.create({ buyer: buyer.id, tokenHash: hash, expiresAt: v.expiresAt ?? inFifteenMinutes });

Check what it set on the app

Nothing to do here: this is what the recipe configured, so you know where to look in Settings later.

PlatformWeb, backend only
CORShttp://localhost:* on /api/mini/*
SchedulerefreshShipments, hourly

Set its keys

On Settings → Environment variables, for development first:

NameWhere it comes from
SHOP_MINIS_API_KEYwritten to the Mini's .env by npx shop-minis setup
SHIP24_API_KEYthe Ship24 dashboard

Finish setup

  1. Set SHOP_MINIS_API_KEY and SHIP24_API_KEY on Settings → Environment variables
  2. Pull the app: mini/ comes with it. In it, npm install, then npx shop-minis setup, and put the app's address in src/config.ts and the manifest
  3. npx shop-minis dev opens the Mini in Shop's simulator; paste a tracking number

In mini/, the app's address goes in src/config.ts and in manifest.json's trusted_domains.

Run it

ib-apps dev syncs both ways while you work and runs the development server.

cd my-parcel-globe
ib-apps dev

Try it end to end

0 of 5 checked

Make it yours

Change the globe

mini/src/globe/Globe.tsx; npx shop-minis dev reloads it.

Another courier

Ship24's calls are in api/lib/ship24.ts.

Ship it

ib-apps test runs its tests, then ib-apps deploy sends development to production; set the keys on production first. See Deploys.