Create odsp-client-specific fluidcontainer interface (#25727)

## Description

#25597 includes several changes that require exposing a slightly
different, ODSPClient-specific `IFluidContainer` that exposes container
methods like `serialize` and `uploadBlob`. Additionally, ODSPClient
already returns a customized version of `FluidContainer` with an
overwritten `attach` method, but the param types are not represented in
the standard IFluidContainer type.

## Breaking Changes

None.

## Reviewer Guidance

For examples of how this interface will be extended, see #25597.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: znewton

packages/service-clients/odsp-client/api-report/odsp-client.alpha.api.md

@@ -7,6 +7,11 @@
 // @beta
 export type IOdspAudience = IServiceAudience<OdspMember>;
 
+// @beta
+export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
+    attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+}
+
 // @beta
 export interface IOdspTokenProvider {
     fetchStorageToken(siteUrl: string, refresh: boolean): Promise<TokenResponse>;
@@ -18,12 +23,12 @@ export class OdspClient {
     constructor(properties: OdspClientProps);
     // (undocumented)
     createContainer<T extends ContainerSchema>(containerSchema: T): Promise<{
-        container: IFluidContainer<T>;
+        container: IOdspFluidContainer<T>;
         services: OdspContainerServices;
     }>;
     // (undocumented)
     getContainer<T extends ContainerSchema>(id: string, containerSchema: T): Promise<{
-        container: IFluidContainer<T>;
+        container: IOdspFluidContainer<T>;
         services: OdspContainerServices;
     }>;
 }
@@ -43,6 +48,12 @@ export interface OdspConnectionConfig {
     tokenProvider: IOdspTokenProvider;
 }
 
+// @beta (undocumented)
+export interface OdspContainerAttachProps {
+    fileName: string | undefined;
+    filePath: string | undefined;
+}
+
 // @beta
 export interface OdspContainerServices {
     audience: IOdspAudience;

packages/service-clients/odsp-client/api-report/odsp-client.beta.api.md

@@ -7,6 +7,11 @@
 // @beta
 export type IOdspAudience = IServiceAudience<OdspMember>;
 
+// @beta
+export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
+    attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+}
+
 // @beta
 export interface IOdspTokenProvider {
     fetchStorageToken(siteUrl: string, refresh: boolean): Promise<TokenResponse>;
@@ -18,12 +23,12 @@ export class OdspClient {
     constructor(properties: OdspClientProps);
     // (undocumented)
     createContainer<T extends ContainerSchema>(containerSchema: T): Promise<{
-        container: IFluidContainer<T>;
+        container: IOdspFluidContainer<T>;
         services: OdspContainerServices;
     }>;
     // (undocumented)
     getContainer<T extends ContainerSchema>(id: string, containerSchema: T): Promise<{
-        container: IFluidContainer<T>;
+        container: IOdspFluidContainer<T>;
         services: OdspContainerServices;
     }>;
 }
@@ -43,6 +48,12 @@ export interface OdspConnectionConfig {
     tokenProvider: IOdspTokenProvider;
 }
 
+// @beta (undocumented)
+export interface OdspContainerAttachProps {
+    fileName: string | undefined;
+    filePath: string | undefined;
+}
+
 // @beta
 export interface OdspContainerServices {
     audience: IOdspAudience;

packages/service-clients/odsp-client/src/index.ts

@@ -14,10 +14,12 @@
  */
 
 export type {
-	OdspConnectionConfig,
+	IOdspAudience,
+	IOdspFluidContainer,
 	OdspClientProps,
+	OdspConnectionConfig,
+	OdspContainerAttachProps,
 	OdspContainerServices,
-	IOdspAudience,
 	OdspMember,
 	TokenResponse,
 } from "./interfaces.js";

packages/service-clients/odsp-client/src/interfaces.ts

@@ -7,7 +7,13 @@ import type {
 	IConfigProviderBase,
 	ITelemetryBaseLogger,
 } from "@fluidframework/core-interfaces";
-import type { IMember, IServiceAudience } from "@fluidframework/fluid-static";
+import type {
+	ContainerAttachProps,
+	ContainerSchema,
+	IFluidContainer,
+	IMember,
+	IServiceAudience,
+} from "@fluidframework/fluid-static";
 
 import type { IOdspTokenProvider } from "./token.js";
 
@@ -59,7 +65,6 @@ export interface OdspClientProps {
 }
 
 /**
- * @legacy
  * @beta
  */
 export interface OdspContainerAttachProps {
@@ -74,6 +79,26 @@ export interface OdspContainerAttachProps {
 	fileName: string | undefined;
 }
 
+/**
+ * ODSP version of the IFluidContainer interface.
+ * @beta
+ */
+export interface IOdspFluidContainer<
+	TContainerSchema extends ContainerSchema = ContainerSchema,
+> extends IFluidContainer<TContainerSchema> {
+	/**
+	 * A newly created container starts detached from the collaborative service.
+	 * Calling `attach()` uploads the new container to the service and connects to the collaborative service.
+	 *
+	 * This function is the same as the IFluidContainer.attach function, but has ODSP specific function signatures.
+	 *
+	 * @param props - Optional properties to pass to the attach function.
+	 *
+	 * @returns A promise which resolves when the attach is complete, with the string identifier of the container.
+	 */
+	attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+}
+
 /**
  * OdspContainerServices is returned by the OdspClient alongside a FluidContainer. It holds the
  * functionality specifically tied to the ODSP service, and how the data stored in the

packages/service-clients/odsp-client/src/odspClient.ts

@@ -20,11 +20,7 @@ import type {
 } from "@fluidframework/core-interfaces";
 import type { IClient } from "@fluidframework/driver-definitions";
 import type { IDocumentServiceFactory } from "@fluidframework/driver-definitions/internal";
-import type {
-	ContainerAttachProps,
-	ContainerSchema,
-	IFluidContainer,
-} from "@fluidframework/fluid-static";
+import type { ContainerAttachProps, ContainerSchema } from "@fluidframework/fluid-static";
 import {
 	createDOProviderContainerRuntimeFactory,
 	createFluidContainer,
@@ -46,6 +42,7 @@ import type {
 	OdspConnectionConfig,
 	OdspContainerAttachProps,
 	OdspContainerServices as IOdspContainerServices,
+	IOdspFluidContainer,
 } from "./interfaces.js";
 import { OdspContainerServices } from "./odspContainerServices.js";
 import type { IOdspTokenProvider } from "./token.js";
@@ -116,7 +113,7 @@ export class OdspClient {
 	public async createContainer<T extends ContainerSchema>(
 		containerSchema: T,
 	): Promise<{
-		container: IFluidContainer<T>;
+		container: IOdspFluidContainer<T>;
 		services: IOdspContainerServices;
 	}> {
 		const loaderProps = this.getLoaderProps(containerSchema);
@@ -129,18 +126,21 @@ export class OdspClient {
 			},
 		});
 
-		const fluidContainer = await this.createFluidContainer(container, this.connectionConfig);
+		const fluidContainer = await this.createFluidContainer<T>(
+			container,
+			this.connectionConfig,
+		);
 
 		const services = await this.getContainerServices(container);
 
-		return { container: fluidContainer as IFluidContainer<T>, services };
+		return { container: fluidContainer, services };
 	}
 
 	public async getContainer<T extends ContainerSchema>(
 		id: string,
 		containerSchema: T,
 	): Promise<{
-		container: IFluidContainer<T>;
+		container: IOdspFluidContainer<T>;
 		services: IOdspContainerServices;
 	}> {
 		const loaderProps = this.getLoaderProps(containerSchema);
@@ -152,11 +152,11 @@ export class OdspClient {
 		});
 		const container = await loadExistingContainer({ ...loaderProps, request: { url } });
 
-		const fluidContainer = await createFluidContainer({
+		const fluidContainer = await createFluidContainer<T>({
 			container,
 		});
 		const services = await this.getContainerServices(container);
-		return { container: fluidContainer as IFluidContainer<T>, services };
+		return { container: fluidContainer, services };
 	}
 
 	private getLoaderProps(schema: ContainerSchema): ILoaderProps {
@@ -192,10 +192,10 @@ export class OdspClient {
 		};
 	}
 
-	private async createFluidContainer(
+	private async createFluidContainer<T extends ContainerSchema>(
 		container: IContainer,
 		connection: OdspConnectionConfig,
-	): Promise<IFluidContainer> {
+	): Promise<IOdspFluidContainer<T>> {
 		/**
 		 * See {@link FluidContainer.attach}
 		 */
@@ -226,7 +226,7 @@ export class OdspClient {
 			 */
 			return resolvedUrl.itemId;
 		};
-		const fluidContainer = await createFluidContainer({ container });
+		const fluidContainer = await createFluidContainer<T>({ container });
 		fluidContainer.attach = attach;
 		return fluidContainer;
 	}