@collective-intelligence/extensions-sdk 0.1.5 → 0.1.7

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.
@@ -7,6 +7,7 @@ import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolD
7
7
  import type { WorkflowFieldDeclaration, WorkflowNodeDeclaration } from "../components/workflows.js";
8
8
  import type { HostedContributionDeclaration } from "../hosted/contributions.js";
9
9
  import type { PackageManifest } from "./manifest.js";
10
+ import type { PackageVariablesDeclaration } from "./variables.js";
10
11
  export type DeclaredPackageComponent = ClassDeclaredComponent<DatasetParserDeclaration, new () => DatasetParserImplementation> | ClassDeclaredComponent<ExternalDatasetProviderDeclaration, new () => ExternalDatasetProviderImplementation> | ClassDeclaredComponent<ManagedDatasetProviderDeclaration, new () => ManagedDatasetProviderImplementation> | ClassDeclaredComponent<OrganizationSsoDeclaration, new () => OrganizationSsoImplementation> | ClassDeclaredComponent<EmailProviderDeclaration, new () => EmailProviderImplementation> | ClassDeclaredComponent<OutboundMessagingProviderDeclaration, new () => OutboundMessagingProviderImplementation> | ClassDeclaredComponent<ToolDeclaration, ToolImplementationConstructor> | ClassDeclaredComponent<ConnectionDeclaration, new () => ConnectionImplementation<unknown>> | ClassDeclaredComponent<DocumentsConnectorDeclaration, new () => DocumentsConnectorImplementation> | ClassDeclaredComponent<KnowledgeConnectorDeclaration, new () => KnowledgeConnectorImplementation> | ClassDeclaredComponent<KnowledgeConnectorOAuthDeclaration, new () => KnowledgeConnectorOAuthImplementation> | ClassDeclaredComponent<WorkflowNodeDeclaration, WorkflowNodeImplementationConstructor> | ClassDeclaredComponent<WorkflowFieldDeclaration, new () => ErasedWorkflowFieldImplementation> | ClassDeclaredComponent<EventListenerDeclaration, new () => EventListenerImplementation> | ClassDeclaredComponent<KnowledgeEntityAdapterDeclaration, new () => KnowledgeEntityAdapterImplementation> | ClassDeclaredComponent<KnowledgeRelationAdapterDeclaration, new () => KnowledgeRelationAdapterImplementation> | ClassDeclaredComponent<FieldTransformerDeclaration, new () => FieldTransformerImplementation> | ClassDeclaredComponent<NotificationChannelDeclaration, new () => NotificationChannelImplementation> | ClassDeclaredComponent<ToolSettingsOptionsDeclaration, new () => ToolSettingsOptionsImplementation> | DeclaredComponent<MetadataComponentManifest>;
11
12
  /** Backwards-compatible name for the discriminated package component union. */
12
13
  export type PackageComponent = DeclaredPackageComponent;
@@ -22,10 +23,12 @@ export type PackageDefinition = Readonly<{
22
23
  export type NormalizedPackageDefinition = PackageDefinition & Readonly<{
23
24
  hostedContributions: readonly HostedContributionDeclaration[];
24
25
  }>;
25
- export type PackageManifestInput = Omit<DeclaredPackageManifest, "apiVersion" | "hostedContributions" | "primitives">;
26
+ export type PackageManifestInput = Omit<DeclaredPackageManifest, "apiVersion" | "hostedContributions" | "primitives" | "variables">;
26
27
  /** Assembles a portable package manifest while retaining component runtimes locally. */
27
28
  export declare const declarePackage: (input: Readonly<{
28
29
  components: readonly DeclaredPackageComponent[];
29
30
  hostedContributions?: readonly HostedContributionDeclaration[];
30
31
  manifest: PackageManifestInput;
32
+ /** The Package Variables whose handles the components reference. */
33
+ variables?: PackageVariablesDeclaration;
31
34
  }>) => NormalizedPackageDefinition;
@@ -1,5 +1,6 @@
1
1
  import type { PackagePrimitiveDeclaration } from "../components/declaration.js";
2
2
  import type { HostedContributionManifest } from "../hosted/contributions.js";
3
+ import type { PackageVariablesDeclaration } from "./variables.js";
3
4
  export declare const PackageManifestVersion: "v4";
4
5
  /** Declarative post-install flow; artifact refs are package-owned FQNs. */
5
6
  export type InstallationWizard = Readonly<{
@@ -38,5 +39,7 @@ export type PackageManifest = Readonly<{
38
39
  tags?: readonly string[];
39
40
  tenantMandatory?: boolean;
40
41
  tenantStandard?: boolean;
42
+ /** The Package Variables that Variable References inside primitives name. */
43
+ variables?: PackageVariablesDeclaration;
41
44
  version: string;
42
45
  }>;
@@ -6,6 +6,7 @@ import type * as D from "../components/declaration.js";
6
6
  import type * as Ext from "../components/external-application.js";
7
7
  import type * as K from "../components/knowledge.js";
8
8
  import type * as Og from "../components/organization-group.js";
9
+ import type * as Os from "../components/organization-settings.js";
9
10
  import type * as S from "../components/studio.js";
10
11
  import type * as T from "../components/tools.js";
11
12
  import type * as W from "../components/workflows.js";
@@ -218,28 +219,7 @@ export declare const primitives: {
218
219
  webhookRegistration?: "listener";
219
220
  }> & import("../index.js").JsonObject>;
220
221
  externalAppGateway: ReadValue<import("../index.js").ExternalAppGatewayDeclaration>;
221
- externalApplication: ReadValue<Readonly<{
222
- description?: string;
223
- displayName: string;
224
- fqn: string;
225
- icon?: string;
226
- kind: "externalApplication";
227
- tags?: readonly string[];
228
- version: string;
229
- }> & Readonly<{
230
- admits?: readonly Ext.ExternalApplicationUserClass[];
231
- allowedOrigins: readonly string[];
232
- applicationType: Ext.ExternalApplicationType;
233
- audience: string;
234
- grants?: readonly Ext.ExternalApplicationGrant[];
235
- lifecycle: import("../index.js").LifecycleOptions;
236
- postLogoutRedirectUris: readonly string[];
237
- primaryRedirectUri?: string;
238
- redirectUris: readonly string[];
239
- roles?: readonly Ext.ExternalApplicationRole[];
240
- scopes: readonly string[];
241
- setupInstructions?: string;
242
- }> & import("../index.js").JsonObject>;
222
+ externalApplication: ReadValue<Ext.ExternalApplicationDeclaration>;
243
223
  externalDatasetProvider: ReadValue<Readonly<{
244
224
  description?: string;
245
225
  displayName: string;
@@ -473,6 +453,7 @@ export declare const primitives: {
473
453
  parent?: string;
474
454
  subgroups?: readonly Og.OrganizationSubgroup[];
475
455
  }> & import("../index.js").JsonObject>;
456
+ organizationSettings: ReadValue<Os.OrganizationSettingsDeclaration>;
476
457
  organizationSso: ReadValue<Readonly<{
477
458
  description?: string;
478
459
  displayName: string;
@@ -1,6 +1,7 @@
1
1
  import type { JsonObject, JsonValue } from "../foundation/json.js";
2
2
  import type * as F from "../schema/forms.js";
3
3
  import type { JsonSchemaDocument, PackageSchemaProjection } from "../schema/projection.js";
4
+ import type { Varying, VaryingDefinition, InnerVaryingDefinition, VaryingStructure } from "./variables.js";
4
5
  export type ReadValue<A> = (value: unknown, path: string) => A;
5
6
  export type Fields<A> = {
6
7
  readonly [K in keyof A]-?: ReadValue<A[K]>;
@@ -19,6 +20,25 @@ export declare const literal: <const A extends string | number>(...values: reado
19
20
  export declare const array: <A>(read: ReadValue<A>) => ReadValue<readonly A[]>;
20
21
  export declare const record: <A>(read: ReadValue<A>) => ReadValue<Readonly<Record<string, A>>>;
21
22
  export declare const object: <A extends object>(fields: Fields<A>) => ReadValue<A & JsonObject>;
23
+ /** Admits a Variable Reference where the definition names a value. */
24
+ export declare const varying: <A>(read: ReadValue<A>) => ReadValue<Varying<A>>;
25
+ /** Admits a Variable Reference where the definition names a structured value. */
26
+ export declare const varyingStructure: <A>(read: ReadValue<A>) => ReadValue<VaryingStructure<A>>;
27
+ export declare const varyingArray: <A>(read: ReadValue<A>) => ReadValue<readonly Varying<A>[]>;
28
+ export declare const varyingStrings: ReadValue<readonly Varying<string>[]>;
29
+ /**
30
+ * Field readers whose values outside the excluded keys admit a Variable
31
+ * Reference. Callers never pass a schema reader, so projections keep their
32
+ * shape.
33
+ */
34
+ export declare const varyingFields: <A extends object>(fields: Fields<InnerVaryingDefinition<A>>) => Fields<VaryingDefinition<A>>;
35
+ export declare const varyingObject: <A extends object>(fields: Fields<InnerVaryingDefinition<A>>) => ReadValue<VaryingDefinition<A> & JsonObject>;
36
+ /**
37
+ * A primitive reader that admits Variable References where the declaration
38
+ * names a value. The host substitutes every reference before a typed read
39
+ * (ARC-003), so the manifest type keeps the declared values.
40
+ */
41
+ export declare const substituted: <A extends Authored, Authored>(read: ReadValue<Authored>) => ReadValue<A>;
22
42
  /** Rejects a structurally valid value that breaks a cross-field rule. */
23
43
  export declare const refine: <A>(read: ReadValue<A>, violation: (value: A) => string | undefined) => ReadValue<A>;
24
44
  export declare const strings: ReadValue<readonly string[]>;
@@ -0,0 +1,100 @@
1
+ import type { KnowledgeConnectorBindingExtraConfig, KnowledgeConnectorFieldMapRule } from "../components/connectors.js";
2
+ import type { KnowledgePolicyBody } from "../components/knowledge.js";
3
+ import type { JsonPrimitive, JsonValue } from "../foundation/json.js";
4
+ import type { PortableFormDefinition } from "../schema/forms.js";
5
+ import type { PackageSchemaProjection } from "../schema/projection.js";
6
+ export declare const packageVariableTypes: readonly ["string", "number", "boolean", "string[]", "json", "secret"];
7
+ export type PackageVariableType = (typeof packageVariableTypes)[number];
8
+ type PackageVariableValues = Readonly<{
9
+ boolean: boolean;
10
+ json: JsonValue;
11
+ number: number;
12
+ secret: string;
13
+ string: string;
14
+ "string[]": readonly string[];
15
+ }>;
16
+ /** The value a Package Variable of `Type` holds once the host resolves it. */
17
+ export type PackageVariableValue<Type extends PackageVariableType> = PackageVariableValues[Type];
18
+ type DefaultableVariableType = Exclude<PackageVariableType, "secret">;
19
+ /**
20
+ * One Package Variable: a `default` makes it optional and enters the manifest;
21
+ * no `default` means required. A `secret` has no default.
22
+ */
23
+ export type PackageVariableDeclaration = Readonly<{
24
+ default?: never;
25
+ description?: string;
26
+ type: "secret";
27
+ }> | {
28
+ [Type in DefaultableVariableType]: Readonly<{
29
+ default?: PackageVariableValue<Type>;
30
+ description?: string;
31
+ type: Type;
32
+ }>;
33
+ }[DefaultableVariableType];
34
+ export type PackageVariablesDeclaration = Readonly<Record<string, PackageVariableDeclaration>>;
35
+ /** The JSON marker that stands in for a value inside a component definition. */
36
+ export type VariableReference = Readonly<{
37
+ $variable: string;
38
+ }>;
39
+ declare const variableValue: unique symbol;
40
+ /**
41
+ * The handle `packageVariables` returns: the marker itself, typed by the
42
+ * declared variable type so a handle fits only a field of that type.
43
+ */
44
+ export type PackageVariable<Value> = VariableReference & Readonly<{
45
+ [variableValue]?: Value;
46
+ }>;
47
+ /** The declared variable type that a leaf value accepts: literals widen. */
48
+ type Widened<Value> = Value extends string ? string : Value extends number ? number : Value extends boolean ? boolean : never;
49
+ /**
50
+ * A definition value or a handle of a Package Variable of the same type. A
51
+ * `string` handle fits a string literal field; the strict reader checks the
52
+ * literal after substitution.
53
+ */
54
+ export type Varying<Value> = Value | PackageVariable<Value> | ([Widened<Value>] extends [never] ? never : PackageVariable<Widened<Value>>);
55
+ /** A structured value or the handle of a `json` variable that replaces it. */
56
+ export type VaryingStructure<Value> = Value | PackageVariable<JsonValue>;
57
+ /**
58
+ * Keys that never hold a Variable Reference: identity, references to other
59
+ * components by FQN and lifecycle. Schema projections are excluded by type.
60
+ */
61
+ export type VaryingExcludedKey = "fqn" | "kind" | "lifecycle" | "version" | `${string}Fqn`;
62
+ /** Structural values whose inside keeps the declared shape. */
63
+ type VaryingAtom = KnowledgeConnectorBindingExtraConfig | KnowledgeConnectorFieldMapRule | KnowledgePolicyBody | PackageSchemaProjection | PortableFormDefinition;
64
+ type Nullish<Value> = Extract<Value, null | undefined>;
65
+ type Present<Value> = Exclude<Value, null | undefined>;
66
+ /**
67
+ * A value as `varyingFields` reads it before it admits a marker at the top:
68
+ * leaves keep their type, arrays and objects vary inside.
69
+ */
70
+ export type InnerVarying<Value> = [Present<Value>] extends [VaryingAtom] ? Value : [Present<Value>] extends [JsonPrimitive] ? Value : [Present<Value>] extends [readonly (infer Item)[]] ? Nullish<Value> | readonly VaryingValue<Item>[] : [Present<Value>] extends [object] ? Nullish<Value> | VaryingDefinition<Present<Value>> : Value;
71
+ /**
72
+ * A definition value and the handles that fit it: a typed handle for a leaf
73
+ * or a list of leaves, a `json` handle for a structured value.
74
+ */
75
+ export type VaryingValue<Value> = [Present<Value>] extends [VaryingAtom] ? Value : [Present<Value>] extends [JsonPrimitive] ? Varying<Value> : [Present<Value>] extends [readonly (infer Item)[]] ? Nullish<Value> | ([Item] extends [JsonPrimitive] ? Varying<readonly Varying<Item>[]> : VaryingStructure<readonly VaryingValue<Item>[]>) : [Present<Value>] extends [object] ? Nullish<Value> | VaryingStructure<VaryingDefinition<Present<Value>>> : Varying<Value>;
76
+ /**
77
+ * A component definition whose values outside the exclusions may be a Package
78
+ * Variable handle, at any depth.
79
+ */
80
+ export type VaryingDefinition<Definition> = {
81
+ readonly [Key in keyof Definition]: Key extends VaryingExcludedKey ? Definition[Key] : VaryingValue<Definition[Key]>;
82
+ };
83
+ /** `VaryingDefinition` before `varyingFields` adds the top-level markers. */
84
+ export type InnerVaryingDefinition<Definition> = {
85
+ readonly [Key in keyof Definition]: Key extends VaryingExcludedKey ? Definition[Key] : InnerVarying<Definition[Key]>;
86
+ };
87
+ export declare const variableReference: (name: string) => VariableReference;
88
+ export declare const isVariableReference: (value: unknown) => value is VariableReference;
89
+ /** Shared authoring and serialized admission invariant of one variable. */
90
+ export declare const packageVariableViolation: (name: string, declaration: Readonly<{
91
+ default?: JsonValue;
92
+ type: PackageVariableType;
93
+ }>) => string | undefined;
94
+ export declare const assertPackageVariables: (declaration: PackageVariablesDeclaration) => void;
95
+ export type PackageVariables<Declaration extends PackageVariablesDeclaration> = {
96
+ readonly [Name in keyof Declaration]: PackageVariable<PackageVariableValue<Declaration[Name]["type"]>>;
97
+ };
98
+ /** One typed handle per declared variable; each serializes as its marker. */
99
+ export declare const packageVariables: <const Declaration extends PackageVariablesDeclaration>(declaration: Declaration) => PackageVariables<Declaration>;
100
+ export {};
@@ -1,6 +1,16 @@
1
1
  import type { BackendExecutionLane, ExtensionHost, FrontendCatalogContract, FrontendCatalogExportName } from "../hosted/contributions.js";
2
2
  import type { PackageManifest } from "../package/manifest.js";
3
3
  export declare const ExtensionReleaseManifestVersion: "v2";
4
+ /** The largest Package Media file a release carries, checked at build, admission and apply. */
5
+ export declare const PACKAGE_MEDIA_SIZE_LIMIT_BYTES: number;
6
+ /** The archive directory of Package Media; a branding `media/<file>` maps to `artifacts/media/<file>`. */
7
+ export declare const PackageMediaArchivePrefix: "artifacts/media/";
8
+ /** One Package Media file of a release: an image an Organization Settings branding key references. */
9
+ export type ExtensionReleaseMedia = Readonly<{
10
+ digest: string;
11
+ path: string;
12
+ size: number;
13
+ }>;
4
14
  export type ExtensionReleaseAsset = Readonly<{
5
15
  digest: string;
6
16
  host: ExtensionHost;
@@ -33,6 +43,8 @@ export type ExtensionReleaseManifest = Readonly<{
33
43
  assets: readonly ExtensionReleaseAsset[];
34
44
  compatibility: Readonly<Record<string, string>>;
35
45
  contributions: readonly ExtensionReleaseContribution[];
46
+ /** Package Media files, sorted by path; absent when the release carries none. */
47
+ media?: readonly ExtensionReleaseMedia[];
36
48
  package: Readonly<{
37
49
  fqn: string;
38
50
  version: string;
@@ -1,4 +1,5 @@
1
1
  export declare const assertArchivePath: (path: string) => void;
2
+ /** Runtime assets live under a Host directory; Package Media is one file directly under `artifacts/media/`. */
2
3
  export declare const assertRuntimeAssetPath: (path: string) => void;
3
4
  /** Reserved immutable declarations entry; never a runtime-loadable asset. */
4
5
  export declare const PackageManifestArchivePath: "package-manifest.json";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/extensions-sdk",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "Framework-neutral authoring contracts for Collective Intelligence extension packages.",
5
5
  "type": "module",
6
6
  "sideEffects": false,