crona-experimental

서버 사이드 코드에서 웹훅을 발동하는 크론(스케줄)을 등록하는 Crona SDK.

⚠️ experimental — API는 예고 없이 바뀔 수 있습니다.

설치

npm install crona-experimental
# 또는
pnpm add crona-experimental

빠른 시작

apiKey만 넘기면 운영 도메인 https://crona.bino.blog로 호출합니다. API 키는 대시보드(crona.bino.blog)의 API Keys 화면에서 발급하며, crona_sk_로 시작하는 값이 발급 시 한 번만 노출되니 안전하게 보관하세요.

import { Crona } from "crona-experimental";

const crona = Crona({ apiKey: "crona_sk_..." });

const result = await crona.schedule({
  name: "일일 리포트",
  repeat: "day",
  time: { hour: 9, minute: 30 },
  webhookUrl: "https://example.com/hooks/report", // 예정 시각에 POST로 호출됨
});

console.log(result.id); // 등록된 스케줄 id

기본 내보내기(default export)도 동일합니다.

import Crona from "crona-experimental";

설정 (CronaConfig)

| 옵션 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | apiKey | string | 사실상 필수 | Authorization: Bearer <apiKey>로 전송. 인증이 필요한 운영 서버에는 반드시 필요. | | baseUrl | string | 아니오 | 생략하면 https://crona.bino.blog. 로컬 개발 등에서 override. |

// 로컬 개발 서버로 보내기
const crona = Crona({
  apiKey: "crona_sk_...",
  baseUrl: "http://localhost:8787",
});

스케줄 스펙 (ScheduleInput)

schedule()의 입력은 반복 규격(CronSpec, easy-rrule에서 재노출)에 발동 시 호출할 webhookUrl을 더한 형태입니다.

// 매주 월요일 9시
await crona.schedule({
  name: "주간 미팅 알림",
  repeat: "week",
  weekday: ["mon"],
  time: { hour: 9, minute: 0 },
  webhookUrl: "https://example.com/hooks/weekly",
});

// 여러 시각(anyOf) — 월요일 9시 또는 금요일 17시
await crona.schedule({
  name: "월 9시 또는 금 17시",
  repeat: "week",
  weekday: ["mon"],
  time: { hour: 9, minute: 0 },
  anyOf: [
    { name: "a", repeat: "week", weekday: ["mon"], time: { hour: 9, minute: 0 } },
    { name: "b", repeat: "week", weekday: ["fri"], time: { hour: 17, minute: 0 } },
  ],
  webhookUrl: "https://example.com/hooks/report",
});

CronSpec 타입은 SDK에서 함께 재노출하므로 easy-rrule을 따로 설치할 필요가 없습니다.

import type { CronSpec, ScheduleInput, ScheduleResult } from "crona-experimental";

그룹 지정 (groupName)

groupName을 넘기면 대시보드 크론 화면에서 해당 그룹으로 묶여 표시됩니다. 생략하면 "기타" 그룹으로 표시됩니다. 발급한 키의 소유자 스코프로 저장되므로, 같은 계정의 대시보드에서 SDK로 만든 크론도 함께 확인·관리할 수 있습니다.

await crona.schedule({
  name: "일일 리포트",
  repeat: "day",
  time: { hour: 9, minute: 30 },
  groupName: "리포트",
  webhookUrl: "https://example.com/hooks/report",
});

동작 방식

• schedule()은 네트워크 호출 전에 스펙을 로컬에서 컴파일/검증합니다. 잘못된 스펙이면 fetch 없이 즉시 throw 합니다.
• 검증을 통과하면 POST {baseUrl}/api/schedules로 JSON 바디를 전송합니다.
• 서버가 2xx가 아니면(예: 401 인증 실패) Error를 throw 합니다.