@collective-intelligence/extensions-sdk 0.1.10 → 0.1.12
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 +425 -85
- package/dist/components/agents.d.ts +3 -0
- package/dist/components/base.d.ts +2 -1
- package/dist/components/connection-instances.d.ts +9 -0
- package/dist/components/connector-instances.d.ts +5 -1
- package/dist/components/data-access.d.ts +11 -0
- package/dist/components/declaration.d.ts +3 -1
- package/dist/components/external-application.d.ts +76 -28
- package/dist/components/knowledge.d.ts +25 -4
- package/dist/components/metadata-authoring.d.ts +24 -11
- package/dist/components/organization-settings.d.ts +1 -1
- package/dist/components/service-principal.d.ts +12 -0
- package/dist/components/workflow-results.d.ts +5 -0
- package/dist/components/workflows.d.ts +3 -0
- package/dist/index.d.ts +6 -2
- package/dist/index.js +2 -2
- package/dist/package/connector-readers.d.ts +1 -0
- package/dist/package/knowledge-readers.d.ts +52 -0
- package/dist/package/primitive-readers.d.ts +18 -0
- package/dist/package/workflow-readers.d.ts +1 -0
- package/dist/release/stored-manifest.d.ts +3 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -427,7 +427,7 @@ fieldSemantics: {
|
|
|
427
427
|
"/companies": {
|
|
428
428
|
relation: {
|
|
429
429
|
targetSchemaFqn: "core.schemas.crm.company",
|
|
430
|
-
cardinality: "
|
|
430
|
+
cardinality: "many_to_many",
|
|
431
431
|
maxItems: 20,
|
|
432
432
|
onDelete: "restrict",
|
|
433
433
|
display: { fields: [{ field: "name", scope: "data" }] },
|
|
@@ -440,8 +440,18 @@ fieldSemantics: {
|
|
|
440
440
|
}
|
|
441
441
|
```
|
|
442
442
|
|
|
443
|
-
`cardinality`
|
|
444
|
-
|
|
443
|
+
`cardinality` describes source-to-target limits, independently of whether an
|
|
444
|
+
inverse field is exposed. One means at most one, not a required link.
|
|
445
|
+
|
|
446
|
+
| Cardinality | Targets per source | Sources per target | Forward / inverse shape |
|
|
447
|
+
| -------------- | ------------------ | ------------------ | ----------------------- |
|
|
448
|
+
| `one_to_one` | At most one | At most one | Scalar / scalar |
|
|
449
|
+
| `one_to_many` | Many | At most one | Array / scalar |
|
|
450
|
+
| `many_to_one` | At most one | Many | Scalar / array |
|
|
451
|
+
| `many_to_many` | Many | Many | Array / array |
|
|
452
|
+
|
|
453
|
+
`maxItems` is an optional positive item limit for `one_to_many` and
|
|
454
|
+
`many_to_many` owners; scalar owners reject it. `onDelete` is `clear` or
|
|
445
455
|
`restrict`; the platform applies `clear` when it is absent. `display.fields`
|
|
446
456
|
and `autocomplete.fields` name `{ field, scope: "data" | "entity" }` fields of
|
|
447
457
|
the target schema; `autocomplete.baseFilters` are ANDed schema-aware filters
|
|
@@ -454,6 +464,159 @@ a relation schema. Package deploy resolves `targetSchemaFqn` among the entity
|
|
|
454
464
|
schemas of the Organization. The metadata-only `relationFields` declaration
|
|
455
465
|
is removed; manifest parsing refuses a release that still declares it.
|
|
456
466
|
|
|
467
|
+
An optional inverse names the owner by schema FQN and exact top-level RFC 6901
|
|
468
|
+
pointer. For example, Company can expose Contact.company through:
|
|
469
|
+
|
|
470
|
+
```ts
|
|
471
|
+
fieldSemantics: {
|
|
472
|
+
"/contacts": {
|
|
473
|
+
relation: {
|
|
474
|
+
inverseOf: { schemaFqn: "core.schemas.crm.contact", field: "/company" },
|
|
475
|
+
display: { fields: [{ field: "name", scope: "data" }] }
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Inverse declarations accept `inverseOf` and optional `display`; they reject a
|
|
482
|
+
target, cardinality, picker (`autocomplete`), `maxItems`, or delete policy.
|
|
483
|
+
The host resolves the member schema and value shape from the owner. Authors
|
|
484
|
+
omit both forward and inverse properties from their ordinary value schema;
|
|
485
|
+
the host generates read contracts and excludes inverse fields from writes.
|
|
486
|
+
Pair resolution, permissions and database enforcement belong to the host,
|
|
487
|
+
not this portable SDK. Removing an inverse does not change owner constraints.
|
|
488
|
+
The legacy `one` and `many` authoring literals are rejected; migrate them to
|
|
489
|
+
`many_to_one` and `many_to_many`, respectively, to preserve reverse sharing.
|
|
490
|
+
|
|
491
|
+
### Complete cardinality example
|
|
492
|
+
|
|
493
|
+
These five declarations belong to one package with the declared Directory domain
|
|
494
|
+
(or a dependency supplying it). Person owns every relationship. Passport.holder
|
|
495
|
+
and Asset.owner are scalar inverses; Company.employees and Group.members are
|
|
496
|
+
list inverses. Every inverse is optional: removing it preserves the corresponding
|
|
497
|
+
owner's constraints and links. A local helper repeats ordinary schema settings;
|
|
498
|
+
it is not an additional SDK API.
|
|
499
|
+
|
|
500
|
+
```ts
|
|
501
|
+
import {
|
|
502
|
+
declareKnowledgeEntitySchema,
|
|
503
|
+
knowledgeRecordSchema,
|
|
504
|
+
type KnowledgeFieldSemantics
|
|
505
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
506
|
+
|
|
507
|
+
// The package also supplies com.acme.domains.directory, or depends on its owner.
|
|
508
|
+
// This local helper only avoids repeating the ordinary schema settings.
|
|
509
|
+
function entity(
|
|
510
|
+
key: string,
|
|
511
|
+
displayName: string,
|
|
512
|
+
fieldSemantics: Readonly<Record<string, KnowledgeFieldSemantics>>
|
|
513
|
+
) {
|
|
514
|
+
return declareKnowledgeEntitySchema({
|
|
515
|
+
manifest: { fqn: `com.acme.schemas.directory.${key}`, version: "1.0.0" },
|
|
516
|
+
presentation: { displayName },
|
|
517
|
+
definition: {
|
|
518
|
+
domainFqn: "com.acme.domains.directory",
|
|
519
|
+
lifecycle: { deployMode: "upsert", readonly: false },
|
|
520
|
+
schema: knowledgeRecordSchema({
|
|
521
|
+
properties: { name: { type: "string" } }
|
|
522
|
+
}),
|
|
523
|
+
fieldSemantics,
|
|
524
|
+
autocompleteConfiguration: {
|
|
525
|
+
autocompleteFields: [],
|
|
526
|
+
defaultAutocompleteFields: []
|
|
527
|
+
},
|
|
528
|
+
displayNameExpression: null,
|
|
529
|
+
embeddingConfig: null,
|
|
530
|
+
persistFullFieldContributions: false,
|
|
531
|
+
usableAsDocumentScope: false,
|
|
532
|
+
versioningEnabled: null
|
|
533
|
+
}
|
|
534
|
+
})
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
export const Person = entity("person", "Person", {
|
|
538
|
+
"/passport": {
|
|
539
|
+
relation: {
|
|
540
|
+
targetSchemaFqn: "com.acme.schemas.directory.passport",
|
|
541
|
+
cardinality: "one_to_one"
|
|
542
|
+
}
|
|
543
|
+
},
|
|
544
|
+
"/assets": {
|
|
545
|
+
relation: {
|
|
546
|
+
targetSchemaFqn: "com.acme.schemas.directory.asset",
|
|
547
|
+
cardinality: "one_to_many"
|
|
548
|
+
}
|
|
549
|
+
},
|
|
550
|
+
"/company": {
|
|
551
|
+
relation: {
|
|
552
|
+
targetSchemaFqn: "com.acme.schemas.directory.company",
|
|
553
|
+
cardinality: "many_to_one"
|
|
554
|
+
}
|
|
555
|
+
},
|
|
556
|
+
"/groups": {
|
|
557
|
+
relation: {
|
|
558
|
+
targetSchemaFqn: "com.acme.schemas.directory.group",
|
|
559
|
+
cardinality: "many_to_many"
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
})
|
|
563
|
+
|
|
564
|
+
export const Passport = entity("passport", "Passport", {
|
|
565
|
+
"/holder": {
|
|
566
|
+
relation: {
|
|
567
|
+
inverseOf: {
|
|
568
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
569
|
+
field: "/passport"
|
|
570
|
+
}
|
|
571
|
+
}
|
|
572
|
+
}
|
|
573
|
+
})
|
|
574
|
+
export const Asset = entity("asset", "Asset", {
|
|
575
|
+
"/owner": {
|
|
576
|
+
relation: {
|
|
577
|
+
inverseOf: {
|
|
578
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
579
|
+
field: "/assets"
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
}
|
|
583
|
+
})
|
|
584
|
+
export const Company = entity("company", "Company", {
|
|
585
|
+
"/employees": {
|
|
586
|
+
relation: {
|
|
587
|
+
inverseOf: {
|
|
588
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
589
|
+
field: "/company"
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
})
|
|
594
|
+
export const Group = entity("group", "Group", {
|
|
595
|
+
"/members": {
|
|
596
|
+
relation: {
|
|
597
|
+
inverseOf: {
|
|
598
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
599
|
+
field: "/groups"
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
}
|
|
603
|
+
})
|
|
604
|
+
|
|
605
|
+
// Add these declarations to the existing package's primitives collection.
|
|
606
|
+
export const relationSchemas = [Person, Passport, Asset, Company, Group]
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
Only Person's forward properties accept writes. For example, `passport` and
|
|
610
|
+
`company` accept an ID or null; `assets` and `groups` accept ID arrays. One means
|
|
611
|
+
at most one, not required participation. Two independent forward declarations
|
|
612
|
+
would create two relationships; use `inverseOf` to expose the same links.
|
|
613
|
+
|
|
614
|
+
See the [relation field operator reference](../../../docs/reference/knowledge-relation-fields.md)
|
|
615
|
+
for SQL enforcement, safe cardinality changes, rollout and read limits. Package
|
|
616
|
+
comparison uses source-owned definitions; the host independently validates the
|
|
617
|
+
resolved inverse runtime shape. Authors never copy generated properties into
|
|
618
|
+
their ordinary schema.
|
|
619
|
+
|
|
457
620
|
The host rejects `onDelete: "restrict"` for targets with `managedProjection`
|
|
458
621
|
and for `core.schemas.directory.organization` and
|
|
459
622
|
`core.schemas.strategy.organization-context`; use `clear` for these targets.
|
|
@@ -635,6 +798,42 @@ export const salesGroup = declareOrganizationGroup({
|
|
|
635
798
|
The manifest stores the FQN string. A subgroup has no handle; name it by its
|
|
636
799
|
FQN string, also inside the same package.
|
|
637
800
|
|
|
801
|
+
## Service principal declarations
|
|
802
|
+
|
|
803
|
+
`servicePrincipal` declares one non-human identity with one Organization Role
|
|
804
|
+
and memberships in Groups declared by the same package. `version` is required
|
|
805
|
+
common SDK primitive metadata; it has no default and is independent of the
|
|
806
|
+
package version. `name` becomes the manifest's `displayName`.
|
|
807
|
+
|
|
808
|
+
```ts
|
|
809
|
+
import {
|
|
810
|
+
declarePackage,
|
|
811
|
+
servicePrincipal
|
|
812
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
813
|
+
|
|
814
|
+
const importer = servicePrincipal({
|
|
815
|
+
fqn: "acme.directory.importer",
|
|
816
|
+
name: "Importer",
|
|
817
|
+
version: "1.0.0",
|
|
818
|
+
organizationRole: "organization_operator",
|
|
819
|
+
groups: [salesGroup, "acme.directory.groups.sales.inside-sales.emea"]
|
|
820
|
+
})
|
|
821
|
+
|
|
822
|
+
export const directory = declarePackage({
|
|
823
|
+
manifest: { fqn: "acme.directory", name: "Directory", version: "1.0.0" },
|
|
824
|
+
components: [salesGroup, importer]
|
|
825
|
+
})
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
`organizationRole` is `organization_admin`, `organization_operator`, or
|
|
829
|
+
`organization_member`. `groups` is a required array; use `[]` for no memberships.
|
|
830
|
+
A root Group handle or a root/subgroup FQN is accepted and serialized as an FQN
|
|
831
|
+
string. Both `declarePackage` and `parsePackageManifest` require each referenced
|
|
832
|
+
Group to be declared in that same manifest. A matching FQN prefix, a package
|
|
833
|
+
dependency, or a Group's external parent does not make a Group package-owned.
|
|
834
|
+
The declaration contains no credentials or runtime implementation. Deployment
|
|
835
|
+
confirmation and runtime authorization belong to the Host.
|
|
836
|
+
|
|
638
837
|
## Organization Settings declarations
|
|
639
838
|
|
|
640
839
|
`declareOrganizationSettings` declares the settings of the Organization that
|
|
@@ -658,7 +857,7 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
658
857
|
domains: ["acme.example"],
|
|
659
858
|
connection: { setupKey: "okta" },
|
|
660
859
|
provisionMembers: true,
|
|
661
|
-
defaultRole: "
|
|
860
|
+
defaultRole: "organization_member"
|
|
662
861
|
}
|
|
663
862
|
],
|
|
664
863
|
applicationConsent: "ask"
|
|
@@ -685,8 +884,9 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
685
884
|
Organization SSO declaration of the same package or `{ providerId }` of a
|
|
686
885
|
pinned dependency; the manifest stores `{ fqn }` or `{ providerId }`.
|
|
687
886
|
Credentials arrive only through `connection: { setupKey }`.
|
|
688
|
-
`provisionMembers` and `defaultRole` (`organization_admin
|
|
689
|
-
`
|
|
887
|
+
`provisionMembers` and `defaultRole` (`organization_admin`,
|
|
888
|
+
`organization_operator`, or `organization_member`) are required. Retired roles
|
|
889
|
+
such as `organization_user` and Tenant roles are rejected by manifest admission. `applicationConsent` is `ask` or `skip`.
|
|
690
890
|
- `locale` holds `defaultLanguage`, `languages` and `timezone`. `governance`
|
|
691
891
|
holds `accessAuditRetentionMonths` and `maxGroupHierarchyDepth`, positive
|
|
692
892
|
integers. Domain claims, language codes and the depth range are host checks.
|
|
@@ -695,109 +895,133 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
695
895
|
manifest readers reject the same declarations; both use
|
|
696
896
|
`organizationSettingsViolation`.
|
|
697
897
|
|
|
698
|
-
## External application roles
|
|
898
|
+
## External application roles
|
|
699
899
|
|
|
700
|
-
`declareExternalApplication`
|
|
701
|
-
|
|
702
|
-
|
|
900
|
+
`declareExternalApplication` requires `userRoles` and accepts three optional
|
|
901
|
+
access fields: `serverRoles`, `defaultServerRole` and `groupBindings`. A
|
|
902
|
+
further optional field, `applicationConsent`, overrides the Application Consent
|
|
703
903
|
rule of the Organization for this application: `inherit` (the default) follows
|
|
704
904
|
the Organization, `ask` always prompts, `skip` never prompts.
|
|
705
905
|
|
|
706
|
-
The host stores and checks the roles, the Admitted Classes and the
|
|
707
|
-
[Declared Grants](#declared-grants) at install, and shows them to the
|
|
708
|
-
Organization admin. It does not yet read them when a user signs in to the
|
|
709
|
-
application or calls it.
|
|
710
|
-
|
|
711
906
|
```ts
|
|
712
|
-
export const
|
|
907
|
+
export const clinic = declareExternalApplication({
|
|
713
908
|
definition: {
|
|
714
909
|
// ...applicationType, audience, redirectUris, scopes, lifecycle
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
910
|
+
userRoles: [
|
|
911
|
+
{
|
|
912
|
+
key: "doctor",
|
|
913
|
+
platformPermissions: ["knowledge:read", "knowledge:manage"],
|
|
914
|
+
appPermissions: ["appointments:book"],
|
|
915
|
+
users: { create: true },
|
|
916
|
+
assignRoles: ["patient"],
|
|
917
|
+
visibility: "user"
|
|
918
|
+
},
|
|
919
|
+
{
|
|
920
|
+
key: "patient",
|
|
921
|
+
platformPermissions: [],
|
|
922
|
+
visibility: "declared",
|
|
923
|
+
bindings: {
|
|
924
|
+
knowledge: {
|
|
925
|
+
schemas: [
|
|
926
|
+
{ fqn: "acme.clinic.schemas.appointment", policy: "own-rows" }
|
|
927
|
+
]
|
|
928
|
+
},
|
|
929
|
+
agents: ["acme.clinic.agents.booking"]
|
|
930
|
+
}
|
|
931
|
+
},
|
|
932
|
+
{
|
|
933
|
+
key: "anonymous",
|
|
934
|
+
platformPermissions: [],
|
|
935
|
+
visibility: "declared",
|
|
936
|
+
bindings: { agents: ["acme.clinic.agents.booking"] }
|
|
937
|
+
}
|
|
938
|
+
],
|
|
939
|
+
serverRoles: [
|
|
940
|
+
{
|
|
941
|
+
key: "server",
|
|
942
|
+
platformPermissions: ["knowledge:read"],
|
|
943
|
+
users: { create: true },
|
|
944
|
+
assignRoles: ["patient"],
|
|
945
|
+
bindings: { workflows: "all" }
|
|
946
|
+
}
|
|
947
|
+
],
|
|
948
|
+
defaultServerRole: "server",
|
|
949
|
+
groupBindings: [
|
|
950
|
+
{
|
|
951
|
+
group: doctorsGroup,
|
|
952
|
+
role: "doctor",
|
|
953
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
954
|
+
}
|
|
720
955
|
]
|
|
721
956
|
},
|
|
722
|
-
manifest: { fqn: "acme.
|
|
723
|
-
presentation: { displayName: "
|
|
957
|
+
manifest: { fqn: "acme.clinic.application", version: "1.0.0" },
|
|
958
|
+
presentation: { displayName: "Clinic" }
|
|
724
959
|
})
|
|
725
960
|
```
|
|
726
961
|
|
|
727
|
-
-
|
|
728
|
-
`parent`,
|
|
962
|
+
- Every role has `key`, `platformPermissions`, and the optional fields
|
|
963
|
+
`parent`, `appPermissions`, `users: { create }`, `assignRoles` and
|
|
964
|
+
`replaces` (`ExternalApplicationRoleBase`).
|
|
965
|
+
- A User Role (`ExternalApplicationUserRole`) has `visibility`. `"user"`
|
|
966
|
+
(User Visibility) shows the resources that CI grants to the user; such a
|
|
967
|
+
role declares no `bindings`. `"declared"` (Declared Visibility) shows the
|
|
968
|
+
optional `bindings` of the role.
|
|
969
|
+
- A Server Role (`ExternalApplicationServerRole`) is the role of a call that
|
|
970
|
+
the application server makes. It has the optional `bindings`. When
|
|
971
|
+
`serverRoles` is not empty, `defaultServerRole` is required and names one of
|
|
972
|
+
them; the host uses it when a server call names no role.
|
|
973
|
+
- `bindings` is an `ExternalApplicationDeclaredBindings`: `knowledge.schemas`
|
|
974
|
+
and `knowledge.domains` list `{ fqn, policy? }` targets; `agents`, `skills`,
|
|
975
|
+
`workflows` and `documents` list FQNs. Each kind is `"all"` or a list; an
|
|
976
|
+
omitted kind binds nothing. The SDK checks the shape only; the host resolves
|
|
977
|
+
the FQNs.
|
|
729
978
|
- A `key` matches `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, holds at most 64
|
|
730
|
-
characters, and is declared one time
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
979
|
+
characters, and is declared one time among the User Roles and the Server
|
|
980
|
+
Roles of the application. A role keyed `anonymous` is a User Role with
|
|
981
|
+
Declared Visibility.
|
|
982
|
+
- A Platform Permission is a `resource:action` string. A resource may be
|
|
983
|
+
namespaced, as in `ai:catalog:read`. Each colon-separated segment starts with
|
|
984
|
+
a lowercase letter and contains only lowercase letters, digits or underscores;
|
|
985
|
+
empty segments are invalid. The SDK checks syntax only: `a:b:c` is valid
|
|
986
|
+
syntax, but the backend rejects permissions outside its known catalog.
|
|
987
|
+
App Permissions are strings that the application defines.
|
|
988
|
+
- `parent` is the key of another declared role of the same kind. A parent role
|
|
989
|
+
holds every Platform Permission and App Permission of each of its children,
|
|
990
|
+
and a role is not its own ancestor.
|
|
991
|
+
- `assignRoles` lists keys of User Roles of the same application that a holder
|
|
992
|
+
of the role can assign. `users.create` lets a holder create users.
|
|
737
993
|
- `replaces` is the key of a role that an earlier release declared and this
|
|
738
994
|
release removed. It cannot be a key of this release, and two roles cannot
|
|
739
995
|
replace the same key.
|
|
740
|
-
-
|
|
741
|
-
`
|
|
742
|
-
|
|
743
|
-
|
|
996
|
+
- The helper infers the declared keys, so TypeScript rejects a `parent`, an
|
|
997
|
+
`assignRoles` entry, a `defaultServerRole` or a Group Role Binding `role`
|
|
998
|
+
that is not a declared key of the right kind; the manifest stores plain
|
|
999
|
+
strings.
|
|
744
1000
|
- `declareExternalApplication` throws a `TypeError` for each violation and
|
|
745
1001
|
manifest readers reject the same declarations; both use
|
|
746
|
-
`externalApplicationViolation`.
|
|
747
|
-
|
|
748
|
-
## Declared Grants
|
|
1002
|
+
`externalApplicationViolation`. A violation message starts with the field
|
|
1003
|
+
path, for example `userRoles[1].parent:`.
|
|
749
1004
|
|
|
750
|
-
|
|
751
|
-
Declared Grant: one Organization Group holds one role of the application. A
|
|
752
|
-
package declares Grants only on its own external application; there is no
|
|
753
|
-
separate Grant declaration.
|
|
1005
|
+
## Group Role Bindings
|
|
754
1006
|
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
// ...applicationType, audience, redirectUris, scopes, lifecycle
|
|
759
|
-
roles: [
|
|
760
|
-
{ key: "manager", permissions: ["knowledge:read", "knowledge:manage"] },
|
|
761
|
-
{ key: "rep", parent: "manager", permissions: ["knowledge:read"] }
|
|
762
|
-
],
|
|
763
|
-
grants: [
|
|
764
|
-
{
|
|
765
|
-
group: salesGroup,
|
|
766
|
-
role: "rep",
|
|
767
|
-
lifecycle: { deployMode: "init_only", readonly: false }
|
|
768
|
-
},
|
|
769
|
-
{
|
|
770
|
-
group: "acme.directory.groups.sales.managers",
|
|
771
|
-
role: "manager",
|
|
772
|
-
lifecycle: { deployMode: "upsert", readonly: true }
|
|
773
|
-
}
|
|
774
|
-
]
|
|
775
|
-
},
|
|
776
|
-
manifest: { fqn: "acme.portal.application", version: "2.0.0" },
|
|
777
|
-
presentation: { displayName: "Partner portal" }
|
|
778
|
-
})
|
|
779
|
-
```
|
|
1007
|
+
`groupBindings` lists Group Role Bindings: the members of one Organization
|
|
1008
|
+
Group hold one User Role of the application. A package declares bindings only
|
|
1009
|
+
on its own external application.
|
|
780
1010
|
|
|
781
1011
|
- `group` is a `DeclarationReference<"organizationGroup">`: the handle that
|
|
782
1012
|
`declareOrganizationGroup` returns for a root Group of the same package, or
|
|
783
1013
|
the FQN string of any Group. Use the FQN string for a subgroup and for a
|
|
784
1014
|
Group that another package declares. TypeScript rejects a handle of another
|
|
785
1015
|
primitive kind. The manifest stores the FQN string in an
|
|
786
|
-
`
|
|
787
|
-
- The SDK does not check that the Group exists
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
lifecycle of the application. An item with no `deployMode` or no `readonly`
|
|
795
|
-
is rejected.
|
|
1016
|
+
`ExternalApplicationGroupBinding` item.
|
|
1017
|
+
- The SDK does not check that the Group exists; the host does.
|
|
1018
|
+
- `role` is the key of a User Role of the same declaration.
|
|
1019
|
+
- `coverage` is `"inherited"` (the default when omitted: members of subgroups
|
|
1020
|
+
also hold the role) or `"direct"` (members of the Group only).
|
|
1021
|
+
- `lifecycle` is a required `LifecycleOptions` of the binding, separate from
|
|
1022
|
+
the lifecycle of the application. An item with no `deployMode` or no
|
|
1023
|
+
`readonly` is rejected.
|
|
796
1024
|
- Two items cannot name the same Group and the same role.
|
|
797
|
-
- `declareExternalApplication` throws a `TypeError` for each violation and
|
|
798
|
-
manifest readers reject the same declarations. Both use
|
|
799
|
-
`externalApplicationViolation` for the Group, the role and the repeated
|
|
800
|
-
pair.
|
|
801
1025
|
|
|
802
1026
|
## Package Variables
|
|
803
1027
|
|
|
@@ -872,8 +1096,9 @@ export default declarePackage({
|
|
|
872
1096
|
- A handle never fits `fqn`, `version`, `kind`, a reference to another
|
|
873
1097
|
component by FQN (`templateFqn`, `schemaFqn`, ...), `lifecycle` or a schema
|
|
874
1098
|
projection (`VaryingExcludedKey`); manifest readers reject a marker there
|
|
875
|
-
with its path. The access model of an External Application (`
|
|
876
|
-
`
|
|
1099
|
+
with its path. The access model of an External Application (`userRoles`,
|
|
1100
|
+
`serverRoles`, `defaultServerRole`, `groupBindings`) and the `provider` of
|
|
1101
|
+
an SSO entry keep their shape.
|
|
877
1102
|
- Manifest readers admit the marker in every other definition value and keep
|
|
878
1103
|
it; cross-field rules that need the value run after substitution. The host
|
|
879
1104
|
owns substitution; `isVariableReference(value)` recognizes a marker and
|
|
@@ -1249,6 +1474,84 @@ specialized package. The common package deliberately does not export
|
|
|
1249
1474
|
`PackageTool`, `PackageRuntimeContext`, `defineCapability`,
|
|
1250
1475
|
`PackageFieldDefinition`, or `PackageWorkflowField`.
|
|
1251
1476
|
|
|
1477
|
+
### Declared connection instances
|
|
1478
|
+
|
|
1479
|
+
`declareConnectionInstance` provisions an Organization connection from an existing
|
|
1480
|
+
connection template. It uses the same `lifecycle` options as connector instances:
|
|
1481
|
+
`upsert` reconciles the package-owned resource, while `init_only` initializes it.
|
|
1482
|
+
The declaration FQN identifies the connection across deployments. Credentials use
|
|
1483
|
+
existing package variables; keep secret values outside release manifests.
|
|
1484
|
+
|
|
1485
|
+
```ts
|
|
1486
|
+
import {
|
|
1487
|
+
declareConnectionInstance,
|
|
1488
|
+
declareKnowledgeConnectorInstance,
|
|
1489
|
+
declarePackage,
|
|
1490
|
+
packageVariables
|
|
1491
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
1492
|
+
|
|
1493
|
+
const variables = { notionToken: { type: "secret" } } as const
|
|
1494
|
+
const vars = packageVariables(variables)
|
|
1495
|
+
const templateFqn =
|
|
1496
|
+
"builtin.integrations.notion.connections.internal-integration-token"
|
|
1497
|
+
const connectionInstanceFqn = "acme.connections.notion"
|
|
1498
|
+
const lifecycle = { deployMode: "upsert", readonly: false } as const
|
|
1499
|
+
|
|
1500
|
+
const notionConnection = declareConnectionInstance({
|
|
1501
|
+
manifest: { fqn: connectionInstanceFqn, version: "1.0.0" },
|
|
1502
|
+
presentation: { displayName: "Company Notion" },
|
|
1503
|
+
definition: {
|
|
1504
|
+
templateFqn,
|
|
1505
|
+
lifecycle,
|
|
1506
|
+
credentials: { integrationToken: vars.notionToken }
|
|
1507
|
+
}
|
|
1508
|
+
})
|
|
1509
|
+
const notionConnector = declareKnowledgeConnectorInstance({
|
|
1510
|
+
manifest: { fqn: "acme.connectors.notion", version: "1.0.0" },
|
|
1511
|
+
presentation: { displayName: "Company Notion content" },
|
|
1512
|
+
definition: {
|
|
1513
|
+
templateFqn: "builtin.integrations.notion.connectors.api",
|
|
1514
|
+
lifecycle,
|
|
1515
|
+
connections: { notion: { connectionInstanceFqn } }
|
|
1516
|
+
}
|
|
1517
|
+
})
|
|
1518
|
+
export default declarePackage({
|
|
1519
|
+
manifest: {
|
|
1520
|
+
fqn: "acme",
|
|
1521
|
+
name: "Acme",
|
|
1522
|
+
version: "1.0.0",
|
|
1523
|
+
dependencies: [{ fqn: "builtin.integrations.notion" }]
|
|
1524
|
+
},
|
|
1525
|
+
variables,
|
|
1526
|
+
components: [notionConnection, notionConnector]
|
|
1527
|
+
})
|
|
1528
|
+
```
|
|
1529
|
+
|
|
1530
|
+
Use the connector template FQN and slot declared by your installed package.
|
|
1531
|
+
A Dataset connector selects the same reference in `definition.connection`.
|
|
1532
|
+
Connector selections accept exactly one of `{ setupKey }` and
|
|
1533
|
+
`{ connectionInstanceFqn }`. Tool and connector template `connectionRefs` can
|
|
1534
|
+
also set `connectionInstanceFqn` beside their required `connectionTemplateFqn`,
|
|
1535
|
+
`slot`, and `label`. The selected instance must use that exact template.
|
|
1536
|
+
FQNs and lifecycle remain static; they cannot be package-variable references.
|
|
1537
|
+
|
|
1538
|
+
Supply the secret through the existing deploy inputs:
|
|
1539
|
+
|
|
1540
|
+
```json
|
|
1541
|
+
{
|
|
1542
|
+
"variables": {
|
|
1543
|
+
"notionToken": { "link": "NOTION_INTEGRATION_TOKEN" }
|
|
1544
|
+
}
|
|
1545
|
+
}
|
|
1546
|
+
```
|
|
1547
|
+
|
|
1548
|
+
Declared connection references do not require an additional manual connection
|
|
1549
|
+
setup slot. A `secret` variable has no default. A missing linked Organization
|
|
1550
|
+
secret is created pending; fill its value through Organization variables before
|
|
1551
|
+
using the connection. Pending credentials stop provider calls. The Host validates
|
|
1552
|
+
template eligibility, credential fields, and secret references before provisioning.
|
|
1553
|
+
References may target this package or its declared dependencies.
|
|
1554
|
+
|
|
1252
1555
|
### Connections and connectors
|
|
1253
1556
|
|
|
1254
1557
|
`PackageConnection` implementations own advertised `test` and `discover`
|
|
@@ -1523,7 +1826,13 @@ then read it with `parseStoredExtensionReleaseManifest`, which maps each retired
|
|
|
1523
1826
|
kind (for example `tool_collection`) to its current spelling. The same read maps
|
|
1524
1827
|
the Organization Team names of earlier releases to Organization Group names: the
|
|
1525
1828
|
Agent audience key `organizationTeams`, and the managed projection names such as
|
|
1526
|
-
`directory_team`.
|
|
1829
|
+
`directory_team`. Historical Entity Relation Field cardinalities map `one` to
|
|
1830
|
+
`many_to_one` and `many` to `many_to_many`, preserving unbounded reverse sharing.
|
|
1831
|
+
The stored reader removes a valid redundant `maxItems` from legacy scalar `one`;
|
|
1832
|
+
list limits and all other relation settings remain intact. Malformed values still
|
|
1833
|
+
fail declaration validation. This conversion creates a read projection: retained
|
|
1834
|
+
release JSON, archive bytes and their provenance remain unchanged and must be
|
|
1835
|
+
verified before conversion.
|
|
1527
1836
|
`withCurrentPrimitiveKinds` applies the same mapping to stored JSON without
|
|
1528
1837
|
parsing it. `parseExtensionReleaseManifest` and `parsePackageManifest` accept
|
|
1529
1838
|
only the current spelling.
|
|
@@ -2015,3 +2324,34 @@ Add these settings to the existing schema declaration's `definition` object:
|
|
|
2015
2324
|
}
|
|
2016
2325
|
}
|
|
2017
2326
|
```
|
|
2327
|
+
|
|
2328
|
+
### Per-source run data access
|
|
2329
|
+
|
|
2330
|
+
`declareAgent`, `declareSkill`, and `declareWorkflow` accept optional
|
|
2331
|
+
`definition.dataAccess`. Its optional `knowledge`, `datasets`, and `documents`
|
|
2332
|
+
entries select `"user"` or the declaration's own kind (`"agent"`, `"skill"`, or
|
|
2333
|
+
`"workflow"`). The exported `DataAccess<Own>` type describes this portable
|
|
2334
|
+
contract. For example, an Agent can declare:
|
|
2335
|
+
|
|
2336
|
+
```ts
|
|
2337
|
+
import type { DataAccess } from "@collective-intelligence/extensions-sdk"
|
|
2338
|
+
|
|
2339
|
+
const dataAccess = {
|
|
2340
|
+
knowledge: "user",
|
|
2341
|
+
documents: "agent"
|
|
2342
|
+
} satisfies DataAccess<"agent">
|
|
2343
|
+
```
|
|
2344
|
+
|
|
2345
|
+
An omitted object or entry means the runtime's own kind. `user` selects the
|
|
2346
|
+
visibility of the identity the run acts for. The own-kind setting selects its
|
|
2347
|
+
configured resources, still limited by their own bindings. Each source is
|
|
2348
|
+
independent; the setting grants no additional tool or resource bindings.
|
|
2349
|
+
|
|
2350
|
+
Workflow declarations copy this setting into `definition.definition.dataAccess`
|
|
2351
|
+
(the portable authored graph) and retain it at `definition.dataAccess`. A
|
|
2352
|
+
setting supplied only on the graph is also accepted. When both locations are
|
|
2353
|
+
supplied, they must agree for every source after omitted entries default to
|
|
2354
|
+
`workflow`; conflicts are rejected. Canonical package manifests preserve these
|
|
2355
|
+
settings and reject unknown sources or another runtime's kind. These SDK checks
|
|
2356
|
+
validate declarations; the Host implements runtime authorization and per-step
|
|
2357
|
+
rechecks.
|
|
@@ -3,6 +3,7 @@ import type { PackageSchemaProjection } from "../schema/projection.js";
|
|
|
3
3
|
import type { PackageCodecSource } from "../schema/source.js";
|
|
4
4
|
import type { ComponentManifest, ComponentPresentation, DeclarationReference, DeclaredComponent } from "./authoring-core.js";
|
|
5
5
|
import type { PackagePrimitiveBase } from "./base.js";
|
|
6
|
+
import type { DataAccess } from "./data-access.js";
|
|
6
7
|
import type { LifecycleOptions } from "./lifecycle.js";
|
|
7
8
|
/** Idle activation sources. Each stays off unless declared `true`. */
|
|
8
9
|
export type AgentActivityPolicy = Readonly<{
|
|
@@ -95,6 +96,7 @@ export type AgentModelTier = (typeof agentModelTiers)[number];
|
|
|
95
96
|
* `skills` and own `tools` are FQN references resolved at install.
|
|
96
97
|
*/
|
|
97
98
|
export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
|
|
99
|
+
dataAccess?: DataAccess<"agent">;
|
|
98
100
|
activity?: AgentActivityPolicy;
|
|
99
101
|
audience?: AgentAudienceDeclaration;
|
|
100
102
|
behavioralBoundaries: readonly string[];
|
|
@@ -119,6 +121,7 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
|
|
|
119
121
|
}>;
|
|
120
122
|
/** Portable governed Skill held by Agents and loaded on demand. */
|
|
121
123
|
export type SkillDeclaration = PackagePrimitiveBase<"skill"> & Readonly<{
|
|
124
|
+
dataAccess?: DataAccess<"skill">;
|
|
122
125
|
instructions: string;
|
|
123
126
|
lifecycle: LifecycleOptions;
|
|
124
127
|
tools: DeclaredToolBindings;
|
|
@@ -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" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
|
|
3
|
+
export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "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;
|
|
@@ -17,6 +17,7 @@ export type ConnectionReference = Readonly<{
|
|
|
17
17
|
* `PackageRuntimeContext.connectionCatalogIds[slot]`.
|
|
18
18
|
*/
|
|
19
19
|
catalogCollection?: string;
|
|
20
|
+
connectionInstanceFqn?: string;
|
|
20
21
|
connectionTemplateFqn: string;
|
|
21
22
|
label: string;
|
|
22
23
|
required?: boolean;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { JsonValue } from "../foundation/json.js";
|
|
2
|
+
import type { PackagePrimitiveBase } from "./base.js";
|
|
3
|
+
import type { LifecycleOptions } from "./lifecycle.js";
|
|
4
|
+
/** An organization connection provisioned with the package lifecycle. */
|
|
5
|
+
export type ConnectionInstanceDeclaration = PackagePrimitiveBase<"connectionInstance"> & Readonly<{
|
|
6
|
+
templateFqn: string;
|
|
7
|
+
lifecycle: LifecycleOptions;
|
|
8
|
+
credentials: Readonly<Record<string, JsonValue>>;
|
|
9
|
+
}>;
|