Schedules and signals

import { nextOccurrence, occurrencesBetween, parseCron } from '@deuz-sdk/core/schedule';

const weekdays = parseCron('0 9 * * MON-FRI');
console.log(weekdays.daysOfWeek); // [1, 2, 3, 4, 5]

const from = Date.parse('2026-01-03T12:00:00Z'); // a Saturday
console.log(new Date(nextOccurrence(weekdays, from)).toISOString());
// 2026-01-05T09:00:00.000Z

// The window excludes `from` and includes `to`, so back-to-back windows never overlap.
const hours = occurrencesBetween('0 */6 * * *', from, from + 86_400_000);
console.log(hours.map((ms) => new Date(ms).toISOString()));

import { generateText } from '@deuz-sdk/core';
import { createScheduler } from '@deuz-sdk/core/schedule';
import { createMockModel } from '@deuz-sdk/core/testing';

const model = createMockModel({ responses: [{ text: 'Three PRs merged overnight.' }] });

const scheduler = createScheduler({
  schedules: [
    {
      id: 'morning-digest',
      cron: '0 9 * * MON-FRI',
      async run(occurrence) {
        const { text } = await generateText({ model, prompt: 'Summarise the night.' });
        console.log(occurrence.key, text);
      },
    },
  ],
});

// e.g. a Vercel cron route or a Cloudflare `scheduled` handler that fires every minute
const result = await scheduler.tick(Date.parse('2026-01-05T09:00:20Z'));
for (const occurrence of result.occurrences) {
  console.log(occurrence.id, occurrence.status); // morning-digest ran
}

import { createInMemoryClaim, createScheduler } from '@deuz-sdk/core/schedule';

const claim = createInMemoryClaim(); // stands in for a durable claim, such as ops.claims
const ran: string[] = [];
const schedules = [
  { id: 'hourly', cron: '0 * * * *', run: (o: { key: string }) => void ran.push(o.key) },
];

const before = createScheduler({ schedules, claim, catchUp: 'all', lookbackMs: 3 * 3_600_000 });
await before.tick(Date.parse('2026-01-01T02:30:00Z')); // runs 00:00, 01:00, 02:00

// The process restarts; the new scheduler looks back over the same hours.
const after = createScheduler({ schedules, claim, catchUp: 'all', lookbackMs: 3 * 3_600_000 });
const result = await after.tick(Date.parse('2026-01-01T03:10:00Z'));
console.log(result.occurrences.map((o) => o.status)); // duplicates, then 03:00 ran
console.log(ran.length); // 4

import { createScheduler } from '@deuz-sdk/core/schedule';
import { createSqliteOpsStore } from '@deuz-sdk/core/ops/sqlite';

// Every process opens the same file; createPostgresOpsStore({ client: pool })
// from '@deuz-sdk/core/ops/postgres' does the same on a shared database.
const ops = createSqliteOpsStore({ path: 'ops.sqlite' });

const scheduler = createScheduler({
  schedules: [{ id: 'nightly-sync', cron: '0 2 * * *', run: (o) => console.log('sync', o.key) }],
  claim: ops.claims,
  // Recover what a restart missed; occurrences that already ran are duplicates.
  catchUp: 'all',
  lookbackMs: 6 * 3_600_000,
});

const result = await scheduler.tick(Date.parse('2026-01-05T02:00:20Z'));
console.log(result.occurrences.map((o) => o.status)); // ['ran'], then 'duplicate' elsewhere
await ops.close();

import { createAgent } from '@deuz-sdk/core/agent';
import { createScheduler } from '@deuz-sdk/core/schedule';
import type { ScheduleDefinition } from '@deuz-sdk/core/schedule';
import { createInMemorySwarmStore, createSwarm, SwarmConflictError } from '@deuz-sdk/core/swarm';
import { createMockModel } from '@deuz-sdk/core/testing';

const writer = createAgent({ model: createMockModel({ responses: [{ text: 'report' }] }) });
const swarm = createSwarm({
  agents: { writer: { agent: writer, version: 'writer-v1' } },
  store: createInMemorySwarmStore(), // shared by every process: SQLite, Postgres or Redis in production
});

const schedules: ScheduleDefinition[] = [
  {
    id: 'weekly-report',
    cron: '0 8 * * MON',
    async run(occurrence) {
      try {
        const handle = await swarm.run({
          scope: 'reports',
          runId: occurrence.key, // the create fails if any process already started it
          tasks: [{ id: 'write', agent: 'writer', prompt: 'Write the weekly report.' }],
        });
        const outcome = await handle.result;
        console.log(occurrence.key, outcome.run.status);
      } catch (error) {
        if (!(error instanceof SwarmConflictError)) throw error;
        console.log(occurrence.key, 'already claimed elsewhere');
      }
    },
  },
];

// Two processes tick the same minute. The swarm store is the claim, so each
// scheduler's own claim can simply say yes.
for (const name of ['a', 'b']) {
  const scheduler = createScheduler({ schedules, claim: () => true });
  await scheduler.tick(Date.parse('2026-01-05T08:00:30Z'));
  console.log('process', name, 'done');
}
// weekly-report@1767600000000 completed, then: already claimed elsewhere

import { createScheduler } from '@deuz-sdk/core/schedule';

const scheduler = createScheduler({
  schedules: [{ id: 'heartbeat', cron: '* * * * *', run: (o) => console.log('beat', o.at) }],
});

const controller = new AbortController();
const stopped = scheduler.start({
  intervalMs: 30_000,
  signal: controller.signal,
  onTick: (result) => console.log(result.occurrences.length, 'occurrences'),
});

// on shutdown
controller.abort();
await stopped;

import { nextZonedOccurrence, timeZoneOffset, zonedOccurrencesBetween } from '@deuz-sdk/core/schedule';

const newYork = { timezone: 'America/New_York' };
const iso = (ms: number) => new Date(ms).toISOString();

// 2026-03-08: New York skips 02:00-03:00. 'shift' (default) runs 02:30 at 03:00 EDT.
const spring = zonedOccurrencesBetween('30 2 * * *', Date.parse('2026-03-07T12:00:00Z'), Date.parse('2026-03-09T12:00:00Z'), newYork);
console.log(spring.map((o) => [iso(o.at), o.shifted ?? false]));
// [ [ '2026-03-08T07:00:00.000Z', true ], [ '2026-03-09T06:30:00.000Z', false ] ]

// 2026-11-01: 01:00-02:00 happens twice. 'both' runs 01:30 at each instant.
const fall = zonedOccurrencesBetween('30 1 1 11 *', Date.parse('2026-10-31T12:00:00Z'), Date.parse('2026-11-01T12:00:00Z'), { ...newYork, dstOverlap: 'both' });
console.log(fall.map((o) => [iso(o.at), o.repeated ?? false]));
// [ [ '2026-11-01T05:30:00.000Z', false ], [ '2026-11-01T06:30:00.000Z', true ] ]

console.log(iso(nextZonedOccurrence('0 9 * * MON-FRI', Date.parse('2026-10-16T12:00:00Z'), { timezone: 'Europe/Istanbul' })));
// 2026-10-19T06:00:00.000Z (09:00 in Istanbul, UTC+3, no DST)
console.log(timeZoneOffset('America/New_York', Date.parse('2026-07-01T00:00:00Z')) / 3_600_000); // -4

import {
  verifyGitHubWebhook,
  verifyHmacSignature,
  verifySlackRequest,
} from '@deuz-sdk/core/schedule';

// GitHub: X-Hub-Signature-256 = "sha256=" + hex HMAC-SHA256 of the raw body.
const github = await verifyGitHubWebhook(
  new Request('https://example.com/hooks/github', {
    method: 'POST',
    body: 'Hello, World!',
    headers: {
      'x-hub-signature-256':
        'sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17',
    },
  }),
  "It's a Secret to Everybody",
);
console.log(github); // { ok: true, body: 'Hello, World!' }

// Slack: v0 signature over "v0:{timestamp}:{body}", with a replay window.
// `now` is required: pass your clock's time (edge code never reads the host clock).
const slack = await verifySlackRequest(
  new Request('https://example.com/slack', { method: 'POST', body: 'text=hi' }),
  'signing-secret',
  { now: Date.parse('2026-01-05T09:00:00Z'), toleranceSeconds: 300 },
);
console.log(slack); // { ok: false, reason: 'missing-timestamp' }

// Anything else signed with an HMAC: pick the algorithm, encoding and prefix.
const custom = await verifyHmacSignature({
  body: '{"event":"paid"}',
  signature: 'sha256=not-a-real-signature',
  secret: 'whsec',
  algorithm: 'SHA-256',
  encoding: 'hex',
  prefix: 'sha256=',
});
console.log(custom); // { ok: false, reason: 'malformed-signature' }

import { createInMemoryClaim, handleSignal, verifyGitHubWebhook } from '@deuz-sdk/core/schedule';

// One process only; across instances use a durable claim such as ops.claims.
const dedupe = createInMemoryClaim();

export async function POST(request: Request): Promise<Response> {
  return handleSignal(request, {
    verify: (r) => verifyGitHubWebhook(r, 'webhook-secret'),
    key: ({ request: r }) => r.headers.get('x-github-delivery') ?? undefined,
    dedupe,
    async dispatch({ body, key }) {
      const event = JSON.parse(body) as { action?: string };
      console.log('start run', key, event.action);
    },
  });
}