Update Add ServiceStack reference examples

Author: mythz

MyApp/_pages/add-servicestack-reference.md

@@ -140,6 +140,8 @@ The [x dotnet tool](/dotnet-tool) provides simple command-line utilities to easi
 dotnet tool install --global x 
 :::
 
+::include npx-get-dtos.md::
+
 This will make the following utilities available from your command-line which will let you download the Server DTO classes for a remote ServiceStack endpoint in your chosen language which you can use with ServiceStack's generic Service clients to be able to make end-to-end API calls.
 
 <table class="table table-bordered">
@@ -390,6 +392,119 @@ in the right-click context menu:
 
 If you're updating references frequently you can save time by [assigning it a keyboard shortcut](https://www.jetbrains.com/help/rider/Configuring_Keyboard_and_Mouse_Shortcuts.html).
 
+
+## Multiple File Upload Support with API Requests supported in all languages
+
+To be able to call [AI Server](/ai-server/) APIs requiring file uploads we've added multiple file upload support with API Requests to the generic service clients for all our supported languages.
+
+Here's what that looks like for different languages calling AI Server's `SpeechToText` API:
+
+### C# Speech to Text
+
+```csharp
+using var fsAudio = File.OpenRead("audio.wav");
+var response = client.PostFileWithRequest(new SpeechToText(),
+    new UploadFile("audio.wav", fsAudio, "audio"));
+```
+
+### Dart Speech to Text
+
+```dart
+var audioFile = new File('audio.wav');
+var uploadFile = new UploadFile(
+    fieldName: 'audio',
+    fileName: audioFile.uri.pathSegments.last,
+    contentType: 'audio/wav',
+    contents: await audioFile.readAsBytes()
+);
+
+var response = await client.postFileWithRequest(new SpeechToText(), uploadFile);
+```
+
+### Python Speech to Text
+
+```python
+with open("files/audio.wav", "rb") as audio:
+  response = client.post_file_with_request(SpeechToText(), 
+    UploadFile(field_name="audio", file_name="audio.wav", content_type="audio/wav", stream=audio))
+```
+
+### PHP Speech to Text
+
+```php
+$audioFile = __DIR__ . '/files/audio.wav';
+
+/** @var GenerationResponse $response */
+$response = $client->postFileWithRequest(new SpeechToText(),
+    new UploadFile(
+        filePath: $audioFile,
+        fileName: 'audio.wav',
+        fieldName: 'audio',
+        contentType: 'audio/wav'
+    ));
+```
+
+### Swift Speech to Text
+
+```swift
+guard let audioURL = Bundle.module.url(forResource: "audio.wav", withExtension: nil) else {
+    return
+}
+
+let audioData = try Data(contentsOf: audioURL)
+let response: TextGenerationResponse = try await client.postFileWithRequestAsync(
+    request:SpeechToText(), 
+    file:UploadFile(fileName: "audio.wav", data:audioData, fieldName:"audio"))
+```
+
+### Kotlin Speech to Text
+
+```kotlin
+val audioBytes = Files.readAllBytes(Paths.get("audio.wav"))
+val response = client.postFileWithRequest(SpeechToText(),
+    UploadFile("audio", "audio.wav", "audio/wav", audioBytes))
+```
+
+### Java Speech to Text
+
+```java
+byte[] audioBytes = Files.readAllBytes(Paths.get("audio.wav"));
+var response = client.postFileWithRequest(request,
+    new UploadFile("audio", "audio.wav", "audio/wav", audioBytes));
+```
+
+### TypeScript Speech to Text
+
+```js
+// Create FormData and append the file
+const formData = new FormData()
+const audioFile = fs.readFileSync('audio.wav')
+const blob = new Blob([audioFile], { type: 'audio/wav' })
+
+// Explicitly set the field name as 'audio'
+formData.append('audio', blob, 'audio.wav')
+
+const api = await client.apiForm(new SpeechToText(), formData)
+```
+
+### Multiple File Uploads
+
+All languages also support a `postFilesWithRequest` variant for uploading multiple files with an API Request.
+E.g. here's an example of using `PostFilesWithRequest` to generate a video with a Watermark:
+
+### C# Watermark Video
+
+```csharp
+using var fsVideo = File.OpenRead("video.mp4");
+using var fsWatermark = File.OpenRead("watermark.png");
+var response = client.PostFilesWithRequest(new QueueWatermarkVideo {
+        Position = WatermarkPosition.BottomRight
+    }, [
+        new UploadFile("video.mp4", fsVideo, "video"),
+        new UploadFile("watermark.png", fsWatermark, "watermark")
+    ]);
+```
+
 ## Advantages over WCF
 
  - **Simple** Server provides DTOs based on metadata and options provided. No heavy client side tools, just a HTTP request!

MyApp/_pages/csharp-client.md

@@ -184,6 +184,38 @@ var response = await client.SendAsync<HelloResponse>(
 
 The service clients use the automatic [pre-defined routes](/endpoints) for each service.
 
+### File Upload with Request
+
+The `PostFileWithRequest*` methods can be used to upload a file with an API Request.
+
+Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:
+
+### C# Speech to Text
+
+```csharp
+using var fsAudio = File.OpenRead("audio.wav");
+var response = client.PostFileWithRequest(new SpeechToText(),
+    new UploadFile("audio.wav", fsAudio, "audio"));
+```
+
+### Multiple File Uploads
+
+Whilst the `PostFilesWithRequest*` methods can be used to upload multiple files with an API Request, e.g:
+
+### C# Watermark Video
+
+```csharp
+using var fsVideo = File.OpenRead("video.mp4");
+using var fsWatermark = File.OpenRead("watermark.png");
+var response = client.PostFilesWithRequest(new QueueWatermarkVideo {
+        Position = WatermarkPosition.BottomRight
+    }, [
+        new UploadFile("video.mp4", fsVideo, "video"),
+        new UploadFile("watermark.png", fsWatermark, "watermark")
+    ]);
+```
+
+
 <a name="native-responses"></a>
 
 ### [Cache Aware Service Clients](/cache-aware-clients)

MyApp/_pages/dart-add-servicestack-reference.md

@@ -262,36 +262,62 @@ Both JSON Service Client variants implement the same flexible `IServiceClient` A
 
 ```csharp
 abstract class IServiceClient {
-  String baseUrl;
-  String bearerToken;
-  String refreshToken;
-  String userName;
-  String password;
+  String? baseUrl;
+  String? replyBaseUrl;
+  String? oneWayBaseUrl;
 
-  Future<T> get<T>(IReturn<T> request, {Map<String, dynamic> args});
-  Future<Map<String, dynamic>> getUrl(String path, {Map<String, dynamic> args});
-  Future<T> getAs<T>(String path, {Map<String, dynamic> args, T responseAs});
+  String? bearerToken;
+  String? refreshToken;
+  String? userName;
+  String? password;
 
-  Future<T> post<T>(IReturn<T> request, {dynamic body, Map<String, dynamic> args});
-  Future<Map<String, dynamic>> postToUrl(String path, dynamic body, {Map<String, dynamic> args});
-  Future<T> postAs<T>(String path, dynamic body, {Map<String, dynamic> args, T responseAs});
+  AsyncCallbackFunction? onAuthenticationRequired;
+  String? getTokenCookie();
+  String? getRefreshTokenCookie();
 
-  Future<T> delete<T>(IReturn<T> request, {Map<String, dynamic> args});
-  Future<Map<String, dynamic>> deleteUrl(String path, {Map<String, dynamic> args});
-  Future<T> deleteAs<T>(String path, {Map<String, dynamic> args, T responseAs});
+  void clearCookies();
 
-  Future<T> put<T>(IReturn<T> request, {dynamic body, Map<String, dynamic> args});
-  Future<Map<String, dynamic>> putToUrl(String path, dynamic body, {Map<String, dynamic> args});
-  Future<T> putAs<T>(String path, dynamic body, {Map<String, dynamic> args, T responseAs});
+  Future<ApiResult<T>> api<T>(IReturn<T> request, {Map<String, dynamic>? args, String? method});
+
+  Future<ApiResult<EmptyResponse>> apiVoid(IReturnVoid request, {Map<String, dynamic>? args, String? method});
+
+  Future<T> get<T>(IReturn<T> request, {Map<String, dynamic>? args});
+
+  Future<Map<String, dynamic>> getUrl(String path, {Map<String, dynamic>? args});
+
+  Future<T> getAs<T>(String path, {Map<String, dynamic>? args, T? responseAs});
+
+  Future<T> post<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});
+
+  Future<Map<String, dynamic>> postToUrl(String path, dynamic body, {Map<String, dynamic>? args});
+
+  Future<T> postAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});
+
+  Future<T> delete<T>(IReturn<T> request, {Map<String, dynamic>? args});
+
+  Future<Map<String, dynamic>> deleteUrl(String path, {Map<String, dynamic>? args});
+
+  Future<T> deleteAs<T>(String path, {Map<String, dynamic>? args, T? responseAs});
+
+  Future<T> put<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});
+
+  Future<Map<String, dynamic>> putToUrl(String path, dynamic body, {Map<String, dynamic>? args});
+
+  Future<T> putAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});
+
+  Future<T> patch<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});
 
-  Future<T> patch<T>(IReturn<T> request, {dynamic body, Map<String, dynamic> args});
   Future<Map<String, dynamic>> patchToUrl(String path, dynamic body, {Map<String, dynamic> args});
-  Future<T> patchAs<T>(String path, dynamic body, {Map<String, dynamic> args, T responseAs});
+
+  Future<T> patchAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});
 
   Future<List<T>> sendAll<T>(Iterable<IReturn<T>> requests);
+
   Future<void> sendAllOneWay<T>(Iterable<IReturn<T>> requests);
 
-  Future<T> send<T>(IReturn<T> request, {String method, Map<String, dynamic> args, T responseAs});
+  Future<T> send<T>(IReturn<T> request, {String? method, Map<String, dynamic>? args, T? responseAs});
+
+  void close({bool force = false});
 }
 ```
 
@@ -307,6 +333,29 @@ var webClient = JsonWebClient(baseUrl)
     ..responseFilter = (res) => print(res.headers["X-Args"]);
 ```
 
+### Uploading Files
+
+The `postFileWithRequest` method can be used to upload a file with an API Request.
+
+### Dart Speech to Text
+
+Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:
+
+```dart
+var audioFile = new File('audio.wav');
+var uploadFile = new UploadFile(
+    fieldName: 'audio',
+    fileName: audioFile.uri.pathSegments.last,
+    contentType: 'audio/wav',
+    contents: await audioFile.readAsBytes()
+);
+
+var response = await client.postFileWithRequest(new SpeechToText(), uploadFile);
+```
+
+To upload multiple files use `postFilesWithRequest`.
+
+
 #### Comprehensive Test Suite
 
 To ensure a high quality implementation we've ported the [TypeScript @servicestack/client](https://github.com/ServiceStack/servicestack-client) test suite over to Dart which is itself a good resource for discovering [different supported features and flexible HTTP Request options](https://github.com/ServiceStack/servicestack-dart/tree/master/test) available. 

MyApp/_pages/java-add-servicestack-reference.md

@@ -120,6 +120,15 @@ The [ServiceClient.java](https://github.com/ServiceStack/ServiceStack.Java/blob/
 ```java
 public interface ServiceClient {
     boolean getAlwaysSendBasicAuthHeaders();
+
+    void setBearerToken(String value);
+    String getBearerToken();
+    void setTokenCookie(String value);
+
+    void setRefreshToken(String bearerToken);
+    String getRefreshToken();
+    void setRefreshTokenCookie(String value);
+
     void setAlwaysSendBasicAuthHeaders(boolean value);
     void setCredentials(String userName, String password);
 
@@ -155,6 +164,21 @@ public interface ServiceClient {
     <TResponse> TResponse delete(String path, Class responseType);
     <TResponse> TResponse delete(String path, Type responseType);
     HttpURLConnection delete(String path);
+
+    void setCookie(String name, String value);
+    void setCookie(String name, String value, Long expiresInSecs);
+    void clearCookies();
+    String getCookieValue(String name);
+    String getTokenCookie();
+    String getRefreshTokenCookie();
+
+    <TResponse> TResponse postFileWithRequest(IReturn<TResponse> request, UploadFile file);
+    <TResponse> TResponse postFileWithRequest(Object request, UploadFile file, Object responseType);
+    <TResponse> TResponse postFileWithRequest(String path, Object request, UploadFile file, Object responseType);
+
+    <TResponse> TResponse postFilesWithRequest(IReturn<TResponse> request, UploadFile[] files);
+    <TResponse> TResponse postFilesWithRequest(Object request, UploadFile[] files, Object responseType);
+    <TResponse> TResponse postFilesWithRequest(String path, Object request, UploadFile[] files, Object responseType);
 }
 ```
 
@@ -261,6 +285,22 @@ AuthenticateResponse authResponse = client.post(new Authenticate()
 TestAuthResponse response = client.get(new TestAuth());
 ``` 
 
+### Uploading Files
+
+The `postFileWithRequest` method can be used to upload a file with an API Request.
+
+### Java Speech to Text
+
+Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:
+
+```java
+byte[] audioBytes = Files.readAllBytes(Paths.get("audio.wav"));
+var response = client.postFileWithRequest(request,
+    new UploadFile("audio", "audio.wav", "audio/wav", audioBytes));
+```
+
+To upload multiple files use `postFilesWithRequest`.
+
 ### AndroidServiceClient
 Unlike .NET, Java doesn't have an established Async story or any language support that simplifies execution and composition of Async tasks, as a result the Async story on Android is fairly fragmented with multiple options built-in for executing non-blocking tasks on different threads including: