skedyul 1.7.8 → 1.7.11

package/dist/.build-stamp

@@ -1 +1 @@
-1785985393398
+1786058725534

package/dist/cli/index.js

@@ -4658,6 +4658,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) {
@@ -4666,49 +4699,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") {
@@ -4717,67 +4781,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/config/types/batch-operation.d.ts

@@ -5,6 +5,10 @@
  * like member imports, data syncs, and batch API calls. The platform handles
  * orchestration, progress tracking, CRM mapping, and upsert.
  */
+import type { InvocationContext } from '../../types/invocation';
+import type { ToolBilling, ToolError, ToolRetry } from '../../types/tool';
+import type { AppInfo, WorkplaceInfo } from '../../types/shared';
+export type { ToolBilling, ToolError, ToolRetry };
 /**
  * Pagination response from an iterate function.
  * Supports both cursor-based and page-based pagination.
@@ -21,6 +25,15 @@ export interface BatchPagination {
     /** Items per page */
     limit?: number;
 }
+/**
+ * Soft-failure return from setup/iterate (tool-call shaped).
+ */
+export interface BatchOperationFailure {
+    success: false;
+    error: ToolError;
+    retry?: ToolRetry;
+    billing?: ToolBilling;
+}
 /**
  * Result from a batch operation setup function.
  */
@@ -29,18 +42,59 @@ export interface BatchOperationSetupResult {
     state?: Record<string, unknown>;
     /** Optional total count for progress display */
     total?: number;
+    /**
+     * Cascade phases (usually injected from the operation definition by the
+     * route handler so the platform workflow can resolve map-gated targets).
+     */
+    cascade?: BatchCascadePhase[];
+    /** Optional billing (normalized by the route if omitted) */
+    billing?: ToolBilling;
+    /** Optional success discriminator (default true when domain fields present) */
+    success?: true;
+}
+/**
+ * Cascade phase for multi-entity batch imports.
+ * Platform upserts configured entities in `order` within each wave.
+ */
+export interface BatchCascadePhase {
+    /** App entity handle to upsert */
+    entity: string;
+    /** Lower runs first within the same wave */
+    order: number;
+    /** setup = once (typically first iterate); page = every iterate page */
+    wave: 'setup' | 'page';
+    /**
+     * Other cascade entities that must also be CRM-configured for this phase
+     * to run (e.g. plan requires package).
+     */
+    requires?: string[];
 }
 /**
  * Result from a batch operation iterate function.
  */
 export interface BatchOperationIterateResult {
-    /** Array of raw items from the external source */
+    /**
+     * Array of raw items for the primary `entity`.
+     * Prefer `itemsByEntity` for cascade imports; when both are set, platform
+     * uses `itemsByEntity` and falls back to `items` for the primary entity.
+     */
     items: Record<string, unknown>[];
+    /**
+     * Multi-entity items keyed by entity handle (cascade imports).
+     * Platform upserts each configured entity in cascade order.
+     */
+    itemsByEntity?: Record<string, Record<string, unknown>[]>;
     /** Pagination info for fetching more pages */
     pagination: BatchPagination;
     /** Optional state to persist for the next iterate call */
     state?: Record<string, unknown>;
+    /** Optional billing (normalized by the route if omitted) */
+    billing?: ToolBilling;
+    /** Optional success discriminator (default true when domain fields present) */
+    success?: true;
 }
+export type BatchOperationSetupReturn = BatchOperationSetupResult | BatchOperationFailure;
+export type BatchOperationIterateReturn = BatchOperationIterateResult | BatchOperationFailure;
 /**
  * Context passed to batch operation setup and iterate functions.
  */
@@ -51,15 +105,27 @@ export interface BatchOperationContext {
     appInstallationId: string;
     /** App ID */
     appId: string;
+    /** App info with version (for rate-limit / SDK context) */
+    app?: AppInfo;
+    /** Workplace info when available */
+    workplace?: WorkplaceInfo;
     /** 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).
+     * Merged environment (process.env + baked MCP_ENV + request env),
+     * same layering as tool handlers via buildToolExecutionEnv.
      */
     env: Record<string, string>;
+    /** Invocation context for log traceability */
+    invocation?: InvocationContext;
+    /**
+     * Entity handles whose CRM maps are configured for this job's cascade.
+     * Platform injects this on iterate so apps can skip expensive fetches
+     * (e.g. per-member credits) when that entity is not mapped.
+     */
+    cascadeEntities?: string[];
     /** Logger instance */
     log: {
         info: (message: string, meta?: Record<string, unknown>) => void;
@@ -70,7 +136,7 @@ export interface BatchOperationContext {
 /**
  * Type for batch operation setup function.
  */
-export type BatchOperationSetupFn = (ctx: BatchOperationContext) => Promise<BatchOperationSetupResult>;
+export type BatchOperationSetupFn = (ctx: BatchOperationContext) => Promise<BatchOperationSetupReturn>;
 /**
  * Type for batch operation iterate function.
  */
@@ -81,7 +147,7 @@ export type BatchOperationIterateFn = (ctx: BatchOperationContext & {
     cursor?: string | number;
     /** Items per page */
     limit: number;
-}) => Promise<BatchOperationIterateResult>;
+}) => Promise<BatchOperationIterateReturn>;
 /**
  * Batch operation definition.
  *
@@ -121,10 +187,15 @@ export interface BatchOperationDefinition {
     /** Description of what this operation does */
     description?: string;
     /**
-     * Entity handle that items will be upserted to.
+     * Primary entity handle (progress + start gate).
      * The platform applies CRM mappings and calls upsertMany.
      */
     entity: string;
+    /**
+     * Optional multi-entity cascade. When set, iterate may return
+     * `itemsByEntity` and the platform upserts map-configured phases in order.
+     */
+    cascade?: BatchCascadePhase[];
     /**
      * Setup function called once at the start of the operation.
      * Use to initialize state, fetch total count, etc.