@proteos/sdk 0.45.0 → 0.47.0

package/src/meta/types.ts

@@ -38,10 +38,52 @@ export type AttributeType =
   | 'enum'
   | 'relation'
   | 'user'
+  | 'principal'
   | 'currency'
   | 'knowledge-text'
   | 'file'
 
+/**
+ * Attribute-level permissions: restricting a FIELD rather than a record — a
+ * salary column readable only by the people team, a margin column writable only
+ * by finance. Mirror of the Go `metamodel.AttributeRestrictions`.
+ *
+ * Orthogonal to instance-level access: a caller who may see a record may still
+ * be blocked from one of its fields.
+ *
+ * Absent means unrestricted. Both arms FAIL CLOSED — an empty rule matches
+ * nobody rather than everybody, and an unknown role or team slug never matches,
+ * so a typo removes access rather than granting it.
+ */
+export interface AttributeAccessRule {
+  /** Role slugs, matched against the caller's roles. */
+  roles?: string[]
+  /**
+   * Team slugs. Matched through the caller's team closure, so a member of a
+   * CHILD team is matched by a rule naming an ancestor.
+   */
+  teams?: string[]
+}
+
+export const AttributeAccessRuleSchema = z.object({
+  roles: z.array(z.string()).optional(),
+  teams: z.array(z.string()).optional(),
+})
+
+/**
+ * Read and write are gated independently, so `write` alone yields a field
+ * everyone can see and only some can change.
+ */
+export interface AttributeRestrictions {
+  read?: AttributeAccessRule
+  write?: AttributeAccessRule
+}
+
+export const AttributeRestrictionsSchema = z.object({
+  read: AttributeAccessRuleSchema.optional(),
+  write: AttributeAccessRuleSchema.optional(),
+})
+
 // ── Attribute meta (sub-discriminators) ──────────────────────────────
 // Mirrors the Go `*AttributeMeta` types in
 // packages/go/model/attribute-{string,number,datetime,array,object,enum}.go.
@@ -88,6 +130,10 @@ export interface EnumValue {
   value: string
   label?: string
   description?: string
+  /** Lucide icon name, canonical PascalCase (e.g. `CircleCheck`). Replaces the badge dot. */
+  icon?: string
+  /** Tint as `#rrggbb`. Renderers derive dot/border/background from it; text stays ink. */
+  color?: string
 }
 
 export interface EnumAttributeMeta {
@@ -144,6 +190,68 @@ export const UserAttributeMetaSchema = z.object({
   description: z.string().optional(),
 })
 
+/**
+ * The stored value of a `principal`-typed attribute: a {@link PrincipalRef}
+ * `{ type, id }` naming anything that can HOLD ACCESS — a user (person, agent
+ * or api client), a team, or the whole organization. Mirror of the Go
+ * `metamodel.PrincipalAttributeMeta`.
+ *
+ * Distinct from `user` on purpose. `user` means "a person did this" — it is
+ * authorship, and its value can never be a team. `principal` means "this party
+ * may be granted access", a different question with a strictly larger
+ * vocabulary. Widening `user` would have made every existing user attribute
+ * silently accept a team, including the created_by / updated_by audit columns.
+ */
+export interface PrincipalAttributeMeta {
+  description?: string
+  /**
+   * Turns the attribute into a GRANTING attribute: the verbs its value confers
+   * on the record. `deals.account_manager` with `["read","write"]` means setting
+   * it gives that principal access with no share call — the business field IS
+   * the ACL.
+   *
+   * `share` is the right to hand access on — share the record, set other
+   * granting attributes, revoke shares. `["read","write","delete","share"]` is
+   * full ownership: there is no separate owner field on the platform, the
+   * business field that grants `share` IS the owner. `share` must accompany
+   * at least one of read/write/delete, and an attribute granting it never
+   * accepts an `org` principal.
+   *
+   * Empty (the default) means an ordinary reference that confers nothing, so an
+   * existing principal attribute cannot start granting access by accident.
+   */
+  grants?: Array<'read' | 'write' | 'delete' | 'share'>
+  /**
+   * Narrows which principal kinds this attribute accepts; empty means all
+   * (except that an attribute granting `share` refuses `org` regardless —
+   * an org-wide right to re-grant would hand record management to every
+   * member).
+   */
+  allowed_types?: PrincipalType[]
+}
+
+export const PrincipalAttributeMetaSchema = z.object({
+  description: z.string().optional(),
+  grants: z.array(z.enum(['read', 'write', 'delete', 'share'])).optional(),
+  allowed_types: z.array(z.enum(['person', 'agent', 'api', 'team', 'org'])).optional(),
+})
+
+/** The kinds a principal reference may name. */
+export type PrincipalType = 'person' | 'agent' | 'api' | 'team' | 'org'
+
+/**
+ * The stored value of a `principal`-typed attribute.
+ */
+export interface PrincipalRef {
+  type: PrincipalType
+  id: string
+}
+
+export const PrincipalRefSchema = z.object({
+  type: z.enum(['person', 'agent', 'api', 'team', 'org']),
+  id: z.string(),
+})
+
 /**
  * The stored value of a `currency`-typed attribute: an exact decimal `amount`
  * (a STRING, never a JS number — preserves financial-system precision and
@@ -236,6 +344,7 @@ export type AttributeMeta =
   | EnumAttributeMeta
   | RelationAttributeMeta
   | UserAttributeMeta
+  | PrincipalAttributeMeta
   | CurrencyAttributeMeta
   | KnowledgeTextAttributeMeta
   | FileAttributeMeta
@@ -259,6 +368,17 @@ export interface Attribute {
    * Mirrors `IsPlatformManaged` in the Go `metamodel.Attribute`.
    */
   is_platform_managed?: boolean
+  /**
+   * Attribute-level permissions. Absent means unrestricted (today's behaviour).
+   * Platform-managed attributes cannot carry restrictions.
+   */
+  restrictions?: AttributeRestrictions
+  /**
+   * Literal default, or — on a `user` / `principal` attribute only — the
+   * current-user sentinel `{ type: 'current_user' }` (see
+   * `CURRENT_USER_DEFAULT`), which data-service resolves to the writer at
+   * record-write time.
+   */
   default_value?: unknown
   /**
    * Type-specific metadata. The concrete shape is determined by `type`
@@ -365,6 +485,7 @@ export const AttributeSchema = z.object({
   is_nullable: z.boolean().optional(),
   is_unique: z.boolean(),
   is_read_only: z.boolean().optional(),
+  restrictions: AttributeRestrictionsSchema.optional(),
   default_value: z.unknown().optional(),
   meta: z.unknown().optional(),
   options: z.record(z.unknown()).optional(),
@@ -393,6 +514,18 @@ export function parseCurrencyMeta(attr: Attribute): CurrencyAttributeMeta | null
   return parsed.success ? parsed.data : null
 }
 
+/**
+ * Returns the typed `PrincipalAttributeMeta` when `attr` is a principal
+ * attribute; null otherwise. Principal meta is optional, so an attribute with
+ * no meta resolves to an empty `{}` rather than null.
+ */
+export function parsePrincipalMeta(attr: Attribute): PrincipalAttributeMeta | null {
+  if (attr.type !== 'principal') return null
+  if (attr.meta == null) return {}
+  const parsed = PrincipalAttributeMetaSchema.safeParse(attr.meta)
+  return parsed.success ? parsed.data : {}
+}
+
 export function parseUserMeta(attr: Attribute): UserAttributeMeta | null {
   if (attr.type !== 'user') return null
   if (attr.meta == null) return {}
@@ -731,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
@@ -744,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
@@ -771,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`.
@@ -782,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[]
@@ -805,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),
@@ -829,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[]
@@ -841,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[]
@@ -914,22 +1131,6 @@ export interface UpdateListViewRequest {
 // Page Types
 // ============================================================================
 
-/**
- * Page action definition. Page-level toolbar item; addressed by permissions
- * and shortcuts systems.
- */
-export interface PageAction {
-  label: string
-  icon: string
-  action: string
-}
-
-export const PageActionSchema = z.object({
-  label: z.string(),
-  icon: z.string(),
-  action: z.string(),
-})
-
 /**
  * Page type — encodes what the page binds to and how it is served (chrome +
  * auth posture both follow from it):
@@ -1252,3 +1453,30 @@ export interface UpdateDesignReferenceRequest {
 export interface DesignReferenceContent {
   content: string
 }
+
+/* -------------------------------------------------------------------------
+   Default-value sentinel
+   ------------------------------------------------------------------------- */
+
+/**
+ * The one non-literal `default_value`: "whoever is writing the record".
+ * Meaningful only on `user` and `principal` attributes, where data-service
+ * resolves it to the caller's `{ type, id }` at write time — an owner field
+ * granting `share`, an `assignee`, a `requested_by` fill themselves without a
+ * hook. An object rather than a bare string because a bare string IS a valid
+ * user value (clients send bare ids). Mirrors `metamodel.CurrentUserDefault`.
+ */
+export const CURRENT_USER_DEFAULT = { type: 'current_user' } as const
+export type CurrentUserDefault = { type: 'current_user' }
+
+/** True when a `default_value` is the current-user sentinel (and nothing else). */
+export function isCurrentUserDefault(value: unknown): value is CurrentUserDefault {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const keys = Object.keys(value)
+  return keys.length === 1 && (value as { type?: unknown }).type === 'current_user'
+}
+
+/** Only the identity-valued attribute types can carry the sentinel. */
+export function acceptsCurrentUserDefault(type: AttributeType): boolean {
+  return type === 'user' || type === 'principal'
+}

package/src/workflow/types.ts

@@ -338,7 +338,14 @@ export interface CronTriggerParams {
   timezone: string
 }
 
-export type ManualTriggerParams = Record<string, never>
+/**
+ * Manual trigger configuration. `input_schema` declares the typed inputs a
+ * manual run may provide (validated on run; they become the trigger item,
+ * addressable as `{{ $json.<name> }}`). Empty = the run takes no inputs.
+ */
+export interface ManualTriggerParams {
+  input_schema?: Attribute[]
+}
 
 export interface WebhookTriggerParams {
   token: string
@@ -474,6 +481,8 @@ export interface UpdateWorkflowRequest {
  */
 export interface RunWorkflowRequest {
   destination_node_id?: string
+  /** Values for the manual trigger's `input_schema`; seed the trigger item. */
+  inputs?: Record<string, unknown>
 }
 
 /** Where a standalone node test's input comes from. */
@@ -598,8 +607,9 @@ export interface ExecutionTriggerContext {
   kind: TriggerKind
   // schedule
   scheduled_at?: string
-  // manual
+  // manual — the actor, and the partial-run bound when `destination_node_id` was passed
   actor?: UserRef
+  destination_node_id?: string
   // webhook
   received_at?: string
   // event
@@ -677,10 +687,17 @@ export interface ListExecutionsOptions extends ListOptions {
 // Execution API shapes
 // ---------------------------------------------------------------------------
 
-/** Execution detail: the header row plus its append-only node executions. */
+/**
+ * Execution detail: the header row plus its append-only node executions.
+ * `nodes_total` is the number of nodes the pinned graph schedules for THIS run
+ * (reachable from the trigger, scoped to the destination path on a partial run;
+ * dead-branch and disabled nodes end as `skipped` rows) — the progress
+ * denominator.
+ */
 export interface GetExecutionDetailResponse {
   execution: WorkflowExecution
   node_executions: NodeExecution[]
+  nodes_total: number
 }
 
 /** Windows into one node run's stored items on one port. */