@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 +64 -5
- package/dist/components/knowledge.d.ts +8 -1
- package/dist/components/metadata-authoring.d.ts +1 -1
- package/dist/components/studio-agent-form.d.ts +3 -3
- package/dist/components/studio.d.ts +11 -1
- package/dist/components/workflows.d.ts +2 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2 -2
- package/dist/package/primitive-readers.d.ts +1 -0
- package/package.json +1 -1
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
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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";
|