@proteos/sdk 0.46.0 → 0.48.0

package/src/conversation/types.ts

@@ -26,6 +26,7 @@ export type Channel =
   | 'teams-meeting'
   | 'webex-meeting'
   | 'adhoc'
+  | 'phone'
   | 'instagram'
   | 'messenger'
   | 'x'
@@ -52,6 +53,83 @@ export type ConnectorKey =
   | 'adhoc-meeting'
   | 'google-calendar-meeting'
   | 'microsoft-calendar-meeting'
+  | 'twilio-phone'
+  | 'aircall'
+  | 'webhook-cti'
+
+/**
+ * Telephony lifecycle of one phone call, carried in the call conversation's
+ * `metadata.call_status` (a call is a conversation plus call facts — no
+ * dedicated resource). Status callbacks apply through a monotonic guard, so a
+ * terminal value never regresses.
+ */
+/**
+ * Body of POST /conversations/v1/calls/token — the softphone's browser-calling
+ * grant for one connection. The client identity is derived server-side from
+ * the authenticated user.
+ */
+export interface MintCallTokenRequest {
+  connection_id: string
+}
+
+/**
+ * Which system answers a provider phone number: connected to this platform,
+ * in use by another integration (connecting takes it over, disconnecting
+ * restores it), or configured nowhere (available).
+ */
+export type PhoneNumberStatus = 'connected' | 'available' | 'in_use'
+
+/** One dispatch target: a platform user (id) or a team (slug). */
+export interface RoutingTarget {
+  type: 'user' | 'team'
+  id: string
+}
+
+/**
+ * A connected number's user-level dispatch: who a call rings. v1 rings every
+ * expanded target in parallel (teams expand to their direct members at ring
+ * time); the object shape leaves room for later strategy options. Empty
+ * targets fall back to the connection-wide routing, then busy.
+ */
+export interface PhoneNumberRouting {
+  targets: RoutingTarget[]
+}
+
+/** One provider phone number on a phone connection. */
+export interface PhoneNumber {
+  /** Provider-side number identity (vendor vocabulary stays in the adapter). */
+  external_id: string
+  phone_number: string
+  friendly_name: string
+  status: PhoneNumberStatus
+  /** Display-only description of what an in_use number is used by. */
+  used_by?: string
+  routing: PhoneNumberRouting
+}
+
+/** Routing update for one phone number (connect/disconnect are actions). */
+export interface UpdatePhoneNumberRequest {
+  routing?: PhoneNumberRouting
+}
+
+/** The minted grant the Voice JS SDK consumes (`new Device(token, { edge })`). */
+export interface CallTokenResponse {
+  token: string
+  identity: string
+  /** Vendor edge to connect through ('dublin' for the EU default). */
+  edge?: string
+  expires_at: string
+}
+
+export type CallStatus =
+  | 'queued'
+  | 'ringing'
+  | 'in_progress'
+  | 'completed'
+  | 'no_answer'
+  | 'busy'
+  | 'failed'
+  | 'canceled'
 
 /**
  * Who operates the integration mechanics behind a connector: Proteos' own
@@ -486,8 +564,27 @@ export interface UpdateConnectionRequest {
   settings?: Record<string, unknown>
 }
 
+/**
+ * Optional body of POST /connections/:id/install. `input` carries
+ * user-supplied install credentials for direct-install connectors
+ * (twilio-phone, aircall, webhook-cti — connector-documented snake_case
+ * keys); omit it for OAuth/hosted connectors.
+ */
+export interface InstallConnectionRequest {
+  input?: Record<string, string>
+}
+
 export interface InstallConnectionResponse {
-  authorization_url: string
+  /** OAuth/hosted installs: open this in a popup. Absent on direct installs. */
+  authorization_url?: string
+  /** Direct installs complete server-side in this request. */
+  is_completed?: boolean
+  /**
+   * A direct-install connector's one-time setup handout (callback URLs to
+   * paste provider-side; a minted token shown exactly once — only its hash is
+   * stored server-side). Never retrievable again.
+   */
+  setup?: Record<string, string>
 }
 
 export interface SendMessageRequest {
@@ -852,6 +949,11 @@ export interface ListConnectionsQuery extends PaginationQuery {
   connector_key?: string
   channel?: string
   scope?: string
+  /**
+   * Narrows to the user-scoped connections one person owns. Org-scoped
+   * connections have no owner and never match.
+   */
+  owner_id?: string
   status?: string
 }
 

package/src/data/types.ts

@@ -18,6 +18,15 @@ export type RecordData = Record<string, any>
  * (via bracket syntax) include `[eq]`, `[ne]`, `[gt]`, `[gte]`, `[lt]`,
  * `[lte]`, `[in]` (pipe-separated), `[not_in]`, `[contains]`, `[starts_with]`,
  * `[ends_with]`, `[empty]`, `[not_empty]`. Missing operator defaults to `[eq]`.
+ * A filter key may reach one hop through a relation attribute with a dotted
+ * path (`"company_id.name[contains]": "acme"`).
+ *
+ * For nested AND/OR trees, pass a filter group (the same wire dialect as
+ * `List.filters` / `visible_when`: `{logical_operator, elements: [{field,
+ * operator, value}], groups}`, string values, pipe-joined for in/not_in)
+ * JSON-encoded under the reserved `_filter` key:
+ * `{ _filter: JSON.stringify(group) }`. The server ANDs it with any flat
+ * filter params.
  */
 export interface ListRecordsOptions {
   /** Page number (0-indexed). First page is 0. */

package/src/functions/actions.ts

@@ -61,6 +61,19 @@ export interface ActionService {
     slug: string,
     params: Record<string, unknown>,
   ): Promise<unknown>
+
+  /**
+   * Invokes an `entity_batch` action against a SET of records. The whole id
+   * array reaches the action in ONE invocation, so the result is a single
+   * aggregate payload, not one per record. `recordIds` must be non-empty;
+   * the server dedupes it, preserving order. Returns the unwrapped `result`.
+   */
+  invokeBatch(
+    entitySlug: string,
+    slug: string,
+    recordIds: string[],
+    params: Record<string, unknown>,
+  ): Promise<unknown>
 }
 
 /**
@@ -117,4 +130,20 @@ export class ActionServiceImpl implements ActionService {
     )
     return response.result
   }
+
+  async invokeBatch(
+    entitySlug: string,
+    slug: string,
+    recordIds: string[],
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    // The one invoke route whose body is an envelope rather than the params
+    // object itself — an id array has nowhere to live in the path.
+    const response = await this.client.request<InvokeActionResponse>(
+      'POST',
+      `/functions/v1/entities/${entitySlug}/actions/${slug}/invoke`,
+      { record_ids: recordIds, params },
+    )
+    return response.result
+  }
 }

package/src/functions/types.ts

@@ -5,11 +5,13 @@ import { type AuditFields, AuditFieldsSchema } from '../types/common.js'
 
 /**
  * Scope of an action. `entity`-scoped actions are invoked against a
- * specific record; `global` actions take no record context.
+ * specific record; `entity_batch` actions against a SET of records of one
+ * entity (one invocation carrying every id, never one per record — they back
+ * a list's toolbar buttons); `global` actions take no record context.
  */
-export type ActionScope = 'entity' | 'global'
+export type ActionScope = 'entity' | 'entity_batch' | 'global'
 
-export const ActionScopeSchema = z.enum(['entity', 'global'])
+export const ActionScopeSchema = z.enum(['entity', 'entity_batch', 'global'])
 
 /**
  * Deployable, user-invokable operation. Mirrors `functionsmodel.Action`
@@ -21,7 +23,7 @@ export interface Action extends AuditFields {
   org_id: string
   module_slug: string
   scope: ActionScope
-  /** Present only when `scope === 'entity'`. */
+  /** Present only when `scope` is `entity` or `entity_batch`. */
   entity?: string
   name: string
   is_active: boolean

package/src/index.ts

@@ -227,6 +227,8 @@ export type {
   AutomatedFilterConfig,
   AutomatedSignal,
   BlockContactRequest,
+  CallStatus,
+  CallTokenResponse,
   Channel,
   Connection,
   ConnectionCredentials,
@@ -310,7 +312,12 @@ export type {
   MessageRecipient,
   MessageService,
   MessageStatus,
+  MintCallTokenRequest,
   MistranscribedTerm,
+  PhoneNumber,
+  PhoneNumberRouting,
+  PhoneNumberStatus,
+  RoutingTarget,
   MistranscribedTermService,
   MistranscribedTermStatus,
   MistranscriptionSuggestionSource,
@@ -349,6 +356,7 @@ export type {
   UpdateConversationTypeRequest,
   UpdateDraftRequest,
   UpdateGlossaryTermRequest,
+  UpdatePhoneNumberRequest,
   VoiceService,
   VoiceTranscriptionStream,
 } from './conversation/index.js'

package/src/meta/layout/control-registry.json

@@ -25,7 +25,8 @@
     "currency",
     "knowledge-text",
     "file",
-    "file-viewer"
+    "file-viewer",
+    "record-filter"
   ],
   "controls": {
     "string": {
@@ -33,7 +34,8 @@
       "compatible": [
         "text",
         "textarea",
-        "password"
+        "password",
+        "record-filter"
       ],
       "byFormat": {
         "email": {

package/src/meta/layout/elements.ts

@@ -20,6 +20,9 @@ export const LayoutElementType = {
   Component: 'component',
   Divider: 'divider',
   Text: 'text',
+  RecordFilter: 'record_filter',
+  List: 'list',
+  WorkflowTrigger: 'workflow_trigger',
 } as const
 export type LayoutElementType = (typeof LayoutElementType)[keyof typeof LayoutElementType]
 
@@ -66,11 +69,19 @@ export type CardElement = CommonProps & {
   content: LayoutElement
 }
 
+/**
+ * One switchable view inside a `tabs` element. `visible_when` hides the tab
+ * when it does not match the record; `default_when` makes it the initially
+ * shown tab when it matches. Both are evaluated live against the record being
+ * viewed or edited. Resolution order: first visible tab (document order) whose
+ * `default_when` matches → `TabsElement.default_tab_id` → first visible tab.
+ */
 export type LayoutTab = {
   id: string
   label: string
   icon?: string
   visible_when?: FilterGroup
+  default_when?: FilterGroup
   content: LayoutElement
 }
 
@@ -151,10 +162,99 @@ export type ComponentElement = CommonProps & {
   reserved_height?: number
 }
 
+/**
+ * A filter builder placed directly on a page. It owns no data of its own: it
+ * publishes the filter (and the chosen subject entity) under its element id,
+ * and every `list` element naming that id in `filter_element_id` renders the
+ * filtered rows.
+ *
+ * `subject_entity` pins which entity the filter is authored against. When it is
+ * absent the element renders a subject picker over the entities its bound lists
+ * offer — one entry per bound list, since a list carries exactly one entity.
+ *
+ * The filter is in-memory: it resets on reload rather than persisting per user.
+ */
+export type RecordFilterElement = CommonProps & {
+  type: 'record_filter'
+  subject_entity?: string
+  /** `toolbar` (default) is the Filter button + active chips, matching every
+   *  list view. `panel` is the always-open AND/OR editor, for a page whose
+   *  point IS the filter. */
+  variant?: 'toolbar' | 'panel'
+  /** Nested AND/OR groups. Defaults to true — the records query carries the
+   *  whole tree, so there is no reason to hide the affordance. */
+  is_complex_enabled?: boolean
+}
+
+/**
+ * Renders records of a configured List — the record-agnostic sibling of
+ * `related_list`, and the only way to show records on a page that has no
+ * record of its own.
+ *
+ * The List supplies everything about presentation and behaviour: columns,
+ * sorting, base filters, toolbar actions, selection mode, and which page a row
+ * opens. Naming more than one list makes the element switchable; the active one
+ * is chosen by the bound filter's subject picker, or by the element's own
+ * switcher when it is unbound.
+ *
+ * `filter_element_id` binds the element to a `record_filter` on the same page.
+ * The bound filter is ANDed with the list's own saved filters — it narrows the
+ * list, it never replaces what the list declared.
+ */
+export type ListElement = CommonProps & {
+  type: 'list'
+  /** Slugs of the lists this element can render. At least one. */
+  list_slugs: string[]
+  /** Element id of the `record_filter` driving this list. Unbound renders the
+   *  list with its own filters only. */
+  filter_element_id?: string
+  /**
+   * Record-page alternative to `filter_element_id`: the attribute on THIS
+   * page's record holding a saved filter (as written by the `record-filter`
+   * control). The list then renders what the record's own filter selects —
+   * a saved-segment record showing its matches.
+   *
+   * Mutually exclusive with `filter_element_id`: two filters driving one list
+   * has no defined precedence, so the layout validator rejects both at once.
+   * Record pages only — a standalone page has no record to read.
+   */
+  filter_attribute?: string
+  /**
+   * Attribute on this page's record naming the subject entity slug. The
+   * element renders whichever of `list_slugs` targets that entity. Without
+   * it the first configured list wins. Pairs with `filter_attribute`.
+   */
+  subject_entity_attribute?: string
+  page_size?: number
+}
+
 export type DividerElement = CommonProps & {
   type: 'divider'
 }
 
+/**
+ * An always-visible button that starts a manual run of `workflow` (by key) —
+ * the in-layout counterpart of a `kind: workflow` toolbar action. `inputs`
+ * maps the manual trigger's input_schema field names to Liquid templates
+ * rendered against the page scope; `skip_confirmation` fires immediately when
+ * every required input resolves. While the run is in flight the element shows
+ * the step progress inline in place of the button.
+ */
+export type WorkflowTriggerElement = CommonProps & {
+  type: 'workflow_trigger'
+  workflow: string
+  label: string
+  icon?: string
+  inputs?: Record<string, string>
+  skip_confirmation?: boolean
+  /**
+   * Optional string attribute on the page's record where the element persists
+   * the id of the execution it starts — and reads it back, so progress
+   * survives reloads and is shared by every viewer. Record pages only.
+   */
+  execution_attribute?: string
+}
+
 export type TextVariant = 'heading' | 'subheading' | 'body' | 'caption' | 'callout'
 
 export type TextElement = CommonProps & {
@@ -175,6 +275,9 @@ export type LayoutElement =
   | ComponentElement
   | DividerElement
   | TextElement
+  | RecordFilterElement
+  | ListElement
+  | WorkflowTriggerElement
 
 // ──────────────────────────────────────────────────────────── Schemas ──
 
@@ -224,6 +327,7 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
           label: z.string().min(1),
           icon: z.string().optional(),
           visible_when: FilterGroupSchema.optional(),
+          default_when: FilterGroupSchema.optional(),
           content: LayoutElementSchema,
         }),
       ),
@@ -265,10 +369,36 @@ export const LayoutElementSchema: z.ZodType<LayoutElement> = z.lazy(() =>
       props: z.record(z.unknown()).optional(),
       reserved_height: z.number().positive().optional(),
     }),
+    z.object({
+      type: z.literal('record_filter'),
+      ...commonPropsShape,
+      subject_entity: z.string().min(1).optional(),
+      variant: z.enum(['toolbar', 'panel']).optional(),
+      is_complex_enabled: z.boolean().optional(),
+    }),
+    z.object({
+      type: z.literal('list'),
+      ...commonPropsShape,
+      list_slugs: z.array(z.string().min(1)).min(1),
+      filter_element_id: z.string().min(1).optional(),
+      filter_attribute: z.string().min(1).optional(),
+      subject_entity_attribute: z.string().min(1).optional(),
+      page_size: z.number().int().positive().optional(),
+    }),
     z.object({
       type: z.literal('divider'),
       ...commonPropsShape,
     }),
+    z.object({
+      type: z.literal('workflow_trigger'),
+      ...commonPropsShape,
+      workflow: z.string().min(1),
+      label: z.string().min(1),
+      icon: z.string().optional(),
+      inputs: z.record(z.string()).optional(),
+      skip_confirmation: z.boolean().optional(),
+      execution_attribute: z.string().min(1).optional(),
+    }),
     z.object({
       type: z.literal('text'),
       ...commonPropsShape,

package/src/meta/layout/index.ts

@@ -26,6 +26,9 @@ export {
   LayoutElementSchema,
   LayoutElementType,
   type LayoutTab,
+  type ListElement,
+  type RecordFilterElement,
+  type WorkflowTriggerElement,
   type RelatedListElement,
   type RelatedRecordElement,
   type RowElement,

package/src/meta/types.ts

@@ -864,6 +864,19 @@ export interface UpdateComponentRequest {
 
 /**
  * List column definition.
+ *
+ * `attribute` is an attribute name or a dot path, told apart by the type of
+ * the first segment:
+ *
+ *   - `name` — an attribute on the list's own entity.
+ *   - `address.city` — a leaf inside one of its `object` attributes.
+ *   - `company_id.name` — a field of the RELATED record, reached through a
+ *     relation attribute (the first segment is the FK).
+ *
+ * A bare `object` attribute is not a valid column — it carries no value of
+ * its own, only leaves. Sorting follows the same grammar minus the relation
+ * hop: an attribute or an object path can be ordered by, a related field
+ * cannot (it would need a join).
  */
 export interface Column {
   attribute: string
@@ -877,7 +890,9 @@ export interface Column {
 export type SortDirection = 'asc' | 'desc'
 
 /**
- * Sort configuration.
+ * Sort configuration. `attribute` is an attribute name or an object path
+ * (`address.city`); relation paths are not sortable — ordering by a related
+ * field would need a join the records query doesn't do.
  */
 export interface SortConfig {
   attribute: string
@@ -904,6 +919,60 @@ export {
   type LogicalOperator,
 }
 
+// ============================================================================
+// Toolbar action buttons (shared by pages and lists)
+// ============================================================================
+
+/**
+ * What a page toolbar button invokes. Absent normalizes to `action` (pages
+ * persisted before `kind` existed).
+ */
+export type PageActionKind = 'action' | 'workflow'
+
+/**
+ * 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.
+ */
+export interface PageAction {
+  label: string
+  icon: string
+  kind?: PageActionKind
+  action?: string
+  workflow?: string
+  params?: Record<string, string>
+  inputs?: Record<string, string>
+  skip_confirmation?: boolean
+}
+
+export const PageActionSchema = z.object({
+  label: z.string(),
+  icon: z.string(),
+  kind: z.enum(['action', 'workflow']).optional(),
+  action: z.string().optional(),
+  workflow: z.string().optional(),
+  params: z.record(z.string()).optional(),
+  inputs: z.record(z.string()).optional(),
+  skip_confirmation: z.boolean().optional(),
+})
+
+/**
+ * Whether a list's rows can be checked, and whether the checkboxes show from
+ * the start:
+ *
+ * - `on_demand` (default) — a Select toggle in the toolbar reveals them.
+ * - `always` — checkboxes are showing from the start.
+ * - `off` — rows can never be checked, even when the list carries actions.
+ */
+export type SelectionMode = 'on_demand' | 'always' | 'off'
+
+export const SelectionModeSchema = z.enum(['on_demand', 'always', 'off'])
+
 /**
  * List configuration.
  * Note: List uses `slug` as its primary identifier, not `id`.
@@ -915,6 +984,15 @@ export interface List extends AuditFields {
   name: string
   entity_slug: string
   columns: Column[]
+  /**
+   * Toolbar buttons on the list, same shape a page carries. They act on the
+   * rows SELECTED in the list, so an `action` button names an `entity_batch`
+   * action (invoked once with every selected record id) and prefill templates
+   * resolve against the list scope `{ selection, entity, user }`.
+   */
+  actions?: PageAction[]
+  /** Row-selection affordance; absent normalizes to `on_demand`. */
+  selection_mode?: SelectionMode
   /** Record page to open from this list; empty/absent = org default for the entity. */
   default_page_slug?: string
   sorting: SortConfig[]
@@ -938,6 +1016,8 @@ export const ListSchema = AuditFieldsSchema.extend({
   name: z.string(),
   entity_slug: z.string(),
   columns: z.array(ColumnSchema),
+  actions: z.array(PageActionSchema).optional(),
+  selection_mode: SelectionModeSchema.optional(),
   default_page_slug: z.string().optional(),
   sorting: z.array(SortConfigSchema),
   filters: z.array(FilterGroupSchema),
@@ -962,6 +1042,8 @@ export interface CreateListRequest {
   entity_slug: string
   name: string
   columns: Column[]
+  actions?: PageAction[]
+  selection_mode?: SelectionMode
   default_page_slug?: string
   sorting: SortConfig[]
   filters: FilterGroup[]
@@ -974,6 +1056,8 @@ export interface UpdateListRequest {
   name?: string
   module_slug?: string
   columns?: Column[]
+  actions?: PageAction[]
+  selection_mode?: SelectionMode
   /** Set to '' to clear back to the org default. */
   default_page_slug?: string
   sorting?: SortConfig[]
@@ -1047,44 +1131,6 @@ export interface UpdateListViewRequest {
 // Page Types
 // ============================================================================
 
-/**
- * What a page toolbar button invokes. Absent normalizes to `action` (pages
- * persisted before `kind` existed).
- */
-export type PageActionKind = 'action' | 'workflow'
-
-/**
- * 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.
- */
-export interface PageAction {
-  label: string
-  icon: string
-  kind?: PageActionKind
-  action?: string
-  workflow?: string
-  params?: Record<string, string>
-  inputs?: Record<string, string>
-  skip_confirmation?: boolean
-}
-
-export const PageActionSchema = z.object({
-  label: z.string(),
-  icon: z.string(),
-  kind: z.enum(['action', 'workflow']).optional(),
-  action: z.string().optional(),
-  workflow: z.string().optional(),
-  params: z.record(z.string()).optional(),
-  inputs: z.record(z.string()).optional(),
-  skip_confirmation: z.boolean().optional(),
-})
-
 /**
  * Page type — encodes what the page binds to and how it is served (chrome +
  * auth posture both follow from it):