@agentuity/core 1.0.33 → 1.0.34

package/dist/services/schedule/service.d.ts

@@ -0,0 +1,439 @@
+import { FetchAdapter } from '../adapter.ts';
+import { z } from 'zod';
+/**
+ * A scheduled job that fires at intervals defined by a cron expression.
+ *
+ * Schedules are the top-level resource. Each schedule has one or more
+ * {@link ScheduleDestination | destinations} that receive HTTP callbacks
+ * when the schedule fires.
+ */
+export declare const ScheduleSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    created_by: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    expression: z.ZodString;
+    due_date: z.ZodString;
+}, z.core.$strip>;
+export type Schedule = z.infer<typeof ScheduleSchema>;
+/**
+ * A delivery target for a scheduled job.
+ *
+ * When the schedule fires, an HTTP request is sent to each of its destinations.
+ */
+export declare const ScheduleDestinationSchema: z.ZodObject<{
+    id: z.ZodString;
+    schedule_id: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    created_by: z.ZodString;
+    type: z.ZodEnum<{
+        url: "url";
+        sandbox: "sandbox";
+    }>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ScheduleDestination = z.infer<typeof ScheduleDestinationSchema>;
+/**
+ * A record of a single delivery attempt for a scheduled execution.
+ *
+ * Each time a schedule fires, one delivery record is created per destination.
+ * Failed deliveries may be retried automatically.
+ */
+export declare const ScheduleDeliverySchema: z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    schedule_id: z.ZodString;
+    schedule_destination_id: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        pending: "pending";
+        failed: "failed";
+    }>;
+    retries: z.ZodNumber;
+    error: z.ZodNullable<z.ZodString>;
+    response: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ScheduleDelivery = z.infer<typeof ScheduleDeliverySchema>;
+/**
+ * Parameters for creating a new schedule.
+ */
+export declare const CreateScheduleParamsSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    expression: z.ZodString;
+    destinations: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
+        type: z.ZodEnum<{
+            url: "url";
+            sandbox: "sandbox";
+        }>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type CreateScheduleParams = z.infer<typeof CreateScheduleParamsSchema>;
+/**
+ * Parameters for creating a new destination on a schedule.
+ */
+export declare const CreateScheduleDestinationParamsSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        url: "url";
+        sandbox: "sandbox";
+    }>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type CreateScheduleDestinationParams = z.infer<typeof CreateScheduleDestinationParamsSchema>;
+/**
+ * Parameters for updating an existing schedule.
+ *
+ * All fields are optional; only provided fields are updated.
+ */
+export declare const UpdateScheduleParamsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    expression: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateScheduleParams = z.infer<typeof UpdateScheduleParamsSchema>;
+/**
+ * Paginated list of schedules.
+ */
+export declare const ScheduleListResultSchema: z.ZodObject<{
+    schedules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        created_by: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        expression: z.ZodString;
+        due_date: z.ZodString;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+export type ScheduleListResult = z.infer<typeof ScheduleListResultSchema>;
+/**
+ * A schedule with its associated destinations.
+ */
+export declare const ScheduleGetResultSchema: z.ZodObject<{
+    schedule: z.ZodObject<{
+        id: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        created_by: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        expression: z.ZodString;
+        due_date: z.ZodString;
+    }, z.core.$strip>;
+    destinations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        schedule_id: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        created_by: z.ZodString;
+        type: z.ZodEnum<{
+            url: "url";
+            sandbox: "sandbox";
+        }>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScheduleGetResult = z.infer<typeof ScheduleGetResultSchema>;
+/**
+ * Result of creating a schedule, including any destinations created atomically.
+ */
+export declare const ScheduleCreateResultSchema: z.ZodObject<{
+    schedule: z.ZodObject<{
+        id: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        created_by: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        expression: z.ZodString;
+        due_date: z.ZodString;
+    }, z.core.$strip>;
+    destinations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        schedule_id: z.ZodString;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+        created_by: z.ZodString;
+        type: z.ZodEnum<{
+            url: "url";
+            sandbox: "sandbox";
+        }>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScheduleCreateResult = z.infer<typeof ScheduleCreateResultSchema>;
+/**
+ * List of delivery attempts for a schedule.
+ */
+export declare const ScheduleDeliveryListResultSchema: z.ZodObject<{
+    deliveries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        date: z.ZodString;
+        schedule_id: z.ZodString;
+        schedule_destination_id: z.ZodString;
+        status: z.ZodEnum<{
+            success: "success";
+            pending: "pending";
+            failed: "failed";
+        }>;
+        retries: z.ZodNumber;
+        error: z.ZodNullable<z.ZodString>;
+        response: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScheduleDeliveryListResult = z.infer<typeof ScheduleDeliveryListResultSchema>;
+/**
+ * Client for the Agentuity Schedule service.
+ *
+ * Provides methods for creating, managing, and monitoring cron-based scheduled jobs.
+ * Schedules fire at intervals defined by cron expressions and deliver HTTP requests
+ * to configured destinations (URLs or sandboxes).
+ *
+ * The service supports:
+ * - CRUD operations on schedules and their destinations
+ * - Cron expression validation
+ * - Delivery history and monitoring
+ * - Automatic due date computation from cron expressions
+ *
+ * All methods are instrumented with OpenTelemetry spans for observability.
+ *
+ * @example
+ * ```typescript
+ * const schedules = new ScheduleService(baseUrl, adapter);
+ *
+ * // Create a schedule that fires every hour
+ * const result = await schedules.create({
+ *   name: 'Hourly Sync',
+ *   expression: '0 * * * *',
+ *   destinations: [{ type: 'url', config: { url: 'https://example.com/sync' } }],
+ * });
+ *
+ * // List all schedules
+ * const { schedules: list, total } = await schedules.list();
+ * ```
+ */
+export declare class ScheduleService {
+    #private;
+    /**
+     * Create a new ScheduleService instance.
+     *
+     * @param baseUrl - The base URL for the Agentuity Schedule API (e.g., `https://api.agentuity.com`)
+     * @param adapter - The HTTP fetch adapter used for making API requests
+     */
+    constructor(baseUrl: string, adapter: FetchAdapter);
+    /**
+     * Create a new schedule with optional destinations.
+     *
+     * The schedule and its destinations are created atomically — if any validation
+     * fails, the entire operation is rolled back.
+     *
+     * @param params - The schedule creation parameters including name, cron expression, and optional destinations
+     * @returns The created schedule and its destinations
+     * @throws ServiceException on API errors (e.g., invalid cron expression, invalid destination URL)
+     *
+     * @example
+     * ```typescript
+     * const result = await schedules.create({
+     *   name: 'Daily Report',
+     *   description: 'Generate and send daily reports',
+     *   expression: '0 9 * * *',
+     *   destinations: [
+     *     { type: 'url', config: { url: 'https://example.com/reports' } },
+     *   ],
+     * });
+     * console.log('Created schedule:', result.schedule.id);
+     * console.log('Next run:', result.schedule.due_date);
+     * ```
+     */
+    create(params: CreateScheduleParams): Promise<ScheduleCreateResult>;
+    /**
+     * List all schedules with optional pagination.
+     *
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of schedules to return (max 500)
+     * @param params.offset - Number of schedules to skip for pagination
+     * @returns A paginated list of schedules with the total count
+     * @throws ServiceException on API errors
+     *
+     * @example
+     * ```typescript
+     * // List first page
+     * const { schedules, total } = await service.list({ limit: 20 });
+     * console.log(`Showing ${schedules.length} of ${total} schedules`);
+     *
+     * // Paginate through all schedules
+     * const page2 = await service.list({ limit: 20, offset: 20 });
+     * ```
+     */
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ScheduleListResult>;
+    /**
+     * Get a schedule by its ID, including all configured destinations.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @returns The schedule record and its array of destinations
+     * @throws ServiceException on API errors (including 404 if not found)
+     *
+     * @example
+     * ```typescript
+     * const { schedule, destinations } = await service.get('sch_abc123');
+     * console.log('Schedule:', schedule.name);
+     * console.log('Next run:', schedule.due_date);
+     * console.log('Destinations:', destinations.length);
+     * ```
+     */
+    get(scheduleId: string): Promise<ScheduleGetResult>;
+    /**
+     * Update an existing schedule. Only the provided fields are modified.
+     *
+     * @remarks If the `expression` field is changed, the `due_date` is automatically
+     * recomputed based on the new cron expression.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @param params - The fields to update (all optional)
+     * @returns The updated schedule record
+     * @throws ServiceException on API errors (e.g., invalid cron expression, schedule not found)
+     *
+     * @example
+     * ```typescript
+     * // Update the name and expression
+     * const { schedule } = await service.update('sch_abc123', {
+     *   name: 'Daily Midnight Sync',
+     *   expression: '0 0 * * *',
+     * });
+     * console.log('Updated. Next run:', schedule.due_date);
+     * ```
+     */
+    update(scheduleId: string, params: UpdateScheduleParams): Promise<{
+        schedule: Schedule;
+    }>;
+    /**
+     * Delete a schedule and all of its destinations and delivery history.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @throws ServiceException on API errors (e.g., schedule not found)
+     *
+     * @example
+     * ```typescript
+     * await service.delete('sch_abc123');
+     * console.log('Schedule deleted');
+     * ```
+     */
+    delete(scheduleId: string): Promise<void>;
+    /**
+     * Create a new destination on an existing schedule.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @param params - The destination configuration including type and type-specific config
+     * @returns The newly created destination record
+     * @throws ServiceException on API errors (e.g., invalid URL, schedule not found)
+     *
+     * @example
+     * ```typescript
+     * const { destination } = await service.createDestination('sch_abc123', {
+     *   type: 'url',
+     *   config: {
+     *     url: 'https://example.com/webhook',
+     *     headers: { 'Authorization': 'Bearer token' },
+     *   },
+     * });
+     * console.log('Destination created:', destination.id);
+     * ```
+     */
+    createDestination(scheduleId: string, params: CreateScheduleDestinationParams): Promise<{
+        destination: ScheduleDestination;
+    }>;
+    /**
+     * Delete a destination from a schedule.
+     *
+     * @param destinationId - The destination ID (prefixed with `sdst_`)
+     * @throws ServiceException on API errors (e.g., destination not found)
+     *
+     * @example
+     * ```typescript
+     * await service.deleteDestination('sdst_xyz789');
+     * console.log('Destination removed');
+     * ```
+     */
+    deleteDestination(destinationId: string): Promise<void>;
+    /**
+     * List delivery attempts for a schedule with optional pagination.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of deliveries to return
+     * @param params.offset - Number of deliveries to skip for pagination
+     * @returns A list of delivery attempt records
+     * @throws ServiceException on API errors (including 404 if schedule not found)
+     *
+     * @example
+     * ```typescript
+     * const { deliveries } = await service.listDeliveries('sch_abc123');
+     * for (const d of deliveries) {
+     *   console.log(`${d.date}: ${d.status} (retries: ${d.retries})`);
+     *   if (d.error) {
+     *     console.error('  Error:', d.error);
+     *   }
+     * }
+     * ```
+     */
+    listDeliveries(scheduleId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ScheduleDeliveryListResult>;
+    /**
+     * Get a specific destination for a schedule by its ID.
+     *
+     * @remarks This is a convenience method that fetches the schedule and filters
+     * its destinations client-side. For large destination lists, prefer using
+     * {@link get} directly.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @param destinationId - The destination ID (prefixed with `sdst_`)
+     * @returns The matching destination record
+     * @throws Error if the destination is not found within the schedule
+     * @throws ServiceException on API errors when fetching the schedule
+     *
+     * @example
+     * ```typescript
+     * const dest = await service.getDestination('sch_abc123', 'sdst_xyz789');
+     * console.log('Destination type:', dest.type);
+     * console.log('Config:', dest.config);
+     * ```
+     */
+    getDestination(scheduleId: string, destinationId: string): Promise<ScheduleDestination>;
+    /**
+     * Get a specific delivery record by its ID.
+     *
+     * @remarks This is a convenience method that lists deliveries and filters
+     * client-side. Use the optional `params` to control the search window if
+     * the delivery may not be in the first page of results.
+     *
+     * @param scheduleId - The schedule ID (prefixed with `sch_`)
+     * @param deliveryId - The delivery ID to find
+     * @param params - Optional pagination parameters to control the search window
+     * @returns The matching delivery record
+     * @throws Error if the delivery is not found in the result set
+     * @throws ServiceException on API errors when listing deliveries
+     *
+     * @example
+     * ```typescript
+     * const delivery = await service.getDelivery('sch_abc123', 'del_xyz789');
+     * console.log('Status:', delivery.status);
+     * console.log('Retries:', delivery.retries);
+     * ```
+     */
+    getDelivery(scheduleId: string, deliveryId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ScheduleDelivery>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/services/schedule/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/services/schedule/service.ts"],"names":[],"mappings":"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"}