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.
What you'll build
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, thenib-apps loginonce.
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-globeTour what the recipe loaded
The recipe replaces the starter, keeping the coding-agent guidance. Here's where each piece lives.
| Where | What'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.ts | The 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.ts | The 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.ts | The 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.
http://localhost:* on /api/mini/*refreshShipments, hourlySet its keys
On Settings → Environment variables, for development first:
| Name | Where it comes from |
|---|---|
SHOP_MINIS_API_KEY | written to the Mini's .env by npx shop-minis setup |
SHIP24_API_KEY | the Ship24 dashboard |
Finish setup
- Set
SHOP_MINIS_API_KEYandSHIP24_API_KEYon Settings → Environment variables - Pull the app:
mini/comes with it. In it,npm install, thennpx shop-minis setup, and put the app's address insrc/config.tsand the manifest npx shop-minis devopens 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 devTry it end to end
Make it yours
mini/src/globe/Globe.tsx; npx shop-minis dev reloads it.
Ship24's calls are in api/lib/ship24.ts.
ib-apps test runs its tests, then ib-apps deploy sends development to production; set the keys on production first. See Deploys.