@pipedream/twilio 0.3.3 → 0.3.5

package/package.json

@@ -1,20 +1,21 @@
 {
-    "name": "@pipedream/twilio",
-    "version": "0.3.3",
-    "description": "Pipedream Twilio Components",
-    "main": "twilio.app.js",
-    "keywords": [
-        "pipedream",
-        "twilio"
-    ],
-    "homepage": "https://pipedream.com/apps/twilio",
-    "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
-    "license": "MIT",
-    "dependencies": {
-        "twilio": "^3.54.2"
-    },
-    "gitHead": "12ad36100ee95629c1b22923c79923bfff156ca7",
-    "publishConfig": {
-        "access": "public"
-    }
-}
+  "name": "@pipedream/twilio",
+  "version": "0.3.5",
+  "description": "Pipedream Twilio Components",
+  "main": "twilio.app.mjs",
+  "keywords": [
+    "pipedream",
+    "twilio"
+  ],
+  "homepage": "https://pipedream.com/apps/twilio",
+  "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
+  "license": "MIT",
+  "dependencies": {
+    "phone": "^3.1.29",
+    "twilio": "^3.54.2"
+  },
+  "gitHead": "e12480b94cc03bed4808ebc6b13e7fdb3a1ba535",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/sources/common-polling.mjs

@@ -0,0 +1,44 @@
+import twilio from "../twilio.app.mjs";
+
+export default {
+  props: {
+    twilio,
+    db: "$.service.db",
+    timer: {
+      label: "Polling schedule",
+      description: "Pipedream polls Twilio for events on this schedule.",
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: 60 * 15,
+      },
+    },
+  },
+  methods: {
+    _getCreatedAfter() {
+      return this.db.get("createdAfter");
+    },
+    _setCreatedAfter(createdAfter) {
+      this.db.set("createdAfter", createdAfter);
+    },
+    emitEvent(result) {
+      const meta = this.generateMeta(result);
+      this.$emit(result, meta);
+    },
+  },
+  async run() {
+    let dateCreatedAfter = this._getCreatedAfter();
+    const params = {
+      dateCreatedAfter,
+    };
+    const results = await this.listResults(params);
+    for (const result of results) {
+      this.emitEvent(result);
+      if (
+        !dateCreatedAfter ||
+        Date.parse(result.dateCreated) > Date.parse(dateCreatedAfter)
+      )
+        dateCreatedAfter = result.dateCreated;
+    }
+    this._setCreatedAfter(dateCreatedAfter);
+  },
+};

package/sources/common-webhook.mjs

@@ -0,0 +1,99 @@
+import twilio from "../twilio.app.mjs";
+
+export default {
+  props: {
+    twilio,
+    incomingPhoneNumber: {
+      propDefinition: [
+        twilio,
+        "incomingPhoneNumber",
+      ],
+    },
+    http: {
+      label: "HTTP Responder",
+      description: "Exposes a `respond()` method that lets the source issue HTTP responses",
+      type: "$.interface.http",
+      customResponse: true,
+    },
+  },
+  hooks: {
+    async activate() {
+      const createWebhookResp = await this.twilio.setWebhookURL({
+        serviceType: this.getServiceType(),
+        phoneNumberSid: this.incomingPhoneNumber,
+        url: this.http.endpoint,
+      });
+      console.log(createWebhookResp);
+    },
+    async deactivate() {
+      // remove the webhook URL if url prop is not set
+      const deleteWebhookResp = await this.twilio.setWebhookURL({
+        serviceType: this.getServiceType(),
+        phoneNumberSid: this.incomingPhoneNumber,
+        url: "",
+      });
+      console.log(deleteWebhookResp);
+    },
+  },
+  methods: {
+    getServiceType() {
+      throw new Error("getServiceType() is not implemented!");
+    },
+    getResponseBody() {
+      return null;
+    },
+    isRelevant() {
+      return true;
+    },
+    emitEvent(body, headers) {
+      const meta = this.generateMeta(body, headers);
+      this.$emit(body, meta);
+    },
+  },
+  async run(event) {
+    let {
+      body,
+      headers,
+    } = event;
+
+    const responseBody = this.getResponseBody();
+    if (responseBody) {
+      this.http.respond({
+        status: 200,
+        headers: {
+          "Content-Type": "text/xml",
+        },
+        body: responseBody,
+      });
+    }
+
+    if (typeof body !== "object") {
+      body = Object.fromEntries(new URLSearchParams(body));
+    }
+
+    if (!this.isRelevant(body)) {
+      console.log("Event not relevant. Skipping...");
+      return;
+    }
+
+    const signature = headers["x-twilio-signature"];
+    if (!signature) {
+      console.log("No x-twilio-signature header in request. Exiting.");
+      return;
+    }
+
+    // The url must match the incoming URL exactly, which contains a `/` at the end
+    const isRequestValid = this.twilio.validateRequest({
+      signature,
+      url: `${this.http.endpoint}/`,
+      params: body,
+    });
+
+    if (!isRequestValid) {
+      console.log("Event could not be validated. Skipping...");
+      return;
+    }
+
+    this.emitEvent(body, headers);
+  },
+};

package/sources/new-call/new-call.mjs

@@ -0,0 +1,33 @@
+import common from "../common-webhook.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  ...common,
+  key: "twilio-new-call",
+  name: "New Call (Instant)",
+  description: "Emit new event each time a call to the phone number is completed. Configures a webhook in Twilio, tied to a phone number.",
+  version: "0.1.0",
+  type: "source",
+  dedupe: "unique",
+  methods: {
+    ...common.methods,
+    getServiceType() {
+      return constants.SERVICE_TYPE.VOICE;
+    },
+    generateMeta(body, headers) {
+      return {
+        /** if Twilio retries a message, but we've already emitted, dedupe */
+        id: headers["i-twilio-idempotency-token"],
+        summary: `New call from ${this.getMaskedNumber(body.From)}`,
+        ts: Date.now(),
+      };
+    },
+    isRelevant(body) {
+      return body.CallStatus == "completed";
+    },
+    getMaskedNumber(number) {
+      const { length: numberLength } = number;
+      return number.slice(numberLength - 4).padStart(numberLength, "#");
+    },
+  },
+};

package/sources/new-incoming-sms/new-incoming-sms.mjs

@@ -0,0 +1,47 @@
+import twilio from "twilio";
+import common from "../common-webhook.mjs";
+import constants from "../../common/constants.mjs";
+
+const MessagingResponse = twilio.twiml.MessagingResponse;
+
+export default {
+  ...common,
+  key: "twilio-new-incoming-sms",
+  name: "New Incoming SMS (Instant)",
+  description: "Emit new event every time an SMS is sent to the phone number set. Configures a webhook in Twilio, tied to an incoming phone number.",
+  version: "0.1.0",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    ...common.props,
+    responseMessage: {
+      propDefinition: [
+        common.props.twilio,
+        "responseMessage",
+      ],
+    },
+  },
+  methods: {
+    ...common.methods,
+    getServiceType() {
+      return constants.SERVICE_TYPE.SMS;
+    },
+    getResponseBody() {
+      const twiml = new MessagingResponse();
+      let responseBody = "<Response></Response>";
+      if (this.responseMessage) {
+        twiml.message(this.responseMessage);
+        responseBody = twiml.toString();
+      }
+      return responseBody;
+    },
+    generateMeta(body, headers) {
+      return {
+        /** if Twilio retries a message, but we've already emitted, dedupe */
+        id: headers["i-twilio-idempotency-token"],
+        summary: body.Body,
+        ts: Date.now(),
+      };
+    },
+  },
+};

package/sources/new-phone-number/new-phone-number.mjs

@@ -0,0 +1,29 @@
+import common from "../common-polling.mjs";
+
+export default {
+  ...common,
+  key: "twilio-new-phone-number",
+  name: "New Phone Number",
+  description: "Emit new event when you add a new phone number to your account",
+  version: "0.1.0",
+  type: "source",
+  dedupe: "unique",
+  methods: {
+    ...common.methods,
+    async listResults(...args) {
+      return await this.twilio.listIncomingPhoneNumbers(...args);
+    },
+    generateMeta(number) {
+      const {
+        sid: id,
+        friendlyName: summary,
+        dateCreated,
+      } = number;
+      return {
+        id,
+        summary,
+        ts: Date.parse(dateCreated),
+      };
+    },
+  },
+};

package/sources/new-recording/new-recording.mjs

@@ -0,0 +1,28 @@
+import common from "../common-polling.mjs";
+
+export default {
+  ...common,
+  key: "twilio-new-recording",
+  name: "New Recording",
+  description: "Emit new event when a new call recording is created",
+  version: "0.1.0",
+  type: "source",
+  dedupe: "unique",
+  methods: {
+    ...common.methods,
+    async listResults(...args) {
+      return await this.twilio.listRecordings(...args);
+    },
+    generateMeta(recording) {
+      const {
+        sid: id,
+        dateCreated,
+      } = recording;
+      return {
+        id,
+        summary: `New recording ${id}`,
+        ts: Date.parse(dateCreated),
+      };
+    },
+  },
+};

package/sources/new-transcription/new-transcription.mjs

@@ -0,0 +1,28 @@
+import common from "../common-polling.mjs";
+
+export default {
+  ...common,
+  key: "twilio-new-transcription",
+  name: "New Transcription",
+  description: "Emit new event when a new call transcription is created",
+  version: "0.1.0",
+  type: "source",
+  dedupe: "unique",
+  methods: {
+    ...common.methods,
+    async listResults(...args) {
+      return await this.twilio.listTranscriptions(...args);
+    },
+    generateMeta(transcription) {
+      const {
+        sid: id,
+        dateCreated,
+      } = transcription;
+      return {
+        id,
+        summary: `New transcription ${id}`,
+        ts: Date.parse(dateCreated),
+      };
+    },
+  },
+};

package/twilio.app.mjs

@@ -0,0 +1,338 @@
+import twilio from "twilio";
+import {
+  callToString,
+  messageToString,
+  recordingToString,
+} from "./common/utils.mjs";
+import constants from "./common/constants.mjs";
+
+export default {
+  type: "app",
+  app: "twilio",
+  propDefinitions: {
+    body: {
+      type: "string",
+      label: "Message Body",
+      description: "The text of the message you want to send, limited to 1600 characters.",
+    },
+    from: {
+      type: "string",
+      label: "From",
+      description: "The phone number or alphanumeric sender ID the message is from",
+      async options() {
+        const numbers = await this.listIncomingPhoneNumbers();
+        return numbers.map((number) => {
+          return {
+            label: number.friendlyName,
+            value: number.phoneNumber,
+          };
+        });
+      },
+    },
+    incomingPhoneNumber: {
+      type: "string",
+      label: "Incoming Phone Number",
+      description:
+        "The Twilio phone number where you'll receive messages. This source creates a webhook tied to this incoming phone number, **overwriting any existing webhook URL**.",
+      async options() {
+        const numbers = await this.listIncomingPhoneNumbers();
+        return numbers.map((number) => {
+          return {
+            label: number.friendlyName,
+            value: number.sid,
+          };
+        });
+      },
+    },
+    mediaUrl: {
+      type: "string[]",
+      label: "Media URL",
+      description: "The URL of the media you wish to send out with the message. The media size limit is `5MB`. You may provide up to 10 media URLs per message.",
+      optional: true,
+    },
+    responseMessage: {
+      type: "string",
+      optional: true,
+      label: "Response Message",
+      description:
+        "The message you want to send in response to incoming messages. Leave this blank if you don't need to issue a response.",
+    },
+    to: {
+      type: "string",
+      label: "To",
+      description: "The destination phone number in E.164 format. Format with a `+` and country code (e.g., `+16175551212`).",
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "The maximum number of results to be worked with during one execution cycle.",
+      optional: true,
+      default: 50,
+    },
+    messageId: {
+      type: "string",
+      label: "Message ID",
+      description: "The SID of the Message",
+      optional: true,
+      async options() {
+        const messages = await this.listMessages();
+        return messages.map((message) => {
+          return {
+            label: messageToString(message),
+            value: message.sid,
+          };
+        });
+      },
+    },
+    parentCallSid: {
+      type: "string",
+      label: "Parent Call SID",
+      description: "Only include calls spawned by calls with this SID.",
+      optional: true,
+      async options() {
+        return this.listCallsOptions();
+      },
+    },
+    sid: {
+      type: "string",
+      label: "Call ID",
+      description: "The SID of the Call",
+      optional: true,
+      async options() {
+        return this.listCallsOptions();
+      },
+    },
+    recordingID: {
+      type: "string",
+      label: "Recording ID",
+      description: "The SID of the Recording",
+      async options() {
+        const recordings = await this.listRecordings();
+        return recordings.map((recording) => {
+          return {
+            label: recordingToString(recording),
+            value: recording.sid,
+          };});
+      },
+    },
+    format: {
+      type: "string",
+      label: "Format",
+      description: "The format of the recording audio file",
+      options: [
+        {
+          label: "MP3",
+          value: ".mp3",
+        },
+        {
+          label: "WAV",
+          value: ".wav",
+        },
+      ],
+      default: ".wav",
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The status of the call",
+      optional: true,
+      options: [
+        "queued",
+        "ringing",
+        "in-progress",
+        "canceled",
+        "completed",
+        "failed",
+        "busy",
+        "no-answer",
+      ],
+    },
+  },
+  methods: {
+    validateRequest({
+      signature, url, params,
+    } = {}) {
+      // See https://www.twilio.com/docs/usage/webhooks/webhooks-security
+      return twilio.validateRequest(
+        this.$auth.authToken,
+        signature,
+        url,
+        params,
+      );
+    },
+    getClient() {
+      return twilio(this.$auth.accountSid, this.$auth.authToken);
+    },
+    setWebhookURL({
+      serviceType = constants.SERVICE_TYPE.SMS, phoneNumberSid, url,
+    } = {}) {
+      const opts = serviceType === constants.SERVICE_TYPE.SMS
+        ? {
+          smsMethod: constants.HTTP_METHOD.POST,
+          smsUrl: url,
+        }
+        : {
+          statusCallbackMethod: constants.HTTP_METHOD.POST,
+          statusCallback: url,
+        };
+      const client = this.getClient();
+      return client.incomingPhoneNumbers(phoneNumberSid).update(opts);
+    },
+    /**
+     * Returns a IncomingPhoneNumber list resource representing an account's
+     * Twilio phone numbers
+     *
+     * @param {object} [params] - an object containing parameters to be fed to
+     * the Twilio API call, as defined in [the API docs](https://bit.ly/3F8y6KY)
+     *
+     * @returns the IncomingPhoneNumber list
+     */
+    listIncomingPhoneNumbers(params) {
+      const client = this.getClient();
+      return client.incomingPhoneNumbers.list(params);
+    },
+    /**
+     * Returns a list of Recordings, each representing a recording generated
+     * during a call or conference for the given account
+     *
+     * @param {object} [params] - an object containing parameters to be fed to
+     * the Twilio API call, as defined in [the API docs](https://bit.ly/3mg9ebJ)
+     *
+     * @returns the list of recordings
+     */
+    listRecordings(params) {
+      const client = this.getClient();
+      return client.recordings.list(params);
+    },
+    /**
+     * Returns a list of Transcriptions generated from all recordings in an
+     * account
+     *
+     * @param {object} [params] - an object containing parameters to be fed to
+     * the Twilio API call, as defined in [the API docs](https://bit.ly/3uwx5HB)
+     *
+     * @returns the list of transcriptions
+     */
+    listTranscriptions(params) {
+      const client = this.getClient();
+      return client.transcriptions.list(params);
+    },
+    /**
+     * Returns a list of messages associated with your account. When getting the
+     * list of all messages, results will be sorted on the DateSent field with
+     * the most recent messages appearing first.
+     *
+     * @param {object} [params] - an object containing parameters to be fed to the
+     * Twilio API call, as defined in [the API docs](https://bit.ly/3mh26eY)
+     *
+     * @returns the list of messages
+     */
+    listMessages(params) {
+      const client = this.getClient();
+      return client.messages.list(params);
+    },
+    /**
+     * Returns a single message specified by the provided Message `sid`
+     *
+     * @param {String} sid - the Twilio-provided string that uniquely identifies
+     * the Message resource to fetch
+     *
+     * @returns the message
+     */
+    getMessage(sid) {
+      const client = this.getClient();
+      return client.messages(sid).fetch();
+    },
+    /**
+     * Deletes a message record from your account. Once the record is deleted,
+     * it will no longer appear in the API and Account Portal logs.
+     *
+     * @param {String} sid - the Twilio-provided string that uniquely identifies
+     * the Message resource to delete
+     * @returns `true` on success
+     */
+    deleteMessage(sid) {
+      const client = this.getClient();
+      return client.messages(sid).remove();
+    },
+    /**
+     * Returns a list of media associated with your message
+     *
+     * @param {String} messageId - The SID of the Message resource that this
+     * Media resource belongs to
+     * @param {Object} [params] - an object containing parameters to be fed to the
+     * Twilio API call, as defined in [the API docs](https://bit.ly/3mc8apg)
+     */
+    listMessageMedia(messageId, params) {
+      const client = this.getClient();
+      return client.messages(messageId).media.list(params);
+    },
+    /**
+     * Return a list of phone calls made to and from an account
+     *
+     * @param {Object} params - an object containing parameters to be fed to the
+     * Twilio API call, as defined in [the API docs](https://bit.ly/3iiHIJ9)
+     * @returns the list of calls
+     */
+    listCalls(params) {
+      const client = this.getClient();
+      return client.calls.list(params);
+    },
+    async listCallsOptions(params = {}) {
+      const calls = await this.listCalls(params);
+      return calls.map((call) => {
+        return {
+          label: callToString(call),
+          value: call.sid,
+        };
+      });
+    },
+    /**
+     * Returns the Call resource of an individual call, identified by its Call `sid`
+     *
+     * @param {String} sid - The SID of the Call resource to fetch
+     * @returns the Call
+     */
+    getCall(sid) {
+      const client = this.getClient();
+      return client.calls(sid).fetch();
+    },
+    /**
+     * This will delete a call record from the account. Once the record is
+     * deleted, it will no longer appear in the API and Account Portal logs.
+     *
+     * @param {String} sid - the Twilio-provided Call SID that uniquely identifies
+     * the Call resource to delete
+     * @returns `true` on success
+     */
+    deleteCall(sid) {
+      const client = this.getClient();
+      return client.calls(sid).remove();
+    },
+    /**
+     * Returns a recording specified by the provided Recording `sid`
+     *
+     * @param {String} sid - the Twilio-provided string that uniquely identifies
+     * the Recording resource to fetch
+     *
+     * @returns the recording
+     */
+    getRecording(sid) {
+      const client = this.getClient();
+      return client.recordings(sid).fetch();
+    },
+    /**
+     * Returns a list of transcriptions available for the recording identified
+     * by the Recording `sid`
+     *
+     * @param {String} sid - the Twilio-provided string that uniquely identifies
+     * the Recording resource
+     *
+     * @returns the list of transcriptions
+     */
+    listRecordingTranscriptions(sid, params) {
+      const client = this.getClient();
+      return client.recordings(sid).transcriptions.list(params);
+    },
+  },
+};