SDK Reference

TypeScript SDK for Spanwise cron monitoring. Full type safety and auto-completion.

Installation

npm install spanwise

Quick Start

import { Spanwise } from 'spanwise';

const client = new Spanwise({ apiKey: 'hp_...' });

// Send a ping
await client.ping('cron-job-id');

// Send a start signal
await client.ping('cron-job-id', { type: 'start' });

// Send a fail signal with output
await client.ping('cron-job-id', { type: 'fail', body: 'Error: connection failed' });

Configuration

const client = new Spanwise({
  apiKey: 'hp_...',
  baseUrl: 'https://api.spanwise.dev', // optional
  timeout: 30000,                      // optional, default 30s
  retries: 2,                          // optional, default 2 retries
});

Pinging

The core of Spanwise - notify us when your job runs.

await client.ping('cron-job-id');                              // Success
await client.ping('cron-job-id', { type: 'start' });           // Job started
await client.ping('cron-job-id', { type: 'fail' });            // Job failed
await client.ping('cron-job-id', { type: 'fail', body: 'Error details' });

Cron Jobs

// List all cron jobs in an environment
const cronJobs = await client.cronJobs.list('environment-id');

// Get a single cron job
const cronJob = await client.cronJobs.get('cron-job-id');

// Create a cron job
const cronJob = await client.cronJobs.create('environment-id', {
  name: 'DB Backup',
  scheduleType: 'PERIOD',
  scheduleValue: '3600', // every hour
});

// Update a cron job
await client.cronJobs.update('cron-job-id', { name: 'New Name' });

// Pause/resume
await client.cronJobs.pause('cron-job-id');
await client.cronJobs.resume('cron-job-id');

// Delete
await client.cronJobs.delete('cron-job-id');

// Uptime stats (last 90 days)
const stats = await client.cronJobs.stats('cron-job-id', 90);

Channels (Notifications)

// List channels
const channels = await client.channels.list('environment-id');

// Create a Slack channel
const channel = await client.channels.create('environment-id', {
  type: 'SLACK_WEBHOOK',
  name: 'Slack Alerts',
  config: { webhookUrl: 'https://hooks.slack.com/...' },
});

// Update
await client.channels.update('environment-id', 'channel-id', { name: 'New Name' });

// Test notification
await client.channels.test('environment-id', 'channel-id');

// Delete
await client.channels.delete('environment-id', 'channel-id');

Organizations

const orgs = await client.organizations.list();
const org = await client.organizations.get('org-id');
const org = await client.organizations.create({ name: 'My Org', slug: 'my-org' });
await client.organizations.update('org-id', { name: 'New Name' });
await client.organizations.delete('org-id');

API Keys

const keys = await client.apiKeys.list('environment-id');
const newKey = await client.apiKeys.create('environment-id', { name: 'CI/CD' });
console.log(newKey.key); // Full key shown only once
await client.apiKeys.delete('environment-id', 'key-id');

Error Handling

import { SpanwiseError, NotFoundError, UnauthorizedError } from 'spanwise';

try {
  await client.cronJobs.get('invalid-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Cron job not found');
  } else if (error instanceof UnauthorizedError) {
    console.log('Invalid API key');
  } else if (error instanceof SpanwiseError) {
    console.log(`Error: ${error.message} (${error.code})`);
  }
}

TypeScript Types

All types are exported for TypeScript users:

import type {
  CronJob,
  MonitorStatus,
  Channel,
  ChannelType,
  Organization,
  Environment,
} from 'spanwise';