JobOrc

Documentation

Quickstart

Quickstart

Get from zero to a processed job in about five minutes. You need a reachable JobOrc API (this site's API, or your own via local setup).

Prerequisites

  • Node.js 20+
  • An API key (jk_…) from the console → project → Settings → API keys

1. Install the SDK

example.bash
BASH
pnpm add @joborc/sdk
# or: npm install @joborc/sdk

2. Configure environment

example.bash
BASH
export JOBORC_API_KEY='jk_...'

That is enough for hosted JobOrc. For local/self-host, also set JOBORC_BASE_URL=http://localhost:8080.

3. Enqueue a job

example.ts
TS
import { createJobOrc } from '@joborc/sdk';
 
const joborc = createJobOrc({
  apiKey: process.env.JOBORC_API_KEY!,
});
 
const job = await joborc.jobs.enqueue(
  'email.send',
  { to: 'you@example.com', subject: 'Hello from JobOrc' },
  {
    queue: 'default',
    idempotencyKey: 'quickstart-welcome-1',
  },
);
 
console.log('Enqueued:', job.id, job.status);

4. Run a worker

Jobs stay queued until a worker claims them.

example.ts
TS
import { createJobOrc } from '@joborc/sdk';
 
const joborc = createJobOrc({
  apiKey: process.env.JOBORC_API_KEY!,
});
 
const worker = joborc.worker({
  queues: ['default'],
  concurrency: 2,
  handlers: {
    'email.send': async (payload, ctx) => {
      console.log(`Sending email for job ${ctx.jobId}`, payload);
      await ctx.heartbeat(); // optional for long work
    },
  },
});
 
await worker.start();
 
process.on('SIGINT', async () => {
  await worker.stop({ drainTimeoutMs: 15_000 });
  process.exit(0);
});

5. Verify in the console

Open the project Jobs view. You should see enqueue → running → succeeded. Timeline events explain each transition.

Troubleshooting

  • Missing API key — set JOBORC_API_KEY or pass apiKey
  • Job stays queued — start a worker on the same queue name
  • 401 — regenerate the API key in the console if unsure

Next: Concepts · Workers · SDK