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 is a Windows or Mac application at a physical location. It connects out to your server. It holds one credential, and it checks that credential 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, a scale reading, or a protocol message.

The third point controls the design. The agent checks its credential offline against a bundled public key set, and it applies the entitlements locally. The credential signature is therefore the only control point. There is no revocation call, and there is 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 the secret key, and nothing else.

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, and 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 @bellhop/node

import { Bellhop } from '@bellhop/node'
import { bellhopExpress } from '@bellhop/node/express'
import { attachWebSocket } from '@bellhop/node/ws'
import { sqliteStore } from '@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, it stores your record, and it returns a pairing link. Show that link to the person at the desk. They open it, the Bellhop application 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, and 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 request, and not a hint. If the printer cannot do what an option asks, the whole job fails with a clear error code, and nothing prints. The agent does not print a reduced version of the job.

If a location is offline, the job waits and it goes out at the next connection. This is normal, and it is not an error: machines sleep overnight. The library re-sends a job that nobody acknowledged, and the agent removes 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, and the library renews it shortly before expiry and sends the new one to the agent. Nobody visits the desk, and 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 and the library re-mints every credential and pushes them 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, and 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, and it 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 the machine-readable code below, so you branch on the code and not on the sentence.

Only 500 is safe to retry without thought. Each 4xx above is a decision, and not a temporary fault.

The licensing API

Each request carries the secret key as a bearer token. The API sends no CORS headers, and it never will. A call from a browser cannot work, and it would 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, and it never reaches a browser.
• Your public URL comes from configuration, and never from a request header. It must match the host in your pairing links byte for byte, and this includes a port that is not the default.
• Adding a location is not idempotent. Do it one time, and store your record in the same transaction.
• Decommissioning is final, and it does not revoke a credential that the machine already holds. Refuse the connection if you must stop a machine immediately.
• An offline location is normal. A job waits, and it 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 you deploy, and not only after you install.

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