@fonoster/sdk 0.6.0 → 0.6.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Fonoster Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,359 @@
-[<a href="https://gitpod.io/#https://github.com/fonoster/fonoster"> <img src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod" alt="Contribute with Gitpod" />
+sdk
+=================
+
+[![Fonoster](https://img.shields.io/badge/fonoster-sdk-brightgreen.svg)](https://fonoster.com)
+[![Version](https://img.shields.io/npm/v/@fonoster/sdk.svg)](https://npmjs.org/package/@fonoster/sdk)
+[![Downloads/week](https://img.shields.io/npm/dw/@fonoster/sdk.svg)](https://npmjs.org/package/@fonoster/sdk)
+[![License](https://img.shields.io/npm/l/@fonoster/sdk.svg)](https://github.com/fonoster/fonoster/blob/main/package.json)
+
+This package provides a set of utilities for working with Fonoster services. It is a polymorphic SDK that can be used in a browser or a Node.js environment.
+
+* [Installation](#installation)
+* [Example](#example)
+* [APIs](#apis)
+
+## Installation
+
+```sh-session
+$ npm install --save @fonoster/sdk
+```
+
+Or in the browser:
+
+```html
+<script src="https://unpkg.com/@fonoster/sdk"></script>
+```
+
+### Importing the library
+
+For CommonJS projects:
+
+```typescript
+const SDK = require("@fonoster/sdk");
+```
+
+For ES6 modules:
+
+```typescript
+import * as SDK from "@fonoster/sdk";
+```
+
+Directly in the browser:
+
+```html
+<script src="https://unpkg.com/@fonoster/sdk"></script>
+<script>
+   // You can now use the SDK
+</script>
+```
+
+## Example
+
+Create a new SDK instance to interact with the Fonoster API. The SDK requires a client object to handle communication with the API.
+
+### Creating a client object
+
+In Node.js:
+
+```typescript
+const SDK = require("@fonoster/sdk");
+const accessKeyId = "WO00000000000000000000000000000000";
+const client = new SDK.Client({ accessKeyId });
+```
+
+In the browser:
+
+```typescript
+const SDK = require("@fonoster/sdk");
+const accessKeyId = "WO00000000000000000000000000000000";
+const client = new SDK.WebClient({ accessKeyId });
+```
+
+### Initializing the client
+
+```typescript
+const username = "admin@fonoster.local";
+const password = "changeme";
+
+client.login(username, password)
+ .then(console.log)
+ .catch(console.error);
+```
+
+### Making a request
+
+```typescript
+// Requires an initialized client object
+const applications = new SDK.Applications(client);
+
+const request = {
+  name: "MyApp",
+  type: "PROGRAMMABLE_VOICE",
+  appEndpoint: "localhost:3000" // Your app endpoint
+};
+
+applications.createApplication(request)
+ .then(console.log)
+ .catch(console.error);
+```
+
+## APIs
+
+* [`Applications`](#Applications)
+
+
+
+<a name="Applications"></a>
+
+## Applications
+Fonoster Applications, part of the Fonoster Voice Subsystem,
+allow you to create, update, retrieve, and delete Voice Applications.
+Note that an active Fonoster deployment is required.
+
+**Kind**: global class  
+**See**
+
+- AbstractClient
+- FonosterClient
+
+
+* [Applications](#Applications)
+    * [new Applications(client)](#new_Applications_new)
+    * [.createApplication(request)](#Applications+createApplication) ⇒ <code>Promise.&lt;CreateAppResponse&gt;</code>
+    * [.getApplication(request)](#Applications+getApplication) ⇒ <code>Promise.&lt;Application&gt;</code>
+    * [.updateApplication(request)](#Applications+updateApplication) ⇒ <code>Promise.&lt;BaseApiObject&gt;</code>
+    * [.listApplications(request)](#Applications+listApplications) ⇒ <code>Promise.&lt;ListApplicationsResponse&gt;</code>
+    * [.deleteApplication(request)](#Applications+deleteApplication) ⇒ <code>Promise.&lt;BaseApiObject&gt;</code>
+
+<a name="new_Applications_new"></a>
+
+### new Applications(client)
+Constructs a new Applications object.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| client | <code>FonosterClient</code> | Client object with underlying implementations to make requests to Fonoster's API |
+
+**Example**  
+```js
+const SDK = require("@fonoster/sdk");
+
+const request = {
+  name: "My application",
+  type: "PROGRAMMABLE_VOICE",
+  appEndpoint: "myapp.mydomain.com",
+  textToSpeech: {
+    productRef: "tts.google",
+    config: {
+      voice: "en-US-Casual-K"
+    }
+  },
+  speechToText: {
+    productRef: "stt.google",
+    config: {
+     languageCode: "en-US"
+    }
+  },
+  intelligence: {
+    productRef: "nlu.dialogflowcx",
+    credentials: {
+       apiKey: "your-api-key"
+    },
+    config: {
+      agentId: "your-agent-id"
+    }
+  }
+};
+
+const username = "admin@fonoster.local";
+const password = "changeme";
+const accessKeyId = "WO00000000000000000000000000000000";
+
+const client = new SDK.Client({ accessKeyId });
+
+client.login(username, password)
+ .then(async () => {
+   const apps = new SDK.Applications(client);
+   const result = await apps.createApplication(request);
+   console.log(result);  // successful response
+ }).catch(console.error); // an error occurred
+```
+<a name="Applications+createApplication"></a>
+
+### applications.createApplication(request) ⇒ <code>Promise.&lt;CreateAppResponse&gt;</code>
+Creates a new Application in Fonoster. The only required fields are the name and type of the application.
+
+**Kind**: instance method of [<code>Applications</code>](#Applications)  
+**Returns**: <code>Promise.&lt;CreateAppResponse&gt;</code> - - The response object that contains the reference to the newly created application  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| request | <code>CreateApplicationRequest</code> | The request object that contains the necessary information to create a new application |
+| request.name | <code>string</code> | The name of the application |
+| request.type | <code>ApplicationType</code> | The type of application (e.g., PROGRAMMABLE_VOICE) |
+| request.appEndpoint | <code>string</code> | The endpoint where the application is hosted |
+| request.textToSpeech | <code>TextToSpeech</code> | The text-to-speech configuration |
+| request.textToSpeech.productRef | <code>string</code> | The product reference of the text-to-speech engine (e.g., tts.google) |
+| request.textToSpeech.config | <code>object</code> | The configuration object for the text-to-speech engine (e.g., { voice: "en-US-Casual-K" }) |
+| request.speechToText | <code>SpeechToText</code> | The speech-to-text configuration |
+| request.speechToText.productRef | <code>string</code> | The product reference of the speech-to-text engine (e.g., stt.google) |
+| request.speechToText.config | <code>object</code> | The configuration object for the speech-to-text engine (e.g., { languageCode: "en-US" }) |
+| request.intelligence | <code>Intelligence</code> | The intelligence configuration |
+| request.intelligence.productRef | <code>string</code> | The product reference of the intelligence engine (e.g., nlu.dialogflowcx) |
+| request.intelligence.credentials | <code>object</code> | The credentials object for the intelligence engine (e.g., { apiKey: "your-api-key" }) |
+| request.intelligence.config | <code>object</code> | The configuration object for the intelligence engine (e.g., { agentId: "your-agent-id" }) |
+
+**Example**  
+```js
+const request = {
+  name: "My application",
+  type: "PROGRAMMABLE_VOICE",
+  appEndpoint: "myapp.mydomain.com",
+  textToSpeech: {
+    productRef: "tts.google",
+    config: {
+      voice: "en-US-Casual-K"
+    }
+  },
+  speechToText: {
+    productRef: "stt.google",
+    config: {
+     languageCode: "en-US"
+    }
+  },
+  intelligence: {
+    productRef: "nlu.dialogflowcx",
+    credentials: {
+       apiKey: "your-api-key"
+    },
+    config: {
+      agentId: "your-agent-id"
+    }
+  }
+};
+
+const apps = new SDK.Applications(client); // Existing client object
+
+apps.createApplication(request)
+ .then(console.log) // successful response
+ .catch(console.error); // an error occurred
+```
+<a name="Applications+getApplication"></a>
+
+### applications.getApplication(request) ⇒ <code>Promise.&lt;Application&gt;</code>
+Retrieves an existing application from Fonoster.
+
+**Kind**: instance method of [<code>Applications</code>](#Applications)  
+**Returns**: <code>Promise.&lt;Application&gt;</code> - - The response object that contains the application information  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| request | <code>GetApplicationRequest</code> | The request object that contains the necessary information to retrieve an application |
+| request.ref | <code>string</code> | The reference of the application to retrieve |
+
+**Example**  
+```js
+const request = {
+ ref: "00000000-0000-0000-0000-000000000000"
+};
+
+const apps = new SDK.Applications(client); // Existing client object
+
+apps.getApplication(request)
+ .then(console.log) // successful response
+ .catch(console.error); // an error occurred
+```
+<a name="Applications+updateApplication"></a>
+
+### applications.updateApplication(request) ⇒ <code>Promise.&lt;BaseApiObject&gt;</code>
+Updates an existing application in Fonoster.
+
+**Kind**: instance method of [<code>Applications</code>](#Applications)  
+**Returns**: <code>Promise.&lt;BaseApiObject&gt;</code> - - The response object that contains the reference to the updated application  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| request | <code>UpdateApplicationRequest</code> | The request object that contains the necessary information to update an application |
+| request.ref | <code>string</code> | The reference of the application to update |
+| request.name | <code>string</code> | The name of the application |
+| request.appEndpoint | <code>string</code> | The endpoint where the application is hosted |
+| request.textToSpeech | <code>TextToSpeech</code> | The text-to-speech configuration |
+| request.textToSpeech.productRef | <code>string</code> | The product reference of the text-to-speech engine (e.g., tts.google) |
+| request.textToSpeech.config | <code>object</code> | The configuration object for the text-to-speech engine (e.g., { voice: "en-US-Casual-K" }) |
+| request.speechToText | <code>SpeechToText</code> | The speech-to-text configuration |
+| request.speechToText.productRef | <code>string</code> | The product reference of the speech-to-text engine (e.g., stt.google) |
+| request.speechToText.config | <code>object</code> | The configuration object for the speech-to-text engine (e.g., { languageCode: "en-US" }) |
+| request.intelligence | <code>Intelligence</code> | The intelligence configuration |
+| request.intelligence.productRef | <code>string</code> | The product reference of the intelligence engine (e.g., nlu.dialogflowcx) |
+| request.intelligence.credentials | <code>object</code> | The credentials object for the intelligence engine (e.g., { apiKey: "your-api-key" }) |
+| request.intelligence.config | <code>object</code> | The configuration object for the intelligence engine (e.g., { agentId: "your-agent-id" }) |
+
+**Example**  
+```js
+const request = {
+ ref: "00000000-0000-0000-0000-000000000000",
+ name: "My application",
+ appEndpoint: "myapp.mydomain.com"
+}
+
+const apps = new SDK.Applications(client); // Existing client object
+
+apps.updateApplication(request)
+ .then(console.log) // successful response
+ .catch(console.error); // an error occurred
+```
+<a name="Applications+listApplications"></a>
+
+### applications.listApplications(request) ⇒ <code>Promise.&lt;ListApplicationsResponse&gt;</code>
+Retrieves a list of applications from Fonoster.
+
+**Kind**: instance method of [<code>Applications</code>](#Applications)  
+**Returns**: <code>Promise.&lt;ListApplicationsResponse&gt;</code> - - The response object that contains the list of applications  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| request | <code>ListApplicationsRequest</code> | The request object that contains the necessary information to retrieve a list of applications |
+| request.pageSize | <code>number</code> | The number of applications to retrieve |
+| request.pageToken | <code>string</code> | The token to retrieve the next page of applications |
+
+**Example**  
+```js
+const request = {
+ pageSize: 10,
+ pageToken: "00000000-0000-0000-0000-000000000000"
+};
+
+const apps = new SDK.Applications(client); // Existing client object
+
+apps.listApplications(request)
+ .then(console.log) // successful response
+ .catch(console.error); // an error occurred
+```
+<a name="Applications+deleteApplication"></a>
+
+### applications.deleteApplication(request) ⇒ <code>Promise.&lt;BaseApiObject&gt;</code>
+Deletes an existing application from Fonoster.
+Note that this operation is irreversible.
+
+**Kind**: instance method of [<code>Applications</code>](#Applications)  
+**Returns**: <code>Promise.&lt;BaseApiObject&gt;</code> - - The response object that contains the reference to the deleted application  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| request | <code>DeleteApplicationRequest</code> | The request object that contains the necessary information to delete an application |
+| request.ref | <code>string</code> | The reference of the application to delete |
+
+**Example**  
+```js
+const request = {
+ ref: "00000000-0000-0000-0000-000000000000"
+};
+
+const apps = new SDK.Applications(client); // Existing client object
+
+apps.deleteApplication(request)
+ .then(console.log) // successful response
+ .catch(console.error); // an error occurred
+```
 
-This module is part of the \[Fonoster\](https://fonoster.com) project. By itself, it does not do much. It is intended to be used as a dependency for other modules. For more information about the project, please visit \[https://github.com/fonoster/fonoster\](https://github.com/fonoster/fonoster).a](../apiserver/README.md)

package/dist/node/Applications.d.ts

@@ -0,0 +1,206 @@
+import { Application, BaseApiObject, CreateApplicationRequest, CreateApplicationResponse, ListApplicationsRequest, ListApplicationsResponse, UpdateApplicationRequest } from "@fonoster/common";
+import { FonosterClient } from "./client/types";
+/**
+ * @classdesc Fonoster Applications, part of the Fonoster Voice Subsystem,
+ * allow you to create, update, retrieve, and delete Voice Applications.
+ * Note that an active Fonoster deployment is required.
+ *
+ * @example
+ *
+ * const SDK = require("@fonoster/sdk");
+ *
+ * const request = {
+ *   name: "My application",
+ *   type: "PROGRAMMABLE_VOICE",
+ *   appEndpoint: "myapp.mydomain.com",
+ *   textToSpeech: {
+ *     productRef: "tts.google",
+ *     config: {
+ *       voice: "en-US-Casual-K"
+ *     }
+ *   },
+ *   speechToText: {
+ *     productRef: "stt.google",
+ *     config: {
+ *      languageCode: "en-US"
+ *     }
+ *   },
+ *   intelligence: {
+ *     productRef: "nlu.dialogflowcx",
+ *     credentials: {
+ *        apiKey: "your-api-key"
+ *     },
+ *     config: {
+ *       agentId: "your-agent-id"
+ *     }
+ *   }
+ * };
+ *
+ * const username = "admin@fonoster.local";
+ * const password = "changeme";
+ * const accessKeyId = "WO00000000000000000000000000000000";
+ *
+ * const client = new SDK.Client({ accessKeyId });
+ *
+ * client.login(username, password)
+ *  .then(async () => {
+ *    const apps = new SDK.Applications(client);
+ *    const result = await apps.createApplication(request);
+ *    console.log(result);  // successful response
+ *  }).catch(console.error); // an error occurred
+ */
+declare class Applications {
+    private client;
+    /**
+     * Constructs a new Applications object.
+     *
+     * @param {FonosterClient} client - Client object with underlying implementations to make requests to Fonoster's API
+     * @see AbstractClient
+     * @see FonosterClient
+     */
+    constructor(client: FonosterClient);
+    /**
+     * Creates a new Application in Fonoster. The only required fields are the name and type of the application.
+     *
+     * @param {CreateApplicationRequest} request - The request object that contains the necessary information to create a new application
+     * @param {string} request.name - The name of the application
+     * @param {ApplicationType} request.type - The type of application (e.g., PROGRAMMABLE_VOICE)
+     * @param {string} request.appEndpoint - The endpoint where the application is hosted
+     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
+     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.google)
+     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "en-US-Casual-K" })
+     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
+     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.google)
+     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { languageCode: "en-US" })
+     * @param {Intelligence} request.intelligence - The intelligence configuration
+     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., nlu.dialogflowcx)
+     * @param {object} request.intelligence.credentials - The credentials object for the intelligence engine (e.g., { apiKey: "your-api-key" })
+     * @param {object} request.intelligence.config - The configuration object for the intelligence engine (e.g., { agentId: "your-agent-id" })
+     * @return {Promise<CreateAppResponse>} - The response object that contains the reference to the newly created application
+     * @example
+     *
+     * const request = {
+     *   name: "My application",
+     *   type: "PROGRAMMABLE_VOICE",
+     *   appEndpoint: "myapp.mydomain.com",
+     *   textToSpeech: {
+     *     productRef: "tts.google",
+     *     config: {
+     *       voice: "en-US-Casual-K"
+     *     }
+     *   },
+     *   speechToText: {
+     *     productRef: "stt.google",
+     *     config: {
+     *      languageCode: "en-US"
+     *     }
+     *   },
+     *   intelligence: {
+     *     productRef: "nlu.dialogflowcx",
+     *     credentials: {
+     *        apiKey: "your-api-key"
+     *     },
+     *     config: {
+     *       agentId: "your-agent-id"
+     *     }
+     *   }
+     * };
+     *
+     * const apps = new SDK.Applications(client); // Existing client object
+     *
+     * apps.createApplication(request)
+     *  .then(console.log) // successful response
+     *  .catch(console.error); // an error occurred
+     */
+    createApplication(request: CreateApplicationRequest): Promise<CreateApplicationResponse>;
+    /**
+     * Retrieves an existing application from Fonoster.
+     *
+     * @param {string} ref - The reference of the application to retrieve
+     * @return {Promise<Application>} - The response object that contains the application information
+     * @example
+     *
+     * const request = {
+     *  ref: "00000000-0000-0000-0000-000000000000"
+     * };
+     *
+     * const apps = new SDK.Applications(client); // Existing client object
+     *
+     * apps.getApplication(request)
+     *  .then(console.log) // successful response
+     *  .catch(console.error); // an error occurred
+     */
+    getApplication(ref: string): Promise<Application>;
+    /**
+     * Updates an existing application in Fonoster.
+     *
+     * @param {UpdateApplicationRequest} request - The request object that contains the necessary information to update an application
+     * @param {string} request.ref - The reference of the application to update
+     * @param {string} request.name - The name of the application
+     * @param {string} request.appEndpoint - The endpoint where the application is hosted
+     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
+     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.google)
+     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "en-US-Casual-K" })
+     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
+     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.google)
+     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { languageCode: "en-US" })
+     * @param {Intelligence} request.intelligence - The intelligence configuration
+     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., nlu.dialogflowcx)
+     * @param {object} request.intelligence.credentials - The credentials object for the intelligence engine (e.g., { apiKey: "your-api-key" })
+     * @param {object} request.intelligence.config - The configuration object for the intelligence engine (e.g., { agentId: "your-agent-id" })
+     * @return {Promise<BaseApiObject>} - The response object that contains the reference to the updated application
+     * @example
+     *
+     * const request = {
+     *  ref: "00000000-0000-0000-0000-000000000000",
+     *  name: "My application",
+     *  appEndpoint: "myapp.mydomain.com"
+     * }
+     *
+     * const apps = new SDK.Applications(client); // Existing client object
+     *
+     * apps.updateApplication(request)
+     *  .then(console.log) // successful response
+     *  .catch(console.error); // an error occurred
+     */
+    updateApplication(request: UpdateApplicationRequest): Promise<BaseApiObject>;
+    /**
+     * Retrieves a list of applications from Fonoster.
+     *
+     * @param {ListApplicationsRequest} request - The request object that contains the necessary information to retrieve a list of applications
+     * @param {number} request.pageSize - The number of applications to retrieve
+     * @param {string} request.pageToken - The token to retrieve the next page of applications
+     * @return {Promise<ListApplicationsResponse>} - The response object that contains the list of applications
+     * @example
+     *
+     * const request = {
+     *  pageSize: 10,
+     *  pageToken: "00000000-0000-0000-0000-000000000000"
+     * };
+     *
+     * const apps = new SDK.Applications(client); // Existing client object
+     *
+     * apps.listApplications(request)
+     *  .then(console.log) // successful response
+     *  .catch(console.error); // an error occurred
+     */
+    listApplications(request: ListApplicationsRequest): Promise<ListApplicationsResponse>;
+    /**
+     * Deletes an existing application from Fonoster.
+     * Note that this operation is irreversible.
+     *
+     * @param {string} ref - The reference of the application to delete
+     * @return {Promise<BaseApiObject>} - The response object that contains the reference to the deleted application
+     * @example
+     *
+     * const ref =  "00000000-0000-0000-0000-000000000000"
+     *
+     * const apps = new SDK.Applications(client); // Existing client object
+     *
+     * apps.deleteApplication(ref)
+     *  .then(console.log) // successful response
+     *  .catch(console.error); // an error occurred
+     */
+    deleteApplication(ref: string): Promise<BaseApiObject>;
+}
+export { Applications };