DEVEXP-308: Fax API

examples/simple-examples/.env.template

@@ -39,3 +39,8 @@ MESSAGE_ID=message_id to fill with one of the messages sent or injected with the
 TEMPLATE_ID=template_id to fill with one of the templates created with the Templates API (v1 or v2)
 WEBHOOK_ID=webhook_id to fill with one of the webhooks created with the Conversation API or the Dashboard
 WEBHOOK_TARGET=target URL where the events should be sent to
+## Fax API
+FAX_SERVICE_ID=serviceId to fill with one the fax services created with the Fax API
+FAX_ID=id from a sendFax response
+FAX_CALLBACK_URL=callback url to override the one defined in the default service or specified service
+FAX_EMAIL=email to associate with a phone number to use the fax-to-email functionality

examples/simple-examples/.gitignore

@@ -6,3 +6,4 @@
 .DS_Store
 
 .env
+fax-pdf/

examples/simple-examples/README.md

@@ -70,6 +70,11 @@ MESSAGE_ID=message_id to fill with one of the messages sent or injected with the
 TEMPLATE_ID=template_id to fill with one of the templates created with the Templates API (v1 or v2)
 WEBHOOK_ID=webhook_id to fill with one of the webhooks created with the Conversation API or the Dashboard
 WEBHOOK_TARGET=target URL where the events should be sent to
+## Fax API
+FAX_SERVICE_ID=serviceId to fill with one the fax services created with the Fax API
+FAX_ID=id from a sendFax response
+FAX_CALLBACK_URL=callback url to override the one defined in the default service or specified service
+FAX_EMAIL=email to associate with a phone number to use the fax-to-email functionality
 ```
 
 **Note**: If you prefer using environment variables, the sample app is also supporting them: they take precedence over the value from the `.env` file.
@@ -225,3 +230,25 @@ yarn run numbers:regions:list
 |              | [./src/conversation/webhooks/list.ts](./src/conversation/webhooks/list.ts)                                   | `CONVERSATION_APP_ID`                                                                      |
 |              | [./src/conversation/webhooks/update.ts](./src/conversation/webhooks/update.ts)                               | `CONVERSATION_APP_ID` + `WEBHOOK_ID`                                                       |
 
+### Fax
+
+| Service  | Sample application name and location                                                   | Required parameters               |
+|----------|----------------------------------------------------------------------------------------|-----------------------------------|
+| Services | [./src/fax/services/create.ts](./src/fax/services/create.ts)                           | `PHONE_NUMBER`                    |
+|          | [./src/fax/services/get.ts](./src/fax/services/get.ts)                                 | `FAX_SERVICE_ID`                  |
+|          | [./src/fax/services/list.ts](./src/fax/services/list.ts)                               |                                   |
+|          | [./src/fax/services/listNumbers.ts](./src/fax/services/listNumbers.ts)                 | `FAX_SERVICE_ID`                  |
+|          | [./src/fax/services/listEmailsForNumber.ts](./src/fax/services/listEmailsForNumber.ts) | `PHONE_NUMBER` + `FAX_SERVICE_ID` |
+|          | [./src/fax/services/update.ts](./src/fax/services/update.ts)                           | `FAX_SERVICE_ID`                  |
+|          | [./src/fax/services/delete.ts](./src/fax/services/delete.ts)                           | `FAX_SERVICE_ID`                  |
+| Faxes    | [./src/fax/faxes/send.ts](./src/fax/faxes/send.ts)                                     | `PHONE_NUMBER`                    |
+|          | [./src/fax/faxes/get.ts](./src/fax/faxes/get.ts)                                       | `FAX_ID`                          |
+|          | [./src/fax/faxes/list.ts](./src/fax/faxes/list.ts)                                     |                                   |
+|          | [./src/fax/faxes/downloadContent.ts](./src/fax/faxes/downloadContent.ts)               | `FAX_ID`                          |
+|          | [./src/fax/faxes/deleteContent.ts](./src/fax/faxes/deleteContent.ts)                   | `FAX_ID`                          |
+| Emails   | [./src/fax/emails/add.ts](./src/fax/emails/add.ts)                                     | `FAX_EMAIL` + `PHONE_NUMBER`      |
+|          | [./src/fax/emails/list.ts](./src/fax/emails/list.ts)                                   |                                   |
+|          | [./src/fax/emails/listNumbers.ts](./src/fax/emails/listNumbers.ts)                     | `FAX_EMAIL`                       |
+|          | [./src/fax/emails/update.ts](./src/fax/emails/update.ts)                               | `FAX_EMAIL` + `PHONE_NUMBER`      |
+|          | [./src/fax/emails/delete.ts](./src/fax/emails/delete.ts)                               | `FAX_EMAIL`                       |
+

examples/simple-examples/package.json

@@ -56,6 +56,23 @@
     "conversation:templatev2:listTranslations": "ts-node src/conversation/templates-v2/list-translations.ts pretty",
     "conversation:templatev2:update": "ts-node src/conversation/templates-v2/update.ts",
     "conversation:templatev2:delete": "ts-node src/conversation/templates-v2/delete.ts",
+    "fax:services:create": "ts-node src/fax/services/create.ts",
+    "fax:services:get": "ts-node src/fax/services/get.ts",
+    "fax:services:list": "ts-node src/fax/services/list.ts",
+    "fax:services:listNumbers": "ts-node src/fax/services/listNumbers.ts",
+    "fax:services:listEmailsForNumber": "ts-node src/fax/services/listEmailsForNumber.ts",
+    "fax:services:update": "ts-node src/fax/services/update.ts",
+    "fax:services:delete": "ts-node src/fax/services/delete.ts",
+    "fax:faxes:send": "ts-node src/fax/faxes/send.ts",
+    "fax:faxes:get": "ts-node src/fax/faxes/get.ts",
+    "fax:faxes:list": "ts-node src/fax/faxes/list.ts",
+    "fax:faxes:download": "ts-node src/fax/faxes/downloadContent.ts",
+    "fax:faxes:delete": "ts-node src/fax/faxes/deleteContent.ts",
+    "fax:emails:add": "ts-node src/fax/emails/add.ts",
+    "fax:emails:list": "ts-node src/fax/emails/list.ts",
+    "fax:emails:listNumbers": "ts-node src/fax/emails/listNumbers.ts",
+    "fax:emails:update": "ts-node src/fax/emails/update.ts",
+    "fax:emails:delete": "ts-node src/fax/emails/delete.ts",
     "numbers:regions:list": "ts-node src/numbers/regions/list.ts",
     "numbers:available:list": "ts-node src/numbers/available/list.ts",
     "numbers:available:checkAvailability": "ts-node src/numbers/available/checkAvailability.ts",

examples/simple-examples/src/config.ts

@@ -145,6 +145,22 @@ export const getEventIdFromConfig = () => {
   return readVariable('EVENT_ID');
 };
 
+export const getFaxServiceIdFromConfig = () => {
+  return readVariable('FAX_SERVICE_ID');
+};
+
+export const getFaxIdFromConfig = () => {
+  return readVariable('FAX_ID');
+};
+
+export const getFaxCallbackUrlFromConfig = () => {
+  return readVariable('FAX_CALLBACK_URL');
+};
+
+export const getFaxEmailFromConfig = () => {
+  return readVariable('FAX_EMAIL');
+};
+
 const readVariable = ( name: string): string => {
   const value = process.env[name];
   if (!value) {

examples/simple-examples/src/fax/emails/add.ts

@@ -0,0 +1,37 @@
+import { AddEmailToNumbersRequestData } from '@sinch/sdk-core';
+import {
+  getFaxEmailFromConfig,
+  getPhoneNumberFromConfig,
+  getPrintFormat,
+  initClient,
+  printFullResponse,
+} from '../../config';
+
+(async () => {
+  console.log('*************************');
+  console.log('* createEmailForProject *');
+  console.log('*************************');
+
+  const phoneNumber = getPhoneNumberFromConfig();
+  const email = getFaxEmailFromConfig();
+
+  const requestData: AddEmailToNumbersRequestData = {
+    emailRequestBody: {
+      email,
+      phoneNumbers: [
+        phoneNumber,
+      ],
+    },
+  };
+
+  const sinchClient = initClient();
+  const response = await sinchClient.fax.emails.addToNumbers(requestData);
+
+  const printFormat = getPrintFormat(process.argv);
+
+  if (printFormat === 'pretty') {
+    console.log(`Email successfully added to numbers '${response.phoneNumbers?.join(', ')}'`);
+  } else {
+    printFullResponse(response);
+  }
+})();

examples/simple-examples/src/fax/emails/delete.ts

@@ -0,0 +1,19 @@
+import { DeleteEmailRequestData } from '@sinch/sdk-core';
+import { getFaxEmailFromConfig, initClient } from '../../config';
+
+(async () => {
+  console.log('***************');
+  console.log('* deleteEmail *');
+  console.log('***************');
+
+  const email = getFaxEmailFromConfig();
+
+  const requestData: DeleteEmailRequestData = {
+    email,
+  };
+
+  const sinchClient = initClient();
+  await sinchClient.fax.emails.delete(requestData);
+
+  console.log(`The email '${requestData.email}' has been successfully removed`);
+})();

examples/simple-examples/src/fax/emails/list.ts

@@ -0,0 +1,67 @@
+import { Email, ListEmailsForProjectRequestData, PageResult } from '@sinch/sdk-core';
+import { getPrintFormat, initClient, printFullResponse } from '../../config';
+
+const populateEmailsList = (
+  emailsPage: PageResult<Email>,
+  fullEmailsList: Email[],
+  emailsList: string[],
+) => {
+  fullEmailsList.push(...emailsPage.data);
+  emailsPage.data.map((email) =>  {
+    emailsList.push(`Email '${email.email}' - Phone numbers: '${email.phoneNumbers?.join(', ')}'`);
+  });
+};
+
+(async () => {
+  console.log('***********************');
+  console.log('* getEmailsForProject *');
+  console.log('***********************');
+
+  const requestData: ListEmailsForProjectRequestData = {
+    pageSize: 2,
+  };
+
+  const sinchClient = initClient();
+
+  // ----------------------------------------------
+  // Method 1: Fetch the data page by page manually
+  // ----------------------------------------------
+  let response = await sinchClient.fax.emails.list(requestData);
+
+  // Init data structure to hold the response content
+  const fullEmailsList: Email[] = [];
+  // Init data structure to hold the response content for pretty print
+  const emailsList: string[] = [];
+
+  // Loop on all the pages to get all the emails
+  let reachedEndOfPages = false;
+  while (!reachedEndOfPages) {
+    populateEmailsList(response, fullEmailsList, emailsList);
+    if (response.hasNextPage) {
+      response = await response.nextPage();
+    } else {
+      reachedEndOfPages = true;
+    }
+  }
+
+  const printFormat = getPrintFormat(process.argv);
+
+  if (printFormat === 'pretty') {
+    console.log(emailsList.length > 0
+      ? `List of emails:\n${emailsList.join('\n')}`
+      : 'Sorry, no emails were found');
+  } else {
+    printFullResponse(fullEmailsList);
+  }
+
+  // ---------------------------------------------------------------------
+  // Method 2: Use the iterator and fetch data on more pages automatically
+  // ---------------------------------------------------------------------
+  for await (const email of sinchClient.fax.emails.list(requestData)) {
+    if (printFormat === 'pretty') {
+      console.log(`Email '${email.email}' - Phone numbers: '${email.phoneNumbers?.join(', ')}'`);
+    } else {
+      console.log(email);
+    }
+  }
+})();

examples/simple-examples/src/fax/emails/listNumbers.ts

@@ -0,0 +1,74 @@
+import {
+  ListNumbersByEmailRequestData,
+  PageResult,
+  ServicePhoneNumber,
+} from '@sinch/sdk-core';
+import { getFaxEmailFromConfig, getPrintFormat, initClient, printFullResponse } from '../../config';
+
+const populateServiceNumbersList = (
+  serviceNumbersPage: PageResult<ServicePhoneNumber>,
+  fullServiceNumbersList: ServicePhoneNumber[],
+  serviceNumbersList: string[],
+) => {
+  fullServiceNumbersList.push(...serviceNumbersPage.data);
+  serviceNumbersPage.data.map((number) =>  {
+    serviceNumbersList.push(`Phone numbers: '${number.phoneNumber}'`);
+  });
+};
+
+(async () => {
+  console.log('*********************');
+  console.log('* getNumbersByEmail *');
+  console.log('*********************');
+
+  const email = getFaxEmailFromConfig();
+
+  const requestData: ListNumbersByEmailRequestData = {
+    email,
+    pageSize: 2,
+  };
+
+  const sinchClient = initClient();
+
+  // ----------------------------------------------
+  // Method 1: Fetch the data page by page manually
+  // ----------------------------------------------
+  let response = await sinchClient.fax.emails.listNumbers(requestData);
+
+  // Init data structure to hold the response content
+  const fullServiceNumbersList: ServicePhoneNumber[] = [];
+  // Init data structure to hold the response content for pretty print
+  const serviceNumbersList: string[] = [];
+
+  // Loop on all the pages to get all the numbers
+  let reachedEndOfPages = false;
+  while (!reachedEndOfPages) {
+    populateServiceNumbersList(response, fullServiceNumbersList, serviceNumbersList);
+    if (response.hasNextPage) {
+      response = await response.nextPage();
+    } else {
+      reachedEndOfPages = true;
+    }
+  }
+
+  const printFormat = getPrintFormat(process.argv);
+
+  if (printFormat === 'pretty') {
+    console.log(serviceNumbersList.length > 0
+      ? `List of configured numbers for the email '${requestData.email}':\n${serviceNumbersList.join('\n')}`
+      : 'Sorry, no numbers were found');
+  } else {
+    printFullResponse(fullServiceNumbersList);
+  }
+
+  // ---------------------------------------------------------------------
+  // Method 2: Use the iterator and fetch data on more pages automatically
+  // ---------------------------------------------------------------------
+  for await (const number of sinchClient.fax.emails.listNumbers(requestData)) {
+    if (printFormat === 'pretty') {
+      console.log(`Phone numbers: '${number.phoneNumber}'`);
+    } else {
+      console.log(number);
+    }
+  }
+})();

examples/simple-examples/src/fax/emails/update.ts

@@ -0,0 +1,38 @@
+import { UpdateEmailRequestData } from '@sinch/sdk-core';
+import {
+  getFaxEmailFromConfig,
+  getPhoneNumberFromConfig,
+  getPrintFormat,
+  initClient,
+  printFullResponse,
+} from '../../config';
+
+(async () => {
+  console.log('*************************');
+  console.log('* createEmailForProject *');
+  console.log('*************************');
+
+  const phoneNumber = getPhoneNumberFromConfig();
+  const email = getFaxEmailFromConfig();
+
+  const requestData: UpdateEmailRequestData = {
+    email,
+    updateEmailRequestBody: {
+      phoneNumbers: [
+        phoneNumber,
+        '+14155552222',
+      ],
+    },
+  };
+
+  const sinchClient = initClient();
+  const response = await sinchClient.fax.emails.update(requestData);
+
+  const printFormat = getPrintFormat(process.argv);
+
+  if (printFormat === 'pretty') {
+    console.log(`Email successfully updated with numbers '${response.phoneNumbers?.join(', ')}'`);
+  } else {
+    printFullResponse(response);
+  }
+})();

examples/simple-examples/src/fax/faxes/deleteContent.ts

@@ -0,0 +1,19 @@
+import { DeleteFaxContentRequestData } from '@sinch/sdk-core';
+import { getFaxIdFromConfig, initClient } from '../../config';
+
+(async () => {
+  console.log('************************');
+  console.log('* deleteFaxContentById *');
+  console.log('************************');
+
+  const faxId = getFaxIdFromConfig();
+
+  const requestData: DeleteFaxContentRequestData = {
+    id: faxId,
+  };
+
+  const sinchClient = initClient();
+  await sinchClient.fax.faxes.deleteContent(requestData);
+
+  console.log(`The content of the fax with the id '${requestData.id}' has been successfully removed from storage`);
+})();

examples/simple-examples/src/fax/faxes/downloadContent.ts

@@ -0,0 +1,25 @@
+import { DownloadFaxContentRequestData } from '@sinch/sdk-core';
+import { getFaxIdFromConfig, initClient } from '../../config';
+import * as fs from 'fs';
+import * as path from 'path';
+
+(async () => {
+  console.log('******************');
+  console.log('* getFaxFileById *');
+  console.log('******************');
+
+  const faxId = getFaxIdFromConfig();
+
+  const requestData: DownloadFaxContentRequestData = {
+    id: faxId,
+    fileFormat: 'pdf',
+  };
+
+  const sinchClient = initClient();
+  const response = await sinchClient.fax.faxes.downloadContent(requestData);
+
+  const filePath = path.join('./fax-pdf', response.fileName);
+  fs.writeFileSync(filePath, response.buffer);
+
+  console.log('File successfully downloaded');
+})();