skedyul 1.7.8 → 1.7.11

package/dist/server.js

@@ -1988,6 +1988,39 @@ async function handleMcpBatchRoute(req, ctx) {
     }
   };
 }
+function isBatchOperationFailure(result) {
+  return result != null && typeof result === "object" && result.success === false && typeof result.error === "object" && result.error != null;
+}
+function toStringEnv(env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function stripBillingFields(result) {
+  const {
+    billing: _billing,
+    success: _success,
+    error: _error,
+    retry: _retry,
+    ...domain
+  } = result;
+  return domain;
+}
+function softFailureResponse(error, retry, billing) {
+  return {
+    status: 200,
+    body: {
+      success: false,
+      error,
+      ...retry ? { retry } : {},
+      billing: normalizeBilling(billing)
+    }
+  };
+}
 async function handleBatchOperationRoute(req, ctx) {
   const bodyResult = parseJsonBody(req);
   if (!bodyResult.success) {
@@ -1996,49 +2029,80 @@ async function handleBatchOperationRoute(req, ctx) {
   const body = bodyResult.data;
   const registry = ctx.batchOperationRegistry;
   if (!registry) {
-    return {
-      status: 404,
-      body: {
-        success: false,
-        error: "No batch operations registered"
-      }
-    };
+    return softFailureResponse({
+      code: "NOT_FOUND",
+      message: "No batch operations registered",
+      category: "validation"
+    });
   }
   const operation = registry[body.handle];
   if (!operation) {
-    return {
-      status: 404,
-      body: {
-        success: false,
-        error: `Batch operation not found: ${body.handle}`
-      }
-    };
+    return softFailureResponse({
+      code: "NOT_FOUND",
+      message: `Batch operation not found: ${body.handle}`,
+      category: "validation"
+    });
   }
   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)"
-      }
-    };
+    return softFailureResponse({
+      code: "VALIDATION_ERROR",
+      message: "Missing context (workplaceId, appInstallationId, and appId required)",
+      category: "validation"
+    });
   }
-  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 ?? "");
-    }
+  if (body.method !== "setup" && body.method !== "iterate") {
+    return softFailureResponse({
+      code: "VALIDATION_ERROR",
+      message: `Unknown method: ${body.method}`,
+      category: "validation"
+    });
+  }
+  const requestEnv = body.env ?? {};
+  const mergedEnv = toStringEnv(buildToolExecutionEnv(requestEnv));
+  const originalEnv = { ...process.env };
+  Object.assign(process.env, mergedEnv);
+  const log = createContextLogger();
+  const app = context.app ?? {
+    id: context.appId,
+    versionId: context.appId
+  };
+  const workplace = context.workplace ?? {
+    id: context.workplaceId,
+    subdomain: ""
+  };
+  const invocation = body.invocation ?? {
+    invocationId: `${body.handle}-${body.method}-${Date.now()}`,
+    invocationType: "batch_operation",
+    batchOperationHandle: body.handle,
+    batchOperationMethod: body.method,
+    appInstallationId: context.appInstallationId
   };
   const requestConfig = {
-    baseUrl: env.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
-    apiToken: env.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+    baseUrl: mergedEnv.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: mergedEnv.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  const rateLimitContext = {
+    app,
+    appInstallationId: context.appInstallationId,
+    invocation,
+    preAcquiredLeases: parsePreAcquiredLeases(
+      mergedEnv.SKEDYUL_RATE_LIMIT_LEASES
+    ),
+    heldMutexQueueKeys: parseHeldMutexQueueKeys(
+      mergedEnv.SKEDYUL_HELD_MUTEX_QUEUE_KEYS
+    )
+  };
+  const opContextBase = {
+    workplaceId: context.workplaceId,
+    appInstallationId: context.appInstallationId,
+    appId: context.appId,
+    app,
+    workplace,
+    input: body.input,
+    env: mergedEnv,
+    invocation,
+    log
   };
   try {
     if (body.method === "setup") {
@@ -2047,67 +2111,98 @@ async function handleBatchOperationRoute(req, ctx) {
           status: 200,
           body: {
             success: true,
-            result: { state: {}, total: void 0 }
+            result: {
+              state: {},
+              total: void 0,
+              cascade: operation.cascade
+            },
+            billing: normalizeBilling(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
+      const raw2 = await runWithConfig(requestConfig, async () => {
+        return runWithRateLimitExecutionContext(rateLimitContext, async () => {
+          return runWithLogContext({ invocation }, async () => {
+            return operation.setup(opContextBase);
+          });
         });
       });
+      if (isBatchOperationFailure(raw2)) {
+        return softFailureResponse(raw2.error, raw2.retry, raw2.billing);
+      }
+      const setupResult = raw2;
+      const domain2 = stripBillingFields(
+        setupResult
+      );
       return {
         status: 200,
         body: {
           success: true,
-          result
+          result: {
+            ...domain2,
+            // Expose definition cascade to the platform workflow
+            cascade: operation.cascade ?? domain2.cascade
+          },
+          billing: normalizeBilling(setupResult.billing)
         }
       };
     }
-    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
+    const iterateBody = body;
+    const raw = await runWithConfig(requestConfig, async () => {
+      return runWithRateLimitExecutionContext(rateLimitContext, async () => {
+        return runWithLogContext({ invocation }, async () => {
+          return operation.iterate({
+            ...opContextBase,
+            state: iterateBody.state,
+            page: iterateBody.page,
+            cursor: iterateBody.cursor,
+            limit: iterateBody.limit,
+            cascadeEntities: iterateBody.cascadeEntities
+          });
         });
       });
-      return {
-        status: 200,
-        body: {
-          success: true,
-          result
-        }
-      };
+    });
+    if (isBatchOperationFailure(raw)) {
+      return softFailureResponse(raw.error, raw.retry, raw.billing);
     }
+    const iterateResult = raw;
+    const domain = stripBillingFields(
+      iterateResult
+    );
     return {
-      status: 400,
+      status: 200,
       body: {
-        success: false,
-        error: `Unknown method: ${body.method}`
+        success: true,
+        result: domain,
+        billing: normalizeBilling(iterateResult.billing)
       }
     };
   } catch (err) {
-    log.error("Batch operation failed", { error: err });
+    if (err instanceof RateLimitExceededError) {
+      return softFailureResponse(
+        {
+          code: "RATE_LIMITED",
+          message: err.message,
+          category: "external"
+        },
+        { allowed: true, afterMs: err.retryAfterMs }
+      );
+    }
+    log.error("Batch operation failed", err);
     return {
       status: 500,
       body: {
         success: false,
-        error: err instanceof Error ? err.message : String(err)
+        error: {
+          code: "INTERNAL_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+          category: "internal"
+        },
+        billing: normalizeBilling(void 0)
       }
     };
+  } finally {
+    process.env = originalEnv;
   }
 }
 function createNotFoundResponse() {

package/dist/serverless/server.mjs

@@ -1949,6 +1949,39 @@ async function handleMcpBatchRoute(req, ctx) {
     }
   };
 }
+function isBatchOperationFailure(result) {
+  return result != null && typeof result === "object" && result.success === false && typeof result.error === "object" && result.error != null;
+}
+function toStringEnv(env) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function stripBillingFields(result) {
+  const {
+    billing: _billing,
+    success: _success,
+    error: _error,
+    retry: _retry,
+    ...domain
+  } = result;
+  return domain;
+}
+function softFailureResponse(error, retry, billing) {
+  return {
+    status: 200,
+    body: {
+      success: false,
+      error,
+      ...retry ? { retry } : {},
+      billing: normalizeBilling(billing)
+    }
+  };
+}
 async function handleBatchOperationRoute(req, ctx) {
   const bodyResult = parseJsonBody(req);
   if (!bodyResult.success) {
@@ -1957,49 +1990,80 @@ async function handleBatchOperationRoute(req, ctx) {
   const body = bodyResult.data;
   const registry = ctx.batchOperationRegistry;
   if (!registry) {
-    return {
-      status: 404,
-      body: {
-        success: false,
-        error: "No batch operations registered"
-      }
-    };
+    return softFailureResponse({
+      code: "NOT_FOUND",
+      message: "No batch operations registered",
+      category: "validation"
+    });
   }
   const operation = registry[body.handle];
   if (!operation) {
-    return {
-      status: 404,
-      body: {
-        success: false,
-        error: `Batch operation not found: ${body.handle}`
-      }
-    };
+    return softFailureResponse({
+      code: "NOT_FOUND",
+      message: `Batch operation not found: ${body.handle}`,
+      category: "validation"
+    });
   }
   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)"
-      }
-    };
+    return softFailureResponse({
+      code: "VALIDATION_ERROR",
+      message: "Missing context (workplaceId, appInstallationId, and appId required)",
+      category: "validation"
+    });
   }
-  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 ?? "");
-    }
+  if (body.method !== "setup" && body.method !== "iterate") {
+    return softFailureResponse({
+      code: "VALIDATION_ERROR",
+      message: `Unknown method: ${body.method}`,
+      category: "validation"
+    });
+  }
+  const requestEnv = body.env ?? {};
+  const mergedEnv = toStringEnv(buildToolExecutionEnv(requestEnv));
+  const originalEnv = { ...process.env };
+  Object.assign(process.env, mergedEnv);
+  const log = createContextLogger();
+  const app = context.app ?? {
+    id: context.appId,
+    versionId: context.appId
+  };
+  const workplace = context.workplace ?? {
+    id: context.workplaceId,
+    subdomain: ""
+  };
+  const invocation = body.invocation ?? {
+    invocationId: `${body.handle}-${body.method}-${Date.now()}`,
+    invocationType: "batch_operation",
+    batchOperationHandle: body.handle,
+    batchOperationMethod: body.method,
+    appInstallationId: context.appInstallationId
   };
   const requestConfig = {
-    baseUrl: env.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
-    apiToken: env.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+    baseUrl: mergedEnv.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: mergedEnv.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  const rateLimitContext = {
+    app,
+    appInstallationId: context.appInstallationId,
+    invocation,
+    preAcquiredLeases: parsePreAcquiredLeases(
+      mergedEnv.SKEDYUL_RATE_LIMIT_LEASES
+    ),
+    heldMutexQueueKeys: parseHeldMutexQueueKeys(
+      mergedEnv.SKEDYUL_HELD_MUTEX_QUEUE_KEYS
+    )
+  };
+  const opContextBase = {
+    workplaceId: context.workplaceId,
+    appInstallationId: context.appInstallationId,
+    appId: context.appId,
+    app,
+    workplace,
+    input: body.input,
+    env: mergedEnv,
+    invocation,
+    log
   };
   try {
     if (body.method === "setup") {
@@ -2008,67 +2072,98 @@ async function handleBatchOperationRoute(req, ctx) {
           status: 200,
           body: {
             success: true,
-            result: { state: {}, total: void 0 }
+            result: {
+              state: {},
+              total: void 0,
+              cascade: operation.cascade
+            },
+            billing: normalizeBilling(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
+      const raw2 = await runWithConfig(requestConfig, async () => {
+        return runWithRateLimitExecutionContext(rateLimitContext, async () => {
+          return runWithLogContext({ invocation }, async () => {
+            return operation.setup(opContextBase);
+          });
         });
       });
+      if (isBatchOperationFailure(raw2)) {
+        return softFailureResponse(raw2.error, raw2.retry, raw2.billing);
+      }
+      const setupResult = raw2;
+      const domain2 = stripBillingFields(
+        setupResult
+      );
       return {
         status: 200,
         body: {
           success: true,
-          result
+          result: {
+            ...domain2,
+            // Expose definition cascade to the platform workflow
+            cascade: operation.cascade ?? domain2.cascade
+          },
+          billing: normalizeBilling(setupResult.billing)
         }
       };
     }
-    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
+    const iterateBody = body;
+    const raw = await runWithConfig(requestConfig, async () => {
+      return runWithRateLimitExecutionContext(rateLimitContext, async () => {
+        return runWithLogContext({ invocation }, async () => {
+          return operation.iterate({
+            ...opContextBase,
+            state: iterateBody.state,
+            page: iterateBody.page,
+            cursor: iterateBody.cursor,
+            limit: iterateBody.limit,
+            cascadeEntities: iterateBody.cascadeEntities
+          });
         });
       });
-      return {
-        status: 200,
-        body: {
-          success: true,
-          result
-        }
-      };
+    });
+    if (isBatchOperationFailure(raw)) {
+      return softFailureResponse(raw.error, raw.retry, raw.billing);
     }
+    const iterateResult = raw;
+    const domain = stripBillingFields(
+      iterateResult
+    );
     return {
-      status: 400,
+      status: 200,
       body: {
-        success: false,
-        error: `Unknown method: ${body.method}`
+        success: true,
+        result: domain,
+        billing: normalizeBilling(iterateResult.billing)
       }
     };
   } catch (err) {
-    log.error("Batch operation failed", { error: err });
+    if (err instanceof RateLimitExceededError) {
+      return softFailureResponse(
+        {
+          code: "RATE_LIMITED",
+          message: err.message,
+          category: "external"
+        },
+        { allowed: true, afterMs: err.retryAfterMs }
+      );
+    }
+    log.error("Batch operation failed", err);
     return {
       status: 500,
       body: {
         success: false,
-        error: err instanceof Error ? err.message : String(err)
+        error: {
+          code: "INTERNAL_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+          category: "internal"
+        },
+        billing: normalizeBilling(void 0)
       }
     };
+  } finally {
+    process.env = originalEnv;
   }
 }
 function createNotFoundResponse() {

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

@@ -3,8 +3,8 @@
  *
  * These types define the registry and context for batch operations at runtime.
  */
-import type { BatchOperationSetupFn, BatchOperationIterateFn } from '../config/types/batch-operation';
-export type { BatchOperationContext } from '../config/types/batch-operation';
+import type { BatchCascadePhase, BatchOperationSetupFn, BatchOperationIterateFn } from '../config/types/batch-operation';
+export type { BatchCascadePhase, BatchOperationContext, } from '../config/types/batch-operation';
 /**
  * Entry in the batch operation registry.
  * Contains both metadata and function implementations.
@@ -16,8 +16,10 @@ export interface BatchOperationRegistryEntry {
     label: string;
     /** Description of what this operation does */
     description?: string;
-    /** Entity handle that items will be upserted to */
+    /** Primary entity handle that items will be upserted to */
     entity: string;
+    /** Optional multi-entity cascade phases */
+    cascade?: BatchCascadePhase[];
     /** Setup function called once at the start */
     setup?: BatchOperationSetupFn;
     /** Iterate function called for each page */
@@ -41,6 +43,7 @@ export interface BatchOperationMetadata {
     label: string;
     description?: string;
     entity: string;
+    cascade?: BatchCascadePhase[];
     maxConcurrent?: number;
     pageSize?: number;
     icon?: string;

package/dist/types/index.d.ts

@@ -6,7 +6,7 @@
  */
 export type { AppInfo, AppInfoWithHandles, WorkplaceInfo, RequestInfo } from './shared';
 export type { InvocationType, ServerHookHandle, InvocationContext, } from './invocation';
-export { createToolCallContext, createServerHookContext, createWebhookContext, createWorkflowStepContext, } from './invocation';
+export { createToolCallContext, createServerHookContext, createWebhookContext, createWorkflowStepContext, createBatchOperationContext, } from './invocation';
 export type { ToolTrigger, ProvisionToolContext, DeveloperPageActionToolContext, DeveloperFormSubmitToolContext, FieldChangeToolContext, PageActionToolContext, FormSubmitToolContext, AgentToolContext, WorkflowToolContext, CronToolContext, CronContext, ToolExecutionContext, } from './tool-context';
 export { isProvisionContext, isRuntimeContext, isCronContext, isDeveloperContext } from './tool-context';
 export type { ToolResult, ToolSuccess, ToolFailure, ErrorCode, ErrorCategory, ToolWarning, ToolPagination, ToolBilling, ToolRetry, ToolTiming, ToolCompletionHints, ToolConfig, QueueTouchPoint, BillingInfo, ToolResponseMeta, ToolEffect, ToolError, ToolExecutionResult, ToolSchemaWithJson, ToolSchema, ToolHandler, ToolDefinition, ToolRegistryEntry, ToolRegistry, ToolName, ToolMetadata, ToolCallResponse, ExecutionScope, } from './tool';

package/dist/types/invocation.d.ts

@@ -1,7 +1,7 @@
 /**
  * Type of invocation that triggered the executable
  */
-export type InvocationType = 'tool_call' | 'server_hook' | 'workflow_step' | 'webhook';
+export type InvocationType = 'tool_call' | 'server_hook' | 'workflow_step' | 'webhook' | 'batch_operation';
 /**
  * Server hook handles for lifecycle events
  */
@@ -19,6 +19,10 @@ export interface InvocationContext {
     toolCallId?: string;
     /** The tool's handle for searching (e.g., "get_customers") */
     toolHandle?: string;
+    /** Batch operation handle (for batch_operation invocations) */
+    batchOperationHandle?: string;
+    /** setup | iterate */
+    batchOperationMethod?: 'setup' | 'iterate';
     /** Hook type: "provision", "install", "uninstall", "oauth_callback", "setup.revalidate" */
     serverHookHandle?: ServerHookHandle;
     /** The app installation that triggered the call */
@@ -69,3 +73,14 @@ export declare function createWorkflowStepContext(params: {
     workflowRunId: string;
     workflowStepId?: string;
 }): InvocationContext;
+/**
+ * Create an invocation context for a batch operation setup/iterate call
+ */
+export declare function createBatchOperationContext(params: {
+    invocationId: string;
+    batchOperationHandle: string;
+    batchOperationMethod: 'setup' | 'iterate';
+    appInstallationId?: string;
+    workflowId?: string;
+    workflowRunId?: string;
+}): InvocationContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skedyul",
-  "version": "1.7.8",
+  "version": "1.7.11",
   "description": "The Skedyul SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -76,7 +76,7 @@
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc --emitDeclarationOnly && pnpm exec tsup-node && node -e \"require('fs').mkdirSync('dist',{recursive:true}); require('fs').writeFileSync('dist/.build-stamp', String(Date.now()))\"",
     "db:generate": "echo 'No database generation needed for this package'",
     "dev:watch": "npx nodemon --watch src --ext js,ts --exec \"pnpm run build\"",
-    "test": "tsc --project tsconfig.tests.json && node --test dist-tests/tests/server.test.js dist-tests/tests/cli.test.js dist-tests/tests/agent-schema-v3.test.js dist-tests/tests/ratelimit.test.js dist-tests/tests/sequencer.test.js dist-tests/tests/config-loader.test.js dist-tests/tests/gsm7.test.js"
+    "test": "tsc --project tsconfig.tests.json && node --test dist-tests/tests/server.test.js dist-tests/tests/cli.test.js dist-tests/tests/agent-schema-v3.test.js dist-tests/tests/ratelimit.test.js dist-tests/tests/sequencer.test.js dist-tests/tests/config-loader.test.js dist-tests/tests/gsm7.test.js dist-tests/tests/batch-operation.test.js"
   },
   "keywords": [
     "mcp",