@collective-intelligence/extensions-sdk 0.1.4 → 0.1.5

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
@@ -188,8 +188,12 @@ its variant schema. Manifest admission applies the same port policies, requires
188
188
  non-empty `connectionTemplateFqns`, and checks the editor rules below.
189
189
 
190
190
  `execution` declares `sideEffect` (`none`, `read`, `write`, `external`) and
191
- optional `mainOutputPort`, `resumable`, `testable`, and `itemModes`
192
- (`single`, `each_item`, `all_items`). Triggers answering their caller declare
191
+ optional `mainOutputPort`, `resumable`, `testable`, `repeatable`, and
192
+ `itemModes` (`single`, `each_item`, `all_items`). `repeatable: false` tells
193
+ the host never to repeat an attempt whose result it does not have (a
194
+ timeout, a failure of unknown kind), because the call can have reached its
195
+ target; a node that sends a
196
+ message or makes a paid call declares it. Triggers answering their caller declare
193
197
  `outputChannels` (`key`, codec `valueSchema`, `cardinality`, `deliveryMode`,
194
198
  `adapterId`, `required`). `connectionRequirements` name credential-free
195
199
  connection selectors; each `selector` must be a `parameter` path present in
@@ -448,6 +452,153 @@ Manifests store every entry as a `ToolBindingDeclaration` with FQN strings.
448
452
  Manifest readers also accept a bare FQN string, the form manifests used before
449
453
  binding controls; `toolBindingDeclaration` reads either form.
450
454
 
455
+ ## Organization Group declarations
456
+
457
+ `declareOrganizationGroup` declares a Group Tree: one root Group and its nested
458
+ subgroups, as one primitive of kind `organizationGroup`. The tree has one
459
+ `version` and one required `LifecycleOptions`; every subgroup takes the
460
+ lifecycle of the root.
461
+
462
+ ```ts
463
+ export const salesGroup = declareOrganizationGroup({
464
+ definition: {
465
+ lifecycle: { deployMode: "upsert", readonly: true },
466
+ subgroups: [
467
+ { key: "managers", displayName: "Sales managers" },
468
+ {
469
+ key: "inside-sales",
470
+ displayName: "Inside sales",
471
+ subgroups: [{ key: "emea", displayName: "Inside sales EMEA" }]
472
+ }
473
+ ]
474
+ },
475
+ manifest: { fqn: "acme.directory.groups.sales", version: "1.0.0" },
476
+ presentation: { displayName: "Sales" }
477
+ })
478
+ // Derived: acme.directory.groups.sales.managers,
479
+ // acme.directory.groups.sales.inside-sales,
480
+ // acme.directory.groups.sales.inside-sales.emea
481
+ ```
482
+
483
+ - `subgroups` is an array of `OrganizationSubgroup` items: `key`,
484
+ `displayName`, an optional `description`, and an optional `subgroups` array,
485
+ to any depth.
486
+ - The FQN of a subgroup is the FQN of its parent, a dot, and its `key`.
487
+ `organizationGroupNodes(declaration)` returns the root and every subgroup as
488
+ a flat list of `{ fqn, parentFqn, displayName, description }`, parents first.
489
+ Take FQNs from this list; do not build them by hand.
490
+ - A `key` is one FQN segment and matches `^[a-z0-9]+(?:-[a-z0-9]+)*$`. Two
491
+ sibling items cannot share a `key`. The FQN of each Group in a tree, root or
492
+ subgroup, holds at most 320 characters (`organizationGroupFqnMaxLength`).
493
+ `declareOrganizationGroup` throws a `TypeError` for each violation and
494
+ manifest readers reject the same trees; both use
495
+ `organizationGroupViolation`.
496
+ - `parent` is an optional `DeclarationReference<"organizationGroup">`: the
497
+ handle of a root Group of the same package, or the FQN string of any Group.
498
+ The manifest stores the FQN string. A subgroup has no handle; name it by its
499
+ FQN string, also inside the same package.
500
+
501
+ ## External application roles and Admitted Classes
502
+
503
+ `declareExternalApplication` accepts two optional access fields: `roles`, the
504
+ role tree of the application, and `admits`, the Admitted Classes ceiling.
505
+
506
+ The host stores and checks the roles, the Admitted Classes and the
507
+ [Declared Grants](#declared-grants) at install, and shows them to the
508
+ Organization admin. It does not yet read them when a user signs in to the
509
+ application or calls it.
510
+
511
+ ```ts
512
+ export const partnerPortal = declareExternalApplication({
513
+ definition: {
514
+ // ...applicationType, audience, redirectUris, scopes, lifecycle
515
+ admits: ["internal", "external"],
516
+ roles: [
517
+ { key: "admin", permissions: ["knowledge:read", "knowledge:manage"] },
518
+ { key: "viewer", parent: "admin", permissions: ["knowledge:read"] },
519
+ { key: "owner", permissions: ["knowledge:read"], replaces: "superuser" }
520
+ ]
521
+ },
522
+ manifest: { fqn: "acme.portal.application", version: "2.0.0" },
523
+ presentation: { displayName: "Partner portal" }
524
+ })
525
+ ```
526
+
527
+ - A role is an `ExternalApplicationRole`: `key`, `permissions`, an optional
528
+ `parent`, and an optional `replaces`.
529
+ - A `key` matches `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, holds at most 64
530
+ characters, and is declared one time in the application.
531
+ - A permission is a `resource:action` string with one colon and no empty side.
532
+ The SDK checks the shape only; the host checks that it knows the permission.
533
+ - `parent` is the key of another declared role. A parent role holds every
534
+ permission of each of its children, and a role is not its own ancestor. The
535
+ helper infers the declared keys, so TypeScript rejects a `parent` that is not
536
+ a declared key; the manifest stores plain strings.
537
+ - `replaces` is the key of a role that an earlier release declared and this
538
+ release removed. It cannot be a key of this release, and two roles cannot
539
+ replace the same key.
540
+ - `admits` is a list of `ExternalApplicationUserClass` values (`internal`,
541
+ `external`) with at least one value and no repeated value. The Organization
542
+ admin can narrow the list but cannot admit a class outside it. When `admits`
543
+ is absent, the application admits internal users only.
544
+ - `declareExternalApplication` throws a `TypeError` for each violation and
545
+ manifest readers reject the same declarations; both use
546
+ `externalApplicationViolation`.
547
+
548
+ ## Declared Grants
549
+
550
+ `declareExternalApplication` accepts an optional `grants` list. Each item is a
551
+ Declared Grant: one Organization Group holds one role of the application. A
552
+ package declares Grants only on its own external application; there is no
553
+ separate Grant declaration.
554
+
555
+ ```ts
556
+ export const partnerPortal = declareExternalApplication({
557
+ definition: {
558
+ // ...applicationType, audience, redirectUris, scopes, lifecycle
559
+ roles: [
560
+ { key: "manager", permissions: ["knowledge:read", "knowledge:manage"] },
561
+ { key: "rep", parent: "manager", permissions: ["knowledge:read"] }
562
+ ],
563
+ grants: [
564
+ {
565
+ group: salesGroup,
566
+ role: "rep",
567
+ lifecycle: { deployMode: "init_only", readonly: false }
568
+ },
569
+ {
570
+ group: "acme.directory.groups.sales.managers",
571
+ role: "manager",
572
+ lifecycle: { deployMode: "upsert", readonly: true }
573
+ }
574
+ ]
575
+ },
576
+ manifest: { fqn: "acme.portal.application", version: "2.0.0" },
577
+ presentation: { displayName: "Partner portal" }
578
+ })
579
+ ```
580
+
581
+ - `group` is a `DeclarationReference<"organizationGroup">`: the handle that
582
+ `declareOrganizationGroup` returns for a root Group of the same package, or
583
+ the FQN string of any Group. Use the FQN string for a subgroup and for a
584
+ Group that another package declares. TypeScript rejects a handle of another
585
+ primitive kind. The manifest stores the FQN string in an
586
+ `ExternalApplicationGrant` item.
587
+ - The SDK does not check that the Group exists. The host refuses the install
588
+ when no Group of the Organization has that FQN and no package of the same
589
+ operation declares it.
590
+ - `role` is the key of a role that the same declaration declares. The helper
591
+ infers the declared keys, so TypeScript rejects another key; the manifest
592
+ stores a plain string.
593
+ - `lifecycle` is a required `LifecycleOptions` of the Grant, separate from the
594
+ lifecycle of the application. An item with no `deployMode` or no `readonly`
595
+ is rejected.
596
+ - Two items cannot name the same Group and the same role.
597
+ - `declareExternalApplication` throws a `TypeError` for each violation and
598
+ manifest readers reject the same declarations. Both use
599
+ `externalApplicationViolation` for the Group, the role and the repeated
600
+ pair.
601
+
451
602
  ## Hosted contributions
452
603
 
453
604
  `declarePackage` accepts lazy Backend, Studio, and Dashboard contributions in
@@ -1248,9 +1399,59 @@ export default declarePackage({
1248
1399
  Use your actual exact dependency release, executable/schema FQNs, source location,
1249
1400
  and authorized Organization reader UUID. Knowledge policies use the native
1250
1401
  `{ subjectMatch, rule? }` AST, including recursive comparisons and logical
1251
- predicates. The old `{ version, rules }` shape is rejected. Schema/domain targets
1252
- cover all sources. Dataset grants use existing user/service principals and native
1253
- operations, fields, `sensitiveFields`, row filters and budgets.
1402
+ predicates. The old `{ version, rules }` shape is rejected. `subject` refs read
1403
+ the caller as CI built it: `user.id`, `user.role` (organization membership
1404
+ role), `groupIds`, `linkedCompanyIds` and `access`. CI sets `access` to `"read"`
1405
+ for get, list, search, facets, autocomplete, traverse and retrieval, and to
1406
+ `"write"` for create, update, delete and relation writes; a policy that does not
1407
+ test it applies to both. For example, this `deny` `filter` policy lets
1408
+ `member`-role users read every company but write only the ones they are linked
1409
+ to:
1410
+
1411
+ ```ts
1412
+ const memberCompanyWrites = declareKnowledgePolicy({
1413
+ manifest: {
1414
+ fqn: "com.acme.members.policies.member_company_writes",
1415
+ version: "1.0.0"
1416
+ },
1417
+ presentation: { displayName: "Members write only their linked companies" },
1418
+ definition: {
1419
+ effect: "deny",
1420
+ policyType: "filter",
1421
+ targetKind: "entity_schema",
1422
+ targetFqn: "com.acme.members.company",
1423
+ policyBody: {
1424
+ subjectMatch: {
1425
+ op: "and",
1426
+ args: [
1427
+ {
1428
+ op: "eq",
1429
+ left: { kind: "subject", path: ["user", "role"] },
1430
+ right: { kind: "literal", value: "member" }
1431
+ },
1432
+ {
1433
+ op: "eq",
1434
+ left: { kind: "subject", path: ["access"] },
1435
+ right: { kind: "literal", value: "write" }
1436
+ }
1437
+ ]
1438
+ },
1439
+ rule: {
1440
+ op: "not",
1441
+ arg: {
1442
+ op: "in",
1443
+ value: { kind: "resource", path: ["id"] },
1444
+ set: { kind: "subject", path: ["linkedCompanyIds"] }
1445
+ }
1446
+ }
1447
+ }
1448
+ }
1449
+ })
1450
+ ```
1451
+
1452
+ Schema/domain targets cover all sources. Dataset grants use existing
1453
+ user/service principals and native operations, fields, `sensitiveFields`, row
1454
+ filters and budgets.
1254
1455
 
1255
1456
  Knowledge settings retain `{ type: "inline" | "linked", value }` entries;
1256
1457
  `remoteFilters` retain native `mode` and `selected_ids`. Binding `parentKey`,
@@ -4,7 +4,7 @@ import type { ConsumerProfileId } from "../schema/profiles.js";
4
4
  import type { PackageSchemaProjection } from "../schema/projection.js";
5
5
  import type { PackageCodec, PackageCodecSource, PackageDecoder, PackageDecoderSource, PackageSchemaSource, SchemaDirection, SchemaValue } from "../schema/source.js";
6
6
  import type { PackagePrimitiveKind } from "./base.js";
7
- import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
7
+ import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
8
8
  import type { PackagePrimitiveDeclaration } from "./declaration.js";
9
9
  import type { FieldOption, FieldOptionPage } from "./fields.js";
10
10
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
@@ -49,7 +49,7 @@ export type DeclarationHandle<Kind extends PackagePrimitiveKind> = DeclaredCompo
49
49
  export type DeclarationReference<Kind extends PackagePrimitiveKind> = DeclarationHandle<Kind> | string;
50
50
  /** The FQN a reference points at; manifests store references as FQNs. */
51
51
  export declare const referenceFqn: (reference: DeclarationReference<PackagePrimitiveKind>) => string;
52
- export type ExecutableManifest = DatasetParserDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ToolDeclaration | ToolSettingsOptionsDeclaration | WorkflowFieldDeclaration | WorkflowNodeDeclaration;
52
+ export type ExecutableManifest = DatasetParserDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | EmailProviderDeclaration | EventListenerDeclaration | OutboundMessagingProviderDeclaration | ToolDeclaration | ToolSettingsOptionsDeclaration | WorkflowFieldDeclaration | WorkflowNodeDeclaration;
53
53
  export type MetadataComponentManifest = Exclude<PackagePrimitiveDeclaration, ExecutableManifest>;
54
54
  export type DefinitionInput<Manifest> = Omit<Manifest, "description" | "displayName" | "fqn" | "icon" | "kind" | "tags" | "version">;
55
55
  export type ClassDeclaration<Manifest, Constructor extends new () => object, Definition = DefinitionInput<Manifest>> = Readonly<{
@@ -1,6 +1,6 @@
1
1
  import type { VisibilityCondition } from "../schema/forms.js";
2
2
  export type BindingScope = "organization" | "tenant";
3
- export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationSso" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -351,6 +351,14 @@ export type EventListenerDeclaration = PackagePrimitiveBase<"eventListener"> & R
351
351
  keyFamily: string;
352
352
  stateKey: string;
353
353
  }>;
354
+ /** Marks a listener whose occurrences carry an **Inbound Message**. */
355
+ messaging?: Readonly<{
356
+ connectionTemplateFqn: string;
357
+ contractVersion: 1;
358
+ service: string;
359
+ }>;
360
+ /** Connection field that chooses the receive mode among the capabilities. */
361
+ receiveModeField?: string;
354
362
  /** State entries the host may project into the listener runtime context. */
355
363
  runtimeState?: readonly Readonly<{
356
364
  keyFamily: string;
@@ -358,15 +366,49 @@ export type EventListenerDeclaration = PackagePrimitiveBase<"eventListener"> & R
358
366
  }>[];
359
367
  safeOccurrenceFields?: readonly string[];
360
368
  safeSelectorFields?: readonly string[];
369
+ /**
370
+ * `connection` gives each connection one source watch and one webhook URL.
371
+ * Omission keeps one source watch per selector.
372
+ */
373
+ sourceScope?: "connection" | "selector";
374
+ /** Status the webhook ingress answers; omission keeps the host default. */
375
+ webhookAcknowledgement?: Readonly<{
376
+ status: 200 | 204;
377
+ }>;
361
378
  /**
362
379
  * Provider subscription handshake the host answers on this listener's
363
380
  * webhook endpoints before callback admission. `echo_query_parameter`
364
381
  * returns the named query parameter as `text/plain`.
382
+ * `echo_query_parameter_with_verify_token` does so only when
383
+ * `tokenParameter` equals the verify token of the endpoint.
384
+ * `echo_json_body_field` returns `field` of a JSON body when the body
385
+ * field `when.field` equals `when.equals`.
365
386
  */
366
387
  webhookHandshake?: Readonly<{
367
388
  kind: "echo_query_parameter";
368
389
  parameter: string;
390
+ } | {
391
+ kind: "echo_query_parameter_with_verify_token";
392
+ parameter: string;
393
+ tokenParameter: string;
394
+ } | {
395
+ field: string;
396
+ kind: "echo_json_body_field";
397
+ when: Readonly<{
398
+ equals: string;
399
+ field: string;
400
+ }>;
369
401
  }>;
402
+ /** `listener` means the listener registers its webhook with the vendor. */
403
+ webhookRegistration?: "listener";
404
+ }>;
405
+ /** Authoring input of `declareInboundMessagingProvider`. */
406
+ export type InboundMessagingProviderDefinition = Pick<EventListenerDeclaration, "eventKind" | "receiveModeField" | "webhookAcknowledgement" | "webhookHandshake" | "webhookRegistration"> & Readonly<{
407
+ capabilities: readonly ("poll" | "webhook")[];
408
+ /** Connection template of the vendor account that receives. */
409
+ connectionTemplateFqn: string;
410
+ /** Vendor service that sends each **Inbound Message**. */
411
+ service: string;
370
412
  }>;
371
413
  /** Canonical package-owned occurrence for durable internal ingress fan-out. */
372
414
  export type EventListenerInternalOccurrence = Readonly<{
@@ -394,6 +436,13 @@ export type EventListenerPollRequest = Readonly<{
394
436
  export type EventListenerWebhookRequest = Readonly<{
395
437
  readonly body: Uint8Array;
396
438
  readonly headers: Readonly<Record<string, string>>;
439
+ /**
440
+ * The ISO 8601 time at which the host accepted the request. The host can
441
+ * verify later, so a time limit of the vendor is checked against this time.
442
+ */
443
+ readonly receivedAt?: string;
444
+ /** The full URL that the vendor called, when the host knows it. */
445
+ readonly url?: string;
397
446
  }>;
398
447
  /** Organization SSO metadata; the provider constructor remains a runtime sidecar. */
399
448
  export type OrganizationSsoDeclaration = PackagePrimitiveBase<"organizationSso"> & Readonly<{
@@ -419,3 +468,13 @@ export type EmailProviderDeclaration = PackagePrimitiveBase<"emailProvider"> & R
419
468
  /** `mailbox` always sends from a real mailbox; `address` is every other provider. */
420
469
  senderKind: "address" | "mailbox";
421
470
  }>;
471
+ /**
472
+ * **Outbound Messaging Provider** metadata; the provider constructor remains a
473
+ * runtime sidecar.
474
+ */
475
+ export type OutboundMessagingProviderDeclaration = PackagePrimitiveBase<"outboundMessagingProvider"> & Readonly<{
476
+ /** Connection template of the vendor account that sends. */
477
+ connectionTemplateFqn: string;
478
+ /** Vendor service that receives each **Outbound Message**. */
479
+ service: string;
480
+ }>;
@@ -1,12 +1,13 @@
1
1
  import type { AgentDeclaration, SkillDeclaration } from "./agents.js";
2
2
  import type { DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./catalog.js";
3
3
  import type { KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration } from "./connector-instances.js";
4
- import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EmailProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
4
+ import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EmailProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration } from "./connectors.js";
5
5
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
6
6
  import type { ExternalApplicationDeclaration } from "./external-application.js";
7
7
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
8
+ import type { OrganizationGroupDeclaration } from "./organization-group.js";
8
9
  import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
9
10
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
10
11
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
11
12
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
12
- export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
13
+ export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -2,7 +2,7 @@ import type { JsonValue } from "../foundation/json.js";
2
2
  import type { FormSchemaSource } from "../schema/forms.js";
3
3
  import type { SchemaValue } from "../schema/source.js";
4
4
  import type { ClassDeclaration, ClassDeclaredComponent, ConnectionClassDeclaration, ConnectionImplementation, EventListenerClassDeclaration, EventListenerImplementation, DocumentsConnectorClassDeclaration, DocumentsConnectorImplementation, FieldTransformerClassDeclaration, FieldTransformerImplementation, KnowledgeConnectorClassDeclaration, KnowledgeConnectorImplementation, KnowledgeConnectorOAuthClassDeclaration, KnowledgeConnectorOAuthImplementation, KnowledgeEntityAdapterClassDeclaration, KnowledgeEntityAdapterImplementation, KnowledgeRelationAdapterClassDeclaration, KnowledgeRelationAdapterImplementation, NotificationChannelClassDeclaration, NotificationChannelImplementation, ToolClassDeclaration, ToolImplementation, ToolSettingsOptionsClassDeclaration, ToolSettingsOptionsImplementation, WorkflowFieldClassDeclaration, WorkflowFieldImplementation, WorkflowFieldValue } from "./authoring-core.js";
5
- import type { ConnectionDeclaration, DocumentsConnectorDeclaration, EmailProviderDeclaration, EventListenerDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
5
+ import type { ConnectionDeclaration, DocumentsConnectorDeclaration, EmailProviderDeclaration, EventListenerDeclaration, InboundMessagingProviderDefinition, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration } from "./connectors.js";
6
6
  import type { DatasetParserImplementation } from "./dataset-parser.js";
7
7
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
8
8
  import type { WorkflowFieldDeclaration } from "./workflows.js";
@@ -30,3 +30,15 @@ export type EmailProviderImplementation = Readonly<{
30
30
  send: (...input: never[]) => object | PromiseLike<object>;
31
31
  }>;
32
32
  export declare const declareEmailProvider: <Constructor extends new () => EmailProviderImplementation>(input: ClassDeclaration<EmailProviderDeclaration, Constructor>) => ClassDeclaredComponent<EmailProviderDeclaration, Constructor>;
33
+ /**
34
+ * Declares an **Inbound Messaging Provider**: the event listener of one vendor
35
+ * service, fixed to the shared **Inbound Message** contract. Each connection
36
+ * gets one source watch, and occurrence summaries hold ids only.
37
+ */
38
+ export declare const declareInboundMessagingProvider: <Constructor extends new () => EventListenerImplementation>(input: ClassDeclaration<EventListenerDeclaration, Constructor, InboundMessagingProviderDefinition>) => ClassDeclaredComponent<EventListenerDeclaration, Constructor>;
39
+ /** Structural admission keeps host APIs and frameworks outside the base SDK. */
40
+ export type OutboundMessagingProviderImplementation = Readonly<{
41
+ send: (...input: never[]) => object | PromiseLike<object>;
42
+ }>;
43
+ /** Declares an **Outbound Messaging Provider** with its one `send` operation. */
44
+ export declare const declareOutboundMessagingProvider: <Constructor extends new () => OutboundMessagingProviderImplementation>(input: ClassDeclaration<OutboundMessagingProviderDeclaration, Constructor>) => ClassDeclaredComponent<OutboundMessagingProviderDeclaration, Constructor>;
@@ -1,14 +1,44 @@
1
1
  import type { PackagePrimitiveBase } from "./base.js";
2
2
  import type { LifecycleOptions } from "./lifecycle.js";
3
3
  export type ExternalApplicationType = "confidential" | "public";
4
+ /** A User Class that an Application can admit. */
5
+ export type ExternalApplicationUserClass = "internal" | "external";
6
+ /**
7
+ * An Application Role: one node of the role tree of the application. `Key` is
8
+ * the union of the declared role keys; a manifest holds plain strings.
9
+ */
10
+ export type ExternalApplicationRole<Key extends string = string> = Readonly<{
11
+ key: Key;
12
+ /** Key of the declared role that holds every permission of this role. */
13
+ parent?: NoInfer<Key>;
14
+ /** CI permissions, each one `resource:action`. */
15
+ permissions: readonly string[];
16
+ /** Key of a role that an earlier release declared and this one removed. */
17
+ replaces?: string;
18
+ }>;
19
+ /** A Declared Grant: one Group holds one role of the application. */
20
+ export type ExternalApplicationGrant = Readonly<{
21
+ /** FQN of the Group that holds the role, in any package. */
22
+ group: string;
23
+ lifecycle: LifecycleOptions;
24
+ /** Key of a declared role of the application. */
25
+ role: string;
26
+ }>;
4
27
  /**
5
28
  * Portable External App definition. Tokens and client secrets are never
6
29
  * declared here; Dashboard rotate remains the credential path.
7
30
  */
8
31
  export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalApplication"> & Readonly<{
32
+ /**
33
+ * Admitted Classes ceiling: the User Classes that an Organization admin
34
+ * can admit. When absent, the application admits internal users only.
35
+ */
36
+ admits?: readonly ExternalApplicationUserClass[];
9
37
  allowedOrigins: readonly string[];
10
38
  applicationType: ExternalApplicationType;
11
39
  audience: string;
40
+ /** The Declared Grants of the application. */
41
+ grants?: readonly ExternalApplicationGrant[];
12
42
  lifecycle: LifecycleOptions;
13
43
  postLogoutRedirectUris: readonly string[];
14
44
  /**
@@ -18,8 +48,13 @@ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalAppli
18
48
  primaryRedirectUri?: string;
19
49
  /** Every accepted callback, including the primary redirect URI. */
20
50
  redirectUris: readonly string[];
51
+ /** The role tree of the application. */
52
+ roles?: readonly ExternalApplicationRole[];
21
53
  scopes: readonly string[];
22
54
  setupInstructions?: string;
23
55
  }>;
24
- /** Shared authoring and serialized admission invariant for callbacks. */
25
- export declare const externalApplicationViolation: ({ primaryRedirectUri, redirectUris }: Pick<ExternalApplicationDeclaration, "primaryRedirectUri" | "redirectUris">) => string | undefined;
56
+ /**
57
+ * Shared authoring and serialized admission invariant for callbacks, the role
58
+ * tree, the Admitted Classes and the Declared Grants.
59
+ */
60
+ export declare const externalApplicationViolation: ({ admits, grants, primaryRedirectUri, redirectUris, roles }: Pick<ExternalApplicationDeclaration, "admits" | "grants" | "primaryRedirectUri" | "redirectUris" | "roles">) => string | undefined;
@@ -182,6 +182,36 @@ export type KnowledgePolicyPredicate = Readonly<{
182
182
  direction: "out" | "in";
183
183
  inner: KnowledgePolicyPredicate;
184
184
  }>;
185
+ /**
186
+ * A Knowledge policy: `subjectMatch` selects whom it applies to, `rule` which
187
+ * records. `subject` refs read the caller as CI built it: `user.id`,
188
+ * `user.role` (the organization membership role), `groupIds`,
189
+ * `linkedCompanyIds` (the user's linked company entities) and `access`.
190
+ * `access` is `"read"` for get, list, search, facets, autocomplete, traverse
191
+ * and retrieval, and `"write"` for create, update, delete and relation writes;
192
+ * the deciding operation sets it, never the caller. A policy that does not
193
+ * test `access` applies to both. `resource` refs read `["id"]` or a `data`
194
+ * path.
195
+ *
196
+ * Write-only deny: members read every company but write only linked ones.
197
+ *
198
+ * ```ts
199
+ * const memberCompanyWrites: KnowledgePolicyBody = {
200
+ * subjectMatch: {
201
+ * op: "and",
202
+ * args: [
203
+ * { op: "eq", left: { kind: "subject", path: ["user", "role"] }, right: { kind: "literal", value: "member" } },
204
+ * { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
205
+ * ]
206
+ * },
207
+ * rule: {
208
+ * op: "not",
209
+ * arg: { op: "in", value: { kind: "resource", path: ["id"] }, set: { kind: "subject", path: ["linkedCompanyIds"] } }
210
+ * }
211
+ * }
212
+ * ```
213
+ * Declare it with `effect: "deny"` and `policyType: "filter"`.
214
+ */
185
215
  export type KnowledgePolicyBody = Readonly<{
186
216
  subjectMatch: KnowledgePolicyPredicate;
187
217
  rule?: KnowledgePolicyPredicate;
@@ -0,0 +1,128 @@
1
+ import type { JsonObject } from "../foundation/json.js";
2
+ /**
3
+ * **Conversation Reference**: the opaque value that identifies where a message
4
+ * continues. The vendor package encodes it; no other code parses it.
5
+ */
6
+ export type ConversationReference = string;
7
+ /**
8
+ * One attachment of an **Inbound Message**. The host stores the bytes on
9
+ * arrival, or marks the attachment as failed. `audio` is audio content, a
10
+ * **Voice Message** included; `file` is every other attachment.
11
+ */
12
+ export type InboundAttachment = Readonly<{
13
+ contentType: string | null;
14
+ filename: string;
15
+ kind: "audio" | "file";
16
+ sizeBytes: number;
17
+ status: "stored";
18
+ storageFileId: string;
19
+ } | {
20
+ filename?: string;
21
+ kind: "audio" | "file";
22
+ reason: "download_failed" | "too_large";
23
+ status: "failed";
24
+ }>;
25
+ /**
26
+ * **Inbound Message**: one message that a person or system sent to a vendor
27
+ * account of the organization. Every **Inbound Messaging Provider** emits this
28
+ * contract.
29
+ */
30
+ export type InboundMessage = Readonly<{
31
+ attachments: readonly InboundAttachment[];
32
+ connectionId: string;
33
+ conversation: ConversationReference;
34
+ /** Provider identity of the conversation. */
35
+ conversationIdentity: Readonly<{
36
+ id: string;
37
+ kind: "channel" | "direct" | "group";
38
+ }>;
39
+ /**
40
+ * The language of the message. **Message Enrichment** adds it when a
41
+ * consumer asks for it; a vendor package never sets it.
42
+ */
43
+ language?: Readonly<{
44
+ code: string;
45
+ confidence: number;
46
+ source: "speech_model" | "text_detection" | "conversation" | "vendor_hint" | "organization_default";
47
+ }>;
48
+ messageId: string;
49
+ receivedAt: string;
50
+ /** Provider identity of the sender, with the vendor's locale when given. */
51
+ sender: Readonly<{
52
+ displayName?: string;
53
+ id: string;
54
+ locale?: string;
55
+ }>;
56
+ service: string;
57
+ text: string | null;
58
+ /**
59
+ * The transcript of an audio message, or the failure of its transcription.
60
+ * **Message Enrichment** adds it when a consumer asks for it; a vendor
61
+ * package never sets it.
62
+ */
63
+ transcription?: Readonly<{
64
+ durationMs: number | null;
65
+ status: "completed";
66
+ text: string;
67
+ } | {
68
+ code: string;
69
+ status: "failed";
70
+ }>;
71
+ /** Vendor extras outside the shared contract. */
72
+ vendorExtras: JsonObject;
73
+ }>;
74
+ /**
75
+ * **Outbound Message**: one message that the organization sends through a
76
+ * vendor account. It continues a conversation or starts a new one with
77
+ * vendor-owned recipient fields.
78
+ *
79
+ * A `voice` content is a text that the host speaks. The vendor shows the audio
80
+ * as a **Voice Message** when the **Speech Model** produces a format that the
81
+ * vendor accepts as one, and as an audio file otherwise.
82
+ */
83
+ export type OutboundMessage = Readonly<{
84
+ content: Readonly<{
85
+ kind: "text";
86
+ text: string;
87
+ } | {
88
+ kind: "voice";
89
+ /** Selects the **Voice**. Absent: the language detected from `text`. */
90
+ language?: string;
91
+ /** Absent: the default text-to-speech Speech Model of the organization. */
92
+ modelId?: string;
93
+ /** Values of the extra settings that the Speech Model declares. */
94
+ modelSettings?: JsonObject;
95
+ speed?: number;
96
+ /** The text to speak. */
97
+ text: string;
98
+ voice: Readonly<
99
+ /** The Voices of the organization. Only with the default model. */
100
+ {
101
+ mode: "organization";
102
+ } | {
103
+ mode: "fixed";
104
+ voiceId: string;
105
+ } | {
106
+ mode: "per_language";
107
+ voices: readonly Readonly<{
108
+ languageCode: string;
109
+ voiceId: string;
110
+ }>[];
111
+ }>;
112
+ }>;
113
+ target: Readonly<{
114
+ conversation: ConversationReference;
115
+ mode: "continue";
116
+ } | {
117
+ mode: "start_new";
118
+ recipient: JsonObject;
119
+ }>;
120
+ }>;
121
+ /**
122
+ * **Message Receipt**: the result of a send that the vendor accepted, with the
123
+ * vendor message id. It does not mean that a person received the message.
124
+ */
125
+ export type MessageReceipt = Readonly<{
126
+ conversation: ConversationReference;
127
+ messageId: string;
128
+ }>;