Add Bellhop to your web app

How the pieces fit

There are three parties. bellhop.dev does the least of the three.

• Your server is the only part that speaks to bellhop.dev. It keeps the secret key. The library makes these calls for you.
• The Bellhop agent runs on a Mac, Windows or Linux machine at a physical location. It connects out to your server. It holds one credential and checks it offline. It does not listen on a port, so nobody has to ask for a firewall exception.
• bellhop.dev signs credentials and counts agents. It never receives a print job or a scale reading. No protocol message passes through it.

The third point controls the design. The agent checks its credential offline against a bundled public key set and applies the entitlements locally. So the credential signature is the only control point. There is no revocation call and no check at run time.

Vocabulary

Getting your keys

Sign in. There is no password: we send a link to your inbox. Create an app. You then have two keys. The library needs only the secret key.

If you have no account yet, create one: it takes an email address and the link we send to it. Only this step needs an account; the rest of the guide reads the same without one.

The prefixes are important. Match bh_sk_ in your log filter. A secret key must never reach a log line or an error report.

A rotation takes effect immediately. There is no grace period. The old key fails at its next use. Deploy the new key first, or accept a short time of failures.

Install a library

npm install @usefae/bellhop-node ws

import { Bellhop } from '@usefae/bellhop-node'
import { bellhopExpress } from '@usefae/bellhop-node/express'
import { attachWebSocket } from '@usefae/bellhop-node/ws'
import { sqliteStore } from '@usefae/bellhop-node/sqlite'

export const bellhop = new Bellhop({
  secretKey: process.env.BELLHOP_SECRET_KEY,
  publicUrl: 'https://deliver.example.com',
  store: sqliteStore('bellhop.db'),
})

app.use(bellhopExpress(bellhop))
const server = app.listen(3000)
attachWebSocket(bellhop, server)

bundle add bellhop-rails
bin/rails generate bellhop:install
bin/rails db:migrate

Configure it

Two settings are necessary. Everything else has a default that is correct for most apps.

const bellhop = new Bellhop({
  secretKey: process.env.BELLHOP_SECRET_KEY,
  publicUrl: 'https://deliver.example.com',
  store: sqliteStore('bellhop.db'),
})

# config/initializers/bellhop.rb
Bellhop.configure do |config|
  config.secret_key = Rails.application.credentials.dig(:bellhop, :secret_key)
  config.public_url = "https://deliver.example.com"
end

Add a location

One call adds a location. It creates the agent on bellhop.dev and stores your record, then returns a pairing link. Show that link to the person at the desk. They open it. The agent claims it, and the location is live.

const { pairingLink } = await bellhop.agents.create({ label: 'Shipping Desk' })

bellhop.agents.repair(id)    // a new link for the same location
bellhop.agents.isOnline(id)  // is that machine connected right now
bellhop.agents.remove(id)    // the location closed; this frees the cap slot

bellhop.agents.list()        // every location you added
bellhop.agents.onlineIds()   // the ones connected right now

agent = Bellhop::Agent.provision(label: "Shipping Desk")
agent.pairing_link

agent.repair!        # a new link for the same location
agent.paired?        # has a machine claimed it
agent.online?        # is that machine connected right now
agent.decommission!  # the location closed; this frees the cap slot

Print

await bellhop.print(agentId, { kind: 'label', format: 'zpl', data: zpl })

agent.print(kind: "label", format: :zpl, data: zpl)

kind is yours; the agent does not read it. Use it in your own admin screens. format is zpl, raw, pdf, or gif. Use raw for bytes the agent must not touch, for example ESC/POS for a receipt printer. A job that names no printer goes to the location's default printer for its format.

agent.print(kind: "packing_slip", format: :pdf) { |job| document_url(job, sig: sign(job)) }

await bellhop.print(agentId, { kind: 'packing_slip', format: 'pdf', url: signedUrl })

The agent reports its shared printers when it connects: an id, a display name, and what each one can do. To print on one specific printer, send its id as printer. To ask for something specific, send options: copies, duplex, paper, bin, dpi, color, pages, rotate, fit, collate, and nup.

await bellhop.print(agentId, {
  kind: 'packing_slip', format: 'pdf', url: signedUrl,
  printer: 'Office_HP', options: { copies: 2, duplex: 'long-edge' },
})

agent.print(kind: "packing_slip", format: :pdf, data: pdf,
            printer: "Office_HP", options: { copies: 2, duplex: "long-edge" })

An option is a firm request. If the printer cannot do what an option asks, the whole job fails with a clear error code. Nothing prints. The agent never prints a reduced version of the job.

If a location is offline, the job waits. It goes out at the next connection. This is normal: machines sleep overnight. The library re-sends any job that nobody acknowledged, and the agent drops the duplicates.

The library refuses some jobs at the call site, because each fails in a way that is hard to trace from the other end: a format that the location did not advertise, an inline document above 50 MB, and an option that is unknown, malformed, or not applicable to the job's format. Only the agent can check an option against the printer itself, and its answer comes back in the ack.

agent.supports?(:zpl)   # what this location advertised
agent.outstanding_jobs  # sent, and not yet acknowledged

bellhop.jobs.get(id)      # Node
bellhop.jobs.recent(20)
bellhop.jobs.outstanding(agentId)

Hear back from the hardware

This is the half of an integration that is yours. The library tells you what happened, and your app decides what that means.

bellhop.on('weight', ({ agentId, grams }) => fillShippingForm(agentId, grams))
bellhop.on('ack', ({ jobId, status, error }) => recordOutcome(jobId, status, error))
bellhop.on('error', (error) => report(error))

ActiveSupport::Notifications.subscribe("weight.bellhop") do |event|
  ShippingForm.fill(event.payload[:agent], grams: event.payload[:grams])
end

ActiveSupport::Notifications.subscribe("ack.bellhop") do |event|
  job = event.payload[:job]
  Rails.logger.warn("#{job.id} failed: #{job.error}") if job.status == "failed"
end

A weight is the useful one. A shipping form that fills itself while the parcel is on the scale is the reason most apps add Bellhop.

Keep credentials fresh

Nothing to do here. A credential lasts a long time. The library renews it shortly before expiry and sends the new one to the agent. Nobody visits the desk. Nothing needs scheduling.

If you would rather renew from your own job runner, turn the automation off and make the one call yourself:

await bellhop.renew()  // with autoRenew: false

Bellhop.renew!  # with config.auto_renew = false

Plan changes, without the wait

Entitlements are read when a credential is minted, so on its own a plan change waits for the next renewal. Register a webhook URL on your app's page and it stops waiting. When your plan changes, Bellhop calls the URL; the library re-mints every credential and pushes the new ones to your agents within moments. When an agent is deactivated on bellhop.dev, the same call has the library retire it locally, exactly as if you had removed it from your own admin. Both libraries answer the webhook at /bellhop/webhook with nothing to configure. Each delivery is signed with the same published keys that sign credentials. A delivery that cannot be verified changes nothing.

Check your setup

Both libraries have a doctor. It checks the secret key, the public URL, the store, and the routes, then tells you which one is wrong. Run it after you install, and again after you deploy.

npx bellhop doctor     // from a terminal
await bellhop.doctor() // or from code

bin/rails bellhop:doctor

agent.print(kind: "test", format: :zpl, data: Bellhop.test_label)

Errors

Both libraries use the same three names. ConfigurationError means a setting is wrong. LicensingError means bellhop.dev refused the call. AgentError means the location cannot take the job. In Rails all three descend from Bellhop::Error, so you can rescue the one class. Each error carries a machine-readable code from the table below. Branch on the code, never on the sentence.

Only 500 is safe to retry without thought. Each 4xx above needs a decision from you; a retry will not clear it.

The licensing API

Each request carries the secret key as a bearer token. The API sends no CORS headers and never will. A call from a browser cannot work; it would also show your secret key to every visitor. Make each call from your server.

Authorization: Bearer bh_sk_...
Content-Type: application/json

Each timestamp is ISO 8601 in UTC. Each error body has the same shape, and each endpoint can also return 401 invalid_secret_key.

{ "error": "machine_readable_code", "message": "Human sentence." }

An activation returns the credential, its expiry, a serial, and the branding that the agent shows while it is idle.

{
  "credential": "eyJraWQiOiIyMDI2LTA4IiwiYWxnIjoiRWREU0EifQ...",
  "expires_at": "2027-08-06T23:05:35Z",
  "serial": "56c2b7ba-7cce-4a7f-b967-a93a59f3ad25",
  "branding": {
    "app_name": "Slaydate",
    "accent_color": "#B91C1C",
    "icon_base64": "iVBORw0KGgoAAAANSUhEUg...",
    "show_bellhop_branding": true
  }
}

GET /api/v1/app is the one an admin screen wants. active_agent_count counts each agent that is not deactivated, so it is the number that the cap is measured against. max_printers: null means unlimited.

{
  "name": "Slaydate",
  "publishable_key": "bh_pk_...",
  "plan": "fleet",
  "entitlements": {
    "agent_cap": 250,
    "scales_allowed": true,
    "max_printers": null,
    "remove_branding": true
  },
  "active_agent_count": 34,
  "in_good_standing": true
}

By hand, with curl

SK="bh_sk_..."

# Look at the app.
curl -s -H "Authorization: Bearer $SK" \
  https://bellhop.dev/api/v1/app

# An admin adds a location.
curl -s -X POST -H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
  -d '{"label":"Toronto Office"}' \
  https://bellhop.dev/api/v1/agents
# => {"id":42,"label":"Toronto Office","status":"pending"}

# A person pairs a machine there.
curl -s -X POST -H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
  -d '{"server_host":"deliver.example.com"}' \
  https://bellhop.dev/api/v1/agents/42/activate

# Much later, in a background job.
curl -s -X POST -H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
  -d '{"server_host":"deliver.example.com"}' \
  https://bellhop.dev/api/v1/agents/42/renew

# The location closes.
curl -s -X POST -H "Authorization: Bearer $SK" \
  https://bellhop.dev/api/v1/agents/42/deactivate

Rules worth repeating

• The secret key stays on your server. It never enters a log or a browser.
• Your public URL comes from configuration, never from a request header. It must match the host in your pairing links byte for byte, non-default port included.
• Adding a location is not idempotent. Do it one time, and store your record in the same transaction.
• Decommissioning is final. It does not revoke a credential that the machine already holds, so refuse the connection if you must stop a machine immediately.
• An offline location is normal. A job waits, then goes out at the next connection.
• Subscribe to the error event. It is where the library tells you about the failures you cannot see.
• Run the doctor after every deploy, as well as after you install.

If you write a client by hand, the wire protocol page has the rules that apply to it.