skedyul 1.5.13 → 1.7.0

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

@@ -6,10 +6,12 @@
 import type { ToolRegistry, WebhookRegistry, ToolMetadata, WebhookMetadata } from '../types';
 import type { ServerHooks } from '../types/handlers';
 import type { CoreApiConfig } from '../core/types';
-import type { EnvSchema, ComputeLayer, ModelDefinition, RelationshipDefinition, ChannelDefinition, WorkflowDefinition, PageDefinition, NavigationConfig, AgentDefinition, SignalDefinition } from './types';
+import type { EnvSchema, ComputeLayer, ModelDefinition, EntityDefinition, RelationshipDefinition, ChannelDefinition, WorkflowDefinition, PageDefinition, NavigationConfig, AgentDefinition, SignalDefinition } from './types';
 import type { AppEventDefinition } from './types/app-event';
 import type { QueueRegistry, SerializableQueueConfig } from './queue-config';
+import type { SequencerRegistry, SerializableSequencerConfig } from './sequencer-config';
 export type { QueueScope, QueueConfig, SerializableQueueConfig, QueueRegistry, } from './queue-config';
+export type { SequencerScope, SerializableSequencerConfig, SequencerRegistry, } from './sequencer-config';
 /**
  * Install configuration - defines per-install env vars and SHARED models.
  * This is configured by users during app installation.
@@ -31,6 +33,11 @@ export interface ProvisionConfig {
     env?: EnvSchema;
     /** INTERNAL model definitions (app-owned, not visible to users) */
     models?: ModelDefinition[];
+    /**
+     * App entity contracts for install-time CRM maps (not shared models).
+     * Workplaces map these to CRM; workflows apply maps via app-handle Liquid filters.
+     */
+    entities?: EntityDefinition[];
     /** Relationship definitions between INTERNAL models */
     relationships?: RelationshipDefinition[];
     /** Communication channel definitions */
@@ -109,6 +116,8 @@ export interface SkedyulConfig {
     build?: BuildConfig;
     /** Rate-limit queue definitions for queuedFetch */
     queues?: QueueRegistry;
+    /** Sequencer definitions for timestamp-aware ordering and short-lived locks */
+    sequencers?: SequencerRegistry;
 }
 /**
  * Serializable config (for database storage).
@@ -131,6 +140,8 @@ export interface SerializableSkedyulConfig {
     events?: AppEventDefinition[];
     /** Rate-limit queue definitions */
     queues?: Record<string, SerializableQueueConfig>;
+    /** Sequencer definitions */
+    sequencers?: Record<string, SerializableSequencerConfig>;
 }
 /**
  * Define a Skedyul app configuration with full type safety.

package/dist/config/define.d.ts

@@ -16,6 +16,7 @@
  * })
  */
 import type { ModelDefinition } from './types/model';
+import type { EntityDefinition } from './types/entity';
 import type { ChannelDefinition } from './types/channel';
 import type { PageDefinition } from './types/page';
 import type { WorkflowDefinition } from './types/workflow';
@@ -37,6 +38,28 @@ import type { NavigationConfig } from './types/navigation';
  * })
  */
 export declare function defineModel(model: ModelDefinition): ModelDefinition;
+/**
+ * Define an app entity (CRM map contract) with full type safety.
+ *
+ * Entities describe external payload shapes that workplaces map to CRM at
+ * install time. They are not shared models — workflows apply maps via Liquid
+ * filters named after the app handle (e.g. `| bft: "format", "member"`).
+ *
+ * @example
+ * export default defineEntity({
+ *   handle: 'member',
+ *   label: 'Glofox Member',
+ *   fields: [
+ *     { handle: 'glofox_id', label: 'Glofox ID', matchCandidate: true, required: true },
+ *     { handle: 'first_name', label: 'First Name' },
+ *   ],
+ *   contextFields: [
+ *     { handle: 'membership_status', label: 'Membership Status',
+ *       options: ['prospect', 'trial_member', 'member', 'inactive_member'] },
+ *   ],
+ * })
+ */
+export declare function defineEntity(entity: EntityDefinition): EntityDefinition;
 /**
  * Define a channel with full type safety.
  *

package/dist/config/index.d.ts

@@ -9,9 +9,9 @@
  * - All definition types extend BaseDefinition
  */
 export * from './types';
-export type { InstallConfig, ProvisionConfig, BuildConfig, CorsOptions, SkedyulConfig, SerializableSkedyulConfig, QueueScope, QueueConfig, SerializableQueueConfig, QueueRegistry, } from './app-config';
+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, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, } from './define';
+export { defineModel, defineEntity, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, } 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/sequencer-config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sequencer configuration for skedyul.config sequencers.
+ */
+import type { QueueScope } from './queue-config';
+export type SequencerScope = QueueScope;
+/**
+ * Serializable sequencer config (stored in DB / .skedyul/config.json).
+ */
+export interface SerializableSequencerConfig {
+    scope: SequencerScope;
+    /** Override endpoint handle for provision_endpoint / install_endpoint scopes */
+    endpoint?: string;
+    /** Opt-in per named sequencer (default false) */
+    enabled?: boolean;
+    /** Lock TTL for acquire() — default 60_000 ms */
+    lockTtlMs?: number;
+    /** Watermark key TTL in Redis — default 7 days */
+    watermarkTtlMs?: number;
+}
+export type SequencerRegistry = Record<string, SerializableSequencerConfig>;

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

@@ -0,0 +1,59 @@
+/**
+ * App entity definition types.
+ *
+ * Entities describe external/logical payload shapes (e.g. Glofox member) that
+ * workplaces map to CRM via install-time CRM maps. They are NOT shared models —
+ * the app does not own CRM writes; workflows/agents apply maps.
+ */
+import type { BaseDefinition, FieldOption } from './base';
+/**
+ * Field on an app entity contract (maps to a path on tool/event payloads).
+ */
+export interface EntityFieldDefinition {
+    /** Unique field handle (snake_case), used as source path by default */
+    handle: string;
+    /** Human-readable label */
+    label: string;
+    /** Optional description */
+    description?: string;
+    /** Data type hint for the install mapper UI */
+    type?: 'string' | 'long_string' | 'number' | 'boolean' | 'date' | 'datetime' | 'object';
+    /** Whether this field is a candidate for upsert match */
+    matchCandidate?: boolean;
+    /** Whether this field should be mapped for a complete configuration */
+    required?: boolean;
+    /** Enum options when the source value is constrained */
+    options?: FieldOption[] | string[];
+}
+/**
+ * Relationship declared on an entity (for install relationship mapping UI).
+ */
+export interface EntityRelationshipDefinition {
+    /** Handle used when writing relationship ids (e.g. "customer", "plan") */
+    handle: string;
+    /** Human-readable label */
+    label: string;
+    /** Target entity handle this relates to (optional documentation) */
+    targetEntity?: string;
+    description?: string;
+}
+/**
+ * App entity — mapping contract for install CRM maps + Liquid filters.
+ */
+export interface EntityDefinition extends BaseDefinition {
+    /** Unique entity handle (e.g. "member", "booking") */
+    handle: string;
+    /** Display label */
+    label: string;
+    labelPlural?: string;
+    description?: string;
+    /** Fields on the primary entity object */
+    fields: EntityFieldDefinition[];
+    /**
+     * Fields that live on the event/tool envelope alongside the entity
+     * (e.g. membership_status on member events).
+     */
+    contextFields?: EntityFieldDefinition[];
+    /** Relationship handles that can be mapped to CRM relationship fields */
+    relationships?: EntityRelationshipDefinition[];
+}

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

@@ -7,6 +7,7 @@ export * from './base';
 export * from './env';
 export * from './resource';
 export * from './model';
+export * from './entity';
 export * from './channel';
 export * from './workflow';
 export * from './agent';

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

@@ -160,6 +160,8 @@ export interface ModelDefinition extends BaseDefinition {
     addNavigation?: boolean;
     /** Root path for developer resource UI (e.g., '/access_requests'). Links internal model to a provision.pages entry. */
     page?: string;
+    /** Encrypted env vars scoped to each instance of this internal model */
+    env?: import('./env').EnvSchema;
 }
 /**
  * One side of a relationship link.

package/dist/core/client.d.ts

@@ -255,9 +255,27 @@ export interface InstanceData {
     id: string;
     /** The app installation this instance belongs to (if any) */
     appInstallationId?: string | null;
+    /** Encrypted env vars for this instance (only when requested via includeEnv) */
+    env?: Record<string, string>;
     _meta: InstanceMeta;
     [fieldHandle: string]: unknown;
 }
+export type InstanceEnv = Record<string, string>;
+export interface InstanceWriteOptions {
+    env?: InstanceEnv;
+}
+export interface InstanceGetOptions {
+    includeEnv?: boolean;
+}
+export type InstanceCreateManyItem = Record<string, unknown> | {
+    data: Record<string, unknown>;
+    env?: InstanceEnv;
+};
+export type InstanceUpdateManyItem = {
+    id: string;
+    data: Record<string, unknown>;
+    env?: InstanceEnv;
+};
 /**
  * Result from instance.list().
  */
@@ -282,9 +300,9 @@ export interface InstanceListArgs {
  */
 export interface InstanceClient {
     list(modelHandle: string, args?: InstanceListArgs): Promise<InstanceListResult>;
-    get(modelHandle: string, id: string): Promise<InstanceData | null>;
-    create(modelHandle: string, data: Record<string, unknown>): Promise<InstanceData>;
-    update(modelHandle: string, id: string, data: Record<string, unknown>): Promise<InstanceData>;
+    get(modelHandle: string, id: string, options?: InstanceGetOptions): Promise<InstanceData | null>;
+    create(modelHandle: string, data: Record<string, unknown>, options?: InstanceWriteOptions): Promise<InstanceData>;
+    update(modelHandle: string, id: string, data: Record<string, unknown>, options?: InstanceWriteOptions): Promise<InstanceData>;
     delete(modelHandle: string, id: string): Promise<{
         deleted: boolean;
     }>;
@@ -299,17 +317,14 @@ export interface InstanceClient {
             error: string;
         }>;
     }>;
-    createMany(modelHandle: string, items: Record<string, unknown>[]): Promise<{
+    createMany(modelHandle: string, items: InstanceCreateManyItem[]): Promise<{
         created: InstanceData[];
         errors: Array<{
             index: number;
             error: string;
         }>;
     }>;
-    updateMany(modelHandle: string, items: Array<{
-        id: string;
-        data: Record<string, unknown>;
-    }>): Promise<{
+    updateMany(modelHandle: string, items: InstanceUpdateManyItem[]): Promise<{
         updated: InstanceData[];
         errors: Array<{
             index: number;

package/dist/dedicated/server.js

@@ -97,6 +97,16 @@ function registerQueueConfig(config) {
   cachedRuntimeQueues = config.queues ?? null;
 }
 
+// src/sequencer/config-loader.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var cachedRuntimeSequencers = null;
+var registeredServerConfig2 = null;
+function registerSequencerConfig(config) {
+  registeredServerConfig2 = config;
+  cachedRuntimeSequencers = config.sequencers ?? null;
+}
+
 // src/server/utils/schema.ts
 var z = __toESM(require("zod"));
 function normalizeBilling(billing) {
@@ -733,7 +743,7 @@ function printStartupLog(config, tools, port) {
 
 // src/server/route-handlers/adapters.ts
 function fromLambdaEvent(event) {
-  const path3 = event.path || event.rawPath || "/";
+  const path4 = event.path || event.rawPath || "/";
   const method = event.httpMethod || event.requestContext?.http?.method || "POST";
   const forwardedProto = event.headers?.["x-forwarded-proto"] ?? event.headers?.["X-Forwarded-Proto"];
   const protocol = forwardedProto ?? "https";
@@ -741,9 +751,9 @@ function fromLambdaEvent(event) {
   const queryString = event.queryStringParameters ? "?" + new URLSearchParams(
     event.queryStringParameters
   ).toString() : "";
-  const url = `${protocol}://${host}${path3}${queryString}`;
+  const url = `${protocol}://${host}${path4}${queryString}`;
   return {
-    path: path3,
+    path: path4,
     method,
     headers: event.headers,
     query: event.queryStringParameters ?? {},
@@ -825,8 +835,8 @@ function parseBodyByContentType(req) {
 }
 
 // src/server/route-handlers/handlers.ts
-var fs2 = __toESM(require("fs"));
-var path2 = __toESM(require("path"));
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
 
 // src/server/core-api-handler.ts
 async function handleCoreMethod(method, params) {
@@ -1293,8 +1303,13 @@ async function handleOAuthCallback(parsedBody, hooks) {
   }
 }
 
+// src/types/webhook.ts
+function isRuntimeWebhookContext(ctx) {
+  return "appInstallationId" in ctx && ctx.appInstallationId !== void 0;
+}
+
 // src/server/handlers/webhook-handler.ts
-function parseWebhookRequest(parsedBody, method, url, path3, headers, query, rawBody, appIdHeader, appVersionIdHeader) {
+function parseWebhookRequest(parsedBody, method, url, path4, headers, query, rawBody, appIdHeader, appVersionIdHeader) {
   const isEnvelope = typeof parsedBody === "object" && parsedBody !== null && "env" in parsedBody && "request" in parsedBody && "context" in parsedBody;
   if (isEnvelope) {
     const envelope = parsedBody;
@@ -1348,7 +1363,7 @@ function parseWebhookRequest(parsedBody, method, url, path3, headers, query, raw
   const webhookRequest = {
     method,
     url,
-    path: path3,
+    path: path4,
     headers,
     query,
     body: parsedBody,
@@ -1377,9 +1392,17 @@ async function executeWebhookHandler(handle, webhookRegistry, data) {
   };
   let webhookResponse;
   try {
+    const rateLimitContext = {
+      app: data.webhookContext.app,
+      appInstallationId: isRuntimeWebhookContext(data.webhookContext) ? data.webhookContext.appInstallationId : void 0,
+      invocation: data.invocation,
+      isProvisionContext: !isRuntimeWebhookContext(data.webhookContext)
+    };
     webhookResponse = await runWithLogContext({ invocation: data.invocation }, async () => {
       return await runWithConfig(requestConfig, async () => {
-        return await webhookDef.handler(data.webhookRequest, data.webhookContext);
+        return await runWithRateLimitExecutionContext(rateLimitContext, async () => {
+          return await webhookDef.handler(data.webhookRequest, data.webhookContext);
+        });
       });
     });
   } catch (err) {
@@ -1406,7 +1429,7 @@ function isMethodAllowed(webhookRegistry, handle, method) {
 
 // src/server/route-handlers/handlers.ts
 function getConfigFilePath() {
-  return process.env.LAMBDA_TASK_ROOT ? path2.join(process.env.LAMBDA_TASK_ROOT, ".skedyul", "config.json") : ".skedyul/config.json";
+  return process.env.LAMBDA_TASK_ROOT ? path3.join(process.env.LAMBDA_TASK_ROOT, ".skedyul", "config.json") : ".skedyul/config.json";
 }
 function findToolInRegistry(registry, toolName) {
   for (const [key, t] of Object.entries(registry)) {
@@ -1445,8 +1468,8 @@ function handleHealthRoute(ctx) {
 function handleConfigRoute(ctx) {
   const configFilePath = getConfigFilePath();
   try {
-    if (fs2.existsSync(configFilePath)) {
-      const fileConfig = JSON.parse(fs2.readFileSync(configFilePath, "utf-8"));
+    if (fs3.existsSync(configFilePath)) {
+      const fileConfig = JSON.parse(fs3.readFileSync(configFilePath, "utf-8"));
       return { status: 200, body: fileConfig };
     }
   } catch (err) {
@@ -2134,6 +2157,7 @@ installContextLogger();
 function createSkedyulServer(config) {
   mergeRuntimeEnv();
   registerQueueConfig(config);
+  registerSequencerConfig(config);
   const registry = config.tools;
   const webhookRegistry = config.webhooks;
   if (config.coreApi?.service) {