@microsoft/agents-hosting-storage-cosmos 1.9.0-beta.8.gf58e66b2ee → 1.9.1

package/README.md

@@ -2,7 +2,11 @@
 
 ## Overview
 
-This package allows to configure Azure CosmosDB Storage as the backend for Agents conversation State
+This package allows to configure Azure CosmosDB Storage as the backend for Agents conversation State
+
+`CosmosDbPartitionedStorage` retains the legacy `Storage` contract. Use
+`CosmosDbPartitionedStorageV2` for the separate `StorageV2` contract; V2 calls
+return keyed operation results with `value`, `status`, and `version`.
 
 ## Usage
 
@@ -17,5 +21,9 @@ const cosmosDbStorageOptions = {
 } as CosmosDbPartitionedStorageOptions
 const cosmosStorage = new CosmosDbPartitionedStorage(cosmosDbStorageOptions)
 const conversationState = new ConversationState(cosmosStorage)
-const userState = new UserState(cosmosStorage)
-```
+const userState = new UserState(cosmosStorage)
+```
+
+```ts
+const cosmosStorageV2 = new CosmosDbPartitionedStorageV2(cosmosDbStorageOptions)
+```

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "@microsoft/agents-hosting-storage-cosmos",
-    "version": "1.9.0-beta.8.gf58e66b2ee",
+    "version": "1.9.1",
     "homepage": "https://github.com/microsoft/Agents-for-js",
     "repository": {
         "type": "git",
@@ -17,9 +17,9 @@
     "types": "dist/src/index.d.ts",
     "dependencies": {
         "@azure/cosmos": "4.9.3",
-        "@microsoft/agents-hosting": "1.9.0-beta.8.gf58e66b2ee",
-        "@microsoft/agents-activity": "1.9.0-beta.8.gf58e66b2ee",
-        "@microsoft/agents-telemetry": "1.9.0-beta.8.gf58e66b2ee"
+        "@microsoft/agents-hosting": "1.9.1",
+        "@microsoft/agents-activity": "1.9.1",
+        "@microsoft/agents-telemetry": "1.9.1"
     },
     "license": "MIT",
     "files": [

package/dist/src/cosmosDbPartitionedStorage.d.ts

@@ -1,13 +1,12 @@
+import { Container } from '@azure/cosmos';
+import { DocumentStoreItem } from './documentStoreItem';
 import { CosmosDbPartitionedStorageOptions } from './cosmosDbPartitionedStorageOptions';
-import { Storage, StoreItems } from '@microsoft/agents-hosting';
-/**
- * Implements storage using Cosmos DB partitioned storage.
- */
-export declare class CosmosDbPartitionedStorage implements Storage {
-    private readonly cosmosDbStorageOptions;
-    private container;
+import { StorageDeleteOptions, StorageDeleteResults, StorageReadResults, StorageWriteOptions, StorageWriteResults, Storage, StorageV2, StoreItems } from '@microsoft/agents-hosting';
+declare class CosmosDbPartitionedStorageInternals {
+    readonly cosmosDbStorageOptions: CosmosDbPartitionedStorageOptions;
+    container: Container;
     private client;
-    private compatibilityModePartitionKey;
+    compatibilityModePartitionKey: boolean;
     [key: string]: any;
     /**
      * The number of items in the storage. This property is not currently used.
@@ -16,29 +15,89 @@ export declare class CosmosDbPartitionedStorage implements Storage {
     /**
      * 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.
+     * Initializes the Cosmos DB container.
+     */
+    initialize(): Promise<void>;
+    private getOrCreateContainer;
+    getPartitionKey(key: string): string | undefined;
+    isExpired(item: DocumentStoreItem): boolean;
+    checkForNestingError(json: object, err: Error | Record<'message', string> | string): void;
+}
+/**
+ * Cosmos DB partitioned storage provider.
+ *
+ * This class implements the legacy {@link Storage} contract. Use
+ * {@link CosmosDbPartitionedStorageV2} for the structured StorageV2 contract.
+ */
+export declare class CosmosDbPartitionedStorage extends CosmosDbPartitionedStorageInternals implements Storage {
+    /**
+     * Reads legacy items and attaches Cosmos DB ETags as `eTag` values.
+     *
+     * @param keys The keys to read.
+     * @returns The stored items; missing keys are omitted.
+     * @throws When the key input is invalid or Cosmos DB cannot complete the operation.
      */
     read(keys: string[]): Promise<StoreItems>;
     /**
-     * Writes items to storage.
-     * @param changes The items to write.
+     * Writes legacy items and applies `eTag` concurrency checks.
+     *
+     * @param changes The keyed legacy items to write.
+     * @throws When the input is invalid or Cosmos DB cannot complete the operation.
      */
     write(changes: StoreItems): Promise<void>;
     /**
-     * Deletes items from storage.
-     * @param keys The keys of the items to delete.
+     * Deletes legacy items and ignores missing documents.
+     *
+     * @param keys The keys to delete.
+     * @throws When Cosmos DB cannot complete the operation.
      */
     delete(keys: string[]): Promise<void>;
+}
+/**
+ * A Cosmos DB provider for the structured {@link StorageV2} contract.
+ *
+ * This is the V2 counterpart to {@link CosmosDbPartitionedStorage} and uses the same
+ * {@link CosmosDbPartitionedStorageOptions}. Each read, write, and delete returns an outcome for
+ * every requested key. Cosmos DB ETags are returned as separate storage versions, and writes
+ * support create-only, replace, and expected-version conditions for optimistic concurrency.
+ */
+export declare class CosmosDbPartitionedStorageV2 extends StorageV2 {
+    private readonly internals;
     /**
-     * Initializes the Cosmos DB container.
+     * Creates a V2 Cosmos DB storage provider.
+     *
+     * @param options The Cosmos DB connection, database, container, and partitioning options.
      */
-    private initialize;
-    private getOrCreateContainer;
-    private getPartitionKey;
-    private checkForNestingError;
+    constructor(options: CosmosDbPartitionedStorageOptions);
+    /**
+     * Reads V2 items with one status and Cosmos DB ETag version per requested key.
+     *
+     * @param keys The keys to read.
+     * @returns The keyed V2 read results.
+     * @throws When the key input is invalid or Cosmos DB cannot complete the operation.
+     */
+    read<T extends object = Record<string, unknown>>(keys: string[]): Promise<StorageReadResults<T>>;
+    /**
+     * Writes V2 items with mode and expected-version conditions.
+     *
+     * @param changes The keyed values to write.
+     * @param options The V2 write mode and expected version.
+     * @returns One keyed operation result per change.
+     * @throws When the input is invalid or Cosmos DB cannot complete the operation.
+     */
+    write<T extends object = Record<string, unknown>>(changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults>;
+    /**
+     * Deletes V2 items with an optional expected-version condition.
+     *
+     * @param keys The keys to delete.
+     * @param options The optional expected version.
+     * @returns One keyed operation result per requested key.
+     * @throws When the key input is invalid or Cosmos DB cannot complete the operation.
+     */
+    delete(keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults>;
 }
+export {};