@synap-core/workspace-templates 0.6.3 → 0.7.0

package/src/types.ts

@@ -259,9 +259,9 @@ export interface TemplateOnboarding {
 // ============================================================================
 // Playbooks — session templates seeded with the workspace
 //
-// Mirrors `PackagePlaybook` in synap-backend `package-definition.ts`. Seeded
-// via the packages/apply provisioning path (not createFromDefinition), so they
-// are carried on the template but not part of WorkspaceDefinitionInput.
+// Mirrors `PackagePlaybook` in synap-backend `package-definition.ts`. The
+// workspace converter normalizes these to the compact createFromDefinition
+// input contract; package apply retains the richer authored representation.
 // ============================================================================
 
 export interface TemplatePlaybookParam {
@@ -297,6 +297,97 @@ export interface TemplatePlaybook {
   status?: 'draft' | 'active' | 'paused';
 }
 
+// ============================================================================
+// Automations — flow-based WHEN→THEN triggers seeded with the workspace
+//
+// Mirrors the backend's `PackagePostWorkspaceBody['automations'][number]`
+// (synap-backend `package-apply-post-workspace.ts`) — the wire shape the
+// SHARED `applyPackagePostWorkspace` door (Hub `POST /packages/apply` AND the
+// proposals approve-executor) actually accepts. Distinct from the LOOP-style
+// `{trigger, action: {playbookSlug}}` automations `workspaces.createFromDefinition`
+// takes. Flow automations travel through the separate `flowAutomations` field on
+// that door, then enter the same generic post-workspace applier as the Hub path.
+//
+// Example (a capability-node automation gating a facet update behind a governed
+// tool call — see the CRM handoff doc):
+//   { name: "Enrich new lead", triggerType: "event",
+//     triggerConfig: { eventPattern: "entity.created:lead" },
+//     flow: { nodes: [
+//       { id: "trigger", type: "trigger" },
+//       { id: "enrich", type: "capability", capabilityKey: "enrichment.lookup" },
+//       { id: "update", type: "entity_facet_update", profileSlug: "lead" },
+//     ], edges: [{ from: "trigger", to: "enrich" }, { from: "enrich", to: "update" }] } }
+// ============================================================================
+
+export interface TemplateAutomation {
+  /** Stable local key (unused on the wire today — reserved for dedup/refs). */
+  key?: string;
+  name: string;
+  description?: string;
+  triggerType: 'event' | 'cron' | 'webhook' | 'manual';
+  triggerConfig?: Record<string, unknown>;
+  flow: { nodes: unknown[]; edges: unknown[]; precondition?: string };
+  status?: 'draft' | 'active' | 'paused';
+}
+
+// ============================================================================
+// Action placements — template-declarable actions on an entity-detail surface
+//
+// A template says "on the `deal` detail page, show a 'Qualify lead' action that
+// launches playbook X / runs capability Y / triggers automation Z" — with NO
+// per-domain code change. Persisted (by `applyPackagePostWorkspace`) into
+// `workspace.settings.actionPlacements`, which `workspaces.update` merges via
+// `z.record` (no migration, no new table). The browser entity-detail cell reads
+// them for the entity's `profileSlug` and renders a small action row.
+//
+// `ref` is authored as a NAME (playbook/automation name) or a stable capability
+// verb key. The apply door resolves playbook/automation names → row ids so the
+// browser can launch them directly (capability refs pass through). See
+// `PackagePostWorkspaceBody['actionPlacements']` in synap-backend
+// `package-apply-post-workspace.ts` — same shape.
+//
+// Example:
+//   actionPlacements:
+//     - profileSlug: deal
+//       surface: entity-detail
+//       kind: playbook
+//       ref: "Qualify lead"
+//       label: "Qualify lead"
+// ============================================================================
+
+export interface TemplateActionPlacement {
+  /** Entity kind whose detail surface this action appears on. */
+  profileSlug: string;
+  /** Where the action renders. Only "entity-detail" is consumed today. */
+  surface: 'entity-detail' | string;
+  /** What the action does when clicked. */
+  kind: 'capability' | 'playbook' | 'automation';
+  /**
+   * Reference to the thing to run: a capability verb key, or a playbook /
+   * automation NAME (resolved to a row id at apply time).
+   */
+  ref: string;
+  /** Human label shown on the action button. */
+  label: string;
+  /** Additional entity-state requirements, evaluated by the rendering surface. */
+  when?: {
+    /** All listed workspace facets must be present on the entity. */
+    requiredFacetSlugs?: string[];
+    /** Entity property values that must equal their configured literal values. */
+    propertyEquals?: Record<string, unknown>;
+    /** Any configured property/value match makes the action applicable. */
+    propertyAnyEquals?: Record<string, unknown[]>;
+    /** Entity property values that must not equal their configured literal values. */
+    propertyNotEquals?: Record<string, unknown>;
+  };
+  /** Explicit intent required before a consequential action is launched. */
+  confirmation?: {
+    title: string;
+    description?: string;
+    confirmLabel?: string;
+  };
+}
+
 // ============================================================================
 // Integrations — capability templates (tools/connectors) to install
 //
@@ -506,6 +597,18 @@ export interface WorkspaceYaml {
   /** Playbooks (session templates) seeded with the workspace */
   playbooks?: TemplatePlaybook[];
 
+  /**
+   * Flow-based automations (WHEN→THEN triggers) seeded with the workspace.
+   * Applier-only — see {@link TemplateAutomation}.
+   */
+  automations?: TemplateAutomation[];
+
+  /**
+   * Entity-detail action placements seeded into `settings.actionPlacements`.
+   * See {@link TemplateActionPlacement}.
+   */
+  actionPlacements?: TemplateActionPlacement[];
+
   /** Capability templates (tools/connectors) to install on provisioning */
   integrations?: TemplateIntegration[];