Skip to content
Cronlet Docs

SDK Overview

@cronlet/sdk is the official TypeScript SDK for Cronlet Cloud.

It exposes:

  • a typed API client: CloudClient
  • task lifecycle methods
  • run history methods
  • secret management
  • usage lookup
  • audit recording
  • preformatted tool definitions for OpenAI, Anthropic, and LangChain

Installation

Terminal window
npm install @cronlet/sdk

Exported surface

import {
  CloudClient,
  CronletError,
  ScheduleParseError,
  cronletTools,
  createToolHandler,
  openaiTools,
  anthropicTools,
  langchainTools,
} from "@cronlet/sdk";

CloudClient

const cronlet = new CloudClient({
  apiKey: process.env.CRONLET_API_KEY!,
  baseUrl: process.env.CRONLET_BASE_URL,
  orgId: "org_123",   // optional internal context
  userId: "user_456", // optional internal context
  role: "admin",      // optional internal context
});

Options

  • apiKey: string required
  • baseUrl?: string optional, defaults to https://api.cronlet.dev
  • orgId?: string optional internal context header
  • userId?: string optional internal context header
  • role?: "viewer" | "member" | "admin" | "owner" optional internal context header

For product integrations, keep the SDK behind a server-side module:

src/
  lib/
    cronlet/
      client.ts
      tasks.ts
      callbacks.ts
      metadata.ts

Example:

src/lib/cronlet/client.ts
import { CloudClient } from "@cronlet/sdk";


export const cronlet = new CloudClient({
  apiKey: process.env.CRONLET_API_KEY!,
  baseUrl: process.env.CRONLET_BASE_URL,
});

Then wrap the raw SDK in domain-specific functions:

src/lib/cronlet/reportSchedules.ts
import { cronlet } from "./client";


export async function createUserReportSchedule(input: {
  userId: string;
  reportId: string;
  timezone: string;
}) {
  return cronlet.tasks.create({
    name: `User report ${input.reportId}`,
    handler: {
      type: "webhook",
      url: "https://app.example.com/internal/reports/run",
      method: "POST",
    },
    schedule: "daily at 9am",
    timezone: input.timezone,
    retryAttempts: 1,
    retryBackoff: "linear",
    retryDelay: "1s",
    timeout: "30s",
    active: true,
    metadata: {
      userId: input.userId,
      reportId: input.reportId,
      scheduleType: "user-report",
    },
    callbackUrl: "https://app.example.com/api/cronlet/callback",
  });
}

Why wrap the SDK

  • centralizes task naming and metadata conventions
  • prevents API key leakage
  • keeps Cronlet-specific logic out of UI code
  • makes callback handling and task lifecycle changes testable
  • allows the agent layer to call product-specific functions instead of raw task primitives

Error handling

The SDK throws CronletError when the API returns an error:

import { CronletError } from "@cronlet/sdk";


try {
  await cronlet.tasks.get("task_missing");
} catch (error) {
  if (error instanceof CronletError) {
    console.error(error.message);
    console.error(error.code);
    console.error(error.status);
  }
}

What the SDK does not currently do for you

  • it does not verify callback signatures
  • it does not manage persistence of Cronlet task IDs in your app
  • it does not reconcile callbacks into your domain model

Implement those product-side pieces in your application.

Next steps