@microsoft/app-manifest 1.0.4-alpha.3344620f2.0 → 1.0.4-alpha.3446e1b60.0

package/build/wrappers/TeamsManifestWrapper.js

@@ -0,0 +1,709 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamsManifestWrapper = exports.ComposeExtensionTypeEnum = exports.ConfigurableTabScope = exports.StaticTabScope = exports.DefaultInstallScope = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const strip_bom_1 = __importDefault(require("strip-bom"));
+const generated_types_1 = require("../generated-types");
+/**
+ * Default install scope enum for Teams manifests.
+ */
+exports.DefaultInstallScope = {
+    personal: "personal",
+    team: "team",
+    groupChat: "groupChat",
+    meetings: "meetings",
+    copilot: "copilot",
+};
+/**
+ * Static tab scope enum for Teams manifests.
+ */
+exports.StaticTabScope = {
+    personal: "personal",
+    team: "team",
+    groupChat: "groupChat",
+};
+/**
+ * Configurable tab scope enum for Teams manifests.
+ */
+exports.ConfigurableTabScope = {
+    team: "team",
+    groupChat: "groupChat",
+};
+/**
+ * Compose extension type enum for Teams manifests.
+ */
+exports.ComposeExtensionTypeEnum = {
+    botBased: "botBased",
+    apiBased: "apiBased",
+};
+/**
+ * OOP wrapper for Teams App Manifest.
+ *
+ * Provides a fluent API for manipulating Teams app manifests with
+ * type safety, state tracking, and convenient operations.
+ *
+ * Note: This class does not extend BaseManifest due to TeamsManifest union type
+ * constraints, but provides the same interface and functionality.
+ *
+ * @example
+ * ```typescript
+ * // Read existing manifest
+ * const manifest = await TeamsManifestWrapper.read("manifest.json");
+ *
+ * // Modify with fluent API
+ * manifest
+ *   .setName("My App", "My Full App Name")
+ *   .setDescription("Short desc", "Full description")
+ *   .addBot("bot-id", ["personal", "team"])
+ *   .addStaticTab("home", "Home", "https://example.com/tab")
+ *   .addDeclarativeAgent("agent1", "declarativeAgent.json");
+ *
+ * // Save changes
+ * await manifest.save();
+ * ```
+ */
+class TeamsManifestWrapper {
+    constructor(data, filePath) {
+        this._isDirty = false;
+        this._data = data;
+        this._filePath = filePath;
+    }
+    // ============= Base Manifest Properties =============
+    /**
+     * Returns the raw manifest data.
+     */
+    get data() {
+        return this._data;
+    }
+    /**
+     * Returns the file path if the manifest was loaded from a file.
+     */
+    get filePath() {
+        return this._filePath;
+    }
+    /**
+     * Indicates whether the manifest has unsaved changes.
+     */
+    get isDirty() {
+        return this._isDirty;
+    }
+    /**
+     * Marks the manifest as having unsaved changes.
+     */
+    markDirty() {
+        this._isDirty = true;
+    }
+    /**
+     * Saves the manifest to the specified file path or the original file path.
+     * @param filePath - Optional path to save to. If not provided, uses the original file path.
+     * @throws Error if no file path is available.
+     */
+    async save(filePath) {
+        const targetPath = filePath !== null && filePath !== void 0 ? filePath : this._filePath;
+        if (!targetPath) {
+            throw new Error("No file path specified for saving.");
+        }
+        await fs_extra_1.default.writeFile(targetPath, this.toJSON(), "utf-8");
+        this._filePath = targetPath;
+        this._isDirty = false;
+    }
+    // ============= Static Factory Methods =============
+    /**
+     * Reads a JSON file synchronously and returns the parsed object.
+     * @param filePath - Path to the JSON file
+     */
+    static readJsonFileSync(filePath) {
+        const content = fs_extra_1.default.readFileSync(filePath, "utf-8");
+        // Strip BOM to handle UTF-8 BOM encoded files
+        const cleanContent = (0, strip_bom_1.default)(content);
+        return JSON.parse(cleanContent);
+    }
+    /**
+     * Reads a Teams manifest from a file.
+     * @param filePath - Path to the manifest JSON file.
+     * @returns A new TeamsManifestWrapper instance.
+     */
+    static async read(filePath) {
+        const data = await generated_types_1.AppManifestUtils.readTeamsManifest(filePath);
+        return new TeamsManifestWrapper(data, filePath);
+    }
+    /**
+     * Reads a Teams manifest from a file synchronously.
+     * @param filePath - Path to the manifest JSON file.
+     * @returns A new TeamsManifestWrapper instance.
+     */
+    static readSync(filePath) {
+        const json = TeamsManifestWrapper.readJsonFileSync(filePath);
+        const data = generated_types_1.TeamsManifestConverter.jsonToManifest(JSON.stringify(json));
+        return new TeamsManifestWrapper(data, filePath);
+    }
+    /**
+     * Creates a TeamsManifestWrapper from a JSON string.
+     * @param json - JSON string representing the manifest.
+     * @returns A new TeamsManifestWrapper instance.
+     */
+    static fromJSON(json) {
+        const data = generated_types_1.TeamsManifestConverter.jsonToManifest(json);
+        return new TeamsManifestWrapper(data);
+    }
+    /**
+     * Creates a new Teams manifest with required fields.
+     * @param init - Initial manifest data with required fields.
+     * @returns A new TeamsManifestWrapper instance.
+     */
+    static create(init) {
+        var _a;
+        const data = {
+            $schema: `https://developer.microsoft.com/en-us/json-schemas/teams/v${init.manifestVersion}/MicrosoftTeams.schema.json`,
+            manifestVersion: init.manifestVersion,
+            id: init.id,
+            version: init.version,
+            name: init.name,
+            description: init.description,
+            developer: init.developer,
+            icons: { color: "color.png", outline: "outline.png" },
+            accentColor: (_a = init.accentColor) !== null && _a !== void 0 ? _a : "#FFFFFF",
+        };
+        return new TeamsManifestWrapper(data);
+    }
+    // ============= Getters =============
+    /**
+     * Returns the manifest version.
+     */
+    get manifestVersion() {
+        return this._data.manifestVersion;
+    }
+    /**
+     * Returns the app ID.
+     */
+    get id() {
+        return this._data.id;
+    }
+    /**
+     * Returns the app version.
+     */
+    get version() {
+        return this._data.version;
+    }
+    /**
+     * Returns the app name.
+     */
+    get name() {
+        return this._data.name;
+    }
+    /**
+     * Returns the app description.
+     */
+    get description() {
+        return this._data.description;
+    }
+    /**
+     * Returns the developer information.
+     */
+    get developer() {
+        return this._data.developer;
+    }
+    /**
+     * Returns the icons configuration.
+     */
+    get icons() {
+        return this._data.icons;
+    }
+    /**
+     * Returns a readonly array of bots.
+     */
+    get bots() {
+        var _a;
+        return (_a = this._data.bots) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns a readonly array of static tabs.
+     */
+    get staticTabs() {
+        var _a;
+        return (_a = this._data.staticTabs) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns a readonly array of configurable tabs.
+     */
+    get configurableTabs() {
+        var _a;
+        return (_a = this._data.configurableTabs) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns a readonly array of compose extensions (message extensions).
+     */
+    get composeExtensions() {
+        var _a;
+        return (_a = this._data.composeExtensions) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns a readonly array of connectors.
+     */
+    get connectors() {
+        var _a;
+        return (_a = this._data.connectors) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns the valid domains.
+     */
+    get validDomains() {
+        var _a;
+        return (_a = this._data.validDomains) !== null && _a !== void 0 ? _a : [];
+    }
+    /**
+     * Returns the web application info for SSO.
+     */
+    get webApplicationInfo() {
+        return this._data.webApplicationInfo;
+    }
+    /**
+     * Returns the copilot agents configuration.
+     */
+    get copilotAgents() {
+        return this._data.copilotAgents;
+    }
+    /**
+     * Returns a readonly array of declarative agents.
+     */
+    get declarativeAgents() {
+        var _a, _b;
+        return (_b = (_a = this._data.copilotAgents) === null || _a === void 0 ? void 0 : _a.declarativeAgents) !== null && _b !== void 0 ? _b : [];
+    }
+    /**
+     * Returns a readonly array of custom engine agents.
+     */
+    get customEngineAgents() {
+        var _a, _b;
+        return (_b = (_a = this._data.copilotAgents) === null || _a === void 0 ? void 0 : _a.customEngineAgents) !== null && _b !== void 0 ? _b : [];
+    }
+    // ============= Setters (Fluent API) =============
+    /**
+     * Sets the app ID.
+     */
+    setId(id) {
+        this._data.id = id;
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the app version.
+     */
+    setVersion(version) {
+        this._data.version = version;
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the app name.
+     */
+    setName(short, full) {
+        this._data.name = { short, full };
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the app description.
+     */
+    setDescription(short, full) {
+        this._data.description = { short, full };
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the developer information.
+     */
+    setDeveloper(developer) {
+        this._data.developer = developer;
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the icons.
+     */
+    setIcons(color, outline) {
+        this._data.icons = { color, outline };
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the accent color.
+     */
+    setAccentColor(color) {
+        this._data.accentColor = color;
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Sets the default install scope.
+     */
+    setDefaultInstallScope(scope) {
+        this._data.defaultInstallScope = scope;
+        this.markDirty();
+        return this;
+    }
+    // ============= Valid Domains Operations =============
+    /**
+     * Adds a valid domain.
+     * @param domain - The domain to add.
+     */
+    addValidDomain(domain) {
+        if (!this._data.validDomains) {
+            this._data.validDomains = [];
+        }
+        if (!this._data.validDomains.includes(domain)) {
+            this._data.validDomains.push(domain);
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Removes a valid domain.
+     * @param domain - The domain to remove.
+     */
+    removeValidDomain(domain) {
+        if (this._data.validDomains) {
+            this._data.validDomains = this._data.validDomains.filter((d) => d !== domain);
+            this.markDirty();
+        }
+        return this;
+    }
+    // ============= Bot Operations =============
+    /**
+     * Adds a bot to the manifest.
+     * @param botId - The Microsoft App ID for the bot.
+     * @param scopes - The scopes for the bot.
+     * @param options - Additional bot configuration options.
+     */
+    addBot(botId, scopes, options) {
+        if (!this._data.bots) {
+            this._data.bots = [];
+        }
+        const existing = this._data.bots.find((b) => b.botId === botId);
+        if (!existing) {
+            this._data.bots.push(Object.assign({ botId,
+                scopes }, options));
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Removes a bot by ID.
+     * @param botId - The bot ID to remove.
+     */
+    removeBot(botId) {
+        if (this._data.bots) {
+            this._data.bots = this._data.bots.filter((b) => b.botId !== botId);
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Checks if a bot exists by ID.
+     */
+    hasBot(botId) {
+        return this.bots.some((b) => b.botId === botId);
+    }
+    /**
+     * Gets a bot by ID.
+     */
+    getBot(botId) {
+        return this.bots.find((b) => b.botId === botId);
+    }
+    // ============= Static Tab Operations =============
+    /**
+     * Adds a static tab to the manifest.
+     * @param entityId - Unique identifier for the tab entity.
+     * @param name - Display name of the tab.
+     * @param contentUrl - URL for the tab content.
+     * @param scopes - The scopes for the tab.
+     */
+    addStaticTab(entityId, name, contentUrl, scopes = ["personal"]) {
+        if (!this._data.staticTabs) {
+            this._data.staticTabs = [];
+        }
+        const existing = this._data.staticTabs.find((t) => t.entityId === entityId);
+        if (!existing) {
+            this._data.staticTabs.push({
+                entityId,
+                name,
+                contentUrl,
+                scopes,
+            });
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Removes a static tab by entity ID.
+     * @param entityId - The entity ID of the tab to remove.
+     */
+    removeStaticTab(entityId) {
+        if (this._data.staticTabs) {
+            this._data.staticTabs = this._data.staticTabs.filter((t) => t.entityId !== entityId);
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Checks if a static tab exists by entity ID.
+     */
+    hasStaticTab(entityId) {
+        return this.staticTabs.some((t) => t.entityId === entityId);
+    }
+    /**
+     * Gets a static tab by entity ID.
+     */
+    getStaticTab(entityId) {
+        return this.staticTabs.find((t) => t.entityId === entityId);
+    }
+    // ============= Configurable Tab Operations =============
+    /**
+     * Adds a configurable tab to the manifest.
+     * @param configurationUrl - URL for the tab configuration.
+     * @param scopes - The scopes for the tab.
+     */
+    addConfigurableTab(configurationUrl, scopes = ["team", "groupChat"]) {
+        if (!this._data.configurableTabs) {
+            this._data.configurableTabs = [];
+        }
+        this._data.configurableTabs.push({
+            configurationUrl,
+            scopes,
+        });
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Removes a configurable tab by configuration URL.
+     * @param configurationUrl - The configuration URL of the tab to remove.
+     */
+    removeConfigurableTab(configurationUrl) {
+        if (this._data.configurableTabs) {
+            this._data.configurableTabs = this._data.configurableTabs.filter((t) => t.configurationUrl !== configurationUrl);
+            this.markDirty();
+        }
+        return this;
+    }
+    // ============= Compose Extension (Message Extension) Operations =============
+    /**
+     * Adds a compose extension to the manifest.
+     * @param extension - The compose extension configuration.
+     */
+    addComposeExtension(extension) {
+        if (!this._data.composeExtensions) {
+            this._data.composeExtensions = [];
+        }
+        this._data.composeExtensions.push(extension);
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Adds a bot-based compose extension.
+     * @param botId - The bot ID for the message extension.
+     * @param commands - The commands for the message extension.
+     */
+    addBotBasedComposeExtension(botId, commands = []) {
+        return this.addComposeExtension({
+            botId,
+            composeExtensionType: "botBased",
+            commands,
+        });
+    }
+    /**
+     * Adds an API-based compose extension.
+     * @param apiSpecificationFile - Path to the API specification file.
+     * @param commands - The commands for the message extension.
+     */
+    addApiBasedComposeExtension(apiSpecificationFile, commands = []) {
+        return this.addComposeExtension({
+            composeExtensionType: "apiBased",
+            apiSpecificationFile,
+            commands,
+        });
+    }
+    /**
+     * Removes a compose extension by bot ID.
+     * @param botId - The bot ID of the compose extension to remove.
+     */
+    removeComposeExtensionByBotId(botId) {
+        if (this._data.composeExtensions) {
+            this._data.composeExtensions = this._data.composeExtensions.filter((ce) => ce.botId !== botId);
+            this.markDirty();
+        }
+        return this;
+    }
+    // ============= Web Application Info (SSO) Operations =============
+    /**
+     * Sets the web application info for SSO.
+     * @param id - The AAD application ID.
+     * @param resource - Optional resource URL for acquiring auth token.
+     */
+    setWebApplicationInfo(id, resource) {
+        this._data.webApplicationInfo = { id, resource };
+        this.markDirty();
+        return this;
+    }
+    /**
+     * Removes the web application info.
+     */
+    removeWebApplicationInfo() {
+        delete this._data.webApplicationInfo;
+        this.markDirty();
+        return this;
+    }
+    // ============= Copilot Agents Operations =============
+    /**
+     * Adds a declarative agent reference.
+     * @param id - Unique identifier for the agent.
+     * @param file - Relative path to the agent manifest file.
+     */
+    addDeclarativeAgent(id, file) {
+        const data = this._data;
+        if (!data.copilotAgents) {
+            data.copilotAgents = {};
+        }
+        if (!data.copilotAgents.declarativeAgents) {
+            data.copilotAgents.declarativeAgents = [];
+        }
+        const existing = data.copilotAgents.declarativeAgents.find((a) => a.id === id);
+        if (!existing) {
+            data.copilotAgents.declarativeAgents.push({ id, file });
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Removes a declarative agent by ID.
+     * @param id - The ID of the agent to remove.
+     */
+    removeDeclarativeAgent(id) {
+        var _a;
+        const data = this._data;
+        if ((_a = data.copilotAgents) === null || _a === void 0 ? void 0 : _a.declarativeAgents) {
+            data.copilotAgents.declarativeAgents = data.copilotAgents.declarativeAgents.filter((a) => a.id !== id);
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Checks if a declarative agent exists by ID.
+     */
+    hasDeclarativeAgent(id) {
+        return this.declarativeAgents.some((a) => a.id === id);
+    }
+    /**
+     * Gets a declarative agent by ID.
+     */
+    getDeclarativeAgent(id) {
+        return this.declarativeAgents.find((a) => a.id === id);
+    }
+    /**
+     * Adds a custom engine agent.
+     * @param id - The bot ID for the custom engine agent.
+     */
+    addCustomEngineAgent(id) {
+        const data = this._data;
+        if (!data.copilotAgents) {
+            data.copilotAgents = {};
+        }
+        if (!data.copilotAgents.customEngineAgents) {
+            data.copilotAgents.customEngineAgents = [];
+        }
+        const existing = data.copilotAgents.customEngineAgents.find((a) => a.id === id);
+        if (!existing) {
+            data.copilotAgents.customEngineAgents.push({ id, type: "bot" });
+            this.markDirty();
+        }
+        return this;
+    }
+    /**
+     * Removes a custom engine agent by ID.
+     * @param id - The ID of the agent to remove.
+     */
+    removeCustomEngineAgent(id) {
+        var _a;
+        const data = this._data;
+        if ((_a = data.copilotAgents) === null || _a === void 0 ? void 0 : _a.customEngineAgents) {
+            data.copilotAgents.customEngineAgents = data.copilotAgents.customEngineAgents.filter((a) => a.id !== id);
+            this.markDirty();
+        }
+        return this;
+    }
+    // ============= Query Operations =============
+    /**
+     * Returns all bot IDs from the manifest.
+     */
+    getBotIds() {
+        return this.bots.map((b) => b.botId);
+    }
+    /**
+     * Returns all static tab entity IDs.
+     */
+    getStaticTabEntityIds() {
+        return this.staticTabs.map((t) => t.entityId);
+    }
+    /**
+     * Returns all declarative agent file paths.
+     */
+    getDeclarativeAgentPaths() {
+        return this.declarativeAgents.map((a) => a.file);
+    }
+    /**
+     * Checks if the manifest has any Copilot agent configuration.
+     */
+    hasCopilotAgents() {
+        return this.declarativeAgents.length > 0 || this.customEngineAgents.length > 0;
+    }
+    // ============= Validation =============
+    /**
+     * Validates the manifest against its JSON schema.
+     * @returns Array of validation error messages, empty if valid.
+     */
+    async validate() {
+        return generated_types_1.AppManifestUtils.validateAgainstSchema(this._data);
+    }
+    // ============= Serialization =============
+    /**
+     * Converts the manifest to a formatted JSON string.
+     */
+    toJSON() {
+        return generated_types_1.TeamsManifestConverter.manifestToJson(this._data);
+    }
+    /**
+     * Creates a deep clone of this manifest.
+     */
+    clone() {
+        const clonedData = JSON.parse(this.toJSON());
+        return new TeamsManifestWrapper(clonedData);
+    }
+    /**
+     * Creates a deep clone with partial modifications applied.
+     * Useful for creating a modified copy without mutating the original.
+     * @param changes - Partial manifest data to merge into the clone.
+     * @returns A new TeamsManifestWrapper with the changes applied.
+     */
+    cloneWith(changes) {
+        const clonedData = JSON.parse(this.toJSON());
+        Object.assign(clonedData, changes);
+        const wrapper = new TeamsManifestWrapper(clonedData);
+        wrapper.markDirty();
+        return wrapper;
+    }
+    /**
+     * Returns a mutable reference to the manifest data for direct modification.
+     * Use with caution - prefer using the fluent API methods when possible.
+     * Changes made through this reference will be tracked as dirty.
+     */
+    get mutableData() {
+        this.markDirty();
+        return this._data;
+    }
+}
+exports.TeamsManifestWrapper = TeamsManifestWrapper;
+//# sourceMappingURL=TeamsManifestWrapper.js.map