skedyul 1.6.0 → 1.7.1

package/dist/cli/index.js

@@ -3870,6 +3870,72 @@ async function handleProvision(body, hooks) {
   }
 }
 
+// src/server/handlers/setup-revalidate-handler.ts
+async function handleSetupRevalidate(body, hooks) {
+  const revalidateHook = hooks?.setup?.revalidate;
+  if (!revalidateHook) {
+    return {
+      status: 404,
+      body: { error: "Setup revalidate handler not configured" }
+    };
+  }
+  if (!body.context?.appInstallationId || !body.context?.workplace || !body.context?.app || !body.reason || !Array.isArray(body.steps)) {
+    return {
+      status: 400,
+      body: {
+        error: {
+          code: -32602,
+          message: "Missing context (appInstallationId, workplace, app, reason, and steps required)"
+        }
+      }
+    };
+  }
+  const ctx = {
+    env: body.env ?? {},
+    workplace: body.context.workplace,
+    appInstallationId: body.context.appInstallationId,
+    app: body.context.app,
+    reason: body.reason,
+    steps: body.steps,
+    crm: body.crm,
+    envChange: body.envChange,
+    invocation: body.invocation,
+    log: createContextLogger()
+  };
+  const requestConfig = {
+    baseUrl: body.env?.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: body.env?.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  try {
+    const handler = typeof revalidateHook === "function" ? revalidateHook : revalidateHook.handler;
+    const result = await runWithLogContext(
+      { invocation: body.invocation },
+      async () => {
+        return await runWithConfig(requestConfig, async () => {
+          return await handler(ctx);
+        });
+      }
+    );
+    return {
+      status: 200,
+      body: {
+        completed: result?.completed ?? [],
+        invalidated: result?.invalidated ?? []
+      }
+    };
+  } catch (err) {
+    return {
+      status: 500,
+      body: {
+        error: {
+          code: -32603,
+          message: err instanceof Error ? err.message : String(err ?? "")
+        }
+      }
+    };
+  }
+}
+
 // src/server/handler-helpers.ts
 function parseHandlerEnvelope(parsedBody) {
   if (typeof parsedBody !== "object" || parsedBody === null || Array.isArray(parsedBody) || !("env" in parsedBody) || !("request" in parsedBody)) {
@@ -4261,6 +4327,14 @@ async function handleProvisionRoute(req, ctx) {
   const result = await handleProvision(parseResult.data, ctx.config.hooks);
   return { status: result.status, body: result.body };
 }
+async function handleSetupRevalidateRoute(req, ctx) {
+  const parseResult = parseJsonBody(req);
+  if (!parseResult.success) {
+    return parseResult.error;
+  }
+  const result = await handleSetupRevalidate(parseResult.data, ctx.config.hooks);
+  return { status: result.status, body: result.body };
+}
 async function handleOAuthCallbackRoute(req, ctx) {
   const parseResult = parseJsonBody(req);
   if (!parseResult.success) {
@@ -4622,6 +4696,9 @@ async function routeRequest(req, ctx) {
     if (req.path === "/provision" && req.method === "POST") {
       return handleProvisionRoute(req, ctx);
     }
+    if (req.path === "/setup/revalidate" && req.method === "POST") {
+      return handleSetupRevalidateRoute(req, ctx);
+    }
     if (req.path === "/oauth_callback" && req.method === "POST") {
       return handleOAuthCallbackRoute(req, ctx);
     }

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

@@ -6,7 +6,7 @@
 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, SetupStepDefinition } from './types';
 import type { AppEventDefinition } from './types/app-event';
 import type { QueueRegistry, SerializableQueueConfig } from './queue-config';
 import type { SequencerRegistry, SerializableSequencerConfig } from './sequencer-config';
@@ -33,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 */
@@ -45,6 +50,11 @@ export interface ProvisionConfig {
     pages?: PageDefinition[];
     /** App signal definitions (event bus subscriptions created on install) */
     signals?: SignalDefinition[];
+    /**
+     * Install setup checklist steps (opt-in).
+     * Seeded as AppInstallSetupStep rows; exposed via setup.* Core API.
+     */
+    setup?: SetupStepDefinition[];
 }
 /**
  * Build configuration - controls how the integration is bundled.

package/dist/config/define.d.ts

@@ -16,12 +16,14 @@
  * })
  */
 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';
 import type { AgentDefinition } from './types/agent';
 import type { EnvSchema } from './types/env';
 import type { NavigationConfig } from './types/navigation';
+import type { SetupStepDefinition } from './types/setup';
 /**
  * Define a model with full type safety.
  *
@@ -37,6 +39,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.
  *
@@ -127,3 +151,18 @@ export declare function defineEnv(env: EnvSchema): EnvSchema;
  * })
  */
 export declare function defineNavigation(navigation: NavigationConfig): NavigationConfig;
+/**
+ * Define an install setup step with full type safety.
+ *
+ * @example
+ * export default defineSetupStep({
+ *   handle: 'crm_members_bookings_events',
+ *   label: 'Setup Members, Bookings and Events',
+ *   kind: 'crm',
+ *   requires: ['access_granted'],
+ *   entities: ['member', 'booking', 'event'],
+ *   listenToCrm: true,
+ *   capabilities: ['crm.member', 'crm.booking', 'crm.event'],
+ * })
+ */
+export declare function defineSetupStep(step: SetupStepDefinition): SetupStepDefinition;

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, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, } from './define';
+export { defineModel, defineEntity, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, defineSetupStep, } 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/entity.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 uniquely identifies a record and can be used as an
+     * upsert match key (e.g. external id, email, phone).
+     */
+    isUnique?: boolean;
+    /**
+     * @deprecated Prefer `isUnique`. Kept for backward compatibility —
+     * treated the same as `isUnique` by the CRM map editor.
+     */
+    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/form.d.ts

@@ -352,15 +352,7 @@ export interface ListBlock {
     /** Message when no items */
     emptyMessage?: string;
 }
-/**
- * Model mapper block definition - for mapping SHARED models to workspace models.
- */
-export interface ModelMapperBlock {
-    type: 'model_mapper';
-    /** The SHARED model handle from provision config */
-    model: string;
-}
 /**
  * Union of all block types.
  */
-export type BlockDefinition = CardBlock | ListBlock | ModelMapperBlock;
+export type BlockDefinition = CardBlock | ListBlock;

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

@@ -7,11 +7,13 @@ export * from './base';
 export * from './env';
 export * from './resource';
 export * from './model';
+export * from './entity';
 export * from './channel';
 export * from './workflow';
 export * from './agent';
 export * from './webhook';
 export * from './signal';
+export * from './setup';
 export * from './app-event';
 export * from './navigation';
 export * from './context';

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

@@ -0,0 +1,37 @@
+/**
+ * App install setup step definition for provision config.
+ *
+ * Declared steps are seeded onto each AppInstallation as AppInstallSetupStep
+ * rows. Apps and the platform UI read/update status via the setup.* Core API.
+ */
+export type SetupStepKind = 'app' | 'crm' | 'realtime' | 'env';
+export interface SetupStepDefinition {
+    /** Stable step handle (unique within the app) */
+    handle: string;
+    /** UI label */
+    label: string;
+    /** Optional longer description */
+    description?: string;
+    /** Step kind — drives default CTAs and listeners */
+    kind: SetupStepKind;
+    /** Prerequisite step handles that must be READY */
+    requires?: string[];
+    /** CRM entity handles this step covers (kind: crm) */
+    entities?: string[];
+    /** Bundled workflow handles this step wires (kind: realtime) */
+    workflowHandles?: string[];
+    /** Env keys this step depends on (kind: env) */
+    envKeys?: string[];
+    /**
+     * When true, platform emits install.setup.crm_changed after CRM migrations
+     * and invokes hooks.setup.revalidate so the app can complete/invalidate.
+     */
+    listenToCrm?: boolean;
+    /**
+     * When true, platform emits install.setup.env_changed when matching env
+     * keys are removed/cleared and invokes hooks.setup.revalidate.
+     */
+    listenToEnv?: boolean;
+    /** Capability keys unlocked when this step is READY */
+    capabilities?: string[];
+}

package/dist/core/client.d.ts

@@ -1241,4 +1241,43 @@ export declare const report: {
      */
     get(handle: string): Promise<ReportDefinition | null>;
 };
+export type SetupStepStatus = 'PENDING' | 'READY' | 'SKIPPED' | 'INVALIDATED' | 'BLOCKED';
+export type SetupStepKindApi = 'APP' | 'CRM' | 'REALTIME' | 'ENV';
+export type SetupStepView = {
+    id: string;
+    handle: string;
+    kind: SetupStepKindApi;
+    status: SetupStepStatus;
+    sortOrder: number;
+    label: string;
+    description: string | null;
+    requires: string[];
+    config: {
+        entities?: string[];
+        workflowHandles?: string[];
+        envKeys?: string[];
+        listenToCrm?: boolean;
+        listenToEnv?: boolean;
+        capabilities?: string[];
+    };
+    completedAt: string | null;
+    skippedAt: string | null;
+    invalidatedAt: string | null;
+    metadata: Record<string, unknown> | null;
+};
+export type SetupListResult = {
+    steps: SetupStepView[];
+    capabilities: Record<string, boolean>;
+};
+/**
+ * Install setup checklist API (requires sk_wkp_ token).
+ */
+export declare const setup: {
+    list(): Promise<SetupListResult>;
+    get(handle: string): Promise<SetupStepView | null>;
+    complete(handle: string, metadata?: Record<string, unknown>): Promise<SetupStepView>;
+    skip(handle: string, metadata?: Record<string, unknown>): Promise<SetupStepView>;
+    invalidate(handle: string, reason?: string, metadata?: Record<string, unknown>): Promise<SetupStepView>;
+    capabilities(): Promise<Record<string, boolean>>;
+};
 export {};

package/dist/dedicated/server.js

@@ -1200,6 +1200,72 @@ async function handleProvision(body, hooks) {
   }
 }
 
+// src/server/handlers/setup-revalidate-handler.ts
+async function handleSetupRevalidate(body, hooks) {
+  const revalidateHook = hooks?.setup?.revalidate;
+  if (!revalidateHook) {
+    return {
+      status: 404,
+      body: { error: "Setup revalidate handler not configured" }
+    };
+  }
+  if (!body.context?.appInstallationId || !body.context?.workplace || !body.context?.app || !body.reason || !Array.isArray(body.steps)) {
+    return {
+      status: 400,
+      body: {
+        error: {
+          code: -32602,
+          message: "Missing context (appInstallationId, workplace, app, reason, and steps required)"
+        }
+      }
+    };
+  }
+  const ctx = {
+    env: body.env ?? {},
+    workplace: body.context.workplace,
+    appInstallationId: body.context.appInstallationId,
+    app: body.context.app,
+    reason: body.reason,
+    steps: body.steps,
+    crm: body.crm,
+    envChange: body.envChange,
+    invocation: body.invocation,
+    log: createContextLogger()
+  };
+  const requestConfig = {
+    baseUrl: body.env?.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: body.env?.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  try {
+    const handler = typeof revalidateHook === "function" ? revalidateHook : revalidateHook.handler;
+    const result = await runWithLogContext(
+      { invocation: body.invocation },
+      async () => {
+        return await runWithConfig(requestConfig, async () => {
+          return await handler(ctx);
+        });
+      }
+    );
+    return {
+      status: 200,
+      body: {
+        completed: result?.completed ?? [],
+        invalidated: result?.invalidated ?? []
+      }
+    };
+  } catch (err) {
+    return {
+      status: 500,
+      body: {
+        error: {
+          code: -32603,
+          message: err instanceof Error ? err.message : String(err ?? "")
+        }
+      }
+    };
+  }
+}
+
 // src/server/handler-helpers.ts
 function parseHandlerEnvelope(parsedBody) {
   if (typeof parsedBody !== "object" || parsedBody === null || Array.isArray(parsedBody) || !("env" in parsedBody) || !("request" in parsedBody)) {
@@ -1591,6 +1657,14 @@ async function handleProvisionRoute(req, ctx) {
   const result = await handleProvision(parseResult.data, ctx.config.hooks);
   return { status: result.status, body: result.body };
 }
+async function handleSetupRevalidateRoute(req, ctx) {
+  const parseResult = parseJsonBody(req);
+  if (!parseResult.success) {
+    return parseResult.error;
+  }
+  const result = await handleSetupRevalidate(parseResult.data, ctx.config.hooks);
+  return { status: result.status, body: result.body };
+}
 async function handleOAuthCallbackRoute(req, ctx) {
   const parseResult = parseJsonBody(req);
   if (!parseResult.success) {
@@ -1952,6 +2026,9 @@ async function routeRequest(req, ctx) {
     if (req.path === "/provision" && req.method === "POST") {
       return handleProvisionRoute(req, ctx);
     }
+    if (req.path === "/setup/revalidate" && req.method === "POST") {
+      return handleSetupRevalidateRoute(req, ctx);
+    }
     if (req.path === "/oauth_callback" && req.method === "POST") {
       return handleOAuthCallbackRoute(req, ctx);
     }