@pipedream/twilio 0.3.3 → 0.3.5

package/README.md

@@ -0,0 +1,14 @@
+# Overview
+
+With the Twilio API, you can build telephone applications that make and receive
+phone calls, as well astext messaging applications that send and receive text
+messages.
+
+Some examples of applications you could build include:
+
+- A phone call application that allows you to make and receive phone calls over
+  the internet
+- A text messaging application that allows you to send and receive text
+  messages over the internet
+- A voicemail application that allows you to leave and receive voicemails over
+  the internet

package/actions/delete-call/delete-call.mjs

@@ -0,0 +1,23 @@
+import twilio from "../../twilio.app.mjs";
+
+export default {
+  key: "twilio-delete-call",
+  name: "Delete Call",
+  description: "Remove a call record from your account. [See the docs](https://www.twilio.com/docs/voice/api/call-resource#delete-a-call-resource) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    sid: {
+      propDefinition: [
+        twilio,
+        "sid",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.deleteCall(this.sid);
+    $.export("$summary", `Successfully deleted the call, "${this.sid}"`);
+    return resp;
+  },
+};

package/actions/delete-message/delete-message.mjs

@@ -0,0 +1,23 @@
+import twilio from "../../twilio.app.mjs";
+
+export default {
+  key: "twilio-delete-message",
+  name: "Delete Message",
+  description: "Delete a message record from your account. [See the docs](https://www.twilio.com/docs/sms/api/message-resource#delete-a-message-resource) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    messageId: {
+      propDefinition: [
+        twilio,
+        "messageId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.deleteMessage(this.messageId);
+    $.export("$summary", `Successfully deleted the message, "${this.messageId}"`);
+    return resp;
+  },
+};

package/actions/download-recording-media/download-recording-media.mjs

@@ -0,0 +1,50 @@
+import twilio from "../../twilio.app.mjs";
+import got from "got";
+import stream from "stream";
+import { promisify } from "util";
+import fs from "fs";
+
+export default {
+  key: "twilio-download-recording-media",
+  name: "Download Recording Media",
+  description: "Download a recording media file. [See the docs](https://www.twilio.com/docs/voice/api/recording#fetch-a-recording-media-file) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    recordingID: {
+      propDefinition: [
+        twilio,
+        "recordingID",
+      ],
+    },
+    format: {
+      propDefinition: [
+        twilio,
+        "format",
+      ],
+    },
+    filePath: {
+      type: "string",
+      label: "File Path",
+      description: "The destination path in [`/tmp`](https://pipedream.com/docs/workflows/steps/code/nodejs/working-with-files/#the-tmp-directory) for the downloaded the file (e.g., `/tmp/myFile.mp3`)",
+    },
+  },
+  async run({ $ }) {
+    // Get Recording resource to get `uri`
+    const recording = await this.twilio.getRecording(this.recordingID);
+    const client = this.twilio.getClient();
+    // `uri` ends in ".json" - remove ".json" from uri
+    const uri = client.api.absoluteUrl(recording.uri).replace(".json", "");
+    // Add chosen download format extension (e.g. ".mp3"), as specified in the Twilio API docs:
+    // https://www.twilio.com/docs/voice/api/recording#fetch-a-recording-media-file
+    const downloadUrl = uri + this.format;
+    const pipeline = promisify(stream.pipeline);
+    const resp = await pipeline(
+      got.stream(downloadUrl),
+      fs.createWriteStream(this.filePath),
+    );
+    $.export("$summary", `Successfully downloaded the recording media file to "${this.filePath}"`);
+    return resp;
+  },
+};

package/actions/get-call/get-call.mjs

@@ -0,0 +1,24 @@
+import twilio from "../../twilio.app.mjs";
+import { callToString } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-get-call",
+  name: "Get Call",
+  description: "Return call resource of an individual call. [See the docs](https://www.twilio.com/docs/voice/api/call-resource#fetch-a-call-resource) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    sid: {
+      propDefinition: [
+        twilio,
+        "sid",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.getCall(this.sid);
+    $.export("$summary", `Successfully fetched the call, "${callToString(resp)}"`);
+    return resp;
+  },
+};

package/actions/get-message/get-message.mjs

@@ -0,0 +1,24 @@
+import twilio from "../../twilio.app.mjs";
+import { messageToString } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-get-message",
+  name: "Get Message",
+  description: "Return details of a message. [See the docs](https://www.twilio.com/docs/sms/api/message-resource#fetch-a-message-resource) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    messageId: {
+      propDefinition: [
+        twilio,
+        "messageId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.getMessage(this.messageId);
+    $.export("$summary", `Successfully fetched the message, "${messageToString(resp)}"`);
+    return resp;
+  },
+};

package/actions/list-calls/list-calls.mjs

@@ -0,0 +1,60 @@
+import twilio from "../../twilio.app.mjs";
+import { omitEmptyStringValues } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-list-calls",
+  name: "List Calls",
+  description: "Return a list of calls associated with your account. [See the docs](https://www.twilio.com/docs/voice/api/call-resource#read-multiple-call-resources) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    from: {
+      propDefinition: [
+        twilio,
+        "from",
+      ],
+      description: "Only include calls from this phone number, SIP address, Client identifier or SIM SID. Format the phone number in E.164 format with a `+` and country code (e.g., `+16175551212`).",
+      optional: true,
+    },
+    to: {
+      propDefinition: [
+        twilio,
+        "to",
+      ],
+      description: "Only show calls made to this phone number, SIP address, Client identifier or SIM SID. Format the phone number in E.164 format with a `+` and country code (e.g., `+16175551212`).",
+      optional: true,
+    },
+    parentCallSid: {
+      propDefinition: [
+        twilio,
+        "parentCallSid",
+      ],
+    },
+    status: {
+      propDefinition: [
+        twilio,
+        "status",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        twilio,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.listCalls(omitEmptyStringValues({
+      to: this.to,
+      from: this.from,
+      parentCallSid: this.parentCallSid,
+      status: this.status,
+      limit: this.limit,
+    }));
+    /* eslint-disable multiline-ternary */
+    $.export("$summary", `Successfully fetched ${resp.length} call${resp.length === 1 ? "" : "s"}${
+      this.from ? ` from ${this.from}` : ""}${this.to ? ` to ${this.to}` : ""}`);
+    return resp;
+  },
+};

package/actions/list-message-media/list-message-media.mjs

@@ -0,0 +1,34 @@
+import twilio from "../../twilio.app.mjs";
+import { omitEmptyStringValues } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-list-message-media",
+  name: "List Message Media",
+  description: "Return a list of media associated with your message. [See the docs](https://www.twilio.com/docs/sms/api/media-resource#read-multiple-media-resources) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    messageId: {
+      propDefinition: [
+        twilio,
+        "messageId",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        twilio,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.listMessageMedia(this.messageId, omitEmptyStringValues({
+      limit: this.limit,
+    }));
+    $.export("$summary", `Successfully fetched ${resp.length} media object${resp.length === 1
+      ? ""
+      : "s"} associated with the message, "${this.messageId}"`);
+    return resp;
+  },
+};

package/actions/list-messages/list-messages.mjs

@@ -0,0 +1,60 @@
+import { phone } from "phone";
+import twilio from "../../twilio.app.mjs";
+import { omitEmptyStringValues } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-list-messages",
+  name: "List Messages",
+  description: "Return a list of messages associated with your account. [See the docs](https://www.twilio.com/docs/sms/api/message-resource#read-multiple-message-resources) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    from: {
+      propDefinition: [
+        twilio,
+        "from",
+      ],
+      description: "Read messages sent from only this phone number or alphanumeric sender ID. Format the phone number in E.164 format with a `+` and country code (e.g., `+16175551212`).",
+      optional: true,
+    },
+    to: {
+      propDefinition: [
+        twilio,
+        "to",
+      ],
+      description: "Read messages sent to only this phone number. Format the phone number in E.164 format with a `+` and country code (e.g., `+16175551212`).",
+      optional: true,
+    },
+    limit: {
+      propDefinition: [
+        twilio,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    // Parse the given number into its E.164 equivalent
+    // The E.164 phone number will be included in the first element
+    // of the array, but the array will be empty if parsing fails.
+    // See https://www.npmjs.com/package/phone
+    let to = this.to;
+    if (this.to) {
+      const toParsed = phone(this.to);
+      if (!toParsed || !toParsed.phoneNumber) {
+        throw new Error(`Phone number ${this.to} couldn't be parsed as a valid number.`);
+      }
+      to = toParsed.phoneNumber;
+    }
+
+    const resp = await this.twilio.listMessages(omitEmptyStringValues({
+      to,
+      from: this.from,
+      limit: this.limit,
+    }));
+    /* eslint-disable multiline-ternary */
+    $.export("$summary", `Successfully fetched ${resp.length} message${resp.length === 1 ? "" : "s"}${
+      this.from ? ` from ${this.from}` : ""}${this.to ? ` to ${this.to}` : ""}`);
+    return resp;
+  },
+};

package/actions/list-recording-transcriptions/list-recording-transcriptions.mjs

@@ -0,0 +1,37 @@
+import twilio from "../../twilio.app.mjs";
+import { omitEmptyStringValues } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-list-recording-transcriptions",
+  name: "List Recording Transcriptions",
+  description: "Return a set of transcriptions available for a recording. [See the docs](https://www.twilio.com/docs/voice/api/recording#fetch-a-recordings-transcriptions) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    recordingID: {
+      propDefinition: [
+        twilio,
+        "recordingID",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        twilio,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const resp = await this.twilio.listRecordingTranscriptions(
+      this.recordingID,
+      omitEmptyStringValues({
+        limit: this.limit,
+      }),
+    );
+    $.export("$summary", `Successfully fetched ${resp.length} recording transcription${resp.length === 1
+      ? ""
+      : "s"} for the recording, "${this.recordingID}"`);
+    return resp;
+  },
+};

package/actions/make-phone-call/make-phone-call.mjs

@@ -0,0 +1,52 @@
+import { phone } from "phone";
+import twilio from "../../twilio.app.mjs";
+import { callToString } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-make-phone-call",
+  name: "Make a Phone Call",
+  description: "Make a phone call, passing text that Twilio will speak to the recipient of the call. [See the docs](https://www.twilio.com/docs/voice/api/call-resource#create-a-call-resource) for more information",
+  version: "0.1.0",
+  type: "action",
+  props: {
+    twilio,
+    from: {
+      propDefinition: [
+        twilio,
+        "from",
+      ],
+    },
+    to: {
+      propDefinition: [
+        twilio,
+        "to",
+      ],
+    },
+    text: {
+      label: "Text",
+      type: "string",
+      description: "The text you'd like Twilio to speak to the user when they pick up the phone.",
+    },
+  },
+  async run({ $ }) {
+    // Parse the given number into its E.164 equivalent
+    // The E.164 phone number will be included in the first element
+    // of the array, but the array will be empty if parsing fails.
+    // See https://www.npmjs.com/package/phone
+    const toParsed = phone(this.to);
+    console.log(toParsed);
+    if (!toParsed || !toParsed.phoneNumber) {
+      throw new Error(`Phone number ${this.to} couldn't be parsed as a valid number.`);
+    }
+
+    const data = {
+      to: toParsed.phoneNumber,
+      from: this.from,
+      twiml: `<Response><Say>${this.text}</Say></Response>`,
+    };
+
+    const resp = await this.twilio.getClient().calls.create(data);
+    $.export("$summary", `Successfully made a new phone call, "${callToString(resp)}"`);
+    return resp;
+  },
+};

package/actions/send-mms/send-mms.mjs

@@ -0,0 +1,59 @@
+import { phone } from "phone";
+import twilio from "../../twilio.app.mjs";
+import { messageToString } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-send-mms",
+  name: "Send MMS",
+  description: "Send an SMS with text and media files. [See the docs](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource) for more information",
+  type: "action",
+  version: "0.1.0",
+  props: {
+    twilio,
+    from: {
+      propDefinition: [
+        twilio,
+        "from",
+      ],
+    },
+    to: {
+      propDefinition: [
+        twilio,
+        "to",
+      ],
+    },
+    body: {
+      propDefinition: [
+        twilio,
+        "body",
+      ],
+    },
+    mediaUrl: {
+      propDefinition: [
+        twilio,
+        "mediaUrl",
+      ],
+    },
+  },
+  async run({ $ }) {
+    // Parse the given number into its E.164 equivalent
+    // The E.164 phone number will be included in the first element
+    // of the array, but the array will be empty if parsing fails.
+    // See https://www.npmjs.com/package/phone
+    const toParsed = phone(this.to);
+    if (!toParsed || !toParsed.phoneNumber) {
+      throw new Error(`Phone number ${this.to} couldn't be parsed as a valid number.`);
+    }
+
+    const data = {
+      to: toParsed.phoneNumber,
+      from: this.from,
+      body: this.body,
+      mediaUrl: this.mediaUrl,
+    };
+
+    const resp = await this.twilio.getClient().messages.create(data);
+    $.export("$summary", `Successfully sent a new MMS, "${messageToString(resp)}"`);
+    return resp;
+  },
+};

package/actions/send-sms/send-sms.mjs

@@ -0,0 +1,52 @@
+import { phone } from "phone";
+import twilio from "../../twilio.app.mjs";
+import { messageToString } from "../../common/utils.mjs";
+
+export default {
+  key: "twilio-send-sms",
+  name: "Send SMS",
+  description: "Send a simple text-only SMS. [See the docs](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource) for more information",
+  type: "action",
+  version: "0.1.0",
+  props: {
+    twilio,
+    from: {
+      propDefinition: [
+        twilio,
+        "from",
+      ],
+    },
+    to: {
+      propDefinition: [
+        twilio,
+        "to",
+      ],
+    },
+    body: {
+      propDefinition: [
+        twilio,
+        "body",
+      ],
+    },
+  },
+  async run({ $ }) {
+    // Parse the given number into its E.164 equivalent
+    // The E.164 phone number will be included in the first element
+    // of the array, but the array will be empty if parsing fails.
+    // See https://www.npmjs.com/package/phone
+    const toParsed = phone(this.to);
+    if (!toParsed || !toParsed.phoneNumber) {
+      throw new Error(`Phone number ${this.to} couldn't be parsed as a valid number.`);
+    }
+
+    const data = {
+      to: toParsed.phoneNumber,
+      from: this.from,
+      body: this.body,
+    };
+
+    const resp = await this.twilio.getClient().messages.create(data);
+    $.export("$summary", `Successfully sent a new SMS, "${messageToString(resp)}"`);
+    return resp;
+  },
+};

package/common/constants.mjs

@@ -0,0 +1,13 @@
+const HTTP_METHOD = {
+  POST: "POST",
+};
+
+const SERVICE_TYPE = {
+  SMS: "sms",
+  VOICE: "voice",
+};
+
+export default {
+  HTTP_METHOD,
+  SERVICE_TYPE,
+};

package/common/utils.mjs

@@ -0,0 +1,144 @@
+/**
+ * Format a number of seconds into a time elapsed string
+ *
+ * @example
+ * // returns "15s"
+ * formatTimeElapsed(15);
+ *
+ * @example
+ * // returns "35min"
+ * formatTimeElapsed(60 * 35.5);
+ *
+ * @param {Number} seconds - the number of seconds
+ * @returns the formatted time elapsed string
+ */
+function formatTimeElapsed(seconds) {
+  var interval = seconds / 31536000;
+
+  if (interval > 1) {
+    return Math.floor(interval) + " years";
+  }
+  interval = seconds / 2592000;
+  if (interval > 1) {
+    return Math.floor(interval) + " months";
+  }
+  interval = seconds / 86400;
+  if (interval > 1) {
+    return Math.floor(interval) + "d";
+  }
+  interval = seconds / 3600;
+  if (interval > 1) {
+    return Math.floor(interval) + "h";
+  }
+  interval = seconds / 60;
+  if (interval > 1) {
+    return Math.floor(interval) + "min";
+  }
+  return Math.floor(seconds) + "s";
+}
+
+/**
+ * Get the time between two dates as a time-elapsed string
+ *
+ * @param {Date} date1 the earlier date
+ * @param {Date} date2 the later date
+ * @returns the time elapsed between two dates
+ */
+function timeBetween(date1, date2) {
+  var seconds = Math.floor((date2 - date1) / 1000);
+
+  return formatTimeElapsed(seconds);
+}
+
+/**
+ * Return a copy of `obj` with properties omitted whose value is an empty string
+ *
+ * @param {Object} obj - the base object
+ * @returns the new object
+ */
+function omitEmptyStringValues(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter((kVpair) => kVpair[1] !== ""),
+  );
+}
+
+/**
+ * Return `value` if `condition` or an empty string otherwise
+ *
+ * @param {*} condition - the condition
+ * @param {*} value - the value to conditionally return
+ * @returns the value, if the condition is true, and empty string otherwise
+ */
+function valueOrEmptyString(condition, value) {
+  return condition
+    ? value
+    : "";
+}
+
+/**
+ * Format a date as a human-readable string
+ *
+ * @example
+ * // returns "2021-10-01"
+ * formatDateString("2021-10-01T01:06:45.000Z");
+ *
+ * @param {Date|String} date - the date to format
+ * @returns the formatted date string
+ */
+function formatDateString(date) {
+  const dateObj = new Date(date);
+  return dateObj.toISOString().split("T")[0];
+}
+
+/**
+ * Format a [Twilio Call object]{@link https://www.twilio.com/docs/voice/api/call-resource} as a
+ * string
+ *
+ * @param {Object} call - The Twilio Call object
+ * @returns the string representing a call
+ */
+function callToString(call) {
+  const fromPart = valueOrEmptyString(call.fromFormatted, call.fromFormatted);
+  const toPart = valueOrEmptyString(call.toFormatted, ` to ${call.toFormatted}`);
+  const datePart = valueOrEmptyString(call.startTime, ` on ${formatDateString(call.startTime)}`);
+  const durationPart = valueOrEmptyString(call.duration, ` for ${formatTimeElapsed(call.duration)}`);
+  return fromPart + toPart + datePart + durationPart;
+}
+
+/**
+ * Format a [Twilio Message object]{@link https://www.twilio.com/docs/sms/api/message-resource} as a
+ * string
+ *
+ * @param {Object} call - The Twilio Message object
+ * @returns the string representing a message
+ */
+function messageToString(message) {
+  const MAX_LENGTH = 30;
+  const messageText = message.body.length > MAX_LENGTH
+    ? `${message.body.slice(0, MAX_LENGTH)}...`
+    : message.body; // truncate long text
+  const messageDate = message.dateSent || message.dateCreated;
+  const dateString = formatDateString(messageDate);
+  return `${message.from} to ${message.to} on ${dateString}: ${messageText}`;
+}
+
+/**
+ * Format a [Twilio Recording object]{@link https://www.twilio.com/docs/voice/api/recording} as a
+ * string
+ *
+ * @param {Object} call - The Twilio Recording object
+ * @returns the string representing a recording
+ */
+function recordingToString(recording) {
+  const datePart = valueOrEmptyString(recording.startTime, ` ${formatDateString(recording.startTime)}`);
+  const durationPart = valueOrEmptyString(recording.duration, ` - ${formatTimeElapsed(recording.duration)}`);
+  return datePart + durationPart;
+}
+
+export {
+  timeBetween,
+  omitEmptyStringValues,
+  callToString,
+  messageToString,
+  recordingToString,
+};