Skip to content

resources.md

Latest commit

 

History

History
703 lines (513 loc) · 12.4 KB

resources.md

File metadata and controls

703 lines (513 loc) · 12.4 KB

Resources Reference

This is a complete reference for all SDK resources and their methods.

Jobs

Create Job

const { id, created } = await client.jobs.create({
  queueName: 'my-queue',           // Required: target queue
  payload: { data: 'value' },      // Required: job data (any JSON)

  // Optional
  priority: 5,                      // -100 to 100 (default: 0)
  maxRetries: 3,                    // Retry attempts (default: 3)
  timeoutSeconds: 300,              // Job timeout (default: 300)
  scheduledAt: new Date(),          // Delay execution
  idempotencyKey: 'unique-key',     // Prevent duplicates
  tags: { env: 'prod' },            // Metadata tags
});

List Jobs

const jobs = await client.jobs.list({
  queueName: 'my-queue',            // Optional: filter by queue
  status: 'pending',                // Optional: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'
  tag: 'billing',                   // Optional: filter by a single tag
  limit: 10,                        // Pagination limit
  offset: 0,                        // Pagination offset
});

Get Job

const job = await client.jobs.get('job_id');
// Returns: { id, queueName, status, payload, priority, ... }

Cancel Job

await client.jobs.cancel('job_id');

Retry Job

const { id } = await client.jobs.retry('job_id');

Boost Priority

await client.jobs.boostPriority('job_id', 10); // Add 10 to priority

Get Statistics

const stats = await client.jobs.getStats();
// { pending, processing, completed, failed, deadLetter }

Bulk Enqueue

const result = await client.jobs.bulkEnqueue({
  queueName: 'my-queue',
  jobs: [
    { payload: { n: 1 } },
    { payload: { n: 2 }, priority: 10 },
    { payload: { n: 3 }, maxRetries: 5 },
  ],
});
// { jobIds: ['job_1', 'job_2', 'job_3'], enqueuedCount: 3 }

Batch Status

const statuses = await client.jobs.batchStatus(['job_1', 'job_2', 'job_3']);
// { job_1: 'completed', job_2: 'processing', job_3: 'pending' }

Claim Jobs (for workers)

const result = await client.jobs.claim({
  queueName: 'my-queue',
  workerId: 'worker-1',
  limit: 10,
  leaseDurationSecs: 300,
});
// { jobs: [...], claimedCount: 5 }

Complete Job

await client.jobs.complete('job_id', {
  workerId: 'worker-1',
  result: { success: true },
});

Fail Job

await client.jobs.fail('job_id', {
  workerId: 'worker-1',
  error: 'Something went wrong',
});

Heartbeat

await client.jobs.heartbeat('job_id', {
  workerId: 'worker-1',
  leaseDurationSecs: 300,
});

Dead Letter Queue

// List DLQ jobs
const dlqJobs = await client.jobs.dlq.list({
  queueName: 'my-queue',
  limit: 50,
});

// Retry DLQ jobs
await client.jobs.dlq.retry({
  jobIds: ['job_1', 'job_2'],
});

// Retry all DLQ jobs for a queue
await client.jobs.dlq.retry({
  queueName: 'my-queue',
});

// Purge DLQ
await client.jobs.dlq.purge({
  queueName: 'my-queue',
  confirm: true,
});

Queues

List Queues

const queues = await client.queues.list();
// [{ queueName, enabled, defaultPriority, ... }]

Get Queue Config

const config = await client.queues.get('my-queue');

Update Queue Config

await client.queues.updateConfig('my-queue', {
  maxRetries: 5,
  defaultTimeout: 600,
  rateLimit: 100,
  enabled: true,
});

Get Queue Stats

const stats = await client.queues.getStats('my-queue');
// { pending, processing, completed, failed, ... }

Pause Queue

await client.queues.pause('my-queue', 'Maintenance window');

Resume Queue

await client.queues.resume('my-queue');

Schedules

Create Schedule

const schedule = await client.schedules.create({
  name: 'Daily Report',
  cronExpression: '0 0 9 * * *',    // 6-field cron (with seconds)
  timezone: 'America/New_York',
  queueName: 'reports',
  payloadTemplate: { type: 'daily' },
  enabled: true,
});

List Schedules

const schedules = await client.schedules.list();

Get Schedule

const schedule = await client.schedules.get('schedule_id');

Update Schedule

await client.schedules.update('schedule_id', {
  cronExpression: '0 0 8 * * *',
  enabled: false,
});

Delete Schedule

await client.schedules.delete('schedule_id');

Pause/Resume

await client.schedules.pause('schedule_id');
await client.schedules.resume('schedule_id');

Trigger Manually

const { jobId } = await client.schedules.trigger('schedule_id');

Get History

const runs = await client.schedules.getHistory('schedule_id', 10);
// Last 10 executions

Workflows

Create Workflow

const workflow = await client.workflows.create({
  name: 'ETL Pipeline',
  jobs: [
    { key: 'extract', queueName: 'etl', payload: {} },
    { key: 'transform', queueName: 'etl', payload: {}, dependsOn: ['extract'] },
    { key: 'load', queueName: 'etl', payload: {}, dependsOn: ['transform'] },
  ],
});
// { workflowId, jobMappings: { extract: 'job_1', ... } }

Get Workflow

const status = await client.workflows.get('workflow_id');
// { workflowId, status, jobs: [...] }

Cancel Workflow

await client.workflows.cancel('workflow_id');

Retry Failed Workflow

Retry all failed jobs in a workflow. Only works on workflows with status failed.

const workflow = await client.workflows.retry('workflow_id');
// Workflow status changes from 'failed' to 'running'
// Failed jobs are reset to 'pending' and reprocessed

Job Dependencies

const deps = await client.workflows.jobs.getDependencies('job_id');

await client.workflows.jobs.addDependencies('job_id', {
  dependsOnJobIds: ['other_job_id'],
});

Webhooks

Create Webhook

const webhook = await client.webhooks.create({
  name: 'Slack Notifications',
  url: 'https://hooks.slack.com/...',
  events: ['job.completed', 'job.failed'],
  secret: 'hmac-secret',
  enabled: true,
});

List Webhooks

const webhooks = await client.webhooks.list();

Get/Update/Delete

const wh = await client.webhooks.get('webhook_id');
await client.webhooks.update('webhook_id', { enabled: false });
await client.webhooks.delete('webhook_id');

Test Webhook

const result = await client.webhooks.test('webhook_id');
// { success, statusCode, ... }

Get Deliveries

const deliveries = await client.webhooks.getDeliveries('webhook_id', { limit: 50 });

Retry Delivery

const result = await client.webhooks.retryDelivery('webhook_id', 'delivery_id');
// { success, message }

Workers

List Workers

const workers = await client.workers.list();

Get Worker

const worker = await client.workers.get('worker_id');

Register Worker

const registration = await client.workers.register({
  queueName: 'my-queue',
  hostname: 'worker-01',
  workerType: 'nodejs',
  maxConcurrency: 10,
  metadata: { version: '1.0.0' },
});
// { id, leaseDurationSecs, heartbeatIntervalSecs }

Heartbeat

await client.workers.heartbeat('worker_id', {
  currentJobs: 5,
  status: 'healthy',
});

Deregister

await client.workers.deregister('worker_id');

API Keys

List Keys

const keys = await client.apiKeys.list();
// Keys are masked (only last 4 chars shown)

Create Key

const { id, key } = await client.apiKeys.create({
  name: 'Production API Key',
  queues: ['queue-1', 'queue-2'],  // Optional: restrict to queues
  rateLimit: 1000,
});
// IMPORTANT: 'key' is only shown once!

Update Key

await client.apiKeys.update('key_id', {
  name: 'Updated Name',
  rateLimit: 2000,
});

Revoke Key

await client.apiKeys.revoke('key_id');

Organizations

Create Organization

const { organization, apiKey } = await client.organizations.create({
  name: 'My Company',
  slug: 'my-company',
  billingEmail: 'billing@company.com',
});

Get Usage

const usage = await client.organizations.getUsage();
// { plan, planDisplayName, usage: { jobsToday, queues, workers, ... } }

List Organizations

const orgs = await client.organizations.list();
// Returns list of organizations accessible to your API key

Check Slug Availability

const { available, valid, suggestion } = await client.organizations.checkSlug('my-company');
// available: boolean - whether slug is available
// valid: boolean - whether slug format is valid
// suggestion: string | null - alternative slug if not available

Generate Slug

const { slug } = await client.organizations.generateSlug('My Company Name');
// Returns a unique, URL-safe slug generated from the name

Billing

Get Status

const status = await client.billing.getStatus();
// { planTier, hasStripeCustomer, ... }

Create Portal Session

const portal = await client.billing.createPortal({
  returnUrl: 'https://yourapp.com/billing',
});
// { url } - Redirect user to this Stripe portal URL

Authentication

Login with API Key

const { accessToken, refreshToken } = await client.auth.login({
  apiKey: 'sk_live_...'
});

// Use JWT for subsequent requests
const jwtClient = new SpooledClient({ accessToken });

Validate Token

const { valid } = await client.auth.validate({ token: accessToken });

Refresh Token

const { accessToken } = await client.auth.refresh({ refreshToken });

Get Current User

const user = await client.auth.me(); // Requires JWT token
// { organizationId, ... }

Logout

await client.auth.logout();

Email-Based Login

// Start email login flow (sends magic link)
const result = await client.auth.startEmailLogin('user@example.com');
// { success, message }

// Check if email exists in system
const { exists } = await client.auth.checkEmail('user@example.com');

Dashboard

Get Dashboard Data

const dashboard = await client.dashboard.get();
// { system, jobs, queues, workers, recentActivity }

Health & Metrics

Health Check

const health = await client.health.get();
// { status, database, cache, timestamp }

Readiness

const ready = await client.health.readiness();
// true | false

Prometheus Metrics

const metrics = await client.metrics.get();
// Raw Prometheus metrics text

Admin API

Requires adminKey in client config.

List Organizations

const orgs = await client.admin.listOrganizations({
  planTier: 'pro',
  limit: 10,
});

Get Organization

const org = await client.admin.getOrganization('org_id');

Update Organization

await client.admin.updateOrganization('org_id', {
  planTier: 'enterprise',
});

Get Admin Stats

const stats = await client.admin.getStats();
// { organizations, jobs, queues, ... }

Create API Key for Organization

const { id, key } = await client.admin.createApiKey({
  organizationId: 'org_id',
  name: 'Admin-created key',
});

Webhook Ingestion

For receiving webhooks from external services. These are signature-based, not API-key-based.

Custom Webhook

await client.ingest.custom('org_id', {
  queueName: 'custom_events',
  eventType: 'custom.event',
  payload: { data: 'value' },
});

Type Exports

import type {
  // Client
  SpooledClient,
  SpooledClientConfig,

  // Jobs
  Job,
  JobStatus,
  CreateJobParams,
  JobStats,

  // Queues
  Queue,
  QueueStats,
  QueueConfig,

  // Schedules
  Schedule,
  CreateScheduleParams,

  // Workflows
  Workflow,
  CreateWorkflowParams,

  // Workers
  Worker,
  WorkerStatus,
  SpooledWorker,
  SpooledWorkerOptions,
  JobContext,

  // Webhooks
  Webhook,
  WebhookEvent,

  // Common
  PaginationParams,
  JsonObject,
} from '@spooled/sdk';