@trackunit/iris-app-api 2.13.2 → 2.13.7-alpha-563d99d17d6.0

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/CHANGELOG.md CHANGED
@@ -1,33 +1,3 @@
1
- ## 2.13.2 (2026-11-04)
2
-
3
- This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
4
-
5
- ## 2.13.1 (2026-11-03)
6
-
7
- This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
8
-
9
- ## 2.13.0 (2026-11-03)
10
-
11
- ### 🚀 Features
12
-
13
- - **iris-app-api:** add organization.manage scope to vocabulary ([e87a78198c6](https://github.com/Trackunit/manager/commit/e87a78198c6))
14
-
15
- ### ❤️ Thank You
16
-
17
- - fhg @FemkeTrackunit
18
-
19
- ## 2.12.28 (2026-11-03)
20
-
21
- This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
22
-
23
- ## 2.12.27 (2026-11-03)
24
-
25
- This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
26
-
27
- ## 2.12.26 (2026-11-03)
28
-
29
- This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
30
-
31
1
  ## 2.12.25 (2026-11-02)
32
2
 
33
3
  This was a version bump only for iris-app-api to align it with other projects, there were no code changes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trackunit/iris-app-api",
3
- "version": "2.13.2",
3
+ "version": "2.13.7-alpha-563d99d17d6.0",
4
4
  "license": "SEE LICENSE IN LICENSE.txt",
5
5
  "repository": "https://github.com/Trackunit/manager",
6
6
  "engines": {
package/src/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  export * from "./types/aiNavigableExtension";
2
2
  export * from "./types/defaultValidHosts";
3
3
  export * from "./types/extensions/adminExtensionManifest";
4
+ export * from "./types/extensions/aiToolsExtensionManifest";
4
5
  export * from "./types/extensions/assetEventsActionsExtensionManifest";
5
6
  export * from "./types/extensions/assetHomeExtensionManifest";
6
7
  export * from "./types/extensions/customerHomeExtensionManifest";
@@ -17,6 +18,8 @@ export * from "./types/iconImage";
17
18
  export * from "./types/icons.generated";
18
19
  export * from "./types/irisAiNavigation";
19
20
  export * from "./types/irisAiNavigationValidation";
21
+ export * from "./types/irisAiTools";
22
+ export * from "./types/irisAiToolsValidation";
20
23
  export * from "./types/irisAppCspInput";
21
24
  export * from "./types/irisAppCustomFields";
22
25
  export * from "./types/irisAppExtensionManifest";
package/src/index.js CHANGED
@@ -4,6 +4,7 @@ const tslib_1 = require("tslib");
4
4
  tslib_1.__exportStar(require("./types/aiNavigableExtension"), exports);
5
5
  tslib_1.__exportStar(require("./types/defaultValidHosts"), exports);
6
6
  tslib_1.__exportStar(require("./types/extensions/adminExtensionManifest"), exports);
7
+ tslib_1.__exportStar(require("./types/extensions/aiToolsExtensionManifest"), exports);
7
8
  tslib_1.__exportStar(require("./types/extensions/assetEventsActionsExtensionManifest"), exports);
8
9
  tslib_1.__exportStar(require("./types/extensions/assetHomeExtensionManifest"), exports);
9
10
  tslib_1.__exportStar(require("./types/extensions/customerHomeExtensionManifest"), exports);
@@ -20,6 +21,8 @@ tslib_1.__exportStar(require("./types/iconImage"), exports);
20
21
  tslib_1.__exportStar(require("./types/icons.generated"), exports);
21
22
  tslib_1.__exportStar(require("./types/irisAiNavigation"), exports);
22
23
  tslib_1.__exportStar(require("./types/irisAiNavigationValidation"), exports);
24
+ tslib_1.__exportStar(require("./types/irisAiTools"), exports);
25
+ tslib_1.__exportStar(require("./types/irisAiToolsValidation"), exports);
23
26
  tslib_1.__exportStar(require("./types/irisAppCspInput"), exports);
24
27
  tslib_1.__exportStar(require("./types/irisAppCustomFields"), exports);
25
28
  tslib_1.__exportStar(require("./types/irisAppExtensionManifest"), exports);
@@ -0,0 +1,17 @@
1
+ import { IrisExtensionAiTools } from "../irisAiTools";
2
+ import { AbstractExtensionManifest } from "../irisAppExtensionManifest";
3
+ /**
4
+ * Serves the app's AI tools on `POST /mcp`, built with `@trackunit/serverside-ai-tools`.
5
+ * When the app version is approved, the platform makes the tools available to AI clients
6
+ * for accounts that have the app. At most one per app.
7
+ */
8
+ export interface AiToolsExtensionManifest extends AbstractExtensionManifest {
9
+ type: "AI_TOOLS_EXTENSION";
10
+ runtime: "DENO";
11
+ id: string;
12
+ name: string;
13
+ description?: string;
14
+ main: `${string}.ts` | `${string}.js`;
15
+ dependencyDefinitionFile: string;
16
+ aiTools: IrisExtensionAiTools;
17
+ }
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=aiToolsExtensionManifest.js.map
@@ -0,0 +1,32 @@
1
+ /**
2
+ * MCP tool annotation hints. All four are required so the AI assistant never
3
+ * has to guess whether a tool writes, overwrites, can be retried or leaves
4
+ * Trackunit. A tool with `readOnlyHint: false` is shown to the user for approval.
5
+ */
6
+ export type IrisAiToolAnnotations = {
7
+ readonly readOnlyHint: boolean;
8
+ readonly destructiveHint: boolean;
9
+ readonly idempotentHint: boolean;
10
+ readonly openWorldHint: boolean;
11
+ };
12
+ /** A JSON Schema with `type: "object"`, as MCP requires for tool input and output. */
13
+ export type IrisAiToolJsonSchema = Readonly<Record<string, unknown>> & {
14
+ readonly type: "object";
15
+ };
16
+ export type IrisAiTool = {
17
+ /** `verb_noun` in snake_case, e.g. `update_fault_priorities`. */
18
+ readonly name: string;
19
+ readonly title: string;
20
+ readonly description: string;
21
+ readonly inputSchema: IrisAiToolJsonSchema;
22
+ readonly outputSchema?: IrisAiToolJsonSchema;
23
+ readonly annotations: IrisAiToolAnnotations;
24
+ };
25
+ export type IrisExtensionAiTools = {
26
+ /**
27
+ * Kebab-case prefix of the tool names AI clients see (`<namespace>_<tool>`).
28
+ * Must not be reserved or used by another app or service.
29
+ */
30
+ readonly namespace: string;
31
+ readonly tools: ReadonlyArray<IrisAiTool>;
32
+ };
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=irisAiTools.js.map
@@ -0,0 +1,23 @@
1
+ import { IrisAppExtensionType } from "./irisAppExtensionManifest";
2
+ /** Clients see `<namespace>_<tool>`; the MCP Tool Guidelines cap that at 60 characters. */
3
+ export declare const AI_TOOLS_MAX_EXPOSED_NAME_LENGTH = 60;
4
+ export declare const AI_TOOLS_MAX_TOOLS = 50;
5
+ export declare const AI_TOOLS_MAX_TITLE_LENGTH = 80;
6
+ export declare const AI_TOOLS_MAX_DESCRIPTION_LENGTH = 2000;
7
+ /** Keeps the registry entry well below Kafka's default 1 MB message limit. */
8
+ export declare const AI_TOOLS_MAX_DECLARATION_BYTES: number;
9
+ export type AiToolsValidationInput = {
10
+ /** Untrusted at the server choke point: comes from a published manifest. */
11
+ readonly extensions: ReadonlyArray<{
12
+ readonly id: string;
13
+ readonly type: IrisAppExtensionType;
14
+ readonly aiTools: unknown;
15
+ }>;
16
+ };
17
+ /**
18
+ * Structural validation of `aiTools` across a manifest's extensions. Returns
19
+ * human-readable errors; an empty array means valid. Shared by the build
20
+ * (`updateExtensions`) and the server (`manifest-validator.ts`). Whether the
21
+ * namespace is free is checked by the server only.
22
+ */
23
+ export declare const validateIrisAiTools: ({ extensions }: AiToolsValidationInput) => ReadonlyArray<string>;
@@ -0,0 +1,124 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.validateIrisAiTools = exports.AI_TOOLS_MAX_DECLARATION_BYTES = exports.AI_TOOLS_MAX_DESCRIPTION_LENGTH = exports.AI_TOOLS_MAX_TITLE_LENGTH = exports.AI_TOOLS_MAX_TOOLS = exports.AI_TOOLS_MAX_EXPOSED_NAME_LENGTH = void 0;
4
+ /** Clients see `<namespace>_<tool>`; the MCP Tool Guidelines cap that at 60 characters. */
5
+ exports.AI_TOOLS_MAX_EXPOSED_NAME_LENGTH = 60;
6
+ exports.AI_TOOLS_MAX_TOOLS = 50;
7
+ exports.AI_TOOLS_MAX_TITLE_LENGTH = 80;
8
+ exports.AI_TOOLS_MAX_DESCRIPTION_LENGTH = 2000;
9
+ /** Keeps the registry entry well below Kafka's default 1 MB message limit. */
10
+ exports.AI_TOOLS_MAX_DECLARATION_BYTES = 256 * 1024;
11
+ const AI_TOOLS_EXTENSION_TYPE = "AI_TOOLS_EXTENSION";
12
+ const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
13
+ const TOOL_NAME_PATTERN = /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/;
14
+ const ANNOTATION_HINTS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
15
+ const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
16
+ /** UTF-8 size of the JSON form, or `undefined` when the value cannot be serialized. */
17
+ const serializedBytes = (value) => {
18
+ try {
19
+ return new TextEncoder().encode(JSON.stringify(value)).length;
20
+ }
21
+ catch {
22
+ return undefined;
23
+ }
24
+ };
25
+ const TEXT_MAX_LENGTH = { title: exports.AI_TOOLS_MAX_TITLE_LENGTH, description: exports.AI_TOOLS_MAX_DESCRIPTION_LENGTH };
26
+ const validateText = (value, field, label, errors) => {
27
+ if (typeof value !== "string" || value.trim().length === 0) {
28
+ errors.push(`${label}: '${field}' is required and must be a non-empty string.`);
29
+ }
30
+ else if (value.length > TEXT_MAX_LENGTH[field]) {
31
+ errors.push(`${label}: '${field}' must be at most ${TEXT_MAX_LENGTH[field]} characters.`);
32
+ }
33
+ };
34
+ const validateSchema = (value, field, label, errors) => {
35
+ if (!isRecord(value) || value.type !== "object") {
36
+ errors.push(`${label}: '${field}' must be a JSON Schema object with type "object".`);
37
+ }
38
+ };
39
+ const validateAnnotations = (value, label, errors) => {
40
+ if (!isRecord(value)) {
41
+ errors.push(`${label}: 'annotations' is required and must declare ${ANNOTATION_HINTS.join(", ")}.`);
42
+ return;
43
+ }
44
+ ANNOTATION_HINTS.forEach(hint => {
45
+ if (typeof value[hint] !== "boolean") {
46
+ errors.push(`${label}: annotation '${hint}' is required and must be a boolean.`);
47
+ }
48
+ });
49
+ };
50
+ const validateTool = (tool, index, namespace, prefix, errors) => {
51
+ if (!isRecord(tool)) {
52
+ errors.push(`${prefix} tool #${index}: must be an object.`);
53
+ return;
54
+ }
55
+ const label = `${prefix} tool #${index} (${typeof tool.name === "string" ? tool.name : "unknown name"})`;
56
+ if (typeof tool.name !== "string" || !TOOL_NAME_PATTERN.test(tool.name)) {
57
+ errors.push(`${label}: 'name' must be verb_noun in snake_case, e.g. 'update_fault_priorities'.`);
58
+ }
59
+ else if (namespace.length + 1 + tool.name.length > exports.AI_TOOLS_MAX_EXPOSED_NAME_LENGTH) {
60
+ errors.push(`${label}: '${namespace}_${tool.name}' must be at most ${exports.AI_TOOLS_MAX_EXPOSED_NAME_LENGTH} characters.`);
61
+ }
62
+ validateText(tool.title, "title", label, errors);
63
+ validateText(tool.description, "description", label, errors);
64
+ validateSchema(tool.inputSchema, "inputSchema", label, errors);
65
+ if (tool.outputSchema !== undefined) {
66
+ validateSchema(tool.outputSchema, "outputSchema", label, errors);
67
+ }
68
+ validateAnnotations(tool.annotations, label, errors);
69
+ };
70
+ const validateExtensionAiTools = (extensionId, aiTools, errors) => {
71
+ const prefix = `aiTools (extension '${extensionId}')`;
72
+ if (!isRecord(aiTools)) {
73
+ errors.push(`${prefix}: must be an object.`);
74
+ return;
75
+ }
76
+ const bytes = serializedBytes(aiTools);
77
+ if (bytes === undefined) {
78
+ errors.push(`${prefix}: must be serializable.`);
79
+ return;
80
+ }
81
+ if (bytes > exports.AI_TOOLS_MAX_DECLARATION_BYTES) {
82
+ errors.push(`${prefix}: must be at most ${exports.AI_TOOLS_MAX_DECLARATION_BYTES} bytes as JSON, found ${bytes}.`);
83
+ return;
84
+ }
85
+ const { namespace, tools } = aiTools;
86
+ const validNamespace = typeof namespace === "string" && NAMESPACE_PATTERN.test(namespace);
87
+ if (!validNamespace) {
88
+ errors.push(`${prefix}: 'namespace' must be kebab-case (lowercase letters, digits, single dashes).`);
89
+ }
90
+ if (!Array.isArray(tools) || tools.length === 0) {
91
+ errors.push(`${prefix}: 'tools' must declare at least one tool.`);
92
+ return;
93
+ }
94
+ if (tools.length > exports.AI_TOOLS_MAX_TOOLS) {
95
+ errors.push(`${prefix}: 'tools' must declare at most ${exports.AI_TOOLS_MAX_TOOLS} tools.`);
96
+ return;
97
+ }
98
+ tools.forEach((tool, index) => validateTool(tool, index, validNamespace ? namespace : "", prefix, errors));
99
+ const names = tools.map((tool) => (isRecord(tool) ? tool.name : undefined));
100
+ const duplicates = names.filter((name, index) => typeof name === "string" && names.indexOf(name) !== index);
101
+ if (duplicates.length > 0) {
102
+ errors.push(`${prefix}: duplicate tool names: ${[...new Set(duplicates)].join(", ")}.`);
103
+ }
104
+ };
105
+ /**
106
+ * Structural validation of `aiTools` across a manifest's extensions. Returns
107
+ * human-readable errors; an empty array means valid. Shared by the build
108
+ * (`updateExtensions`) and the server (`manifest-validator.ts`). Whether the
109
+ * namespace is free is checked by the server only.
110
+ */
111
+ const validateIrisAiTools = ({ extensions }) => {
112
+ const aiToolsExtensions = extensions.filter(extension => extension.type === AI_TOOLS_EXTENSION_TYPE);
113
+ const errors = [];
114
+ if (aiToolsExtensions.length > 1) {
115
+ errors.push(`aiTools: at most one ${AI_TOOLS_EXTENSION_TYPE} per app, found ${aiToolsExtensions.map(extension => extension.id).join(", ")}.`);
116
+ }
117
+ extensions
118
+ .filter(extension => extension.type !== AI_TOOLS_EXTENSION_TYPE && extension.aiTools !== undefined)
119
+ .forEach(extension => errors.push(`aiTools (extension '${extension.id}'): only ${AI_TOOLS_EXTENSION_TYPE} may declare aiTools, not '${extension.type}'.`));
120
+ aiToolsExtensions.forEach(extension => validateExtensionAiTools(extension.id, extension.aiTools, errors));
121
+ return errors;
122
+ };
123
+ exports.validateIrisAiTools = validateIrisAiTools;
124
+ //# sourceMappingURL=irisAiToolsValidation.js.map
@@ -1,4 +1,4 @@
1
- export declare const irisAppExtensionTypes: readonly ["REPORT_EXTENSION", "IRIS_APP_SETTINGS_EXTENSION", "ADMIN_EXTENSION", "FLEET_EXTENSION", "WIDGET_EXTENSION", "ASSET_HOME_EXTENSION", "ASSET_EVENTS_ACTIONS_EXTENSION", "CUSTOMER_HOME_EXTENSION", "SITE_HOME_EXTENSION", "LIFECYCLE_EXTENSION", "SERVERSIDE_API_EXTENSION"];
1
+ export declare const irisAppExtensionTypes: readonly ["REPORT_EXTENSION", "IRIS_APP_SETTINGS_EXTENSION", "ADMIN_EXTENSION", "FLEET_EXTENSION", "WIDGET_EXTENSION", "ASSET_HOME_EXTENSION", "ASSET_EVENTS_ACTIONS_EXTENSION", "CUSTOMER_HOME_EXTENSION", "SITE_HOME_EXTENSION", "LIFECYCLE_EXTENSION", "SERVERSIDE_API_EXTENSION", "AI_TOOLS_EXTENSION"];
2
2
  export type IrisAppExtensionType = (typeof irisAppExtensionTypes)[number];
3
3
  export declare const nonUiExtensionTypes: Array<IrisAppExtensionType>;
4
4
  export declare const serverSideExtensionTypes: Array<IrisAppExtensionType>;
@@ -13,15 +13,18 @@ exports.irisAppExtensionTypes = [
13
13
  "SITE_HOME_EXTENSION",
14
14
  "LIFECYCLE_EXTENSION",
15
15
  "SERVERSIDE_API_EXTENSION",
16
+ "AI_TOOLS_EXTENSION",
16
17
  ];
17
18
  exports.nonUiExtensionTypes = [
18
19
  "REPORT_EXTENSION",
19
20
  "LIFECYCLE_EXTENSION",
20
21
  "SERVERSIDE_API_EXTENSION",
22
+ "AI_TOOLS_EXTENSION",
21
23
  ];
22
24
  exports.serverSideExtensionTypes = [
23
25
  "LIFECYCLE_EXTENSION",
24
26
  "SERVERSIDE_API_EXTENSION",
27
+ "AI_TOOLS_EXTENSION",
25
28
  ];
26
29
  exports.languageKeys = [
27
30
  "en",
@@ -1,4 +1,5 @@
1
1
  import { CSPDirectives } from "./cspDirectives";
2
+ import { AiToolsExtensionManifest } from "./extensions/aiToolsExtensionManifest";
2
3
  import { AdminExtensionManifest } from "./extensions/adminExtensionManifest";
3
4
  import { AssetEventsActionsExtensionManifest } from "./extensions/assetEventsActionsExtensionManifest";
4
5
  import { AssetHomeExtensionManifest } from "./extensions/assetHomeExtensionManifest";
@@ -91,7 +92,7 @@ export type RequiredOrOptionalScope = {
91
92
  scope: Scope;
92
93
  optional?: boolean;
93
94
  };
94
- export declare type IrisAppExtension = AssetHomeExtensionManifest | IrisAppSettingsExtensionManifest | AdminExtensionManifest | FleetExtensionManifest | SiteHomeExtensionManifest | WidgetExtensionManifest | ReportExtensionManifest | CustomerHomeExtensionManifest | AssetEventsActionsExtensionManifest | LifecycleExtensionManifest | ServersideApiExtensionManifest;
95
+ export declare type IrisAppExtension = AssetHomeExtensionManifest | IrisAppSettingsExtensionManifest | AdminExtensionManifest | FleetExtensionManifest | SiteHomeExtensionManifest | WidgetExtensionManifest | ReportExtensionManifest | CustomerHomeExtensionManifest | AssetEventsActionsExtensionManifest | LifecycleExtensionManifest | ServersideApiExtensionManifest | AiToolsExtensionManifest;
95
96
  export declare type CustomFieldDefinition = BooleanFieldDefinition | DecimalNumberFieldDefinition | IntegerNumberFieldDefinition | DateFieldDefinition | DropDownFieldDefinition | StringFieldDefinition | StringListFieldDefinition | EmailFieldDefinition | PhoneNumberFieldDefinition | WebAddressFieldDefinition | JsonFieldDefinition | MonetaryFieldDefinition | FileFieldDefinition;
96
97
  /**
97
98
  * @deprecated
@@ -62,7 +62,6 @@ export declare const accountScope: {
62
62
  readonly CONNECTION_VIEW: "connection.view";
63
63
  readonly CONNECTION_MANAGE: "connection.manage";
64
64
  readonly ORGANIZATION_VIEW: "organization.view";
65
- readonly ORGANIZATION_MANAGE: "organization.manage";
66
65
  readonly SSO_VIEW: "sso.view";
67
66
  readonly SSO_MANAGE: "sso.manage";
68
67
  };
@@ -142,7 +141,6 @@ export declare const allScopes: {
142
141
  CONNECTION_VIEW: "connection.view";
143
142
  CONNECTION_MANAGE: "connection.manage";
144
143
  ORGANIZATION_VIEW: "organization.view";
145
- ORGANIZATION_MANAGE: "organization.manage";
146
144
  SSO_VIEW: "sso.view";
147
145
  SSO_MANAGE: "sso.manage";
148
146
  };
@@ -84,7 +84,6 @@ exports.accountScope = {
84
84
  CONNECTION_VIEW: "connection.view",
85
85
  CONNECTION_MANAGE: "connection.manage",
86
86
  ORGANIZATION_VIEW: "organization.view",
87
- ORGANIZATION_MANAGE: "organization.manage",
88
87
  SSO_VIEW: "sso.view",
89
88
  SSO_MANAGE: "sso.manage",
90
89
  };