@collective-intelligence/extensions-sdk 0.1.13 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -139,7 +139,15 @@ body), `"number"` (finite number) or `"boolean"`;
139
139
  `value`; values unique, at least one option); and
140
140
  `{ key, label, type: "json", schema }` for nested objects and lists, whose
141
141
  value must satisfy the Draft 2020-12 JSON Schema `schema` and which Studio
142
- edits as JSON text. A `schema` CI cannot compile strictly closes the form. The
142
+ edits as JSON text; and `{ key, label, type: "rich_text" }` (trigger forms
143
+ only), which Studio edits in a rich-text editor (paragraphs, headings, bold,
144
+ italic, strike, underline, code, lists, quotes, rules, links) and sends as an
145
+ HTML string of at most 20,000 characters. CI sanitizes that HTML when the run
146
+ starts, keeping only `p`, `br`, `h1`–`h6`, `strong`/`b`, `em`/`i`, `u`, `s`,
147
+ `code`, `pre`, `blockquote`, `ul`, `ol`, `li`, `hr`, `img` with an `https`
148
+ `src`, and `a` with an `http`, `https` or `mailto` `href`, and refuses HTML
149
+ with no safe content, so `{{ trigger.form.<key> }}` can feed a Send email
150
+ node's `html`. A `schema` CI cannot compile strictly closes the form. The
143
151
  run starts only once every field holds a value of its type, takes only the
144
152
  declared fields, and nodes bind `{{ trigger.form.<key> }}` (or a path inside a
145
153
  `json` value, such as `{{ trigger.form.request.company.name }}`).
@@ -188,15 +196,16 @@ withStudioTriggerForm(trigger, {
188
196
  selects an ordered list of IDs; `required: false` permits absence or `null` for a
189
197
  single field, or `[]` for a list. These defaults are interpreted by the Host;
190
198
  the portable declaration preserves omitted options. Both options accept booleans
191
- only. The Host must validate current Organization membership at run admission;
199
+ only. The Host must validate that each user is a current Organization member at
200
+ run admission;
192
201
  labels and profile objects never replace the IDs in `form.<key>`.
193
202
 
194
203
  `withStudioAgentForm(agent, { fields })` gives a declared Agent a Studio form,
195
204
  stored under the Agent's `metadata.studioForm`; `readStudioAgentForm` reads it
196
205
  back. `StudioAgentFormField` retains the shared field types (`file`,
197
206
  `text`, `textarea`, `number`, `boolean`, `enum`, `json`, `entities`).
198
- Workflow-only `user_select`, any other type, or a repeated key fails at Agent
199
- form declaration and manifest admission.
207
+ Workflow-only `user_select` and `rich_text`, any other type, or a repeated key
208
+ fails at Agent form declaration and manifest admission.
200
209
  `builtin:view.agent-form` names the Agent by FQN in `props.agentRef`. A submit
201
210
  runs the Agent for the Studio user, within the Agent's audience, with the JSON
202
211
  object of the declared field values as its task.
@@ -437,7 +446,15 @@ the host replaces the value shape while preserving its required list. Ordinary U
437
446
  implicitly become User fields. User fields cannot share File or Relation
438
447
  semantics and are not supported on relation schemas or nested properties.
439
448
  Values contain IDs only; the host owns membership validation and profile
440
- resolution, duplicate rejection, and preservation of list order.
449
+ resolution, duplicate rejection, and preservation of list order. Only the
450
+ schema's accounts field (below) also accepts the Organization's External App
451
+ Users; every other User field accepts Organization members only.
452
+
453
+ At most one User field per schema sets `accounts: true`
454
+ (`accounts: { accounts: true, multiple: true }`). It becomes the schema's
455
+ accounts field: the users it lists act for the record, and the host adds the
456
+ record to their policy subject's `linkedCompanyIds` in place of company links
457
+ for that schema.
441
458
 
442
459
  `declareKnowledgeEntitySchema` declares File fields in `fileFields`, keyed by
443
460
  top-level property key. Each declaration takes `multiple`, `accepts` (matched
@@ -857,6 +874,7 @@ package version. `name` becomes the manifest's `displayName`.
857
874
  ```ts
858
875
  import {
859
876
  declarePackage,
877
+ declareWorkflow,
860
878
  servicePrincipal
861
879
  } from "@collective-intelligence/extensions-sdk"
862
880
 
@@ -883,6 +901,47 @@ dependency, or a Group's external parent does not make a Group package-owned.
883
901
  The declaration contains no credentials or runtime implementation. Deployment
884
902
  confirmation and runtime authorization belong to the Host.
885
903
 
904
+ ### Selecting a Workflow run-as principal
905
+
906
+ Set `servicePrincipalFqn` in `declareWorkflow`'s definition to select an explicit
907
+ run-as identity. You can reference a principal declared by the same package:
908
+
909
+ ```ts
910
+ const importWorkflow = declareWorkflow({
911
+ manifest: { fqn: "acme.directory.import", version: "1.0.0" },
912
+ presentation: { displayName: "Import directory" },
913
+ definition: {
914
+ definition: importGraph,
915
+ lifecycle: { deployMode: "upsert", readonly: true },
916
+ name: "Import directory",
917
+ servicePrincipalFqn: importer.manifest.fqn,
918
+ slug: "import-directory"
919
+ }
920
+ })
921
+ ```
922
+
923
+ Include both `importer` and `importWorkflow` in the package's `components`.
924
+ The manifest stores the FQN string, not a principal ID or credentials. The Host
925
+ resolves an enabled service principal in the installing Organization before
926
+ publishing the Workflow. The SDK permits omission for declarations that do not
927
+ select an identity; omission does not select a default principal or bypass the
928
+ Host's publication requirements. Principal roles, Group ownership, and deployment
929
+ confirmation continue to follow the service-principal declaration rules above.
930
+ Installing a principal with `organization_admin` requires explicit administrator
931
+ confirmation; referencing it from a Workflow does not bypass that confirmation.
932
+
933
+ ### Watching fields in an Entity Updated trigger
934
+
935
+ `watchedFields` in a `builtin.core.workflows.nodes.triggers.entity-updated`
936
+ trigger lists top-level properties of the target schema, each as a key
937
+ (`status`) or a one-segment JSON pointer (`/status`). The trigger starts a run
938
+ only when an update changes one of them. The Host checks each entry against the
939
+ schema installed in the Organization when the Workflow is saved, published or
940
+ installed, and refuses one the schema does not declare. A release that adds a
941
+ field cannot watch it yet: ship the field in one release and the trigger that
942
+ watches it in a later one. Removing a schema field does not update triggers
943
+ that watch it; they stop starting runs for it.
944
+
886
945
  ## Organization Settings declarations
887
946
 
888
947
  `declareOrganizationSettings` declares the settings of the Organization that
@@ -26,8 +26,15 @@ export type KnowledgeFileField = Readonly<{
26
26
  export type KnowledgeFileFieldDeclaration = KnowledgeFileField & Readonly<{
27
27
  visibility?: KnowledgeFieldSemantics["mediaVisibility"];
28
28
  }>;
29
- /** Explicit top-level Organization member references; the host generates UUID values. */
29
+ /**
30
+ * Explicit top-level references to Organization members or External App Users
31
+ * of the Organization; the host generates UUID values. `accounts: true` makes
32
+ * it the schema's accounts field (at most one per schema): the users it lists
33
+ * act for the record, and the record is among their policy subject's
34
+ * `linkedCompanyIds`.
35
+ */
30
36
  export type KnowledgeUserField = Readonly<{
37
+ accounts?: true;
31
38
  multiple: boolean;
32
39
  }>;
33
40
  /** Declares a User field by top-level key, separate from its host-generated value schema. */
@@ -79,7 +79,7 @@ type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeE
79
79
  fieldSemantics?: KnowledgeFieldSemanticsInput;
80
80
  /** The File fields of the schema, by top-level property key. */
81
81
  fileFields?: Readonly<Record<string, KnowledgeFileFieldDeclaration>>;
82
- /** Organization member selections, by top-level property key. */
82
+ /** User fields by top-level property key; at most one sets `accounts: true`. */
83
83
  userFields?: Readonly<Record<string, KnowledgeUserFieldDeclaration>>;
84
84
  schema: DecoderSource<Schema>;
85
85
  }>;
@@ -6,10 +6,10 @@ import type { StudioTriggerFormField } from "./studio.js";
6
6
  /**
7
7
  * The Studio form of an Agent. `builtin:view.agent-form` renders its fields
8
8
  * and runs the Agent with the filled values as the task. The fields are the
9
- * shared form fields except workflow-only User selection.
9
+ * shared form fields except workflow-only User selection and rich text.
10
10
  */
11
11
  export type StudioAgentFormField = Exclude<StudioTriggerFormField, {
12
- type: "user_select";
12
+ type: "rich_text" | "user_select";
13
13
  }>;
14
14
  export type StudioAgentFormDeclaration = Readonly<{
15
15
  fields: readonly StudioAgentFormField[];
@@ -18,7 +18,7 @@ export type StudioAgentFormDeclaration = Readonly<{
18
18
  export declare const studioAgentMetadata: (read: ReadValue<JsonObject>) => ReadValue<JsonObject>;
19
19
  /**
20
20
  * Gives an Agent a Studio form. Unsupported types (including workflow-only
21
- * User fields) or repeated field keys fail here with a `TypeError`.
21
+ * User and rich-text fields) or repeated field keys fail here with a `TypeError`.
22
22
  */
23
23
  export declare const withStudioAgentForm: (agent: DeclaredComponent<AgentDeclaration>, form: StudioAgentFormDeclaration) => DeclaredComponent<AgentDeclaration>;
24
24
  /**
@@ -32,6 +32,16 @@ export type StudioTriggerFormValueField = Readonly<{
32
32
  label: string;
33
33
  type: "boolean" | "number" | "text" | "textarea";
34
34
  }>;
35
+ /**
36
+ * A field that holds formatted text the user writes in a rich-text editor.
37
+ * The Host sanitizes the HTML when the run starts, so `form.<key>` holds
38
+ * sanitized HTML, such as the `html` of an email. Trigger forms only.
39
+ */
40
+ export type StudioTriggerFormRichTextField = Readonly<{
41
+ key: string;
42
+ label: string;
43
+ type: "rich_text";
44
+ }>;
35
45
  /** A choice the user makes in an `enum` field. */
36
46
  export type StudioTriggerFormOption = Readonly<{
37
47
  label: string;
@@ -87,7 +97,7 @@ export type StudioTriggerFormUserField = Readonly<{
87
97
  type: "user_select";
88
98
  }>;
89
99
  /** A field of a Studio trigger form; its value lands at `form.<key>` of the run. */
90
- export type StudioTriggerFormField = StudioTriggerFormEntitiesField | StudioTriggerFormEnumField | StudioTriggerFormFileField | StudioTriggerFormJsonField | StudioTriggerFormUserField | StudioTriggerFormValueField;
100
+ export type StudioTriggerFormField = StudioTriggerFormEntitiesField | StudioTriggerFormEnumField | StudioTriggerFormFileField | StudioTriggerFormJsonField | StudioTriggerFormRichTextField | StudioTriggerFormUserField | StudioTriggerFormValueField;
91
101
  /**
92
102
  * The Studio form of a user-invoked Workflow trigger. Studio shows and runs
93
103
  * the trigger only for users of `organizationGroup`.
@@ -456,6 +456,8 @@ export type WorkflowDeclaration = PackagePrimitiveBase<"workflow"> & Readonly<{
456
456
  definition: WorkflowAuthoringDefinition;
457
457
  lifecycle: LifecycleOptions;
458
458
  name: string;
459
+ /** Explicit run-as service principal FQN, resolved in the installing Organization. */
460
+ servicePrincipalFqn?: string;
459
461
  slug: string;
460
462
  }>;
461
463
  export type WorkflowTemplateDeclaration = PackagePrimitiveBase<"workflowTemplate"> & Readonly<{
package/dist/index.d.ts CHANGED
@@ -31,7 +31,7 @@ export { BACKEND_EXECUTION_LANES, declareHostedContribution, FRONTEND_CATALOG_CO
31
31
  export type { BackendExecutionLane, BackendHostedContributionManifest, ExtensionHost, FrontendCatalogContract, FrontendCatalogContributionManifest, FrontendCatalogExportName, FrontendExtensionHost, HostedContributionDeclaration, HostedContributionInput, HostedContributionManifest, HostedContributionSourceIdentity } from "./hosted/contributions.js";
32
32
  export type { ComponentManifest, ComponentPresentation, DeclarationHandle, DeclarationReference, DeclaredComponent, DocumentsConnectorImplementation, PackageSchemaRuntimeSidecar, MetadataComponentManifest, ToolClassDeclaration, WorkflowFieldClassDeclaration, KnowledgeEntityAdapterClassDeclaration, ConnectionClassDeclaration, KnowledgeConnectorClassDeclaration, KnowledgeConnectorOAuthClassDeclaration, EventListenerClassDeclaration, FieldTransformerClassDeclaration, NotificationChannelClassDeclaration, KnowledgeRelationAdapterClassDeclaration, ToolSettingsOptionsClassDeclaration, WorkflowNodeClassDeclaration, WorkflowNodePortInput } from "./components/authoring-core.js";
33
33
  export type { DeclaredPackageComponent, DeclaredPackageManifest, PackageDefinition, PackageManifestInput, NormalizedPackageDefinition, PackageComponent } from "./package/definition.js";
34
- export type { StudioAppDeclaration, StudioAppDeclarationInput, StudioAppDefinition, StudioAppDefinitionInput, StudioAppGrant, StudioAppLayoutDefinition, StudioAppLifecycle, StudioAppPageDefinition, StudioAppPageInput, StudioAppRole, StudioAppSectionDefinition, StudioAppSectionInput, StudioAppTemplateDeclaration, StudioAppTemplateDefinition, StudioAppTemplatePageDefinition, StudioAppTemplateSectionDefinition, StudioAppViewDataBinding, StudioAppViewDefinition, StudioAppViewInput, StudioAppViewPropsInput, StudioNodeAccess, StudioNodeAccessInput, StudioTriggerReference, StudioComponentDeclaration, StudioTriggerFormDeclaration, StudioTriggerFormEntitiesField, StudioTriggerFormEnumField, StudioTriggerFormField, StudioTriggerFormFileField, StudioTriggerFormInput, StudioTriggerFormJsonField, StudioTriggerFormOption, StudioTriggerFormUserField, StudioTriggerFormValueField } from "./components/studio.js";
34
+ export type { StudioAppDeclaration, StudioAppDeclarationInput, StudioAppDefinition, StudioAppDefinitionInput, StudioAppGrant, StudioAppLayoutDefinition, StudioAppLifecycle, StudioAppPageDefinition, StudioAppPageInput, StudioAppRole, StudioAppSectionDefinition, StudioAppSectionInput, StudioAppTemplateDeclaration, StudioAppTemplateDefinition, StudioAppTemplatePageDefinition, StudioAppTemplateSectionDefinition, StudioAppViewDataBinding, StudioAppViewDefinition, StudioAppViewInput, StudioAppViewPropsInput, StudioNodeAccess, StudioNodeAccessInput, StudioTriggerReference, StudioComponentDeclaration, StudioTriggerFormDeclaration, StudioTriggerFormEntitiesField, StudioTriggerFormEnumField, StudioTriggerFormField, StudioTriggerFormFileField, StudioTriggerFormInput, StudioTriggerFormJsonField, StudioTriggerFormOption, StudioTriggerFormRichTextField, StudioTriggerFormUserField, StudioTriggerFormValueField } from "./components/studio.js";
35
35
  export type { StudioAgentFormDeclaration, StudioAgentFormField } from "./components/studio-agent-form.js";
36
36
  export { readStudioAgentForm, withStudioAgentForm } from "./components/studio-agent-form.js";
37
37
  export { defaultStudioTriggerFormFileAccept, maxStudioTriggerFormFileBytes, readStudioTriggerForm, studioViewKey, withStudioTriggerForm } from "./components/studio.js";