skedyul 1.7.6 → 1.7.8

package/dist/.build-stamp

@@ -1 +1 @@
-1785913911217
+1785985393398

package/dist/cli/index.js

@@ -4658,6 +4658,128 @@ async function handleMcpBatchRoute(req, ctx) {
     }
   };
 }
+async function handleBatchOperationRoute(req, ctx) {
+  const bodyResult = parseJsonBody(req);
+  if (!bodyResult.success) {
+    return bodyResult.error;
+  }
+  const body = bodyResult.data;
+  const registry = ctx.batchOperationRegistry;
+  if (!registry) {
+    return {
+      status: 404,
+      body: {
+        success: false,
+        error: "No batch operations registered"
+      }
+    };
+  }
+  const operation = registry[body.handle];
+  if (!operation) {
+    return {
+      status: 404,
+      body: {
+        success: false,
+        error: `Batch operation not found: ${body.handle}`
+      }
+    };
+  }
+  const context = body.context;
+  if (!context?.workplaceId || !context?.appInstallationId || !context?.appId) {
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: "Missing context (workplaceId, appInstallationId, and appId required)"
+      }
+    };
+  }
+  const env = body.env ?? {};
+  const log = {
+    info: (message, meta) => {
+      console.log(`[batch:${body.handle}] ${message}`, meta ?? "");
+    },
+    warn: (message, meta) => {
+      console.warn(`[batch:${body.handle}] ${message}`, meta ?? "");
+    },
+    error: (message, meta) => {
+      console.error(`[batch:${body.handle}] ${message}`, meta ?? "");
+    }
+  };
+  const requestConfig = {
+    baseUrl: env.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: env.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  try {
+    if (body.method === "setup") {
+      if (!operation.setup) {
+        return {
+          status: 200,
+          body: {
+            success: true,
+            result: { state: {}, total: void 0 }
+          }
+        };
+      }
+      const result = await runWithConfig(requestConfig, async () => {
+        return operation.setup({
+          workplaceId: context.workplaceId,
+          appInstallationId: context.appInstallationId,
+          appId: context.appId,
+          input: body.input,
+          env,
+          log
+        });
+      });
+      return {
+        status: 200,
+        body: {
+          success: true,
+          result
+        }
+      };
+    }
+    if (body.method === "iterate") {
+      const result = await runWithConfig(requestConfig, async () => {
+        return operation.iterate({
+          workplaceId: context.workplaceId,
+          appInstallationId: context.appInstallationId,
+          appId: context.appId,
+          input: body.input,
+          state: body.state,
+          page: body.page,
+          cursor: body.cursor,
+          limit: body.limit,
+          env,
+          log
+        });
+      });
+      return {
+        status: 200,
+        body: {
+          success: true,
+          result
+        }
+      };
+    }
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: `Unknown method: ${body.method}`
+      }
+    };
+  } catch (err) {
+    log.error("Batch operation failed", { error: err });
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: err instanceof Error ? err.message : String(err)
+      }
+    };
+  }
+}
 function createNotFoundResponse() {
   return {
     status: 404,
@@ -4737,6 +4859,9 @@ async function routeRequest(req, ctx) {
     if (req.path === "/mcp/batch" && req.method === "POST") {
       return handleMcpBatchRoute(req, ctx);
     }
+    if (req.path === "/batch-operation" && req.method === "POST") {
+      return handleBatchOperationRoute(req, ctx);
+    }
     return createNotFoundResponse();
   } catch (err) {
     return createErrorResponse(err);
@@ -4778,11 +4903,13 @@ function createDedicatedServerInstance(config, tools, callTool, state, mcpServer
   const defaultHeaders = getDefaultHeaders(config.cors);
   const registry = config.tools;
   const webhookRegistry = config.webhooks;
+  const batchOperationRegistry = config.batchOperations;
   const ctx = {
     config,
     tools,
     registry,
     webhookRegistry,
+    batchOperationRegistry,
     callTool,
     state,
     mcpServer,
@@ -4897,12 +5024,14 @@ function createServerlessInstance(config, tools, callTool, state, mcpServer) {
   const defaultHeaders = getDefaultHeaders(config.cors);
   const registry = config.tools;
   const webhookRegistry = config.webhooks;
+  const batchOperationRegistry = config.batchOperations;
   let hasLoggedStartup = false;
   const ctx = {
     config,
     tools,
     registry,
     webhookRegistry,
+    batchOperationRegistry,
     callTool,
     state,
     mcpServer,

package/dist/config/app-config.d.ts

@@ -3,7 +3,7 @@
  *
  * This module defines the main configuration interfaces for Skedyul apps.
  */
-import type { ToolRegistry, WebhookRegistry, ToolMetadata, WebhookMetadata } from '../types';
+import type { ToolRegistry, WebhookRegistry, ToolMetadata, WebhookMetadata, BatchOperationRegistry } from '../types';
 import type { ServerHooks } from '../types/handlers';
 import type { CoreApiConfig } from '../core/types';
 import type { EnvSchema, ComputeLayer, ModelDefinition, EntityDefinition, RelationshipDefinition, ChannelDefinition, WorkflowDefinition, PageDefinition, NavigationConfig, AgentDefinition, SignalDefinition, SetupStepDefinition } from './types';
@@ -103,6 +103,10 @@ export interface SkedyulConfig {
     webhooks?: WebhookRegistry | Promise<{
         webhookRegistry: WebhookRegistry;
     }>;
+    /** Batch operation registry - direct object or dynamic import */
+    batchOperations?: BatchOperationRegistry | Promise<{
+        batchOperationRegistry: BatchOperationRegistry;
+    }>;
     /** Lifecycle hooks for install, provision, uninstall, and oauth_callback */
     hooks?: ServerHooks;
     /** Provision configuration - direct object or dynamic import */

package/dist/config/define.d.ts

@@ -24,6 +24,7 @@ import type { AgentDefinition } from './types/agent';
 import type { EnvSchema } from './types/env';
 import type { NavigationConfig } from './types/navigation';
 import type { SetupStepDefinition } from './types/setup';
+import type { BatchOperationDefinition } from './types/batch-operation';
 /**
  * Define a model with full type safety.
  *
@@ -166,3 +167,38 @@ export declare function defineNavigation(navigation: NavigationConfig): Navigati
  * })
  */
 export declare function defineSetupStep(step: SetupStepDefinition): SetupStepDefinition;
+/**
+ * Define a batch operation with full type safety.
+ *
+ * Batch operations are long-running, paginated tasks like imports and syncs.
+ * The platform handles orchestration, progress tracking, CRM mapping, and upsert.
+ *
+ * @example
+ * export default defineBatchOperation({
+ *   handle: 'import_members',
+ *   label: 'Import Members',
+ *   entity: 'member',
+ *   setup: async (ctx) => {
+ *     const count = await glofox.getMemberCount()
+ *     return { total: count }
+ *   },
+ *   iterate: async (ctx) => {
+ *     const apiKey = ctx.env.GLOFOX_API_KEY
+ *     const { data, pagination } = await glofox.getMembers({
+ *       apiKey,
+ *       limit: ctx.limit,
+ *       offset: ctx.cursor ?? 0,
+ *     })
+ *     return {
+ *       items: data,
+ *       pagination: {
+ *         hasMore: pagination.hasMore,
+ *         nextCursor: pagination.offset + pagination.limit,
+ *       }
+ *     }
+ *   },
+ *   maxConcurrent: 1,
+ *   pageSize: 50,
+ * })
+ */
+export declare function defineBatchOperation(operation: BatchOperationDefinition): BatchOperationDefinition;

package/dist/config/index.d.ts

@@ -11,7 +11,7 @@
 export * from './types';
 export type { InstallConfig, ProvisionConfig, BuildConfig, CorsOptions, SkedyulConfig, SerializableSkedyulConfig, QueueScope, QueueConfig, SerializableQueueConfig, QueueRegistry, SequencerScope, SerializableSequencerConfig, SequencerRegistry, } from './app-config';
 export { defineConfig } from './app-config';
-export { defineModel, defineEntity, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, defineSetupStep, } from './define';
+export { defineModel, defineEntity, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, defineSetupStep, defineBatchOperation, } from './define';
 export { SCHEMA_FILE_EXTENSIONS, loadSchema, saveSchema, serializeSchemaToJson, serializeSchemaToTypeScript, transformToBackendSchema, transformFromBackendSchema, type LoadSchemaOptions, type LoadSchemaResult, type SerializeSchemaOptions, type BackendModelDefinition, type BackendFieldDefinition, type BackendRelationshipDefinition, type BackendDesiredSchema, } from './schema-loader';
 export { loadAndResolveConfig, serializeResolvedConfig, type ResolvedConfig } from './resolver';
 export { getAllEnvKeys, getRequiredInstallEnvKeys } from './utils';

package/dist/config/types/batch-operation.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Batch operation definition types.
+ *
+ * Batch operations allow apps to define long-running, paginated operations
+ * like member imports, data syncs, and batch API calls. The platform handles
+ * orchestration, progress tracking, CRM mapping, and upsert.
+ */
+/**
+ * Pagination response from an iterate function.
+ * Supports both cursor-based and page-based pagination.
+ */
+export interface BatchPagination {
+    /** Whether there are more items to fetch */
+    hasMore: boolean;
+    /** Current page number (1-indexed, for page-based pagination) */
+    page?: number;
+    /** Total number of pages (for page-based pagination) */
+    total?: number;
+    /** Cursor for next page (for cursor-based pagination) */
+    nextCursor?: string | number;
+    /** Items per page */
+    limit?: number;
+}
+/**
+ * Result from a batch operation setup function.
+ */
+export interface BatchOperationSetupResult {
+    /** Optional state to persist across iterate calls */
+    state?: Record<string, unknown>;
+    /** Optional total count for progress display */
+    total?: number;
+}
+/**
+ * Result from a batch operation iterate function.
+ */
+export interface BatchOperationIterateResult {
+    /** Array of raw items from the external source */
+    items: Record<string, unknown>[];
+    /** Pagination info for fetching more pages */
+    pagination: BatchPagination;
+    /** Optional state to persist for the next iterate call */
+    state?: Record<string, unknown>;
+}
+/**
+ * Context passed to batch operation setup and iterate functions.
+ */
+export interface BatchOperationContext {
+    /** Workplace ID */
+    workplaceId: string;
+    /** App installation ID */
+    appInstallationId: string;
+    /** App ID */
+    appId: string;
+    /** User-provided input (if any) */
+    input?: Record<string, unknown>;
+    /** State from previous setup or iterate call */
+    state?: Record<string, unknown>;
+    /**
+     * Runtime environment variables from the platform invoke
+     * (APP_INSTALL overrides + SKEDYUL_API_TOKEN / SKEDYUL_API_URL).
+     */
+    env: Record<string, string>;
+    /** Logger instance */
+    log: {
+        info: (message: string, meta?: Record<string, unknown>) => void;
+        warn: (message: string, meta?: Record<string, unknown>) => void;
+        error: (message: string, meta?: Record<string, unknown>) => void;
+    };
+}
+/**
+ * Type for batch operation setup function.
+ */
+export type BatchOperationSetupFn = (ctx: BatchOperationContext) => Promise<BatchOperationSetupResult>;
+/**
+ * Type for batch operation iterate function.
+ */
+export type BatchOperationIterateFn = (ctx: BatchOperationContext & {
+    /** Page to fetch (1-indexed, for page-based pagination) */
+    page?: number;
+    /** Cursor from previous iterate (for cursor-based pagination) */
+    cursor?: string | number;
+    /** Items per page */
+    limit: number;
+}) => Promise<BatchOperationIterateResult>;
+/**
+ * Batch operation definition.
+ *
+ * @example
+ * export default defineBatchOperation({
+ *   handle: 'import_members',
+ *   label: 'Import Members',
+ *   entity: 'member',
+ *   setup: async (ctx) => {
+ *     const count = await glofox.getMemberCount()
+ *     return { total: count }
+ *   },
+ *   iterate: async (ctx) => {
+ *     const apiKey = ctx.env.GLOFOX_API_KEY
+ *     const { data, pagination } = await glofox.getMembers({
+ *       apiKey,
+ *       limit: ctx.limit,
+ *       offset: ctx.cursor ?? 0,
+ *     })
+ *     return {
+ *       items: data,
+ *       pagination: {
+ *         hasMore: pagination.hasMore,
+ *         nextCursor: pagination.offset + pagination.limit,
+ *       }
+ *     }
+ *   },
+ *   maxConcurrent: 1,
+ *   pageSize: 50,
+ * })
+ */
+export interface BatchOperationDefinition {
+    /** Unique handle for this operation */
+    handle: string;
+    /** Human-readable label */
+    label: string;
+    /** Description of what this operation does */
+    description?: string;
+    /**
+     * Entity handle that items will be upserted to.
+     * The platform applies CRM mappings and calls upsertMany.
+     */
+    entity: string;
+    /**
+     * Setup function called once at the start of the operation.
+     * Use to initialize state, fetch total count, etc.
+     */
+    setup?: BatchOperationSetupFn;
+    /**
+     * Iterate function called for each page of data.
+     * Must return items and pagination info.
+     */
+    iterate: BatchOperationIterateFn;
+    /**
+     * Maximum concurrent operations per app installation.
+     * @default 1
+     */
+    maxConcurrent?: number;
+    /**
+     * Default page size (items per iterate call).
+     * @default 50
+     */
+    pageSize?: number;
+    /**
+     * Optional icon for the operation (Lucide icon name)
+     */
+    icon?: string;
+}

package/dist/config/types/index.d.ts

@@ -19,3 +19,4 @@ export * from './navigation';
 export * from './context';
 export * from './form';
 export * from './page';
+export * from './batch-operation';

package/dist/dedicated/server.js

@@ -1988,6 +1988,128 @@ async function handleMcpBatchRoute(req, ctx) {
     }
   };
 }
+async function handleBatchOperationRoute(req, ctx) {
+  const bodyResult = parseJsonBody(req);
+  if (!bodyResult.success) {
+    return bodyResult.error;
+  }
+  const body = bodyResult.data;
+  const registry = ctx.batchOperationRegistry;
+  if (!registry) {
+    return {
+      status: 404,
+      body: {
+        success: false,
+        error: "No batch operations registered"
+      }
+    };
+  }
+  const operation = registry[body.handle];
+  if (!operation) {
+    return {
+      status: 404,
+      body: {
+        success: false,
+        error: `Batch operation not found: ${body.handle}`
+      }
+    };
+  }
+  const context = body.context;
+  if (!context?.workplaceId || !context?.appInstallationId || !context?.appId) {
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: "Missing context (workplaceId, appInstallationId, and appId required)"
+      }
+    };
+  }
+  const env = body.env ?? {};
+  const log = {
+    info: (message, meta) => {
+      console.log(`[batch:${body.handle}] ${message}`, meta ?? "");
+    },
+    warn: (message, meta) => {
+      console.warn(`[batch:${body.handle}] ${message}`, meta ?? "");
+    },
+    error: (message, meta) => {
+      console.error(`[batch:${body.handle}] ${message}`, meta ?? "");
+    }
+  };
+  const requestConfig = {
+    baseUrl: env.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: env.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  try {
+    if (body.method === "setup") {
+      if (!operation.setup) {
+        return {
+          status: 200,
+          body: {
+            success: true,
+            result: { state: {}, total: void 0 }
+          }
+        };
+      }
+      const result = await runWithConfig(requestConfig, async () => {
+        return operation.setup({
+          workplaceId: context.workplaceId,
+          appInstallationId: context.appInstallationId,
+          appId: context.appId,
+          input: body.input,
+          env,
+          log
+        });
+      });
+      return {
+        status: 200,
+        body: {
+          success: true,
+          result
+        }
+      };
+    }
+    if (body.method === "iterate") {
+      const result = await runWithConfig(requestConfig, async () => {
+        return operation.iterate({
+          workplaceId: context.workplaceId,
+          appInstallationId: context.appInstallationId,
+          appId: context.appId,
+          input: body.input,
+          state: body.state,
+          page: body.page,
+          cursor: body.cursor,
+          limit: body.limit,
+          env,
+          log
+        });
+      });
+      return {
+        status: 200,
+        body: {
+          success: true,
+          result
+        }
+      };
+    }
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: `Unknown method: ${body.method}`
+      }
+    };
+  } catch (err) {
+    log.error("Batch operation failed", { error: err });
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: err instanceof Error ? err.message : String(err)
+      }
+    };
+  }
+}
 function createNotFoundResponse() {
   return {
     status: 404,
@@ -2067,6 +2189,9 @@ async function routeRequest(req, ctx) {
     if (req.path === "/mcp/batch" && req.method === "POST") {
       return handleMcpBatchRoute(req, ctx);
     }
+    if (req.path === "/batch-operation" && req.method === "POST") {
+      return handleBatchOperationRoute(req, ctx);
+    }
     return createNotFoundResponse();
   } catch (err) {
     return createErrorResponse(err);
@@ -2108,11 +2233,13 @@ function createDedicatedServerInstance(config, tools, callTool, state, mcpServer
   const defaultHeaders = getDefaultHeaders(config.cors);
   const registry = config.tools;
   const webhookRegistry = config.webhooks;
+  const batchOperationRegistry = config.batchOperations;
   const ctx = {
     config,
     tools,
     registry,
     webhookRegistry,
+    batchOperationRegistry,
     callTool,
     state,
     mcpServer,
@@ -2227,12 +2354,14 @@ function createServerlessInstance(config, tools, callTool, state, mcpServer) {
   const defaultHeaders = getDefaultHeaders(config.cors);
   const registry = config.tools;
   const webhookRegistry = config.webhooks;
+  const batchOperationRegistry = config.batchOperations;
   let hasLoggedStartup = false;
   const ctx = {
     config,
     tools,
     registry,
     webhookRegistry,
+    batchOperationRegistry,
     callTool,
     state,
     mcpServer,