npm package: @goddiegold/jobcore-sdk
Description: SDK for JobCore job queue service
Latest version: 1.0.0

# JobCore SDK

Lightweight SDK for interacting with the JobCore service.

## Install
```
npm install jobcore-sdk
```

## Usage
```ts
import Redis from 'ioredis';
import {
  JobContracts,
  JobCoreQueue,
  JobCoreWorker,
  JobCoreScheduler,
  ProcessorRegistry,
} from 'jobcore-sdk';

type Jobs = {
  send_email: { userId: number; template: string };
  send_notification: { userId: number; message: string };
};

const redis = new Redis('redis://127.0.0.1:6379');
const queue = new JobCoreQueue<Jobs>({ redis });

const processors = new ProcessorRegistry<Jobs>()
  .register('send_email', async (payload) => {
    // your business logic here
    payload.userId;
  });

const scheduler = new JobCoreScheduler({ redis });
await scheduler.start();

const worker = new JobCoreWorker<Jobs>({ redis, processors });
worker.start();

await queue.enqueueJob({
  type: 'send_email',
  payload: { userId: 123, template: 'welcome' },
});
```

## Typed job contracts
Use a `Jobs` type to enforce payload shapes at compile time:
```ts
type Jobs = {
  send_email: { userId: number; template: string };
  send_notification: { userId: number; message: string };
};

const queue = new JobCoreQueue<Jobs>({ redis });
queue.enqueueJob({ type: 'send_email', payload: { userId: 1, template: 'welcome' } });
```

## Worker options
```ts
const worker = new JobCoreWorker({
  redis,
  processors,
  retryStrategy: 'exponential',
  retryDelayMs: 30_000,
  retryJitterMs: 2_000,
  lockTtlMs: 30_000,
  lockRenewalIntervalMs: 15_000,
  blockTimeoutSec: 1,
  gracefulShutdownMs: 10_000,
  concurrency: 5,
});
```

## Graceful shutdown
```ts
await worker.stop();
await scheduler.stop();
await redis.quit();
```

## List jobs (preview)
```ts
let cursor = '0';
do {
  const page = await queue.listJobs(50, cursor);
  cursor = page.cursor;
  console.log(page.jobs);
} while (cursor !== '0');
```

## Metrics helper
```ts
const summary = await queue.getMetrics();
console.log(summary.queues, summary.metrics);
```

## UI dashboard
Use one of the integrations below to expose the UI and `/api/summary` from your server.

### Express integration
```ts
import express from 'express';
import Redis from 'ioredis';
import { createExpressRouter } from 'jobcore-sdk';

const app = express();
const redis = new Redis();

app.use(createExpressRouter(express, { redis }));
app.listen(3000);
```

### Fastify integration
```ts
import Fastify from 'fastify';
import Redis from 'ioredis';
import { registerFastifyPlugin } from 'jobcore-sdk';

const app = Fastify();
const redis = new Redis();

await registerFastifyPlugin(app, { redis });
await app.listen({ port: 3000 });
```

### NestJS integration
```ts
import { Controller, Get } from '@nestjs/common';
import Redis from 'ioredis';
import { createNestHandlers } from 'jobcore-sdk';

const redis = new Redis();
const handlers = createNestHandlers({ redis });

@Controller()
export class DashboardController {
  @Get('/ui')
  getUi() {
    return handlers.getUi();
  }

  @Get('/api/summary')
  getSummary() {
    return handlers.getSummary();
  }
}
```

## Processor functions (local)
```ts
import { ProcessorRegistry } from 'jobcore-sdk';

const processors = new ProcessorRegistry()
  .register('send_email', async (payload) => {
    // your business logic here
  })
  .register('send_notification', async (payload) => {
    // your business logic here
  });

await processors.process({ type: 'send_email', payload: { userId: 123 } });
```