Node.js SDK

A typed client for the Stamp.Show API for Node.js 18 and later: register exhibits from your own system, read the expo's public content and verify webhooks. No runtime dependencies, ESM and CommonJS. MIT license.

@stamp-show/sdk on npm · Source on GitHub

npm install @stamp-show/sdk

Quick start

An API key belongs to one expo. Create it in the expo's API keys tab and keep it on your server, never in a browser.

import { StampShow } from "@stamp-show/sdk"

const stampshow = new StampShow({ apiKey: process.env.STAMPSHOW_API_KEY! })

const palmares = await stampshow.content.palmares()
if (palmares.visible) {
  for (const award of palmares.awards) console.log(award.medal, award.title, award.exhibitor)
}

What it covers

Client	Methods
stampshow.applications	list(), create(application), get(id), accept(id), reject(id)
stampshow.exhibits	list(), submit(exhibitId, exhibit), get(exhibitId)
stampshow.content	palmares(), sponsors(), specialPrizes(), judges(), commissioners(), catalog()

Every method maps to one endpoint of the API reference, and the request and response types are generated from its OpenAPI description.

Register an exhibit

Two calls, like the expo's own registration: apply first, and send the exhibit once that application is accepted. The exhibit is an Open Exhibit document (JSON Schema, examples).

const application = await stampshow.applications.create({
  exhibitor: { email: "ana@example.com", name: "Ana Pérez", country: "PE" },
  external_reference_id: "exh-001", // makes a retried request safe
  title: "The 1856 issue",
  exhibit_class: "traditional",
  frame_count: 3,
})

// when application.accepted arrives, or after polling applications.get(id):
await stampshow.exhibits.submit(application.exhibit_id!, openExhibitDocument)

const submission = await stampshow.exhibits.get(application.exhibit_id!)
// submission.status: "processing" | "ready" | "failed"

Webhooks

Set a webhook URL on the API key and tick the events you want. Verify each delivery against the raw body with the key's webhook secret.

import { constructEvent } from "@stamp-show/sdk"

// Express: use express.raw({ type: "application/json" }) on this route
app.post("/stampshow", express.raw({ type: "application/json" }), (req, res) => {
  const event = constructEvent(req.body, req.headers["x-stampshow-signature"], process.env.STAMPSHOW_WEBHOOK_SECRET!)
  if (event.event === "application.accepted") queueExhibit(event.data.exhibit_id!)
  res.sendStatus(200)
})

For Next.js, Hono, Cloudflare Workers, Deno and Bun, webhookHandler(secret, handlers) takes a Web Request and returns a Response: 401 for a bad signature, 500 if your handler throws (so the delivery is retried), 200 otherwise.

// app/api/stampshow/route.ts
import { webhookHandler } from "@stamp-show/sdk"

export const POST = webhookHandler(process.env.STAMPSHOW_WEBHOOK_SECRET!, {
  "results.published": () => revalidatePath("/palmares"),
  "content.changed": ({ resource }) => revalidateTag(resource),
})

Errors and retries

A non-2xx answer throws StampShowError with status and detail; a request that gets no answer throws StampShowConnectionError. A 429 is retried for any method, honouring Retry-After. A 5xx or a network failure is retried for GET only, so an application is never created twice. maxRetries (default 2), timeoutMs (default 15000), baseUrl and fetch are options.

Other languages: the OpenAPI description works with OpenAPI Generator.