@proteos/sdk 0.32.1 → 0.34.0

package/src/connector/types.ts

@@ -7,7 +7,7 @@ export type ConnectionStatus = 'pending' | 'active' | 'error' | 'revoked'
 export type ConnectionScope = 'org' | 'user'
 
 /** How a connector authenticates. */
-export type CredentialKind = 'oauth' | 'api_key' | 'basic' | 'bot_token'
+export type CredentialKind = 'oauth' | 'api_key' | 'basic' | 'bot_token' | 'service_account'
 
 export interface UserRef {
   type: string
@@ -45,6 +45,17 @@ export interface ConnectorOAuthConfig {
   client_secret_variable_key: string
 }
 
+/**
+ * The service-account wiring of a connector supporting the service_account
+ * kind. Like the OAuth app credentials, the SA key is an org VARIABLE —
+ * key_variable_key names the default; a connection may reference its own via
+ * settings.service_account_key_variable.
+ */
+export interface ConnectorServiceAccountConfig {
+  key_variable_key: string
+  scopes: string[]
+}
+
 /** A connector TYPE (google-calendar, a customer's vertex-tax, …). */
 export interface Connector {
   key: string
@@ -53,12 +64,21 @@ export interface Connector {
   description?: string
   icon?: string
   credential_kind: CredentialKind
+  /** Every kind a connection may use; absent/empty = exactly [credential_kind]. */
+  supported_credential_kinds?: CredentialKind[]
   oauth?: ConnectorOAuthConfig
+  service_account?: ConnectorServiceAccountConfig
   /**
    * COMPUTED: the broker's per-environment OAuth callback — register it as an
    * authorized redirect URI on the provider app.
    */
   oauth_redirect_uri?: string
+  /**
+   * COMPUTED: the environment ships platform-default OAuth app credentials
+   * for this connector, so the connect wizard can skip collecting them.
+   * Org variables always override the default.
+   */
+  has_default_app_credentials?: boolean
   config_schema?: Attribute[]
   methods: ConnectorMethod[]
   origin: 'pre_built' | 'custom'
@@ -79,6 +99,8 @@ export interface ConnectorConnection {
   scope: ConnectionScope
   owner?: UserRef
   external_account_id: string
+  /** Redacted {kind, data} credential envelope — secrets are masked; use kind to tell how the connection authenticates. */
+  credentials?: { kind: CredentialKind; data?: Record<string, unknown> }
   settings: Record<string, unknown>
   status: ConnectionStatus
   status_detail?: string

package/src/conversation/index.ts

@@ -40,6 +40,7 @@ import type {
   RecordPermissionEventRequest,
   Room,
   SendMessageRequest,
+  SyncConnectionRequest,
   Transcription,
   UnreadCounts,
   UpdateAgentListenerRequest,
@@ -106,10 +107,17 @@ export interface MeetingService {
   /** Make the bot leave the meeting and end the conversation (by conversation id). */
   remove(conversationId: string): Promise<Conversation>
   /**
-   * Regenerate this meeting conversation's markdown summary from its stored
-   * transcript, overwriting any existing one. Resolves with the updated
-   * conversation (its fresh `summary`). Rejects with `no_transcript` when the
-   * conversation has no completed transcript to summarize.
+   * START regenerating this meeting conversation's markdown summary from its
+   * stored transcript, overwriting any existing one when it lands. Generation
+   * runs server-side beyond this request, so the promise resolves as soon as the
+   * conversation is CLAIMED — with `summary_status: 'processing'` and the OLD
+   * `summary` still attached. Poll `conversations.get(id)` until
+   * `summary_status` is `completed` (or `failed`) to read the new one.
+   *
+   * Rejects with `no_transcript` when the conversation has no completed
+   * transcript to summarize, `summarization_unavailable` when the environment
+   * has no generator configured, and `summary_in_progress` when a generation is
+   * already running for this conversation.
    */
   summarize(conversationId: string): Promise<Conversation>
 }
@@ -145,6 +153,15 @@ export interface ConnectionService {
   delete(id: string): Promise<void>
   /** Begin the connector's install flow; open the returned URL in a popup. */
   install(id: string): Promise<InstallConnectionResponse>
+  /**
+   * Trigger a historical backfill ("sync all") on an email connection: the
+   * server fetches provider mail in the chosen range and ingests it through
+   * the normal pipeline (conversation filters, dedupe, agent listeners).
+   * Returns 202 with the connection already showing
+   * settings.sync_status='in_progress' — poll get(id) until it flips to
+   * done/failed. A running sync answers 409 (sync_already_running).
+   */
+  sync(id: string, request: SyncConnectionRequest): Promise<Connection>
   /** Search the contact addresses this connection can reach (org-deduped) for the compose picker. */
   listContactAddresses(
     connectionId: string,
@@ -194,6 +211,14 @@ class ConnectionServiceImpl implements ConnectionService {
     )
   }
 
+  sync(id: string, request: SyncConnectionRequest): Promise<Connection> {
+    return this.client.request(
+      'POST',
+      `${CONVERSATION_BASE_PATH}/connections/${encodeURIComponent(id)}/sync`,
+      request,
+    )
+  }
+
   listContactAddresses(
     connectionId: string,
     query: ListContactAddressesQuery = {},

package/src/conversation/types.ts

@@ -41,6 +41,7 @@ export type Channel =
 export type ConnectorKey =
   | 'slack'
   | 'gmail'
+  | 'outlook'
   | 'echo'
   | 'unipile-whatsapp'
   | 'unipile-linkedin'
@@ -73,6 +74,15 @@ export type ConnectionStatus = 'pending' | 'active' | 'error' | 'revoked'
  * drafting) — hidden from the default list until the first successful send.
  */
 export type ConversationStatus = 'active' | 'ended' | 'archived' | 'draft'
+/**
+ * Generation lifecycle of a conversation's `summary`. `none` is the resting
+ * default — no summary exists and none is being produced, the state of every
+ * conversation that is not a transcript-backed meeting. `processing` is claimed
+ * for the duration of one generation run (automatic at transcript attach, or a
+ * manual `meetings.summarize()`), so any client can render "Summarizing…"
+ * without having started the run itself.
+ */
+export type ConversationSummaryStatus = 'none' | 'processing' | 'completed' | 'failed'
 export type AgentListenerTriggerType = 'always' | 'mention' | 'channel' | 'keyword'
 
 export interface UserRef {
@@ -166,6 +176,20 @@ export interface ReactionCapability {
   max_per_actor: number
 }
 
+/** How far back a historical backfill ("sync all") reaches. */
+export type ConnectionSyncRange = '30d' | '90d' | '365d' | 'all'
+
+/**
+ * Lifecycle of a historical backfill, carried as settings.sync_status.
+ * Absent key = 'none' (never synced). 'in_progress' is claimed before the
+ * trigger request returns — poll get(id) until it flips to done/failed.
+ */
+export type ConnectionSyncStatus = 'none' | 'in_progress' | 'done' | 'failed'
+
+export interface SyncConnectionRequest {
+  range: ConnectionSyncRange
+}
+
 export interface Connection {
   id: string
   org_id: string
@@ -177,6 +201,11 @@ export interface Connection {
   owner?: UserRef
   external_account_id: string
   credentials: ConnectionCredentials
+  /**
+   * Connector-shaped configuration + state. A historical backfill writes the
+   * sync_* keys here: sync_status (ConnectionSyncStatus), sync_range,
+   * sync_started_at, sync_completed_at, sync_synced_count, sync_error.
+   */
   settings: Record<string, unknown>
   status: ConnectionStatus
   /** Computed on read: the connector implements the reaction capability. */
@@ -207,6 +236,16 @@ export interface Conversation {
    * conversations, editable via update(). Absent when no summary exists.
    */
   summary?: string
+  /**
+   * Generation lifecycle of `summary`. Poll `conversations.get(id)` while this
+   * reads `processing` to pick up the finished summary.
+   */
+  summary_status: ConversationSummaryStatus
+  /**
+   * When the current `processing` run was claimed; absent otherwise. Bounds the
+   * claim server-side and gives clients an elapsed time to show.
+   */
+  summary_started_at?: string
   status: ConversationStatus
   /**
    * Room directory row a room-borne thread (Slack channel conversation) lives

package/src/index.ts

@@ -198,6 +198,8 @@ export type {
   ConnectionScope,
   ConnectionService,
   ConnectionStatus,
+  ConnectionSyncRange,
+  ConnectionSyncStatus,
   ConnectorKey,
   ConnectorProvider,
   ConsentStatus,
@@ -223,6 +225,7 @@ export type {
   ConversationParticipant,
   ConversationService,
   ConversationStatus,
+  ConversationSummaryStatus,
   CreateAgentListenerRequest,
   CreateConnectionRequest,
   CreateConversationFilterRequest,
@@ -271,6 +274,7 @@ export type {
   Room,
   SendMessageRequest,
   SendRecipient,
+  SyncConnectionRequest,
   TranscribeStreamOptions,
   TranscriptResult,
   UnreadCounts,
@@ -421,6 +425,8 @@ export type {
   // App types
   App,
   AppService,
+  // Array/enum attribute metas (config_schema renderers narrow on these)
+  ArrayAttributeMeta,
   Attribute,
   AttributeType,
   Column,
@@ -450,6 +456,8 @@ export type {
   Entity,
   EntityService,
   EntityWithSchema,
+  EnumAttributeMeta,
+  EnumValue,
   // File attribute meta
   FileAttributeMeta,
   FilterElement,
@@ -589,7 +597,6 @@ export {
 } from './types/index.js'
 export type {
   AgentActionParams,
-  AgentKickoff,
   BinaryRef,
   ConnectionEndpoint,
   CreateWorkflowRequest,
@@ -613,8 +620,8 @@ export type {
   ListExecutionsOptions,
   ListWorkflowsOptions,
   ManualTriggerParams,
-  MessageKickoff,
   MessageTriggerParams,
+  ModelCallParams,
   NodeDescriptor,
   NodeExecution,
   NodeGroup,
@@ -627,13 +634,12 @@ export type {
   NodeTypeService,
   NodeTypeStatus,
   OnErrorPolicy,
-  OutcomeKickoff,
-  OutcomeRubric,
   PairedItem,
   PortSpec,
   PropertyOption,
   PropertyType,
   RunWorkflowRequest,
+  SystemSource,
   TestNodeCandidate,
   TestNodeInputSource,
   TestNodeRequest,
@@ -643,7 +649,6 @@ export type {
   WebhookTriggerParams,
   Workflow,
   WorkflowConnection,
-  WorkflowContentBlock,
   WorkflowExecution,
   WorkflowGraph,
   WorkflowNode,

package/src/meta/layout/elements.ts

@@ -15,6 +15,7 @@ export const LayoutElementType = {
   Tabs: 'tabs',
   Field: 'field',
   RelatedList: 'related_list',
+  RelatedRecord: 'related_record',
   Component: 'component',
   Divider: 'divider',
   Text: 'text',
@@ -96,6 +97,31 @@ export type RelatedListElement = CommonProps & {
   follows_parent_edit_mode?: boolean
 }
 
+/**
+ * Renders the FIRST record of `related_entity_slug` that references the
+ * current record through the `via_attribute` relation attribute — the
+ * singular counterpart of `related_list`, addressing the relation the same
+ * inbound way. The match is taken oldest-first so the choice is stable.
+ *
+ * `page_slug` optionally pins which record page supplies the layout; when
+ * omitted (or dangling) the renderer falls back to the related entity's
+ * default record page. The element renders that page bare — wrap it in a
+ * `section` element for a title or collapse affordance.
+ */
+export type RelatedRecordElement = CommonProps & {
+  type: 'related_record'
+  related_entity_slug: string
+  via_attribute: string
+  page_slug?: string
+  /**
+   * When absent or true, the element enters edit mode together with the host
+   * page's edit mode. False keeps it independent — editable only through its
+   * own hover control. Either way the element saves the related record
+   * itself; the host page's Save never covers it.
+   */
+  follows_parent_edit_mode?: boolean
+}
+
 export type ComponentElement = CommonProps & {
   type: 'component'
   component_slug: string
@@ -127,6 +153,7 @@ export type LayoutElement =
   | TabsElement
   | FieldElement
   | RelatedListElement
+  | RelatedRecordElement
   | ComponentElement
   | DividerElement
   | TextElement
@@ -196,6 +223,14 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
       list_slug: z.string().min(1).optional(),
       follows_parent_edit_mode: z.boolean().optional(),
     }),
+    z.object({
+      type: z.literal('related_record'),
+      ...commonPropsShape,
+      related_entity_slug: z.string().min(1),
+      via_attribute: z.string().min(1),
+      page_slug: z.string().min(1).optional(),
+      follows_parent_edit_mode: z.boolean().optional(),
+    }),
     z.object({
       type: z.literal('component'),
       ...commonPropsShape,

package/src/meta/layout/index.ts

@@ -26,6 +26,7 @@ export {
   LayoutElementType,
   type LayoutTab,
   type RelatedListElement,
+  type RelatedRecordElement,
   type RowElement,
   type SectionElement,
   type TabsElement,

package/src/meta/types.ts

@@ -782,6 +782,8 @@ export interface List extends AuditFields {
   name: string
   entity_slug: string
   columns: Column[]
+  /** Record page to open from this list; empty/absent = org default for the entity. */
+  default_page_slug?: string
   sorting: SortConfig[]
   filters: FilterGroup[]
 }
@@ -803,6 +805,7 @@ export const ListSchema = AuditFieldsSchema.extend({
   name: z.string(),
   entity_slug: z.string(),
   columns: z.array(ColumnSchema),
+  default_page_slug: z.string().optional(),
   sorting: z.array(SortConfigSchema),
   filters: z.array(FilterGroupSchema),
 })
@@ -826,6 +829,7 @@ export interface CreateListRequest {
   entity_slug: string
   name: string
   columns: Column[]
+  default_page_slug?: string
   sorting: SortConfig[]
   filters: FilterGroup[]
 }
@@ -837,6 +841,8 @@ export interface UpdateListRequest {
   name?: string
   module_slug?: string
   columns?: Column[]
+  /** Set to '' to clear back to the org default. */
+  default_page_slug?: string
   sorting?: SortConfig[]
   filters?: FilterGroup[]
 }

package/src/workflow/index.ts

@@ -42,7 +42,6 @@ export type { ExecutionService } from './executions.js'
 export type { NodeTypeService } from './node-types.js'
 export type {
   AgentActionParams,
-  AgentKickoff,
   BinaryRef,
   ConnectionEndpoint,
   CreateWorkflowRequest,
@@ -66,8 +65,8 @@ export type {
   ListExecutionsOptions,
   ListWorkflowsOptions,
   ManualTriggerParams,
-  MessageKickoff,
   MessageTriggerParams,
+  ModelCallParams,
   NodeDescriptor,
   NodeExecution,
   NodeGroup,
@@ -79,13 +78,12 @@ export type {
   NodeTypeKey,
   NodeTypeStatus,
   OnErrorPolicy,
-  OutcomeKickoff,
-  OutcomeRubric,
   PairedItem,
   PortSpec,
   PropertyOption,
   PropertyType,
   RunWorkflowRequest,
+  SystemSource,
   TestNodeCandidate,
   TestNodeInputSource,
   TestNodeRequest,
@@ -95,7 +93,6 @@ export type {
   WebhookTriggerParams,
   Workflow,
   WorkflowConnection,
-  WorkflowContentBlock,
   WorkflowExecution,
   WorkflowGraph,
   WorkflowNode,

package/src/workflow/types.ts

@@ -13,6 +13,7 @@
  * workflow; per-node results live in append-only NodeExecution rows.
  */
 
+import type { Attribute } from '../meta/types.js'
 import type { AuditFields, ListOptions, UserRef } from '../types/common.js'
 
 // ---------------------------------------------------------------------------
@@ -163,6 +164,8 @@ export type PropertyType =
   | 'fixed_collection'
   | 'credentials_select'
   | 'button'
+  /** Edits a platform attribute list (`Attribute[]`) via the shared attribute schema builder. */
+  | 'attribute_schema'
   // Wave 2 (editor support lands with Phase 3):
   | 'resource_locator'
   | 'resource_mapper'
@@ -355,54 +358,86 @@ export interface MessageTriggerParams {
   event_types?: string[]
 }
 
-export type KickoffType = 'message' | 'outcome'
+/** Matches every event type on the subscribed topic. */
+export const PLATFORM_EVENT_WILDCARD = '*'
 
 /**
- * Where a kickoff draws its instruction text from: typed inline (`manual`) or
- * resolved from a reusable agent-service Prompt by key (`prompt`) at run time.
+ * Fires the workflow when an event whose type is in `event_types` arrives on
+ * the named platform bus topic. Unlike {@link EventTriggerParams} (records
+ * only), any per-org topic in the event catalog is a valid target.
+ *
+ * `event_types` may hold the single wildcard `'*'` to match every type — custom
+ * topics have no catalogued type list, so there is nothing to enumerate.
  */
-export type KickoffSource = 'manual' | 'prompt'
-
-export interface WorkflowContentBlock {
-  type: 'text' | 'file'
-  text?: string
-  file_id?: string
+export interface PlatformEventTriggerParams {
+  topic: string
+  event_types: string[]
 }
 
-export interface MessageKickoff {
-  source?: KickoffSource
-  /** Inline content blocks (manual source). */
-  content?: WorkflowContentBlock[]
-  /** Prompt key whose body becomes the message text (prompt source). */
-  prompt_key?: string
-}
+export type KickoffType = 'message' | 'outcome'
 
-export interface OutcomeRubric {
-  type: 'text' | 'file'
-  content?: string
-  file_id?: string
-}
+/**
+ * Where a kickoff slot draws its instruction text from: typed inline
+ * (`manual`) or resolved from a reusable agent-service Prompt by key
+ * (`prompt`) at run time.
+ */
+export type KickoffSource = 'manual' | 'prompt'
 
-export interface OutcomeKickoff {
-  /** Description and rubric are independently sourced (manual vs prompt). */
+/**
+ * Flat, descriptor-driven parameters of the `action.agent` node (gated by
+ * display_options on `kickoff_type` / `*_source`). `output_schema` declares
+ * the node's structured output as platform attributes — the agent records it
+ * via the session-scoped `set_output` tool; `is_output_required` fails the
+ * node when the agent finishes without setting it.
+ */
+export interface AgentActionParams {
+  agent_key: string
+  kickoff_type: KickoffType
+  message_source?: KickoffSource
+  message_text?: string
+  message_prompt_key?: string
   description_source?: KickoffSource
   description?: string
   description_prompt_key?: string
   rubric_source?: KickoffSource
-  rubric?: OutcomeRubric
+  rubric_type?: 'text' | 'file'
+  rubric_content?: string
+  rubric_file_id?: string
   rubric_prompt_key?: string
   max_iterations?: number
+  output_schema?: Attribute[]
+  is_output_required?: boolean
 }
 
-export interface AgentKickoff {
-  type: KickoffType
-  message?: MessageKickoff
-  outcome?: OutcomeKickoff
-}
+/**
+ * Where a model call's optional system instruction comes from. Empty/absent
+ * defaults to `none`.
+ */
+export type SystemSource = 'none' | 'manual' | 'prompt'
 
-export interface AgentActionParams {
-  agent_key: string
-  kickoff: AgentKickoff
+/**
+ * Flat, descriptor-driven parameters of the `proteos-nodes-core.model-call`
+ * node: one stateless LLM call per input item. The prompt and the optional
+ * system instruction are independently sourced — typed inline (`manual`,
+ * Liquid-resolved per item) or resolved verbatim from a reusable Prompt by key
+ * (`prompt`). With `has_structured_output`, `output_schema` declares the
+ * reply's shape as platform attributes: generation is schema-constrained
+ * (forced tool) AND the node validates the returned JSON, failing the item
+ * after one automatic repair attempt.
+ */
+export interface ModelCallParams {
+  /** Empty resolves to the platform default model. */
+  model_id?: string
+  temperature?: number
+  max_tokens?: number
+  prompt_source?: KickoffSource
+  prompt_text?: string
+  prompt_key?: string
+  system_source?: SystemSource
+  system_text?: string
+  system_prompt_key?: string
+  has_structured_output?: boolean
+  output_schema?: Attribute[]
 }
 
 // ---------------------------------------------------------------------------
@@ -544,7 +579,15 @@ export type ExecutionStatus =
   | 'cancelled'
   | 'skipped'
 
-export type TriggerKind = 'schedule' | 'manual' | 'webhook' | 'event' | 'message' | 'workflow'
+export type TriggerKind =
+  | 'schedule'
+  | 'manual'
+  | 'webhook'
+  | 'event'
+  | 'message'
+  | 'connector'
+  | 'platform_event'
+  | 'workflow'
 
 /**
  * Why and how an execution fired. Flat, kind-discriminated: `kind` selects