@microsoft/agents-hosting-storage-cosmos 0.1.49

package/README.md

@@ -0,0 +1,21 @@
+# @microsoft/agents-hosting-storage-cosmos
+
+## Overview
+
+This package allows to configure Azure CosmosDB Storage as the backend for Agents conversation State
+
+## Usage
+
+```ts
+const cosmosDbStorageOptions = {
+  databaseId: process.env.COSMOS_DATABASE_ID || 'agentsDB',
+  containerId: process.env.COSMOS_CONTAINER_ID || 'agentsState',
+  cosmosClientOptions: {
+    endpoint: process.env.COSMOS_ENDPOINT!,
+    key: process.env.COSMOS_KEY!,
+  }
+} as CosmosDbPartitionedStorageOptions
+const cosmosStorage = new CosmosDbPartitionedStorage(cosmosDbStorageOptions)
+const conversationState = new ConversationState(cosmosStorage)
+const userState = new UserState(cosmosStorage)
+```

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/cosmosDbKeyEscape.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provides methods for escaping keys for Cosmos DB.
+ */
+export declare namespace CosmosDbKeyEscape {
+    /**
+     * Escapes a key for use in Cosmos DB.
+     * @param key The key to escape.
+     * @param keySuffix The suffix to append to the key.
+     * @param compatibilityMode Indicates whether compatibility mode is enabled.
+     * @returns The escaped key.
+     */
+    function escapeKey(key: string, keySuffix?: string, compatibilityMode?: boolean): string;
+}

package/dist/src/cosmosDbKeyEscape.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CosmosDbKeyEscape = void 0;
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+const crypto_1 = require("crypto");
+/**
+ * Provides methods for escaping keys for Cosmos DB.
+ */
+var CosmosDbKeyEscape;
+(function (CosmosDbKeyEscape) {
+    const maxKeyLength = 255;
+    const illegalKeys = ['\\', '?', '/', '#', '\t', '\n', '\r', '*'];
+    const illegalKeyCharacterReplacementMap = illegalKeys.reduce((map, c) => {
+        map.set(c, `*${c.charCodeAt(0).toString(16)}`);
+        return map;
+    }, new Map());
+    /**
+     * Escapes a key for use in Cosmos DB.
+     * @param key The key to escape.
+     * @param keySuffix The suffix to append to the key.
+     * @param compatibilityMode Indicates whether compatibility mode is enabled.
+     * @returns The escaped key.
+     */
+    function escapeKey(key, keySuffix, compatibilityMode) {
+        if (!key) {
+            throw new Error("The 'key' parameter is required.");
+        }
+        const keySplitted = key.split('');
+        const firstIllegalCharIndex = keySplitted.findIndex((c) => illegalKeys.some((i) => i === c));
+        if (firstIllegalCharIndex === -1) {
+            return truncateKey(`${key}${keySuffix || ''}`, compatibilityMode);
+        }
+        const sanitizedKey = keySplitted.reduce((result, c) => result + (illegalKeyCharacterReplacementMap.has(c) ? illegalKeyCharacterReplacementMap.get(c) : c), '');
+        return truncateKey(`${sanitizedKey}${keySuffix || ''}`, compatibilityMode);
+    }
+    CosmosDbKeyEscape.escapeKey = escapeKey;
+    function truncateKey(key, truncateKeysForCompatibility) {
+        if (truncateKeysForCompatibility === false) {
+            return key;
+        }
+        if (key.length > maxKeyLength) {
+            key = hashKey(key);
+        }
+        return key;
+    }
+    function hashKey(key) {
+        const hash = (0, crypto_1.createHash)('sha256');
+        hash.update(key);
+        return hash.digest('hex');
+    }
+})(CosmosDbKeyEscape || (exports.CosmosDbKeyEscape = CosmosDbKeyEscape = {}));
+//# sourceMappingURL=cosmosDbKeyEscape.js.map

package/dist/src/cosmosDbKeyEscape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosmosDbKeyEscape.js","sourceRoot":"","sources":["../../src/cosmosDbKeyEscape.ts"],"names":[],"mappings":";;;AAAA,4DAA4D;AAC5D,kCAAkC;AAClC,mCAAmC;AAEnC;;GAEG;AACH,IAAiB,iBAAiB,CAyDjC;AAzDD,WAAiB,iBAAiB;IAChC,MAAM,YAAY,GAAW,GAAG,CAAA;IAChC,MAAM,WAAW,GAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;IACnF,MAAM,iCAAiC,GAAwB,WAAW,CAAC,MAAM,CAC/E,CAAC,GAAwB,EAAE,CAAS,EAAE,EAAE;QACtC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;QAC9C,OAAO,GAAG,CAAA;IACZ,CAAC,EACD,IAAI,GAAG,EAAE,CACV,CAAA;IAED;;;;;;OAMG;IACH,SAAgB,SAAS,CAAE,GAAW,EAAE,SAAkB,EAAE,iBAA2B;QACrF,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QACrD,CAAC;QAED,MAAM,WAAW,GAAa,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAC3C,MAAM,qBAAqB,GAAW,WAAW,CAAC,SAAS,CAAC,CAAC,CAAS,EAAW,EAAE,CACjF,WAAW,CAAC,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CACzC,CAAA;QAED,IAAI,qBAAqB,KAAK,CAAC,CAAC,EAAE,CAAC;YACjC,OAAO,WAAW,CAAC,GAAG,GAAG,GAAG,SAAS,IAAI,EAAE,EAAE,EAAE,iBAAiB,CAAC,CAAA;QACnE,CAAC;QAED,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CACrC,CAAC,MAAc,EAAE,CAAS,EAAE,EAAE,CAC5B,MAAM,GAAG,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iCAAiC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EACrG,EAAE,CACH,CAAA;QAED,OAAO,WAAW,CAAC,GAAG,YAAY,GAAG,SAAS,IAAI,EAAE,EAAE,EAAE,iBAAiB,CAAC,CAAA;IAC5E,CAAC;IArBe,2BAAS,YAqBxB,CAAA;IAED,SAAS,WAAW,CAAE,GAAW,EAAE,4BAAsC;QACvE,IAAI,4BAA4B,KAAK,KAAK,EAAE,CAAC;YAC3C,OAAO,GAAG,CAAA;QACZ,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YAC9B,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QACpB,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,SAAS,OAAO,CAAE,GAAW;QAC3B,MAAM,IAAI,GAAG,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAA;QACjC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;AACH,CAAC,EAzDgB,iBAAiB,iCAAjB,iBAAiB,QAyDjC"}

package/dist/src/cosmosDbPartitionedStorage.d.ts

@@ -0,0 +1,46 @@
+import { CosmosDbPartitionedStorageOptions } from './cosmosDbPartitionedStorageOptions';
+import { Storage, StoreItems } from '@microsoft/agents-hosting';
+export declare class DoOnce<T> {
+    private task;
+    waitFor(key: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Implements storage using Cosmos DB partitioned storage.
+ */
+export declare class CosmosDbPartitionedStorage implements Storage {
+    private readonly cosmosDbStorageOptions;
+    private container;
+    private client;
+    private compatibilityModePartitionKey;
+    [key: string]: any;
+    length: number;
+    /**
+     * Initializes a new instance of the CosmosDbPartitionedStorage class.
+     * @param cosmosDbStorageOptions The options for configuring Cosmos DB partitioned storage.
+     */
+    constructor(cosmosDbStorageOptions: CosmosDbPartitionedStorageOptions);
+    /**
+     * Reads items from storage.
+     * @param keys The keys of the items to read.
+     * @returns A promise that resolves to the read items.
+     */
+    read(keys: string[]): Promise<StoreItems>;
+    /**
+     * Writes items to storage.
+     * @param changes The items to write.
+     */
+    write(changes: StoreItems): Promise<void>;
+    /**
+     * Deletes items from storage.
+     * @param keys The keys of the items to delete.
+     */
+    delete(keys: string[]): Promise<void>;
+    /**
+     * Initializes the Cosmos DB container.
+     */
+    initialize(): Promise<void>;
+    private getOrCreateContainer;
+    private getPartitionKey;
+    private checkForNestingError;
+    private throwInformativeError;
+}

package/dist/src/cosmosDbPartitionedStorage.js

@@ -0,0 +1,252 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CosmosDbPartitionedStorage = exports.DoOnce = void 0;
+const cosmos_1 = require("@azure/cosmos");
+const cosmosDbKeyEscape_1 = require("./cosmosDbKeyEscape");
+const documentStoreItem_1 = require("./documentStoreItem");
+class DoOnce {
+    constructor() {
+        this.task = {};
+    }
+    waitFor(key, fn) {
+        if (!this.task[key]) {
+            this.task[key] = fn();
+        }
+        return this.task[key];
+    }
+}
+exports.DoOnce = DoOnce;
+const _doOnce = new DoOnce();
+const maxDepthAllowed = 127;
+/**
+ * Implements storage using Cosmos DB partitioned storage.
+ */
+class CosmosDbPartitionedStorage {
+    /**
+     * Initializes a new instance of the CosmosDbPartitionedStorage class.
+     * @param cosmosDbStorageOptions The options for configuring Cosmos DB partitioned storage.
+     */
+    constructor(cosmosDbStorageOptions) {
+        var _a;
+        this.cosmosDbStorageOptions = cosmosDbStorageOptions;
+        this.compatibilityModePartitionKey = false;
+        this.length = 0;
+        if (!cosmosDbStorageOptions) {
+            throw new ReferenceError('CosmosDbPartitionedStorageOptions is required.');
+        }
+        const { cosmosClientOptions } = cosmosDbStorageOptions;
+        if (!(cosmosClientOptions === null || cosmosClientOptions === void 0 ? void 0 : cosmosClientOptions.endpoint)) {
+            throw new ReferenceError('endpoint in cosmosClientOptions is required.');
+        }
+        if (!(cosmosClientOptions === null || cosmosClientOptions === void 0 ? void 0 : cosmosClientOptions.key) && !(cosmosClientOptions === null || cosmosClientOptions === void 0 ? void 0 : cosmosClientOptions.tokenProvider)) {
+            throw new ReferenceError('key or tokenProvider in cosmosClientOptions is required.');
+        }
+        if (!cosmosDbStorageOptions.databaseId) {
+            throw new ReferenceError('databaseId is for CosmosDB required.');
+        }
+        if (!cosmosDbStorageOptions.containerId) {
+            throw new ReferenceError('containerId for CosmosDB is required.');
+        }
+        (_a = cosmosDbStorageOptions.compatibilityMode) !== null && _a !== void 0 ? _a : (cosmosDbStorageOptions.compatibilityMode = true);
+        if (cosmosDbStorageOptions.keySuffix) {
+            if (cosmosDbStorageOptions.compatibilityMode) {
+                throw new ReferenceError('compatibilityMode cannot be true while using a keySuffix.');
+            }
+            const suffixEscaped = cosmosDbKeyEscape_1.CosmosDbKeyEscape.escapeKey(cosmosDbStorageOptions.keySuffix);
+            if (cosmosDbStorageOptions.keySuffix !== suffixEscaped) {
+                throw new ReferenceError(`Cannot use invalid Row Key characters: ${cosmosDbStorageOptions.keySuffix} in keySuffix`);
+            }
+        }
+    }
+    /**
+     * Reads items from storage.
+     * @param keys The keys of the items to read.
+     * @returns A promise that resolves to the read items.
+     */
+    async read(keys) {
+        if (!keys) {
+            throw new ReferenceError('Keys are required when reading.');
+        }
+        else if (keys.length === 0) {
+            return {};
+        }
+        await this.initialize();
+        const storeItems = {};
+        await Promise.all(keys.map(async (k) => {
+            try {
+                const escapedKey = cosmosDbKeyEscape_1.CosmosDbKeyEscape.escapeKey(k, this.cosmosDbStorageOptions.keySuffix, this.cosmosDbStorageOptions.compatibilityMode);
+                const readItemResponse = await this.container
+                    .item(escapedKey, this.getPartitionKey(escapedKey))
+                    .read();
+                const documentStoreItem = readItemResponse.resource;
+                if (documentStoreItem) {
+                    storeItems[documentStoreItem.realId] = documentStoreItem.document;
+                    storeItems[documentStoreItem.realId].eTag = documentStoreItem._etag;
+                }
+            }
+            catch (err) {
+                if (err.code === 404) {
+                    this.throwInformativeError('Not Found', err);
+                }
+                else if (err.code === 400) {
+                    this.throwInformativeError(`Error reading from container. You might be attempting to read from a non-partitioned
+                    container or a container that does not use '/id' as the partitionKeyPath`, err);
+                }
+                else {
+                    this.throwInformativeError('Error reading from container', err);
+                }
+            }
+        }));
+        return storeItems;
+    }
+    /**
+     * Writes items to storage.
+     * @param changes The items to write.
+     */
+    async write(changes) {
+        if (!changes) {
+            throw new ReferenceError('Changes are required when writing.');
+        }
+        else if (changes.length === 0) {
+            return;
+        }
+        await this.initialize();
+        await Promise.all(Object.entries(changes).map(async ([key, { eTag, ...change }]) => {
+            const document = new documentStoreItem_1.DocumentStoreItem({
+                id: cosmosDbKeyEscape_1.CosmosDbKeyEscape.escapeKey(key, this.cosmosDbStorageOptions.keySuffix, this.cosmosDbStorageOptions.compatibilityMode),
+                realId: key,
+                document: change,
+            });
+            const accessCondition = eTag !== '*' && eTag != null && eTag.length > 0
+                ? { accessCondition: { type: 'IfMatch', condition: eTag } }
+                : undefined;
+            try {
+                await this.container.items.upsert(document, accessCondition);
+            }
+            catch (err) {
+                this.checkForNestingError(change, err);
+                this.throwInformativeError('Error upserting document', err);
+            }
+        }));
+    }
+    /**
+     * Deletes items from storage.
+     * @param keys The keys of the items to delete.
+     */
+    async delete(keys) {
+        await this.initialize();
+        await Promise.all(keys.map(async (k) => {
+            const escapedKey = cosmosDbKeyEscape_1.CosmosDbKeyEscape.escapeKey(k, this.cosmosDbStorageOptions.keySuffix, this.cosmosDbStorageOptions.compatibilityMode);
+            try {
+                await this.container.item(escapedKey, this.getPartitionKey(escapedKey)).delete();
+            }
+            catch (err) {
+                if (err.code === 404) {
+                    this.throwInformativeError('Not Found', err);
+                }
+                else {
+                    this.throwInformativeError('Unable to delete document', err);
+                }
+            }
+        }));
+    }
+    /**
+     * Initializes the Cosmos DB container.
+     */
+    async initialize() {
+        if (!this.container) {
+            if (!this.client) {
+                this.client = new cosmos_1.CosmosClient(this.cosmosDbStorageOptions.cosmosClientOptions);
+            }
+            const dbAndContainerKey = `${this.cosmosDbStorageOptions.databaseId}-${this.cosmosDbStorageOptions.containerId}`;
+            this.container = await _doOnce.waitFor(dbAndContainerKey, async () => await this.getOrCreateContainer());
+        }
+    }
+    async getOrCreateContainer() {
+        let createIfNotExists = !this.cosmosDbStorageOptions.compatibilityMode;
+        let container;
+        try {
+            const { database } = await this.client.databases.createIfNotExists({
+                id: this.cosmosDbStorageOptions.databaseId
+            });
+            if (this.cosmosDbStorageOptions.compatibilityMode) {
+                try {
+                    container = database.container(this.cosmosDbStorageOptions.containerId);
+                    // @ts-ignore
+                    const partitionKeyResponse = await container.readPartitionKeyDefinition();
+                    if (partitionKeyResponse.resource && partitionKeyResponse.resource.paths) {
+                        const paths = partitionKeyResponse.resource.paths;
+                        if (paths.includes('/_partitionKey')) {
+                            this.compatibilityModePartitionKey = true;
+                        }
+                        else if (paths.indexOf(documentStoreItem_1.DocumentStoreItem.partitionKeyPath) === -1) {
+                            throw new Error(`Custom Partition Key Paths are not supported. ${this.cosmosDbStorageOptions.containerId} has a custom Partition Key Path of ${paths[0]}.`);
+                        }
+                    }
+                    else {
+                        this.compatibilityModePartitionKey = true;
+                    }
+                    return container;
+                }
+                catch {
+                    createIfNotExists = true;
+                }
+            }
+            if (createIfNotExists) {
+                const result = await database.containers.createIfNotExists({
+                    id: this.cosmosDbStorageOptions.containerId,
+                    partitionKey: {
+                        paths: [documentStoreItem_1.DocumentStoreItem.partitionKeyPath],
+                    },
+                    throughput: this.cosmosDbStorageOptions.containerThroughput,
+                });
+                return result.container;
+            }
+            if (!container) {
+                throw new Error(`Container ${this.cosmosDbStorageOptions.containerId} not found.`);
+            }
+            return container;
+        }
+        catch (err) {
+            this.throwInformativeError(`Failed to initialize Cosmos DB database/container: ${this.cosmosDbStorageOptions.databaseId}/${this.cosmosDbStorageOptions.containerId}`, err);
+            throw err;
+        }
+    }
+    getPartitionKey(key) {
+        return this.compatibilityModePartitionKey ? undefined : key;
+    }
+    checkForNestingError(json, err) {
+        const checkDepth = (obj, depth, isInDialogState) => {
+            if (depth > maxDepthAllowed) {
+                let message = `Maximum nesting depth of ${maxDepthAllowed} exceeded.`;
+                if (isInDialogState) {
+                    message +=
+                        ' This is most likely caused by recursive component dialogs. ' +
+                            'Try reworking your dialog code to make sure it does not keep dialogs on the stack ' +
+                            "that it's not using. For example, consider using replaceDialog instead of beginDialog.";
+                }
+                else {
+                    message += ' Please check your data for signs of unintended recursion.';
+                }
+                this.throwInformativeError(message, err);
+            }
+            else if (obj && typeof obj === 'object') {
+                for (const [key, value] of Object.entries(obj)) {
+                    checkDepth(value, depth + 1, key === 'dialogStack' || isInDialogState);
+                }
+            }
+        };
+        checkDepth(json, 0, false);
+    }
+    throwInformativeError(prependedMessage, err) {
+        if (typeof err === 'string') {
+            err = new Error(err);
+        }
+        err.message = `[${prependedMessage}] ${err.message}`;
+        throw err;
+    }
+}
+exports.CosmosDbPartitionedStorage = CosmosDbPartitionedStorage;
+//# sourceMappingURL=cosmosDbPartitionedStorage.js.map

package/dist/src/cosmosDbPartitionedStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosmosDbPartitionedStorage.js","sourceRoot":"","sources":["../../src/cosmosDbPartitionedStorage.ts"],"names":[],"mappings":"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"}

package/dist/src/cosmosDbPartitionedStorageOptions.d.ts

@@ -0,0 +1,30 @@
+import { CosmosClientOptions } from '@azure/cosmos';
+/**
+ * Options for configuring Cosmos DB partitioned storage.
+ */
+export interface CosmosDbPartitionedStorageOptions {
+    /**
+     * The ID of the database.
+     */
+    databaseId: string;
+    /**
+     * The ID of the container.
+     */
+    containerId: string;
+    /**
+     * The throughput of the container.
+     */
+    containerThroughput?: number;
+    /**
+     * The suffix to append to keys.
+     */
+    keySuffix?: string;
+    /**
+     * Indicates whether compatibility mode is enabled.
+     */
+    compatibilityMode?: boolean;
+    /**
+     * The options for the Cosmos client.
+     */
+    cosmosClientOptions?: CosmosClientOptions;
+}

package/dist/src/cosmosDbPartitionedStorageOptions.js

@@ -0,0 +1,5 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cosmosDbPartitionedStorageOptions.js.map

package/dist/src/cosmosDbPartitionedStorageOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosmosDbPartitionedStorageOptions.js","sourceRoot":"","sources":["../../src/cosmosDbPartitionedStorageOptions.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC"}

package/dist/src/documentStoreItem.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Represents an item stored in the document store.
+ */
+export declare class DocumentStoreItem {
+    /**
+     * Gets the partition key path.
+     */
+    static get partitionKeyPath(): string;
+    /**
+     * The ID of the document.
+     */
+    id: string;
+    /**
+     * The real ID of the document.
+     */
+    realId: string;
+    /**
+     * The document object.
+     */
+    document: object;
+    /**
+     * The ETag of the document.
+     */
+    eTag: string;
+    /**
+     * Gets the partition key.
+     */
+    get partitionKey(): string;
+    /**
+     * Initializes a new instance of the DocumentStoreItem class.
+     * @param storeItem The store item to initialize.
+     */
+    constructor(storeItem: {
+        id: string;
+        realId: string;
+        document: object;
+        eTag?: string;
+    });
+}

package/dist/src/documentStoreItem.js

@@ -0,0 +1,34 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentStoreItem = void 0;
+/**
+ * Represents an item stored in the document store.
+ */
+class DocumentStoreItem {
+    /**
+     * Gets the partition key path.
+     */
+    static get partitionKeyPath() {
+        return '/id';
+    }
+    /**
+     * Gets the partition key.
+     */
+    get partitionKey() {
+        return this.id;
+    }
+    /**
+     * Initializes a new instance of the DocumentStoreItem class.
+     * @param storeItem The store item to initialize.
+     */
+    constructor(storeItem) {
+        this.id = storeItem.id;
+        this.realId = storeItem.realId || '';
+        this.document = storeItem.document || {};
+        this.eTag = storeItem.eTag || '';
+    }
+}
+exports.DocumentStoreItem = DocumentStoreItem;
+//# sourceMappingURL=documentStoreItem.js.map

package/dist/src/documentStoreItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentStoreItem.js","sourceRoot":"","sources":["../../src/documentStoreItem.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;AAElC;;GAEG;AACH,MAAa,iBAAiB;IAC5B;;OAEG;IACH,MAAM,KAAK,gBAAgB;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAmBD;;OAEG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,EAAE,CAAA;IAChB,CAAC;IAED;;;OAGG;IACH,YAAa,SAA0E;QACrF,IAAI,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,EAAE,CAAA;QACpC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,IAAI,EAAE,CAAA;QACxC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,EAAE,CAAA;IAClC,CAAC;CACF;AA1CD,8CA0CC"}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './cosmosDbPartitionedStorage';
+export * from './cosmosDbPartitionedStorageOptions';

package/dist/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cosmosDbPartitionedStorage"), exports);
+__exportStar(require("./cosmosDbPartitionedStorageOptions"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,4DAA4D;AAC5D,kCAAkC;;;;;;;;;;;;;;;;AAElC,+DAA4C;AAC5C,sEAAmD"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@microsoft/agents-hosting-storage-cosmos",
+  "version": "0.1.49",
+  "homepage": "https://github.com/microsoft/Agents-for-js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/Agents-for-js.git"
+  },
+  "author": {
+    "name": "Microsoft",
+    "email": "agentssdk@microsoft.com",
+    "url": "https://aka.ms/Agents"
+  },
+  "description": "Microsoft 365 Agents SDK State Cosmos Storage support.",
+  "main": "dist/index.js",
+  "types": "dist/src/index.d.ts",
+  "dependencies": {
+    "@azure/cosmos": "^4.3.0",
+    "@microsoft/agents-hosting": "0.1.49"
+  },
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist/src",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cosmosDbKeyEscape.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+import { createHash } from 'crypto'
+
+/**
+ * Provides methods for escaping keys for Cosmos DB.
+ */
+export namespace CosmosDbKeyEscape {
+  const maxKeyLength: number = 255
+  const illegalKeys: readonly string[] = ['\\', '?', '/', '#', '\t', '\n', '\r', '*']
+  const illegalKeyCharacterReplacementMap: Map<string, string> = illegalKeys.reduce<Map<string, string>>(
+    (map: Map<string, string>, c: string) => {
+      map.set(c, `*${c.charCodeAt(0).toString(16)}`)
+      return map
+    },
+    new Map()
+  )
+
+  /**
+   * Escapes a key for use in Cosmos DB.
+   * @param key The key to escape.
+   * @param keySuffix The suffix to append to the key.
+   * @param compatibilityMode Indicates whether compatibility mode is enabled.
+   * @returns The escaped key.
+   */
+  export function escapeKey (key: string, keySuffix?: string, compatibilityMode?: boolean): string {
+    if (!key) {
+      throw new Error("The 'key' parameter is required.")
+    }
+
+    const keySplitted: string[] = key.split('')
+    const firstIllegalCharIndex: number = keySplitted.findIndex((c: string): boolean =>
+      illegalKeys.some((i: string) => i === c)
+    )
+
+    if (firstIllegalCharIndex === -1) {
+      return truncateKey(`${key}${keySuffix || ''}`, compatibilityMode)
+    }
+
+    const sanitizedKey = keySplitted.reduce(
+      (result: string, c: string) =>
+        result + (illegalKeyCharacterReplacementMap.has(c) ? illegalKeyCharacterReplacementMap.get(c)! : c),
+      ''
+    )
+
+    return truncateKey(`${sanitizedKey}${keySuffix || ''}`, compatibilityMode)
+  }
+
+  function truncateKey (key: string, truncateKeysForCompatibility?: boolean): string {
+    if (truncateKeysForCompatibility === false) {
+      return key
+    }
+
+    if (key.length > maxKeyLength) {
+      key = hashKey(key)
+    }
+    return key
+  }
+
+  function hashKey (key: string): string {
+    const hash = createHash('sha256')
+    hash.update(key)
+    return hash.digest('hex')
+  }
+}

package/src/cosmosDbPartitionedStorage.ts

@@ -0,0 +1,302 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Container, CosmosClient } from '@azure/cosmos'
+import { CosmosDbKeyEscape } from './cosmosDbKeyEscape'
+import { DocumentStoreItem } from './documentStoreItem'
+import { CosmosDbPartitionedStorageOptions } from './cosmosDbPartitionedStorageOptions'
+import { Storage, StoreItems } from '@microsoft/agents-hosting'
+export class DoOnce<T> {
+  private task: {
+    [key: string]: Promise<T>;
+  } = {}
+
+  waitFor (key: string, fn: () => Promise<T>): Promise<T> {
+    if (!this.task[key]) {
+      this.task[key] = fn()
+    }
+
+    return this.task[key]
+  }
+}
+
+const _doOnce: DoOnce<Container> = new DoOnce<Container>()
+
+const maxDepthAllowed = 127
+
+/**
+ * Implements storage using Cosmos DB partitioned storage.
+ */
+export class CosmosDbPartitionedStorage implements Storage {
+  private container!: Container
+  private client!: CosmosClient
+  private compatibilityModePartitionKey = false;
+  [key: string]: any;
+  length: number = 0
+
+  /**
+   * Initializes a new instance of the CosmosDbPartitionedStorage class.
+   * @param cosmosDbStorageOptions The options for configuring Cosmos DB partitioned storage.
+   */
+  constructor (private readonly cosmosDbStorageOptions: CosmosDbPartitionedStorageOptions) {
+    if (!cosmosDbStorageOptions) {
+      throw new ReferenceError('CosmosDbPartitionedStorageOptions is required.')
+    }
+    const { cosmosClientOptions } = cosmosDbStorageOptions
+    if (!cosmosClientOptions?.endpoint) {
+      throw new ReferenceError('endpoint in cosmosClientOptions is required.')
+    }
+    if (!cosmosClientOptions?.key && !cosmosClientOptions?.tokenProvider) {
+      throw new ReferenceError('key or tokenProvider in cosmosClientOptions is required.')
+    }
+    if (!cosmosDbStorageOptions.databaseId) {
+      throw new ReferenceError('databaseId is for CosmosDB required.')
+    }
+    if (!cosmosDbStorageOptions.containerId) {
+      throw new ReferenceError('containerId for CosmosDB is required.')
+    }
+    cosmosDbStorageOptions.compatibilityMode ??= true
+    if (cosmosDbStorageOptions.keySuffix) {
+      if (cosmosDbStorageOptions.compatibilityMode) {
+        throw new ReferenceError('compatibilityMode cannot be true while using a keySuffix.')
+      }
+      const suffixEscaped = CosmosDbKeyEscape.escapeKey(cosmosDbStorageOptions.keySuffix)
+      if (cosmosDbStorageOptions.keySuffix !== suffixEscaped) {
+        throw new ReferenceError(
+          `Cannot use invalid Row Key characters: ${cosmosDbStorageOptions.keySuffix} in keySuffix`
+        )
+      }
+    }
+  }
+
+  /**
+   * Reads items from storage.
+   * @param keys The keys of the items to read.
+   * @returns A promise that resolves to the read items.
+   */
+  async read (keys: string[]): Promise<StoreItems> {
+    if (!keys) {
+      throw new ReferenceError('Keys are required when reading.')
+    } else if (keys.length === 0) {
+      return {}
+    }
+
+    await this.initialize()
+
+    const storeItems: StoreItems = {}
+
+    await Promise.all(
+      keys.map(async (k: string): Promise<void> => {
+        try {
+          const escapedKey = CosmosDbKeyEscape.escapeKey(
+            k,
+            this.cosmosDbStorageOptions.keySuffix,
+            this.cosmosDbStorageOptions.compatibilityMode
+          )
+
+          const readItemResponse = await this.container
+            .item(escapedKey, this.getPartitionKey(escapedKey))
+            .read<DocumentStoreItem>()
+          const documentStoreItem = readItemResponse.resource
+          if (documentStoreItem) {
+            storeItems[documentStoreItem.realId] = documentStoreItem.document
+            storeItems[documentStoreItem.realId].eTag = documentStoreItem._etag
+          }
+        } catch (err: any) {
+          if (err.code === 404) {
+            this.throwInformativeError('Not Found',
+              err)
+          } else if (err.code === 400) {
+            this.throwInformativeError(
+                            `Error reading from container. You might be attempting to read from a non-partitioned
+                    container or a container that does not use '/id' as the partitionKeyPath`,
+                            err
+            )
+          } else {
+            this.throwInformativeError('Error reading from container', err)
+          }
+        }
+      })
+    )
+
+    return storeItems
+  }
+
+  /**
+   * Writes items to storage.
+   * @param changes The items to write.
+   */
+  async write (changes: StoreItems): Promise<void> {
+    if (!changes) {
+      throw new ReferenceError('Changes are required when writing.')
+    } else if (changes.length === 0) {
+      return
+    }
+
+    await this.initialize()
+
+    await Promise.all(
+      Object.entries(changes).map(async ([key, { eTag, ...change }]): Promise<void> => {
+        const document = new DocumentStoreItem({
+          id: CosmosDbKeyEscape.escapeKey(
+            key,
+            this.cosmosDbStorageOptions.keySuffix,
+            this.cosmosDbStorageOptions.compatibilityMode
+          ),
+          realId: key,
+          document: change,
+        })
+
+        const accessCondition =
+                    eTag !== '*' && eTag != null && eTag.length > 0
+                      ? { accessCondition: { type: 'IfMatch', condition: eTag } }
+                      : undefined
+
+        try {
+          await this.container.items.upsert(document, accessCondition)
+        } catch (err: any) {
+          this.checkForNestingError(change, err)
+          this.throwInformativeError('Error upserting document', err)
+        }
+      })
+    )
+  }
+
+  /**
+   * Deletes items from storage.
+   * @param keys The keys of the items to delete.
+   */
+  async delete (keys: string[]): Promise<void> {
+    await this.initialize()
+
+    await Promise.all(
+      keys.map(async (k: string): Promise<void> => {
+        const escapedKey = CosmosDbKeyEscape.escapeKey(
+          k,
+          this.cosmosDbStorageOptions.keySuffix,
+          this.cosmosDbStorageOptions.compatibilityMode
+        )
+        try {
+          await this.container.item(escapedKey, this.getPartitionKey(escapedKey)).delete()
+        } catch (err: any) {
+          if (err.code === 404) {
+            this.throwInformativeError('Not Found', err)
+          } else {
+            this.throwInformativeError('Unable to delete document', err)
+          }
+        }
+      })
+    )
+  }
+
+  /**
+   * Initializes the Cosmos DB container.
+   */
+  async initialize (): Promise<void> {
+    if (!this.container) {
+      if (!this.client) {
+        this.client = new CosmosClient(this.cosmosDbStorageOptions.cosmosClientOptions!)
+      }
+      const dbAndContainerKey = `${this.cosmosDbStorageOptions.databaseId}-${this.cosmosDbStorageOptions.containerId}`
+      this.container = await _doOnce.waitFor(
+        dbAndContainerKey,
+        async (): Promise<Container> => await this.getOrCreateContainer()
+      )
+    }
+  }
+
+  private async getOrCreateContainer (): Promise<Container> {
+    let createIfNotExists = !this.cosmosDbStorageOptions.compatibilityMode
+    let container: Container | undefined
+
+    try {
+      const { database } = await this.client.databases.createIfNotExists({
+        id: this.cosmosDbStorageOptions.databaseId
+      })
+
+      if (this.cosmosDbStorageOptions.compatibilityMode) {
+        try {
+          container = database.container(this.cosmosDbStorageOptions.containerId)
+          // @ts-ignore
+          const partitionKeyResponse = await container.readPartitionKeyDefinition()
+          if (partitionKeyResponse.resource && partitionKeyResponse.resource.paths) {
+            const paths = partitionKeyResponse.resource.paths
+            if (paths.includes('/_partitionKey')) {
+              this.compatibilityModePartitionKey = true
+            } else if (paths.indexOf(DocumentStoreItem.partitionKeyPath) === -1) {
+              throw new Error(
+                            `Custom Partition Key Paths are not supported. ${this.cosmosDbStorageOptions.containerId} has a custom Partition Key Path of ${paths[0]}.`
+              )
+            }
+          } else {
+            this.compatibilityModePartitionKey = true
+          }
+          return container
+        } catch {
+          createIfNotExists = true
+        }
+      }
+
+      if (createIfNotExists) {
+        const result = await database.containers.createIfNotExists({
+          id: this.cosmosDbStorageOptions.containerId,
+          partitionKey: {
+            paths: [DocumentStoreItem.partitionKeyPath],
+          },
+          throughput: this.cosmosDbStorageOptions.containerThroughput,
+        })
+        return result.container
+      }
+
+      if (!container) {
+        throw new Error(`Container ${this.cosmosDbStorageOptions.containerId} not found.`)
+      }
+      return container
+    } catch (err: any) {
+      this.throwInformativeError(
+            `Failed to initialize Cosmos DB database/container: ${this.cosmosDbStorageOptions.databaseId}/${this.cosmosDbStorageOptions.containerId}`,
+            err
+      )
+      throw err
+    }
+  }
+
+  private getPartitionKey (key: string) {
+    return this.compatibilityModePartitionKey ? undefined : key
+  }
+
+  private checkForNestingError (json: object, err: Error | Record<'message', string> | string): void {
+    const checkDepth = (obj: unknown, depth: number, isInDialogState: boolean): void => {
+      if (depth > maxDepthAllowed) {
+        let message = `Maximum nesting depth of ${maxDepthAllowed} exceeded.`
+
+        if (isInDialogState) {
+          message +=
+                        ' This is most likely caused by recursive component dialogs. ' +
+                        'Try reworking your dialog code to make sure it does not keep dialogs on the stack ' +
+                        "that it's not using. For example, consider using replaceDialog instead of beginDialog."
+        } else {
+          message += ' Please check your data for signs of unintended recursion.'
+        }
+
+        this.throwInformativeError(message, err)
+      } else if (obj && typeof obj === 'object') {
+        for (const [key, value] of Object.entries(obj)) {
+          checkDepth(value, depth + 1, key === 'dialogStack' || isInDialogState)
+        }
+      }
+    }
+
+    checkDepth(json, 0, false)
+  }
+
+  private throwInformativeError (prependedMessage: string, err: Error | Record<'message', string> | string): void {
+    if (typeof err === 'string') {
+      err = new Error(err)
+    }
+
+    err.message = `[${prependedMessage}] ${err.message}`
+
+    throw err
+  }
+}

package/src/cosmosDbPartitionedStorageOptions.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { CosmosClientOptions } from '@azure/cosmos'
+
+/**
+ * Options for configuring Cosmos DB partitioned storage.
+ */
+export interface CosmosDbPartitionedStorageOptions {
+  /**
+   * The ID of the database.
+   */
+  databaseId: string;
+  /**
+   * The ID of the container.
+   */
+  containerId: string;
+  /**
+   * The throughput of the container.
+   */
+  containerThroughput?: number;
+  /**
+   * The suffix to append to keys.
+   */
+  keySuffix?: string;
+  /**
+   * Indicates whether compatibility mode is enabled.
+   */
+  compatibilityMode?: boolean;
+
+  /**
+   * The options for the Cosmos client.
+   */
+  cosmosClientOptions?: CosmosClientOptions;
+  // tokenCredential?: TokenCredential;
+}

package/src/documentStoreItem.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Represents an item stored in the document store.
+ */
+export class DocumentStoreItem {
+  /**
+   * Gets the partition key path.
+   */
+  static get partitionKeyPath (): string {
+    return '/id'
+  }
+
+  /**
+   * The ID of the document.
+   */
+  id: string
+  /**
+   * The real ID of the document.
+   */
+  realId: string
+  /**
+   * The document object.
+   */
+  document: object
+  /**
+   * The ETag of the document.
+   */
+  eTag: string
+
+  /**
+   * Gets the partition key.
+   */
+  get partitionKey (): string {
+    return this.id
+  }
+
+  /**
+   * Initializes a new instance of the DocumentStoreItem class.
+   * @param storeItem The store item to initialize.
+   */
+  constructor (storeItem: { id: string; realId: string; document: object; eTag?: string }) {
+    this.id = storeItem.id
+    this.realId = storeItem.realId || ''
+    this.document = storeItem.document || {}
+    this.eTag = storeItem.eTag || ''
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './cosmosDbPartitionedStorage'
+export * from './cosmosDbPartitionedStorageOptions'