@collective-intelligence/extensions-sdk 0.1.6 → 0.1.8

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
@@ -498,10 +498,73 @@ export const salesGroup = declareOrganizationGroup({
498
498
  The manifest stores the FQN string. A subgroup has no handle; name it by its
499
499
  FQN string, also inside the same package.
500
500
 
501
+ ## Organization Settings declarations
502
+
503
+ `declareOrganizationSettings` declares the settings of the Organization that
504
+ installs the package, as one primitive of kind `organizationSettings`. A
505
+ package declares at most one, and a package that declares one binds to the
506
+ organization scope only: `declarePackage` rejects a second component of this
507
+ kind and a manifest whose `bindingScopes` includes `tenant`.
508
+
509
+ ```ts
510
+ export const acmeSettings = declareOrganizationSettings({
511
+ definition: {
512
+ identity: { name: "Acme", companyDomains: ["acme.example"] },
513
+ branding: { logo: { media: "media/logo.svg" } },
514
+ authentication: {
515
+ password: { enabled: false },
516
+ otp: { enabled: true, domains: ["acme.example"] },
517
+ sso: [
518
+ {
519
+ provider: oktaSso, // the handle of a same-package Organization SSO
520
+ enabled: true,
521
+ domains: ["acme.example"],
522
+ connection: { setupKey: "okta" },
523
+ provisionMembers: true,
524
+ defaultRole: "organization_user"
525
+ }
526
+ ],
527
+ applicationConsent: "ask"
528
+ },
529
+ locale: { defaultLanguage: "en", languages: ["en", "it"], timezone: "UTC" },
530
+ governance: { accessAuditRetentionMonths: 12, maxGroupHierarchyDepth: 4 },
531
+ lifecycle: { deployMode: "upsert", readonly: true }
532
+ },
533
+ manifest: { fqn: "acme.directory.settings", version: "1.0.0" },
534
+ presentation: { displayName: "Acme organization" }
535
+ })
536
+ ```
537
+
538
+ - Every section and key is optional, and an omitted key leaves the current
539
+ value of the Organization untouched. The declaration needs at least one
540
+ setting. `slug` is not declarable; TypeScript rejects it and the helper
541
+ throws.
542
+ - `identity` holds `name` and `companyDomains`. `branding` holds `logo`,
543
+ `icon` and `cover`, each `{ media: "media/<file>" }`: a Package Media path
544
+ with one file segment, used by one branding key at most.
545
+ - `authentication.password` and `authentication.otp` are local sign-in methods
546
+ with `enabled` and `domains`; an enabled method needs at least one domain.
547
+ `authentication.sso` lists SSO providers: `provider` is the handle of an
548
+ Organization SSO declaration of the same package or `{ providerId }` of a
549
+ pinned dependency; the manifest stores `{ fqn }` or `{ providerId }`.
550
+ Credentials arrive only through `connection: { setupKey }`.
551
+ `provisionMembers` and `defaultRole` (`organization_admin` or
552
+ `organization_user`) are required. `applicationConsent` is `ask` or `skip`.
553
+ - `locale` holds `defaultLanguage`, `languages` and `timezone`. `governance`
554
+ holds `accessAuditRetentionMonths` and `maxGroupHierarchyDepth`, positive
555
+ integers. Domain claims, language codes and the depth range are host checks.
556
+ - `lifecycle` is a required `LifecycleOptions`.
557
+ - `declareOrganizationSettings` throws a `TypeError` for each violation and
558
+ manifest readers reject the same declarations; both use
559
+ `organizationSettingsViolation`.
560
+
501
561
  ## External application roles and Admitted Classes
502
562
 
503
563
  `declareExternalApplication` accepts two optional access fields: `roles`, the
504
- role tree of the application, and `admits`, the Admitted Classes ceiling.
564
+ role tree of the application, and `admits`, the Admitted Classes ceiling. A
565
+ third optional field, `applicationConsent`, overrides the Application Consent
566
+ rule of the Organization for this application: `inherit` (the default) follows
567
+ the Organization, `ask` always prompts, `skip` never prompts.
505
568
 
506
569
  The host stores and checks the roles, the Admitted Classes and the
507
570
  [Declared Grants](#declared-grants) at install, and shows them to the
@@ -599,6 +662,86 @@ export const partnerPortal = declareExternalApplication({
599
662
  `externalApplicationViolation` for the Group, the role and the repeated
600
663
  pair.
601
664
 
665
+ ## Package Variables
666
+
667
+ `packageVariables` declares the values that change between environments and
668
+ returns one typed handle per variable. A handle stands in a component
669
+ definition where a value would; the manifest stores the marker
670
+ `{ "$variable": "<name>" }`, so the release digest is the same in every
671
+ environment and the host substitutes the value at deployment.
672
+
673
+ ```ts
674
+ import {
675
+ declareKnowledgeConnectorInstance,
676
+ declarePackage,
677
+ packageVariables,
678
+ type PackageVariablesDeclaration
679
+ } from "@collective-intelligence/extensions-sdk"
680
+
681
+ const variables = {
682
+ collection: {
683
+ type: "string",
684
+ default: "customers",
685
+ description: "Remote CRM collection"
686
+ },
687
+ companyDomains: { type: "string[]" },
688
+ crmToken: { type: "secret" }
689
+ } as const satisfies PackageVariablesDeclaration
690
+
691
+ const vars = packageVariables(variables)
692
+
693
+ const customers = declareKnowledgeConnectorInstance({
694
+ definition: {
695
+ entityBindings: [
696
+ {
697
+ key: "customers",
698
+ schemaFqn: "acme.sales.customer",
699
+ bindingMode: "managed",
700
+ remoteCollectionId: vars.collection
701
+ }
702
+ ],
703
+ lifecycle: { deployMode: "upsert", readonly: false },
704
+ templateFqn: "acme.integrations.crm"
705
+ },
706
+ manifest: { fqn: "acme.sales.instances.customers", version: "1.0.0" },
707
+ presentation: { displayName: "CRM customers" }
708
+ })
709
+
710
+ export default declarePackage({
711
+ components: [customers],
712
+ manifest: { fqn: "acme.sales", name: "Sales", version: "1.0.0" },
713
+ variables
714
+ })
715
+ ```
716
+
717
+ - A variable has a `type` of `string`, `number`, `boolean`, `string[]`,
718
+ `json` or `secret`, an optional `description` and an optional `default`. A
719
+ default is part of the manifest; a variable without one is required at
720
+ deployment. A `secret` declares no default; `packageVariables`,
721
+ `declarePackage` and manifest readers reject one, and a default outside its
722
+ type. Both use `packageVariableViolation`.
723
+ - `declarePackage({ variables })` stores the declaration as
724
+ `manifest.variables`, keyed by name. Connection slots are not declared here;
725
+ the host derives them from the `setupKey`s of the components.
726
+ - A handle is a `PackageVariable<T>` where `T` is the value of its type (a
727
+ `secret` is a `string`). `Varying<T>` is a value or a handle of that type;
728
+ the definition inputs of `declareOrganizationSettings`,
729
+ `declareExternalApplication`, `declareKnowledgeConnectorInstance` and
730
+ `declareDatasetConnectorInstance` are typed with `VaryingDefinition`, so a
731
+ `string` handle does not compile on a `number` field or on a list of
732
+ strings, while it fits a string literal field. A `json` handle fits a
733
+ `JsonValue` field or a whole structured value; a `string[]` handle fits a
734
+ list of strings.
735
+ - A handle never fits `fqn`, `version`, `kind`, a reference to another
736
+ component by FQN (`templateFqn`, `schemaFqn`, ...), `lifecycle` or a schema
737
+ projection (`VaryingExcludedKey`); manifest readers reject a marker there
738
+ with its path. The access model of an External Application (`admits`,
739
+ `grants`, `roles`) and the `provider` of an SSO entry keep their shape.
740
+ - Manifest readers admit the marker in every other definition value and keep
741
+ it; cross-field rules that need the value run after substitution. The host
742
+ owns substitution; `isVariableReference(value)` recognizes a marker and
743
+ `variableReference(name)` builds one.
744
+
602
745
  ## Hosted contributions
603
746
 
604
747
  `declarePackage` accepts lazy Backend, Studio, and Dashboard contributions in
@@ -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" | "organizationSso" | "outboundMessagingProvider" | "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" | "organizationSettings" | "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;
@@ -6,8 +6,9 @@ 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
8
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
9
+ import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
9
10
  import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
10
11
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
11
12
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
12
13
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
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;
14
+ 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 | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -1,6 +1,13 @@
1
+ import type { VaryingDefinition } from "../package/variables.js";
1
2
  import type { PackagePrimitiveBase } from "./base.js";
2
3
  import type { LifecycleOptions } from "./lifecycle.js";
3
4
  export type ExternalApplicationType = "confidential" | "public";
5
+ /**
6
+ * Application Consent override of one application: `inherit` follows the
7
+ * Organization rule, `ask` and `skip` fix the consent prompt.
8
+ */
9
+ export type ExternalApplicationConsent = "inherit" | "ask" | "skip";
10
+ export declare const externalApplicationConsents: readonly ["inherit", "ask", "skip"];
4
11
  /** A User Class that an Application can admit. */
5
12
  export type ExternalApplicationUserClass = "internal" | "external";
6
13
  /**
@@ -35,6 +42,7 @@ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalAppli
35
42
  */
36
43
  admits?: readonly ExternalApplicationUserClass[];
37
44
  allowedOrigins: readonly string[];
45
+ applicationConsent?: ExternalApplicationConsent;
38
46
  applicationType: ExternalApplicationType;
39
47
  audience: string;
40
48
  /** The Declared Grants of the application. */
@@ -53,8 +61,12 @@ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalAppli
53
61
  scopes: readonly string[];
54
62
  setupInstructions?: string;
55
63
  }>;
64
+ /** The access model of the application; it keeps its shape. */
65
+ export type ExternalApplicationAccessKey = "admits" | "grants" | "roles";
66
+ /** The declaration as manifest readers admit it, before substitution. */
67
+ export type VaryingExternalApplication = Pick<ExternalApplicationDeclaration, ExternalApplicationAccessKey> & VaryingDefinition<Omit<ExternalApplicationDeclaration, ExternalApplicationAccessKey>>;
56
68
  /**
57
69
  * Shared authoring and serialized admission invariant for callbacks, the role
58
70
  * tree, the Admitted Classes and the Declared Grants.
59
71
  */
60
- export declare const externalApplicationViolation: ({ admits, grants, primaryRedirectUri, redirectUris, roles }: Pick<ExternalApplicationDeclaration, "admits" | "grants" | "primaryRedirectUri" | "redirectUris" | "roles">) => string | undefined;
72
+ export declare const externalApplicationViolation: ({ admits, applicationConsent, grants, primaryRedirectUri, redirectUris, roles }: Pick<VaryingExternalApplication, "admits" | "applicationConsent" | "grants" | "primaryRedirectUri" | "redirectUris" | "roles">) => string | undefined;
@@ -15,6 +15,12 @@ export type KnowledgeFieldSemantics = Readonly<{
15
15
  indexOverview?: boolean;
16
16
  indexed?: boolean;
17
17
  managedProjectionSource?: "organization_group" | "organization_user";
18
+ /**
19
+ * Who may fetch the file of a file field through its Stable Media URL:
20
+ * `public` anyone, `protected` (the default) a reader of the entity,
21
+ * `private` a principal that may manage Knowledge.
22
+ */
23
+ mediaVisibility?: "private" | "protected" | "public";
18
24
  queryGuidance?: string;
19
25
  unique?: boolean;
20
26
  }>;
@@ -1,15 +1,17 @@
1
+ import type { VaryingDefinition, VaryingStructure } from "../package/variables.js";
1
2
  import type { PackageCodecSource, PackageDecoderSource } from "../schema/source.js";
2
- import type { ClassDeclaration, ClassDeclaredComponent, ComponentManifest, ComponentPresentation, DeclarationReference, DeclaredComponent, DecoderSource, MetadataComponentManifest } from "./authoring-core.js";
3
+ import type { ClassDeclaration, ClassDeclaredComponent, ComponentManifest, ComponentPresentation, DeclarationHandle, DeclarationReference, DeclaredComponent, DecoderSource, MetadataComponentManifest } from "./authoring-core.js";
3
4
  import type { DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./catalog.js";
4
5
  import type { KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration } from "./connector-instances.js";
5
6
  import type { DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration } from "./connectors.js";
6
7
  import type { DatasetParserImplementation } from "./dataset-parser.js";
7
8
  import type { ExternalDatasetProviderImplementation, ManagedDatasetProviderImplementation } from "./datasets.js";
8
9
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
9
- import type { ExternalApplicationDeclaration, ExternalApplicationRole } from "./external-application.js";
10
+ import type { ExternalApplicationAccessKey, ExternalApplicationDeclaration, ExternalApplicationRole } from "./external-application.js";
10
11
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
11
12
  import type { LifecycleOptions } from "./lifecycle.js";
12
13
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
14
+ import type { OrganizationSettingsDeclaration, VaryingOrganizationSettingsAuthentication, VaryingOrganizationSettingsSso } from "./organization-settings.js";
13
15
  import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
14
16
  import type { RemoteToolCollectionDeclaration, RemoteToolCollectionDefinition, ToolCollectionDeclaration } from "./tools.js";
15
17
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowNodeCollectionDeclaration, WorkflowTemplateDeclaration, WorkflowTemplateGraphDefinition } from "./workflows.js";
@@ -19,6 +21,11 @@ type MetadataClassDeclaration<Manifest, Definition = MetadataDefinition<Manifest
19
21
  manifest: ComponentManifest;
20
22
  presentation: ComponentPresentation;
21
23
  }>;
24
+ /**
25
+ * The authored definition of a metadata component: its values outside the
26
+ * exclusions may be Package Variable handles (ARC-003).
27
+ */
28
+ type VaryingMetadataDefinition<Manifest> = VaryingDefinition<MetadataDefinition<Manifest>>;
22
29
  export declare const declareDomain: (input: MetadataClassDeclaration<DomainDeclaration>) => DeclaredComponent<DomainDeclaration>;
23
30
  export type ManagedDatasetProviderClassDeclaration<Constructor extends new () => ManagedDatasetProviderImplementation = new () => ManagedDatasetProviderImplementation> = ClassDeclaration<ManagedDatasetProviderDeclaration, Constructor>;
24
31
  export declare const declareManagedDatasetProvider: <Constructor extends new () => ManagedDatasetProviderImplementation>(input: ManagedDatasetProviderClassDeclaration<Constructor>) => ClassDeclaredComponent<ManagedDatasetProviderDeclaration, Constructor>;
@@ -27,7 +34,7 @@ export declare const declareExternalDatasetProvider: <Constructor extends new ()
27
34
  export type DatasetParserClassDeclaration<Constructor extends new () => DatasetParserImplementation = new () => DatasetParserImplementation> = ClassDeclaration<DatasetParserDeclaration, Constructor>;
28
35
  export declare const declareDatasetParser: <Constructor extends new () => DatasetParserImplementation>(input: DatasetParserClassDeclaration<Constructor>) => ClassDeclaredComponent<DatasetParserDeclaration, Constructor>;
29
36
  export declare const declareDomainTemplate: (input: MetadataClassDeclaration<DomainTemplateDeclaration>) => DeclaredComponent<DomainTemplateDeclaration>;
30
- type ExternalApplicationDefinitionInput<Key extends string> = Omit<MetadataDefinition<ExternalApplicationDeclaration>, "grants" | "roles"> & Readonly<{
37
+ type ExternalApplicationDefinitionInput<Key extends string> = VaryingDefinition<Omit<MetadataDefinition<ExternalApplicationDeclaration>, ExternalApplicationAccessKey>> & Pick<ExternalApplicationDeclaration, "admits"> & Readonly<{
31
38
  grants?: readonly Readonly<{
32
39
  group: DeclarationReference<"organizationGroup">;
33
40
  lifecycle: LifecycleOptions;
@@ -46,6 +53,19 @@ type OrganizationGroupDefinitionInput = Omit<MetadataDefinition<OrganizationGrou
46
53
  }>;
47
54
  /** Declares a Group Tree materialized by package install. */
48
55
  export declare const declareOrganizationGroup: (input: MetadataClassDeclaration<OrganizationGroupDeclaration, OrganizationGroupDefinitionInput>) => DeclaredComponent<OrganizationGroupDeclaration>;
56
+ type OrganizationSettingsSsoInput = Omit<VaryingOrganizationSettingsSso, "provider"> & Readonly<{
57
+ provider: DeclarationHandle<"organizationSso"> | VaryingDefinition<Readonly<{
58
+ providerId: string;
59
+ }>>;
60
+ }>;
61
+ type OrganizationSettingsAuthenticationInput = Omit<VaryingOrganizationSettingsAuthentication, "sso"> & Readonly<{
62
+ sso?: VaryingStructure<readonly VaryingStructure<OrganizationSettingsSsoInput>[]>;
63
+ }>;
64
+ type OrganizationSettingsDefinitionInput = VaryingDefinition<Omit<MetadataDefinition<OrganizationSettingsDeclaration>, "authentication">> & Readonly<{
65
+ authentication?: VaryingStructure<OrganizationSettingsAuthenticationInput>;
66
+ }>;
67
+ /** Declares the settings of the Organization that installs the package. */
68
+ export declare const declareOrganizationSettings: (input: MetadataClassDeclaration<OrganizationSettingsDeclaration, OrganizationSettingsDefinitionInput>) => DeclaredComponent<OrganizationSettingsDeclaration>;
49
69
  export declare const declareSkillTemplate: (input: MetadataClassDeclaration<SkillTemplateDeclaration>) => DeclaredComponent<SkillTemplateDeclaration>;
50
70
  type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeEntitySchemaDeclaration>, "schema"> & Readonly<{
51
71
  schema: DecoderSource<Schema>;
@@ -80,6 +100,6 @@ type StudioComponentDefinitionInput<Schema> = Omit<MetadataDefinition<StudioComp
80
100
  propsSchema: DecoderSource<Schema>;
81
101
  }>;
82
102
  export declare const declareStudioComponent: <Schema>(input: MetadataClassDeclaration<StudioComponentDeclaration, StudioComponentDefinitionInput<Schema>>) => DeclaredComponent<StudioComponentDeclaration>;
83
- export declare const declareKnowledgeConnectorInstance: (input: MetadataClassDeclaration<KnowledgeConnectorInstanceDeclaration>) => DeclaredComponent<KnowledgeConnectorInstanceDeclaration>;
84
- export declare const declareDatasetConnectorInstance: (input: MetadataClassDeclaration<DatasetConnectorInstanceDeclaration>) => DeclaredComponent<DatasetConnectorInstanceDeclaration>;
103
+ export declare const declareKnowledgeConnectorInstance: (input: MetadataClassDeclaration<KnowledgeConnectorInstanceDeclaration, VaryingMetadataDefinition<KnowledgeConnectorInstanceDeclaration>>) => DeclaredComponent<KnowledgeConnectorInstanceDeclaration>;
104
+ export declare const declareDatasetConnectorInstance: (input: MetadataClassDeclaration<DatasetConnectorInstanceDeclaration, VaryingMetadataDefinition<DatasetConnectorInstanceDeclaration>>) => DeclaredComponent<DatasetConnectorInstanceDeclaration>;
85
105
  export {};
@@ -0,0 +1,87 @@
1
+ import type { VaryingDefinition, VaryingStructure } from "../package/variables.js";
2
+ import type { PackagePrimitiveBase } from "./base.js";
3
+ import type { LifecycleOptions } from "./lifecycle.js";
4
+ /** A Package Media reference: the `media/<file>` path inside the package. */
5
+ export type OrganizationSettingsMedia = Readonly<{
6
+ media: string;
7
+ }>;
8
+ /** A local sign-in method and the email domains it admits. */
9
+ export type OrganizationSettingsLocalMethod = Readonly<{
10
+ domains?: readonly string[];
11
+ enabled: boolean;
12
+ }>;
13
+ export type OrganizationSettingsSsoRole = "organization_admin" | "organization_user";
14
+ /** One SSO provider of the Organization; credentials arrive through the slot. */
15
+ export type OrganizationSettingsSso = Readonly<{
16
+ connection: Readonly<{
17
+ setupKey: string;
18
+ }>;
19
+ defaultRole: OrganizationSettingsSsoRole;
20
+ domains: readonly string[];
21
+ enabled: boolean;
22
+ /** The FQN of a same-package SSO declaration or a pinned `providerId`. */
23
+ provider: Readonly<{
24
+ fqn: string;
25
+ }> | Readonly<{
26
+ providerId: string;
27
+ }>;
28
+ provisionMembers: boolean;
29
+ }>;
30
+ export type OrganizationSettingsApplicationConsent = "ask" | "skip";
31
+ export type OrganizationSettingsAuthentication = Readonly<{
32
+ applicationConsent?: OrganizationSettingsApplicationConsent;
33
+ otp?: OrganizationSettingsLocalMethod;
34
+ password?: OrganizationSettingsLocalMethod;
35
+ sso?: readonly OrganizationSettingsSso[];
36
+ }>;
37
+ /**
38
+ * Portable Organization Settings. Every section and key is optional; an
39
+ * omitted key leaves the current value of the Organization untouched. `slug`
40
+ * is not declarable.
41
+ */
42
+ export type OrganizationSettingsDeclaration = PackagePrimitiveBase<"organizationSettings"> & Readonly<{
43
+ authentication?: OrganizationSettingsAuthentication;
44
+ branding?: Readonly<{
45
+ cover?: OrganizationSettingsMedia;
46
+ icon?: OrganizationSettingsMedia;
47
+ logo?: OrganizationSettingsMedia;
48
+ }>;
49
+ governance?: Readonly<{
50
+ accessAuditRetentionMonths?: number;
51
+ maxGroupHierarchyDepth?: number;
52
+ }>;
53
+ identity?: Readonly<{
54
+ companyDomains?: readonly string[];
55
+ name?: string;
56
+ }>;
57
+ lifecycle: LifecycleOptions;
58
+ locale?: Readonly<{
59
+ defaultLanguage?: string;
60
+ languages?: readonly string[];
61
+ timezone?: string;
62
+ }>;
63
+ }>;
64
+ /** An SSO entry whose provider reference keeps its shape. */
65
+ export type VaryingOrganizationSettingsSso = VaryingDefinition<Omit<OrganizationSettingsSso, "provider">> & Readonly<{
66
+ provider: Readonly<{
67
+ fqn: string;
68
+ }> | VaryingDefinition<Readonly<{
69
+ providerId: string;
70
+ }>>;
71
+ }>;
72
+ export type VaryingOrganizationSettingsAuthentication = VaryingDefinition<Omit<OrganizationSettingsAuthentication, "sso">> & Readonly<{
73
+ sso?: VaryingStructure<readonly VaryingStructure<VaryingOrganizationSettingsSso>[]>;
74
+ }>;
75
+ /** The declaration as manifest readers admit it, before substitution. */
76
+ export type VaryingOrganizationSettings = VaryingDefinition<Omit<OrganizationSettingsDeclaration, "authentication">> & Readonly<{
77
+ authentication?: VaryingStructure<VaryingOrganizationSettingsAuthentication>;
78
+ }>;
79
+ declare const sections: readonly ["authentication", "branding", "governance", "identity", "locale"];
80
+ type OrganizationSettingsSections = Pick<VaryingOrganizationSettings, (typeof sections)[number]>;
81
+ /**
82
+ * Shared authoring and serialized admission invariant: at least one setting,
83
+ * no `slug`, local methods with domains, media paths and the consent rule. A
84
+ * Variable Reference is checked after substitution.
85
+ */
86
+ export declare const organizationSettingsViolation: (definition: OrganizationSettingsSections) => string | undefined;
87
+ export {};
package/dist/index.d.ts CHANGED
@@ -18,9 +18,11 @@ export { resolveWorkflowNodePorts, WorkflowPortIssueCodes } from "./components/w
18
18
  export type { WorkflowNodePortsContract, WorkflowPortIssue, WorkflowPortIssueCode, WorkflowResolvedPorts } from "./components/workflow-ports.js";
19
19
  export { workflowSchemaAt } from "./components/workflow-schema.js";
20
20
  export type { WorkflowSchemaLocation } from "./components/workflow-schema.js";
21
- export { declareDatasetParser, declareDomain, declareDomainTemplate, declareExternalApplication, declareExternalAppGateway, declareExternalDatasetProvider, declareKnowledgeEntitySchema, declareKnowledgePolicy, declareKnowledgeRelationSchema, declareManagedDatasetProvider, declareOrganizationGroup, declareRemoteToolCollection, declareSkillTemplate, declareStudioApp, declareStudioComponent, declareToolCollection, declareWorkflow, declareWorkflowFieldCollection, declareWorkflowNodeCollection, declareWorkflowTemplate } from "./components/metadata-authoring.js";
21
+ export { declareDatasetParser, declareDomain, declareDomainTemplate, declareExternalApplication, declareExternalAppGateway, declareExternalDatasetProvider, declareKnowledgeEntitySchema, declareKnowledgePolicy, declareKnowledgeRelationSchema, declareManagedDatasetProvider, declareOrganizationGroup, declareOrganizationSettings, declareRemoteToolCollection, declareSkillTemplate, declareStudioApp, declareStudioComponent, declareToolCollection, declareWorkflow, declareWorkflowFieldCollection, declareWorkflowNodeCollection, declareWorkflowTemplate } from "./components/metadata-authoring.js";
22
22
  export { DATASET_TABLE_TEMPLATE_PHYSICAL_CODES, DATASET_TABLE_TEMPLATE_SEMANTIC_ROLES, declareDatasetBlueprint, declareDatasetTableTemplate, rejectUnsupportedDatasetTableTemplate } from "./components/templates.js";
23
23
  export { declarePackage } from "./package/definition.js";
24
+ export { isVariableReference, packageVariables, packageVariableTypes, packageVariableViolation, variableReference } from "./package/variables.js";
25
+ export type { PackageVariable, PackageVariableDeclaration, PackageVariables, PackageVariablesDeclaration, PackageVariableType, PackageVariableValue, VariableReference, Varying, VaryingDefinition, VaryingExcludedKey, VaryingStructure } from "./package/variables.js";
24
26
  export { normalizeNotificationChannelCapabilities } from "./components/notification-channel-capabilities.js";
25
27
  export { renderKnowledgeRemoteReferenceUrl } from "./components/knowledge-remote-reference.js";
26
28
  export { BACKEND_EXECUTION_LANES, declareHostedContribution, FRONTEND_CATALOG_CONTRACT, FRONTEND_CATALOG_EXPORT_NAME, HOSTS } from "./hosted/contributions.js";
@@ -37,17 +39,19 @@ export { canonicalPackageManifest, packageManifestJson } from "./package/canonic
37
39
  export { parsePackageDependencyPins, resolvePackageDependencyOrder } from "./package/dependencies.js";
38
40
  export { PackageManifestVersion } from "./package/manifest.js";
39
41
  export type { InstallationWizard, InstallationWizardStep, PackageDependencyPin, PackageManifest } from "./package/manifest.js";
40
- export { canonicalExtensionReleaseManifest, ExtensionReleaseManifestVersion, parseExtensionReleaseManifest } from "./release/manifest.js";
42
+ export { canonicalExtensionReleaseManifest, ExtensionReleaseManifestVersion, PACKAGE_MEDIA_SIZE_LIMIT_BYTES, PackageMediaArchivePrefix, parseExtensionReleaseManifest } from "./release/manifest.js";
41
43
  export { parseExtensionReleaseArchive, validateExtensionReleaseArchiveMetadata } from "./release/archive.js";
42
44
  export { parseStoredExtensionReleaseManifest, withCurrentPrimitiveKinds } from "./release/stored-manifest.js";
43
- export type { BuildAttemptResult, ExtensionReleaseArchiveEntry, ExtensionReleaseAsset, ExtensionReleaseContribution, ExtensionReleaseManifest, ExtensionReleasePrivateSourceMap } from "./release/manifest.js";
45
+ export type { BuildAttemptResult, ExtensionReleaseArchiveEntry, ExtensionReleaseAsset, ExtensionReleaseContribution, ExtensionReleaseManifest, ExtensionReleaseMedia, ExtensionReleasePrivateSourceMap } from "./release/manifest.js";
44
46
  export type { BindingScope, ConnectionReference, PackagePrimitiveBase, PackagePrimitiveKind } from "./components/base.js";
45
47
  export type { LifecycleDeployMode, LifecycleOptions } from "./components/lifecycle.js";
46
48
  export type { CatalogTags, DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./components/catalog.js";
47
- export { externalApplicationViolation } from "./components/external-application.js";
48
- export type { ExternalApplicationDeclaration, ExternalApplicationGrant, ExternalApplicationRole, ExternalApplicationType, ExternalApplicationUserClass } from "./components/external-application.js";
49
+ export { externalApplicationConsents, externalApplicationViolation } from "./components/external-application.js";
50
+ export type { ExternalApplicationAccessKey, ExternalApplicationConsent, ExternalApplicationDeclaration, ExternalApplicationGrant, ExternalApplicationRole, ExternalApplicationType, ExternalApplicationUserClass, VaryingExternalApplication } from "./components/external-application.js";
49
51
  export { organizationGroupFqnMaxLength, organizationGroupNodes, organizationGroupViolation } from "./components/organization-group.js";
50
52
  export type { OrganizationGroupDeclaration, OrganizationSubgroup } from "./components/organization-group.js";
53
+ export { organizationSettingsViolation } from "./components/organization-settings.js";
54
+ export type { OrganizationSettingsApplicationConsent, OrganizationSettingsAuthentication, OrganizationSettingsDeclaration, OrganizationSettingsLocalMethod, OrganizationSettingsMedia, OrganizationSettingsSso, OrganizationSettingsSsoRole, VaryingOrganizationSettings } from "./components/organization-settings.js";
51
55
  export { declareAgent, declareSkill, duplicateToolBinding, toolBindingDeclaration } from "./components/agents.js";
52
56
  export type { AgentActivityPolicy, AgentAudience, AgentAudienceDeclaration, AgentDeclaration, AgentDefinitionInput, AgentMemberAudience, AgentModelTier, DeclaredToolBindings, KnowledgeScopeSelection, SkillDeclaration, SkillDefinitionInput, ToolBinding, ToolBindingApproval, ToolBindingDeclaration, ToolBindingKnowledgeScope } from "./components/agents.js";
53
57
  export type { DocumentsDeltaCursorExpired, DocumentsDeltaItem, DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrive, DocumentsDrivesPage, DocumentsFolder, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, KnowledgeConnectorContribution, KnowledgeConnectorBindingExtraConfig, KnowledgeConnectorDeclaration, KnowledgeConnectorFieldMapRule, KnowledgeEntitySchemaCapability, KnowledgeConnectorOAuthDeclaration, KnowledgeConnectorOAuthTokens, KnowledgeConnectorRemoteReference, EventListenerDeclaration, EventListenerInternalOccurrence, EventListenerPollRequest, EventListenerPollResult, EventListenerWebhookRequest, KnowledgePredefinedSchedule, ManagedDatasetProviderDeclaration, KnowledgeRelationAdapterDeclaration, KnowledgeRelationSchemaCapability } from "./components/connectors.js";