Instructions for AI agents

curl https://api.taberna.io/v1/store -H "Authorization: Bearer $TABERNA_API_KEY"

{
  "id": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
  "name": "My Store",
  "image": null,
  "enabledPaymentMethods": ["usdc_base", "sol"],
  "requireCustomerEmail": true,
  "createdAt": "2026-07-01T09:12:44.000Z",
  "slug": "my-store",
  "storefrontEnabled": true,
  "scopes": ["orders:read", "orders:write"],
  "storefrontUrl": "https://my-store.taberna.io"
}

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.TABERNA_WEBHOOK_SECRET; // tbrn_whsec_… never logged

app.post(
	'/webhooks/taberna',
	express.raw({ type: 'application/json' }), // raw bytes, not a parsed object
	async (req, res) => {
		const timestamp = req.get('x-taberna-timestamp');
		const received = req.get('x-taberna-signature');
		const deliveryId = req.get('x-taberna-delivery-id');
		if (!timestamp || !received) return res.sendStatus(400);

		// Replay defence.
		if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
			return res.sendStatus(400);
		}

		const expected = crypto
			.createHmac('sha256', SECRET)
			.update(`${timestamp}.${req.body}`)
			.digest('hex');
		const a = Buffer.from(expected);
		const b = Buffer.from(received);
		if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
			return res.sendStatus(400);
		}

		const { event, data } = JSON.parse(req.body.toString('utf8'));

		// Ack first, work after — the dispatcher gives up on slow endpoints.
		res.sendStatus(200);

		// The worker draining this queue does the idempotency check, against its
		// own state — e.g. skip if the order behind data.id is already fulfilled.
		// deliveryId is carried for correlation only; a resend reuses it.
		await enqueue({ event, data, deliveryId });
	},
);

// 1. Boot: assert capability, never assume it.
const store = await api('/v1/store');
for (const scope of ['orders:read', 'orders:write']) {
	if (!store.scopes.includes(scope)) {
		throw new Error(`Taberna key is missing the ${scope} scope`);
	}
}

// 2. Charge: idempotent, with correlation data.
const order = await api('/v1/orders', {
	method: 'POST',
	headers: { 'Idempotency-Key': purchase.id },
	body: {
		items: [{ productId: PRODUCT_ID, quantity: 1 }],
		extraContext: { purchaseId: purchase.id, userId: user.id },
		successUrl: 'https://yourapp.com/thanks',
		cancelUrl: 'https://yourapp.com/pricing',
	},
});
await savePendingPurchase(purchase.id, order.id);

// 3. Redirect the buyer.
redirect(order.checkoutUrl);

// 4. Fulfil from the verified webhook (see the reference handler above),
//    guarded by your own business state. Reconcile with
//    GET /v1/orders/{id} only when no webhook arrived.