@proteos/sdk 0.61.0 → 0.76.0

package/src/meta/types.ts

@@ -657,6 +657,24 @@ export interface EntityContactBindingInput {
   duplicate_policy?: ContactBindingDuplicatePolicy
 }
 
+/**
+ * A composite unique constraint: no two records may share the same values for
+ * `attributes` (2+). One-attribute constraints are `is_unique` on the
+ * attribute. Enforced as a unique index on the record table; a violating write
+ * fails with 409 `record_unique_violation` naming the constraint.
+ */
+export interface UniqueConstraint {
+  /** snake_case, unique within the entity. */
+  name: string
+  /** Attribute names or object paths (`address.city`); never platform columns. */
+  attributes: string[]
+}
+
+export const UniqueConstraintSchema = z.object({
+  name: z.string(),
+  attributes: z.array(z.string()),
+})
+
 export interface Entity extends AuditFields {
   slug: string
   name: string
@@ -689,6 +707,8 @@ export interface Entity extends AuditFields {
    */
   title_template: string
   attributes: Attribute[]
+  /** Composite unique constraints; absent when none are declared. */
+  unique_constraints?: UniqueConstraint[]
 }
 
 export const EntitySchema = AuditFieldsSchema.extend({
@@ -706,6 +726,7 @@ export const EntitySchema = AuditFieldsSchema.extend({
   // the wire.
   title_template: z.string().default(''),
   attributes: z.array(AttributeSchema),
+  unique_constraints: z.array(UniqueConstraintSchema).optional(),
 })
 
 /**
@@ -753,6 +774,11 @@ export interface CreateEntityRequest {
   description: string
   title_template?: string
   attributes: Attribute[]
+  /**
+   * Composite unique constraints. Full-replacement on upsert: omitted means
+   * none (the `is_unique` ones travel with their attributes).
+   */
+  unique_constraints?: UniqueConstraint[]
 }
 
 /**
@@ -771,6 +797,8 @@ export interface UpdateEntityRequest {
   description?: string
   title_template?: string
   attributes?: Attribute[]
+  /** Omitted leaves the stored list alone; a list (empty included) replaces it. */
+  unique_constraints?: UniqueConstraint[]
 }
 
 // ============================================================================
@@ -905,6 +933,14 @@ export interface Component extends AuditFields {
   bundle_file_id: string
   /** FK to a tar.gz of the component source directory in storage (provenance / rebuild). Empty until deployed. */
   source_file_id: string
+  /**
+   * Content address of the compiled bundle, `sha256:<hex>`, stamped server-side
+   * at deploy. Lets `pro module deploy` skip an unchanged upload and lets the
+   * runtime fetch the bundle under an immutable URL
+   * ({@link ComponentService.bundleUrl}). Absent on rows deployed before
+   * checksum stamping.
+   */
+  bundle_checksum?: string
   /** The component's JSON Schema, driving the page-designer props editor + runtime validation. `null` until set. */
   props_schema: Record<string, unknown> | null
   /**
@@ -914,6 +950,13 @@ export interface Component extends AuditFields {
    * `functions.actions.invokePublic`.
    */
   is_public: boolean
+  /**
+   * Height in px the host reserves for a placement of this component before
+   * it has rendered — when the page element sets no `reserved_height` and no
+   * earlier visit is remembered. Declared in the component's manifest.
+   * Absent / 0 = undeclared, the host default applies.
+   */
+  reserved_height?: number
 }
 
 export const ComponentSchema = AuditFieldsSchema.extend({
@@ -923,6 +966,8 @@ export const ComponentSchema = AuditFieldsSchema.extend({
   module_slug: z.string(),
   bundle_file_id: z.string(),
   source_file_id: z.string(),
+  bundle_checksum: z.string().optional(),
+  reserved_height: z.number().int().nonnegative().optional(),
   // default(false): rows serialized before the flag existed lack the field.
   props_schema: z.record(z.unknown()).nullable(),
   is_public: z.boolean().default(false),
@@ -950,6 +995,8 @@ export interface CreateComponentRequest {
   props_schema?: Record<string, unknown>
   /** See {@link Component.is_public}. Manifest-driven: omitting it sets false. */
   is_public?: boolean
+  /** See {@link Component.reserved_height}. Manifest-driven: omitting it sets 0. */
+  reserved_height?: number
 }
 
 /**
@@ -962,6 +1009,7 @@ export interface UpdateComponentRequest {
   source_file_id?: string
   props_schema?: Record<string, unknown>
   is_public?: boolean
+  reserved_height?: number
 }
 
 // ============================================================================
@@ -1036,20 +1084,84 @@ export {
 // ============================================================================
 
 /**
- * What a page toolbar button invokes. Absent normalizes to `action` (pages
+ * What an action button invokes. Absent normalizes to `action` (buttons
  * persisted before `kind` existed).
  */
-export type PageActionKind = 'action' | 'workflow'
+export type PageActionKind = 'action' | 'workflow' | 'agent' | 'intent' | 'link'
+
+export const PageActionKindSchema = z.enum(['action', 'workflow', 'agent', 'intent', 'link'])
+
+/** What a `kind: intent` button has the model prepare — a record proposal
+ *  (`*_record`) or an action's / workflow's inputs (`invoke_*`). */
+export type PageActionIntent =
+  | 'create_record'
+  | 'update_record'
+  | 'upsert_record'
+  | 'invoke_action'
+  | 'invoke_workflow'
+
+/** Most candidates an `upsert_record` button hands the model. */
+export const PAGE_ACTION_MATCH_MAX_LIMIT = 25
+
+/**
+ * The list query an `upsert_record` button finds its candidate records with —
+ * a page of `entity` records, fetched when the button is pressed. `filter`
+ * has the list endpoint's `_filter` shape; every element's `value` is a
+ * Liquid template, and a value that renders empty yields NO candidates (never
+ * a wider query). `sort` is `field:asc|desc`; `limit` defaults to 10.
+ */
+export interface PageActionMatch {
+  filter?: FilterGroup
+  sort?: string
+  limit?: number
+}
+
+export const PageActionMatchSchema = z.object({
+  filter: FilterGroupSchema.optional(),
+  sort: z.string().optional(),
+  limit: z.number().int().min(1).max(PAGE_ACTION_MATCH_MAX_LIMIT).optional(),
+})
 
 /**
- * Page action definition — one toolbar button. `kind: action` invokes a
- * function-service Action by slug (`action`) and may prefill its params;
- * `kind: workflow` starts a manual run of a workflow by key (`workflow`) and
- * may prefill its manual-trigger inputs. `params` / `inputs` map target field
- * names to Liquid templates rendered against the page scope
- * `{ record, entity, params, user }`; a resolved field is locked in the invoke
- * dialog. `skip_confirmation` fires the target immediately when every required
- * field resolved from the templates.
+ * One action button — a page's or a list's toolbar button, or a conversation
+ * type's action (the strip in the call or meeting surface's footer, during
+ * and after the conversation).
+ * Which target it invokes follows from `kind`:
+ *
+ * - `action`   → `action` (slug) + `params`
+ * - `workflow` → `workflow` (key) + `inputs`
+ * - `agent`    → `agent` (key) + `prompt` + `context`: opens an Ava chat with
+ *   that agent; `prompt` becomes the visible first message (the label when
+ *   empty), `context` is handed to the model alongside it and never shown.
+ * - `intent`   → `intent` + `entity` (+ `record` | `match`) + `prompt` + `context`:
+ *   prepares a record proposal (one model call), shows it as an editable
+ *   review and saves only what the person confirms. `update_record` targets
+ *   `record` when set, else the surface's linked record of `entity`.
+ *   `upsert_record` hands the model the records `match` finds and lets it
+ *   change one of them or prepare a new record — `prompt` says how to choose.
+ *   `field_scope` (any intent) lists the attributes the proposal may fill,
+ *   replacing the app's bound create / edit page.
+ *   `invoke_action` / `invoke_workflow` open the invoke dialog of `action` /
+ *   `workflow` with the model's values in the fields `params` / `inputs`
+ *   (Liquid, locked) left open — always reviewed, never run unseen; on a
+ *   call surface it opens as a workspace tab instead of a modal.
+ * - `link`     → `url`: opens the rendered address in a new browser tab
+ *   (http, https, mailto and tel only). Renders synchronously on the press,
+ *   so `| summarize` renders '' there.
+ *
+ * `params` / `inputs` map target field names to Liquid templates; `prompt`,
+ * `context`, `entity`, `record` and `url` are Liquid templates too. Everything
+ * renders client-side against the surface's scope (a page:
+ * `{ record, entity, params, current_user }`; a conversation:
+ * `{ conversation, contact, records, records_by_entity, tags,
+ * tags_by_definition, brief, current_user }`, where `| summarize: "<lens>"`
+ * on the conversation or a tag writes a focused summary of what was said when
+ * the button is pressed). `prompt` is literal message TEXT, never a Prompt
+ * resource key. `visible_when` hides the button unless the surface's subject
+ * matches (the record on a page, the whole scope on a conversation — the
+ * stage is `conversation.status eq active` / `in ended|archived`, a detected
+ * tag `tags_by_definition.<key> not_empty`). `skip_confirmation` fires an
+ * action/workflow immediately when every required field resolved.
  */
 export interface PageAction {
   label: string
@@ -1057,9 +1169,23 @@ export interface PageAction {
   kind?: PageActionKind
   action?: string
   workflow?: string
+  agent?: string
+  intent?: PageActionIntent
+  entity?: string
+  record?: string
+  /** `upsert_record` only: how the candidate records are found. */
+  match?: PageActionMatch
+  /** Intent only: the attribute names the proposal may fill (plain names).
+   *  Replaces the app's bound create / edit page as the scope; required
+   *  attributes without a default are always added. */
+  field_scope?: string[]
+  url?: string
   params?: Record<string, string>
   inputs?: Record<string, string>
+  prompt?: string
+  context?: string
   skip_confirmation?: boolean
+  visible_when?: FilterGroup
   /** List-extension stamp on a toolbar action a list extension appended to its host list. */
   extension_key?: string
 }
@@ -1067,12 +1193,24 @@ export interface PageAction {
 export const PageActionSchema = z.object({
   label: z.string(),
   icon: z.string(),
-  kind: z.enum(['action', 'workflow']).optional(),
+  kind: PageActionKindSchema.optional(),
   action: z.string().optional(),
   workflow: z.string().optional(),
+  agent: z.string().optional(),
+  intent: z
+    .enum(['create_record', 'update_record', 'upsert_record', 'invoke_action', 'invoke_workflow'])
+    .optional(),
+  entity: z.string().optional(),
+  record: z.string().optional(),
+  match: PageActionMatchSchema.optional(),
+  field_scope: z.array(z.string()).optional(),
+  url: z.string().optional(),
   params: z.record(z.string()).optional(),
   inputs: z.record(z.string()).optional(),
+  prompt: z.string().optional(),
+  context: z.string().optional(),
   skip_confirmation: z.boolean().optional(),
+  visible_when: FilterGroupSchema.optional(),
   extension_key: z.string().optional(),
 })
 
@@ -1255,10 +1393,46 @@ export interface UpdateListViewRequest {
  * - `public`:   standalone, NO app chrome (bare page at `/p/…`);
  *   UNAUTHENTICATED — the layout is world-readable and its components may only
  *   call `is_public` global actions.
+ * - `trigger`:  what the person sees when they trigger an action or a
+ *   workflow — rendered inside the invoke dialog. Bound by `kind` +
+ *   `reference` to ONE invocable; its `field` elements bind to that
+ *   invocable's params and returns instead of an entity's attributes. Which
+ *   dialog phase a trigger page renders in is the app configuration's binding
+ *   (`action_pages` / `workflow_pages`), like which record mode a record page
+ *   opens in (`record_pages`).
  */
-export type PageType = 'record' | 'platform' | 'kiosk' | 'public'
+export type PageType = 'record' | 'platform' | 'kiosk' | 'public' | 'trigger'
 
-export const PageTypeSchema = z.enum(['record', 'platform', 'kiosk', 'public'])
+export const PageTypeSchema = z.enum(['record', 'platform', 'kiosk', 'public', 'trigger'])
+
+/**
+ * How the viewer interacts with a record page — the `mode` the Liquid scope
+ * and the component protocol carry (the same three words as `PageMode` in
+ * `@proteos/component-sdk`). A record page serves every mode; which page a
+ * mode opens in is the app configuration's `record_pages` binding.
+ *
+ * - `view`:   a read-only record page.
+ * - `create`: the form for a record that is not saved yet.
+ * - `edit`:   the form over a saved record.
+ */
+export type PageMode = 'view' | 'create' | 'edit'
+
+/**
+ * Where an invocation is in the invoke dialog's lifecycle — the `phase` the
+ * dialog's Liquid scope and component protocol carry, and the key of a
+ * `TriggerPageBinding`. Orthogonal to `PageMode`: the input phase renders in
+ * `create` mode, running and result in `view` mode. A trigger page serves
+ * every phase; which page a phase renders is the app configuration's binding.
+ *
+ * - `input`:   the form (and the confirm step, rendered read-only) over the
+ *   params.
+ * - `running`: while the invoke call runs; for a workflow, the "started" page
+ *   after the run was accepted. The params, read-only; the scope also carries
+ *   `execution` for workflows.
+ * - `result`:  once the action returned (the params plus its returns) or the
+ *   workflow run reached a terminal status (`execution` in scope).
+ */
+export type TriggerPhase = 'input' | 'running' | 'result'
 
 /**
  * Page configuration. A `record` page is the detail-page shape for a single
@@ -1273,8 +1447,13 @@ export interface Page extends AuditFields {
   name: string
   module_slug: string
   type: PageType
-  /** Required for `record` pages; absent on `platform` pages. */
+  /** Required for `record` pages; absent on every other type. */
   entity_slug?: string
+  /** Trigger pages only: what the page opens for — `action` (an action slug)
+   *  or `workflow` (a workflow key). Absent = `action`. Immutable. */
+  kind?: PageActionKind
+  /** Trigger pages only: the action slug / workflow key. Immutable. */
+  reference?: string
   actions: PageAction[]
   layout: PageLayout
 }
@@ -1285,6 +1464,8 @@ export const PageSchema = AuditFieldsSchema.extend({
   module_slug: z.string(),
   type: PageTypeSchema,
   entity_slug: z.string().optional(),
+  kind: PageActionKindSchema.optional(),
+  reference: z.string().optional(),
   actions: z.array(PageActionSchema),
   layout: PageLayoutSchema,
 })
@@ -1297,6 +1478,10 @@ export const PageSchema = AuditFieldsSchema.extend({
 export interface PublicPageComponent {
   slug: string
   props_schema?: Record<string, unknown>
+  /** Content address of the compiled bundle (`sha256:<hex>`), for the immutable bundle URL. */
+  bundle_checksum?: string
+  /** See {@link Component.reserved_height}. */
+  reserved_height?: number
 }
 
 /**
@@ -1318,12 +1503,16 @@ export interface ListPagesOptions extends MetaListOptions {
   module_slug?: string
   type?: PageType
   entity_slug?: string
+  /** The trigger pages of one invocable. */
+  kind?: PageActionKind
+  reference?: string
 }
 
 /**
  * Request to create a page. `type` defaults to `record` when omitted.
- * `entity_slug` is required for record pages and must be absent for platform
- * pages.
+ * `entity_slug` is required for record pages and must be absent for every
+ * other type. Trigger pages set `reference` (and `kind`, which defaults to
+ * `action`); no other type may.
  */
 export interface CreatePageRequest {
   slug: string
@@ -1331,6 +1520,8 @@ export interface CreatePageRequest {
   module_slug?: string
   type?: PageType
   entity_slug?: string
+  kind?: PageActionKind
+  reference?: string
   actions: PageAction[]
   layout: PageLayout
 }
@@ -1832,6 +2023,37 @@ export const AppHomeSchema = z.object({
   reference: z.string(),
 })
 
+/**
+ * The record pages one entity opens in, per mode (`PageMode`). Every key
+ * optional; the web falls back create → edit → view → the entity's first
+ * record page. Strict object on the wire — no string shorthand.
+ */
+export interface RecordPageBinding {
+  view?: string
+  create?: string
+  edit?: string
+}
+
+export const RecordPageBindingSchema = z
+  .object({ view: z.string().optional(), create: z.string().optional(), edit: z.string().optional() })
+  .strict()
+
+/**
+ * The trigger pages one action / workflow opens, per dialog phase
+ * (`TriggerPhase`). Every key optional; an unbound phase falls back to the
+ * invocable's first trigger page, then to the dialog's generated layout. One
+ * page may serve every phase. Strict object on the wire.
+ */
+export interface TriggerPageBinding {
+  input?: string
+  running?: string
+  result?: string
+}
+
+export const TriggerPageBindingSchema = z
+  .object({ input: z.string().optional(), running: z.string().optional(), result: z.string().optional() })
+  .strict()
+
 /**
  * AppConfiguration — a TYPED binding row: "how app X presents itself" to
  * everyone (`profile_slug: ''` = the app's default configuration) or to one
@@ -1855,8 +2077,12 @@ export interface AppConfiguration extends AuditFields {
   default_agent_key?: string
   /** Agents offered in this app; empty = every org agent. */
   agent_keys?: string[]
-  /** entity_slug → record page slug opened from this app. */
-  record_pages?: Record<string, string>
+  /** entity_slug → the record pages opened from this app, per mode. */
+  record_pages?: Record<string, RecordPageBinding>
+  /** action slug → the trigger pages its invoke dialog renders, per phase. */
+  action_pages?: Record<string, TriggerPageBinding>
+  /** workflow key → the trigger pages its invoke dialog renders, per phase. */
+  workflow_pages?: Record<string, TriggerPageBinding>
   /** Entity slugs the command palette searches (by record title) inside
    *  this app; empty = no record search. */
   searchable_entities?: string[]
@@ -1872,7 +2098,9 @@ export const AppConfigurationSchema = AuditFieldsSchema.extend({
   menu_slug: z.string().optional(),
   default_agent_key: z.string().optional(),
   agent_keys: z.array(z.string()).optional(),
-  record_pages: z.record(z.string()).optional(),
+  record_pages: z.record(RecordPageBindingSchema).optional(),
+  action_pages: z.record(TriggerPageBindingSchema).optional(),
+  workflow_pages: z.record(TriggerPageBindingSchema).optional(),
   searchable_entities: z.array(z.string()).optional(),
 })
 
@@ -1897,7 +2125,9 @@ export interface CreateAppConfigurationRequest {
   menu_slug?: string
   default_agent_key?: string
   agent_keys?: string[]
-  record_pages?: Record<string, string>
+  record_pages?: Record<string, RecordPageBinding>
+  action_pages?: Record<string, TriggerPageBinding>
+  workflow_pages?: Record<string, TriggerPageBinding>
   searchable_entities?: string[]
 }
 
@@ -1911,7 +2141,9 @@ export interface UpdateAppConfigurationRequest {
   menu_slug?: string
   default_agent_key?: string
   agent_keys?: string[]
-  record_pages?: Record<string, string>
+  record_pages?: Record<string, RecordPageBinding>
+  action_pages?: Record<string, TriggerPageBinding>
+  workflow_pages?: Record<string, TriggerPageBinding>
   searchable_entities?: string[]
 }
 

package/src/scheduling/types.ts

@@ -435,7 +435,7 @@ export interface SlotParameters {
 }
 
 /**
- * Asks for the bookable starts of some hosts in [from, to) (≤ 31 days).
+ * Asks for the bookable starts of some hosts in [from, to) (≤ 42 days).
  * Exactly one of type_key | link_key | parameters governs the rules;
  * assignment picks union (single / round_robin) or intersection (collective).
  * timezone is the requester's zone: slots are grouped by its local day.
@@ -528,6 +528,8 @@ export interface ListCalendarEventsQuery {
   record_entity_slug?: string
   record_id?: string
   contact_id?: string
+  /** The instance(s) of one provider event, by iCalendar UID. */
+  ical_uid?: string
   is_deleted_included?: boolean
 }
 
@@ -658,6 +660,8 @@ export interface UpdateSchedulingLinkRequest {
 export interface ListSchedulingLinksQuery {
   /** Links offering this type. */
   type_key?: string
+  /** Links listing this user among their hosts. */
+  host_user_id?: string
   is_public?: boolean
   is_enabled?: boolean
   search?: string

package/src/workflow/types.ts

@@ -71,8 +71,11 @@ export interface WorkflowNode {
 export const DEFAULT_PORT = 'main'
 
 /**
- * The reserved output-port key the `on_error: continue_error_output` policy
- * routes failed items to, when the node's descriptor declares it.
+ * The reserved output-port key every non-trigger node implicitly has. Under
+ * `on_error: continue_error_output` the engine emits one item per input item
+ * on it: the input's `json` plus an `error` object (`code`, `message`,
+ * `details`, `is_user_error`), paired to the input index. Descriptors never
+ * declare this port.
  */
 export const ERROR_PORT = 'error'
 
@@ -265,6 +268,11 @@ export interface NodeDescriptor {
   documentation_url?: string
   /** Liquid over parameters, shown on the canvas node card. */
   subtitle?: string
+  /**
+   * Retry policy a node of this type runs with when the graph node sets none.
+   * Non-idempotent types pin `max_attempts: 1`; absent = engine defaults.
+   */
+  default_retry?: NodeRetryPolicy
 }
 
 /** Registry lifecycle of one (type, version) row. */