Schedules

import type { PartnerScheduleDeclaration } from '@ekanos/sdk/integration';
import { ACME_API_KEY } from './config';

export const dailyReconcile: PartnerScheduleDeclaration<MyStorage> = {
  id: 'daily-reconcile',
  description: 'Pull the latest payments each morning and store a summary.',
  cron: '0 6 * * *', // 06:00 daily

  async handler(ctx, invocation) {
    const apiKey = await ctx.secrets.get(ACME_API_KEY);

    if (!apiKey) {
      // Not configured is expected — skip, don't fail
      return { status: 'skipped', detail: 'No API key configured.' };
    }

    const response = await ctx.fetch('https://api.acme.example/v1/payments', {
      headers: { authorization: `Bearer ${apiKey}` },
    });

    if (!response.ok) {
      // Upstream failure IS a failed run — throw so the transport records it
      throw new Error(`Acme returned ${response.status} during reconcile.`);
    }

    const payments = await response.json();
    const summary = {
      count: payments.length,
      total: payments.reduce((s, p) => s + p.amount, 0),
      succeeded: payments.filter((p) => p.status === 'succeeded').length,
    };

    await ctx.storage.account.set('cache/daily-summary', summary);

    return {
      status: 'completed',
      detail: `Reconciled ${payments.length} payments.`,
    };
  },
};

// In defineIntegration:
export const integration = defineIntegration({
  schedules: [dailyReconcile],
});

schedules: [
  {
    id: 'daily-reconcile', // kebab-case
    description: 'Pull latest payments…',
    cron: '0 6 * * *', // 5 fields, standard syntax
    async handler(ctx, invocation) {
      /* … */
    },
  },
];

{
  scheduledFor: string; // ISO 8601 — the tick this invocation stands for
  invokedAt: string; // ISO 8601 — when the handler actually started
  trigger: 'schedule' | 'manual'; // Cron or human button press
}

0 6 * * *     — 6 AM every day
0 9 * * 1-5   — 9 AM weekdays
*/30 * * * *  — Every 30 minutes
0 0 1 * *     — 1st of month at midnight
*/15 * * * *  — Every 15 minutes

async handler(ctx, invocation) {
  const apiKey = await ctx.secrets.get('api_key');
  if (!apiKey) {
    return { status: 'skipped', detail: 'Not configured.' };
  }

  const response = await ctx.fetch('https://api.example/data');
  if (!response.ok) throw new Error(`API: ${response.status}`);

  await ctx.storage.account.set('cache/data', await response.json());
  return { status: 'completed' };
}

async handler(ctx, invocation) {
  const last = await ctx.storage.account.get('sync_state/last-run');
  const ranRecently =
    last !== null && Date.now() - Date.parse(last.updatedAt) < 3_600_000;

  // A scheduled tick respects the window; a human pressing "Run now" does not
  if (ranRecently && invocation.trigger === 'schedule') {
    return { status: 'skipped', detail: 'Ran within the last hour.' };
  }

  await doWork();
  await ctx.storage.account.set('sync_state/last-run', { at: invocation.invokedAt });
  return { status: 'completed' };
}

import { invokeSchedule } from '@ekanos/sdk/testing';

const { result, ctx } = await invokeSchedule(integration, 'daily-reconcile', {
  contextOptions: {
    secrets: { account: { api_key: 'test_key' } },
    fetchHandlers: [
      { match: 'https://api.acme.example', respond: () => Response.json([]) },
    ],
  },
});

expect(result.status).toBe('completed');
expect(ctx.dumpStorage().account['cache/daily-summary']).toBeDefined();

const { ctx } = await invokeSchedule(integration, 'hourly-check', {
  contextOptions: {/* … */},
});

const second = await invokeSchedule(integration, 'hourly-check', {
  context: ctx, // Reuse storage and logs
});