DEV Community: Charla Bigelow

How to Create an Automated SMS Notification System

Charla Bigelow — Tue, 18 Apr 2023 06:40:00 +0000

Introduction

All apps need a solid, automated notifications system. Whether it’s reminders, updates, or alerts, some notifications can be urgent and time-sensitive, in which case SMS is the most effective communication channel.

Let’s take a moment to talk about what that means for you as a developer. You need to:

store data on how each individual user is interacting with your app,
design personalized messages that inform your users based on different activities,
respect your user’s communication preferences to avoid notification fatigue,
and view logs in a centralized location for efficient debugging.

Realistically, building this feature from scratch can be time-consuming and complicated. You risk wasting time on simple tasks like integrating with SMS providers, managing message delivery, and scaling your system to handle increased message volume.

To simplify this process, we will use Courier, which provides a layer of abstraction over multiple SMS providers, making integration easier. It includes:

CDP integrations to send automated messages based on user activity
message delivery tracking and retry mechanisms, which can help ensure reliable message delivery
scalable architecture, which can handle increased message volume as your application grows.

This tutorial will cover everything you need to know to set up an effective and efficient automated SMS notification system using Courier. Let’s begin.

Send with SMS

The following is a simple API call that sends SMS messages with Courier, adapted from the Node.js quick start:



const { CourierClient } = require("@trycourier/courier");

const courier = CourierClient({ authorizationToken: "<auth_token>" });

async function sendSMS() {

    const { requestId } = await courier.send({

        message: {

            to: {

                phone_number: "123-456-7890",

            },

            content: {

                title: "Welcome!",

                body: "Thanks for signing up, {{name}}",

            },

            data: {

                name: "Peter Parker",

            },

            routing: {

                method: "single",

                channels: ["sms"],

            },

            },

    });

}

sendSMS();

Integrate SMS API

You can use Twilio or any of the following providers based on your preference.

** Step 1: Sign up for Twilio**

** Step 2: Set up your preferred SMS API in channels**

Each Courier Integration needs specific information based on the Integration provider's requirements (check the Provider Documentation section on the left sidebar for each Integration's needs).

For Twilio, you will need to provide an Account SID, an Auth Token, and a Messaging Service SID, which you will get directly from Twilio. If you don’t have a Messaging Service SID from Twilio, you can add a From Number instead.

After you sign in to Twilio, click the house icon on the sidebar to go to the Dashboard. On this page, you'll see a section called Project Info, which shows your Account SID and Auth Token. Copy these and paste them into the matching fields on Courier's Twilio Integration page.

You can find more information on how to get a phone number from Twilio and how to set up a Messaging Service SID in our Twilio documentation.

Create Your Notification(s)

Step 1: Create a new template

Go to the Courier Designer and click on the Create Notification button to create a new notification template. You will need to give your notification a name (otherwise it will default to “Untitled Notification”. You can choose to use AI to generate content based on the name you chose.

Leave the Subscription Topic blank for now.

Step 2: Select your preferred channel and integration

In this case, you will use the SMS channel and Twilio integration.

Step 3: Customize your message and publish changes when complete

** Step 4: Add links to the Preference Center**

You’ll set up your Preference Center later in this tutorial, but you can add links to the Preference Center here by including ({$.urls.preferences}) in the message or hyperlinking text with {$.urls.preferences}. Learn more.

Optional Step 4: Test your event

To confirm that your message is appearing the way you’d expect it to, go to the Preview tab and create a new test event. Replace the value of phone_number in the JSON with a number you would like to receive the test SMS at. Click create and proceed to the Send tab. Click Send Test to receive the test message. Click on the Design tab to revise the message until you are satisfied with the way it looks.

Learn more about designing templates.

Step 5: Repeat this process to create all notifications you need to send via SMS

Create an Automation

Step 1: Create a new Automation

Step 2: Drag and drop your preferred trigger

If you have integrated a CDP in Courier and want to send notifications based on events being tracked within your application, you can choose any of them as the trigger (Segment or Rudderstack).

This will require you to have the integration setup within the CDPs:

Step 3: Drag and drop a Send step

Connect the notification template based on which message you want to send with this trigger.

Edit the recipient information:

add a phone_number field to send to a specific number,
add a user_id to send to a specific contact within your [Courier Users database](https://app.courier.com/users0,
or add a list_id to send to a list of users (another way to do this is to use the Send to List step)

Step 4: Publish the Automation template

Learn more about designing Automation templates

Set up user preferences

To allow your users to decide how they receive messages, you can use Subscription Topics to categorize your notifications and give users the ability to opt in/out of these Topics.

Step 1: Create Subscription Topics

Head over to the Preferences Designer and add your Topics. Some examples are “Marketing Messages,” “Billing Alerts,” and “Critical Messages.” You can edit the Default State of each Topic to decide whether users can opt in/out or if they are required to receive these notifications.

Step 2: Link the Notification Templates

Edit your Topics to link the Templates you created earlier.

Optional Step 3: Enable Channel Delivery Customization

You can also edit the Section settings (a Section groups multiple topics together) and enable Channel Delivery Customization so users can decide which channel they receive messages on. This means that if a user opts out of “SMS” notifications for a Section, they will not receive any SMS notifications within the Topics of that Section.

Learn more about the Preferences Designer.

Best Practices for SMS Notifications

The ease and convenience of SMS have made it an effective and popular method for delivering messages to customers, employees, and stakeholders. However, best practices must be followed to ensure the effectiveness of SMS notifications. Here are some of the best practices for SMS notifications:

A. Timing and frequency of SMS notifications

SMS notifications require precise timing and frequency to be effective. The notifications should be sent at the optimal time for the recipient to read and respond to the message. For example, a retail store may send SMS notifications to customers with promotions and discounts during the holiday season or a special sale event. Similarly, a healthcare provider may send reminders to patients for upcoming appointments or medication refills. It is also important to avoid overloading the recipient with too many messages. Finding the right balance between frequency and relevance is crucial to ensure that SMS notifications are well-received and effective.

B. Personalizing the SMS notifications for each recipient

Personalization is a key factor in delivering effective SMS notifications. By personalizing the message with the recipient's name, location, or other relevant information, it becomes more engaging and meaningful. Personalized SMS notifications can also help to build stronger relationships between the sender and recipient. For example, a fitness center may send SMS notifications to members with personalized workout plans based on their fitness goals and progress. Similarly, a bank may send personalized SMS notifications to customers with account balances and transaction details.

C. Measuring the success of SMS notifications with analytics

Analytics can provide valuable insights into how the recipient is engaging with the message. For example, open rates, click-through rates, and conversion rates can indicate the effectiveness of the SMS notification. By analyzing these metrics, the sender can identify areas for improvement and make data-driven decisions. Analytics can also help to refine the timing and frequency of SMS notifications.

D. Improving the SMS notification strategy based on recipient engagement

Finally, we can continuously improve the SMS notification strategy based on recipient engagement. By soliciting feedback from recipients, the sender can better understand their preferences and needs. For example, a survey or feedback form can be included in the SMS notification to gather feedback from the recipient. Based on this feedback, the sender can adjust the timing, frequency, and content of the SMS notifications to meet the recipient's needs better.

Conclusion

Now you have a completely automated SMS notification system that respects your user’s preferences. Creating an automated SMS notification system with Courier and Twilio is a powerful way to enhance customer communication. Courier's advanced features, like multi-channel support, pre-built templates, and detailed analytics, make it a great tool for managing all your notifications in one place. Twilio's SMS API is easy to use and provides a wide range of features, like two-factor authentication and automated responses, to help you create an efficient and secure notification system. Combining these two powerful tools allows you to create a notification system that meets your business needs and helps you stay connected with your customers.

New Datadog integration for Courier notification logs and metrics

Charla Bigelow — Wed, 12 Apr 2023 16:00:00 +0000

The ability to unify all notification metrics and logs across channels and providers into an easy-to-use dashboard is a core advantage of Courier’s notification infrastructure.

However, with product notifications so critical to the entire application experience, it’s important to connect that data back to central cloud observability platforms that look across the entire stack. This gives platform engineering teams a complete understanding of application health and lets them quickly troubleshoot even the most complex issues.

Today, we’re incredibly excited to announce our first observability integration with Datadog.

Datadog is a tool for collecting metrics and other data from applications and viewing them in a centralized place. Datadog’s dashboards and monitoring tools build a more accurate picture of the health of your application and how it changes over time.

Our integration with Datadog is easy to spin up when you use our “dashboard starter kit.” This consists of some pre-configured JSON to set up a simple dashboard in Datadog for your Courier data.

Our Datadog integration is currently only available on Courier’s Business plan, much like our other production-focused features such as template analytics, Okta integration for SSO, and advanced user preferences.

The fastest way to pull your notification data into Datadog

Courier's message logs and analytics dashboard are optimized for helping product teams understand everything about the messaging use case — the status of notifications, recipients, lists, automations, and more. It brings all this data together across channels and providers in one place and provides the fastest way to learn about your notifications and troubleshoot notifications-related issues.

However, many organizations need to understand how notifications interact with the rest of the tech stack or would prefer to view and store all logs and metrics data in one place.

Until now, the only way to pull this data outside of Courier was to build your own bespoke solution, by listening to Courier’s outbound webhooks and writing custom code. But now the Datadog integration enables sending information about health and performance directly to your own monitoring system, which is much more convenient.

Use cases

Notification metrics and logs

The most obvious use cases involve sending data about the health and delivery status of your notifications. This could include metrics such as:

Percentage of messages that are successfully sent, delivered, opened, and clicked.
Delivery errors
Percentage of customers who are unsubscribing from your messages
Any metrics that measure outliers — for example, a metric that checks if you are sending either more or fewer messages than you should be.
Number of people who opened your emails over time.

(An example Datadog dashboard showing key notification health metrics)

(A Datadog graph showing the number of emails that are being sent over the course of the day — as well as how many emails are being opened and how many people are clicking on email links. There are options to compare these metrics to other time periods such as the previous day, week, or quarter.)

Feature-specific metrics and logs

The integration also supports data from Courier platform features. This can provide even more color on how notifications support your business or operational goals. For example, If you use Courier Automations to build smart notification workflows, you may want to monitor how many times each automation has been invoked. Or, if you use Courier’s in-app notification Inbox, you might choose to monitor the number of connections to your Inbox and compare this to the number of active users on your site. A significant difference could indicate a problem that needs further investigation.For example, you might have released a change that broke your Inbox implementation through changes to an authentication method or a key.

What data can be sent to Datadog from Courier?

Metrics

Courier metric names will have a courier.* prefix — for example, courier.notification.sent. A full list of all the Courier metrics that are available for you to send to Datadog is provided here. These metrics will be sent with additional information, such as success or failure codes, and tags (including whether the metric is for your production or staging environment).

Once the metrics are being sent to Datadog, you can set up corresponding alerts in Datadog. For example, you could set up an alert that emails your engineers when the number of notification delivery errors reach a certain predefined threshold.

Logs

Courier always had the ability to record logs about notifications, recipients, lists, and automations. Now these can be sent to Datadog in the same way that metrics are sent.

Courier’s logs provide details about delivery failures, as well as other information that can be relevant when debugging. With these logs now in Datadog, you’ll now be able to easily correlate the logs to your metrics, helping you debug any issues.

Setting up the Datadog integration

To set up this integration all you need is your Datadog API key and URL. From there, simply follow the setup guide, which will cover the steps to connect Courier with Datadog and how to create a Courier-specific dashboard in Datadog. This is where you’ll find our “dashboard starter kit,” a JSON file that has everything you need to set up a Courier dashboard, including commonly used Courier metrics. You can easily customize the JSON to add or remove different metrics according to your needs.

Next steps

If you’re already on Courier’s Business plan, you can start sending metrics and logs to Datadog right away. Otherwise, you can request a demo, and we’ll walk you through this integration in more detail, along with the other features in the Business plan to see if it’s right for your use case.

The ability to access your metrics and logs in an observability platform like Datadog allows you to set up a dashboard that shows the data that’s most important to you. You can also create graphs that enable you to see at a glance if something’s not right, or even set up alerts based on message delivery failures. Whatever size your business is, some level of monitoring is necessary if you want to have control over your application.

If you’re a Datadog user who is interested in trying Courier’s full-featured notifications infrastructure, you can try it for free.

Streamline your workflow with CourierJS: Our new client-side SDK

Charla Bigelow — Mon, 10 Apr 2023 16:03:00 +0000

We are thrilled to announce the release of our first client-side SDK for Courier, written for JavaScript. This new addition expands our existing SDK offerings, which include Java, Python, Node, Go, Ruby, and PHP, and makes it even easier for developers to integrate Courier into their projects. By enabling direct calls to Courier within your JavaScript code, you can eliminate the need to use a back-end service as an extra layer between your front end and the Courier API, saving valuable time and resources.

With the initial release, we're introducing three new API calls: the identify call for tying a user to actions they perform, such as logging in or updating their profile, and the subscribe and unsubscribe calls for subscribing and unsubscribing to lists. By simplifying these key interactions, CourierJS enhances the overall experience of using Courier.

Client-side vs. Server-side SDKs

You may still be wondering: why introduce a client-side JavaScript SDK for Courier when we already have SDKs for many other languages? Let's dive into the differences between client-side and server-side SDKs, which will help you determine the right type of SDK for your specific needs.

(Comparing integration flows: with and without Courier client-side SDK)

Client-side SDKs are designed to provide a way for you to interact with an API within your application's front-end code. Server-side SDKs, in contrast, interact with your back-end code, making them more suitable for processing and handling data that doesn't directly involve user interactions on the front end. By offering a client-side JavaScript SDK, we're providing developers with an alternative to server-side SDKs that is more suitable when you need to integrate Courier's functionality directly into your web application's front end. When trying to call the API from your front end, having an extra layer of back-end code might not always be the most suitable option for certain use cases. With CourierJS, we provide an alternative that streamlines the process and caters to a broader range of scenarios, enhancing efficiency and helping you deliver valuable applications more quickly.

We have taken inspiration from popular customer data platforms like Segment and RudderStack, both of which provide an identify call. In addition to an identify call, which ties a user action to a particular user, our initial release also includes support for subscribing and unsubscribing to lists, allowing users to manage their communication preferences with ease.

The JavaScript SDK has been designed to be both intuitive and efficient, working exactly how you'd expect. Instead of issuing multiple commands to update specific fields, you can now easily update multiple fields in a single operation. For example, if you have a user with an ID, name, email address, physical address, and phone number, and you just want to update the email address and phone number, you can pass in just those values. The SDK also automatically merges new data with pre-existing data, overwriting only the specified fields. This functionality ensures a smooth integration with your front-end code and a more seamless user experience.

Discover the advantages of CourierJS

Previously, developers using Courier only had access to server-side SDKs. These SDKs required the front-end code to communicate with the back-end services to utilize Courier's functionality, often adding an unnecessary extra layer. In some cases, you even had to create an entire back-end service just to handle the Courier SDK.

One of the primary challenges faced when using server-side SDKs in the context of Courier arises when you need to send data from the front end to Courier, which previously required going through the back end. This process can be manageable, but it can also be tedious for developers who want a more streamlined solution. To address this, we’ve developed the client-side SDK, making it easier for those who want to directly integrate Courier's functionality into their web application's front end, bypassing the need to pass data through the back end first.

By introducing the new Courier client-side SDK, we aim to simplify this process and reduce the workload for engineers. This not only saves time but also accelerates the implementation of new features, making your development process more efficient and agile.

Ready to get started? Using CourierJS is a breeze

Now that you've discovered the advantages of the Courier client-side SDK, it's time to dive into how you can seamlessly integrate it into your project. To begin, all you need to do is install the JavaScript package and start using the provided function calls in your code. For a comprehensive step-by-step guide on setting up the Courier client-side SDK, you can refer to our documentation here.

Exploring the new API calls in Courier's client-side SDK

Now that you're all set up, let's take a closer look at the new API calls introduced in the SDK.

The `identify` call

The identify call allows you to create and update user profiles with ease. Here's an example of how the identify call can be used in your code:

await courierSDK.identify("user123", {
  email: "user123@example.com",
  firstName: "John",
  lastName: "Doe",
});

In this example, the identify call creates or updates a user profile with the specified user ID, email, first name, and last name. The simplicity of the call ensures that you can quickly and easily update user profiles as needed, making it an invaluable tool in your communication management toolkit.

Subscribing and unsubscribing from lists

A list in Courier is a way to group recipient profiles, allowing you to send a message to all subscribed recipients with a single call. This feature is particularly useful for managing newsletters, product updates, and other types of mass communication.

Managing user subscriptions is easy with the new subscribe and unsubscribe API calls. These calls make it straightforward to maintain up-to-date lists of subscribers, due to not needing to call a back-end service. Here are examples of how to use the subscribe and unsubscribe calls in your code:

// Subscribe a user to a list
await courierSDK.subscribe("user123", "my-newsletter-list");

// Unsubscribe a user from a list
await courierSDK.unsubscribe("user123", "my-newsletter-list");

As you can see from the comments in these examples, the subscribe call adds a user to a specified list, while the unsubscribe call removes them from the list.

By incorporating these new API calls into your project, you can further streamline your development process.

Conclusion

Throughout this article, we've unveiled the power of the new CourierJS client-side SDK and explored its features, including the identify call and subscribe and unsubscribe calls. By using the CourierJS client-side SDK, you can reduce the workload involved in your development process and improve the overall efficiency of your projects.

As you’ve seen, the SDK saves you time and effort by eliminating the need for complex back-end services and enabling direct communication between the front end and Courier. Its intuitive functionality, ease of use, and powerful capabilities make it a valuable addition to your development toolkit.

We encourage you to try out the new CourierJS client-side SDK and experience the benefits it offers firsthand. By adopting this innovative tool, you can enhance your product-triggered communication management and unlock the full potential of the Courier ecosystem.

Introducing the new and improved Automations designer

Charla Bigelow — Mon, 03 Apr 2023 15:31:00 +0000

Courier Automations lets you build smart notification workflows. With Automations, notifications can be scheduled, driven by events, canceled, and more.

We’ve just completed a big redesign of the automations UI — before this overhaul, notifications were restricted to linear workflows. This made it difficult to build more advanced automations, however the new automations UI, based on React Flow, allows you to build more sophisticated workflows, including those requiring branching logic.

In this article, we explain the differences in functionality between the old and new UI, how the new UI helps developers as well as product managers, and how the migration will affect you if you’re already using the automations designer. For those who are new to Courier automations, we explain the background of what automations are for and how to use them. We also cover how to use the new UI, while providing some useful real-world examples to help you get started.

What is Courier?

Courier serves as a product-oriented notification platform, and is well-suited for the post-marketing phase of a business; allowing you to streamline communication with users across your websites and/or applications. Its unified API accommodates multi-channel delivery — including email, SMS, browser notifications, push notifications, and direct messages through platforms such as Slack or Microsoft Teams. The power of the Courier app is that it allows you to design versatile message templates that can be easily repurposed across each messaging channel.

You can pull data from other systems into Courier, to populate variables within your message templates or when building your application logic in your automations. This data can come from a variety of sources — for example, from customer data platforms (CDPs) like Segment or RudderStack, or from your own site.

What are Courier automations?

Courier automations enable you to craft intricate notification delivery workflows while seamlessly integrating your custom application logic into the Courier notification ecosystem. Automations can be controlled either through an API or through the automations designer inside the Courier app. The automations designer allows you to design automations either by using a visual builder or by directly editing JSON. It’s the fastest way to build workflows.

The latest update to the automations designer includes a big update to the visual builder. Where previously your workflows were limited, or were made unnecessarily complex by the linear nature of the visual builder, you can now use the designer to design complex workflows in a simple and intuitive way.

For example, if you want to send different welcome emails to different groups of people based on user attributes, it was difficult to handle this level of complexity in the old UI.

(The old UI consists of a linear series of steps. In this example, a Segment event, “Account Created” triggers a 10-minute delay before sending a welcome email.)

(The new automations designer has drag-and-drop elements that can help you create non-linear workflows. In this example, the Segment event, “Account Created” triggers a 10-minute delay and then checks whether the user’s job role contains “engineer.” If they are an engineer, they will be sent the engineer-specific welcome email, and if not, they will receive a generic welcome email.)

The new automations designer was built using React Flow, a library for building node-based interactive UIs. You can build your messaging workflows by dragging and dropping different elements such as triggers and actions onto a canvas. You can then connect them together in a sequential order, or use branching logic if required to build a more complex workflow.

The example above shows a workflow for waiting until a user has signed up to send them a message. If they’re online, you can just send a browser notification; otherwise you might want to send an email.

The elements of a Courier automation

Triggers

Triggers are events that cause a new automation run to be started. They define the conditions that must occur before an action can happen. A simple example of a trigger is a scheduler that waits until a particular timestamp is reached before an action can happen (such as sending a notification). Data pulled from your CDP can act as a trigger, too — for example, a new user signing up to your system.

You can also make use of data from Courier Audiences to design your triggers. An Audience is a dynamic list of your users. When someone joins or leaves an Audience, this event could be used as a trigger to send a notification. An example of this could involve an Audience of all users who are software engineers. If a user who previously worked in tech support becomes a software engineer, as soon as they update their profile they become part of the “software engineer” audience — which will cause your trigger to invoke an action such as sending a message.

Actions

An action is an activity that happens following a trigger. The most common action in Courier is the sending of a message, either to an individual or group. However, actions can also include fetching data from another API, updating a user profile, or adding a delay to your workflow – for example, waiting for 24 hours after a user signed up to remind them to fill in their profile.

Branching logic

Branching logic is a new feature in the latest automations designer that allows you to design more complex workflows by dragging and dropping if statement blocks into your workflow. These are accessed in the menu on the left, under “Control Flow.” An if statement block has nodes next to its true and false conditions, so you can draw lines that link these different conditions to the next steps in your workflow. As this doesn’t involve writing code, non-developers with a decent understanding of the data involved are often able to design their own notification workflows.

(Once you’ve dragged an if statement box onto the canvas, you can connect it to different parts of your workflow by drawing lines from the true or false nodes to other elements within your automations template.)

Why the new version of the Courier automations designer helps you

Until now, if you were using automations for complex, non-linear workflows, there was a good chance you had to manage this logic yourself using our API, which may even have required a separate back-end service just for dealing with this. And, due to ever-changing requirements, you may have needed to regularly update your code in small but necessary ways.

This can now be done in the UI, leading to much faster turnaround for small workflow changes. To achieve the fastest turnaround, it’s worth empowering product managers or designers to make their own changes to the logic when needed, so they don’t have to wait for a developer to fit small changes around feature work. As long as they have some knowledge of the underlying data, this can be accomplished with minimal training, as the interface is very intuitive. Allowing your colleagues to create or edit automations has the added benefit of freeing up your time to do more feature work instead of having to focus on small updates to application logic.

How to use the automations designer

You can follow our documentation on how to create a basic automation using the new automations designer UI. After creating your automation template, you’ll need to publish it before it can be invoked. The standard way for an automation to be invoked is automatically — when its trigger condition is met. However, it is still possible to invoke an automation by using our automations API.

If you need to use variables within your automations — for example, if you want to send your message to varying recipients, or if you want your message template to vary according to certain conditions — you can use our refs variable, which stores dynamic data within Courier.

The automations API

If you prefer to use the API directly, or use an SDK, that’s still an option. You can use these to either invoke automations or get the status of automations. For existing users of the API, you can be reassured that we’ve made no changes to the API — our latest automations release applies to the UI only.

Details for existing users of the automations designer

For existing users of the automations designer, we’ll now cover the main points that are likely to be of interest: the main differences between the old and new UIs, and what you need to do to migrate to the new version of automations.

Differences between the old and new automations designer UIs

The main difference is that the new automations designer UI is more expansive: you are no longer forced to follow a linear workflow, and can take advantage of branching logic. In addition to this, we have added some improvements to make the UI easier to use. For example, running an automation on a repeat schedule used to require users to learn Cron expressions — something that even most engineers have a tough time remembering. Now, with the new “Schedule” trigger, scheduling an automation is as easy as scheduling an appointment in your favorite Calendar app. Changes like these have made the UI more user-friendly, meaning that letting non-developers set up their own workflows is finally an option.

What you need to do to migrate to the new version of automations

You don’t need to do anything! We have already rolled out the new changes, so no work is required from your end.

If you have any existing automations templates that you’ve designed in the past, these will not change. They will appear in exactly the same way using the old UI. However, any new automations templates that you create will now appear using the new UI.

Get started

You can get started creating automations with the new Designer directly in the Courier UI. Setting up smart notifications in the new UI is fast and intuitive — just follow our documentation.

Simplifying notifications with the Courier iOS SDK

Charla Bigelow — Thu, 23 Mar 2023 17:16:58 +0000

Push notifications are a valuable tool for keeping users informed and increasing their engagement with your app. You can use push notifications to alert users about promotions, new content, or any other important updates. While push notifications are a powerful tool, setting up push notifications in iOS can be a daunting task that requires a significant amount of effort and time. Fortunately, the Courier iOS Mobile Notifications Software Development Kit (SDK) simplifies this process.

The Courier iOS SDK can help you to implement push notifications in iOS apps more easily thanks to some useful tools. The benefits of using the SDK include:

Simplified setup process. The Courier iOS SDK streamlines the process, making it easy to get set up and start sending push notifications. With some easy-to-follow setup steps and a few lines of code, you can quickly integrate the SDK into your apps.
Effective management of tokens and user state. When implementing push notifications, you would normally need to handle token management manually, which involves generating and storing unique identifiers for each device that can receive notifications. This can be complex and time-consuming. The Courier iOS SDK provides tools that enable you to manage tokens and user state effectively.
Sending test notifications. Before sending push notifications to all users, it's important to test that they're working as intended. With the Courier iOS SDK, you can send test notifications to check that your notifications are working as intended before they go live. This can save time and prevent problems later.

Token management

Managing push notification tokens is a complex task. Let’s talk a bit about how they work, to help us better understand the benefits of the Courier SDK.

Tokens are unique identifiers that are used to identify a specific device for push notifications. They are generated and managed by the push notification service, which is the Apple Push Notification Service (APNS) for iOS. These tokens need to be securely stored on the back end, associated with the relevant user or device, and regularly updated as they can change or expire. Additionally, token management includes handling token deletion when a user unsubscribes from push notifications or uninstalls your app.

Setting up and managing your own token management infrastructure can be a time-consuming and challenging task, requiring collaboration between front-end, mobile, and back-end developers. However, with the Courier iOS SDK, token management is handled automatically. The SDK automatically takes push notification tokens, stores them in Courier, and invalidates tokens that expire, so you can focus on building your product without having to learn the complex logistics of token management.

Getting started with Courier's iOS SDK

Before you can use the Courier iOS SDK, you'll need a few things:

Xcode. You'll need to have Apple's integrated development environment (IDE), Xcode, installed on your computer.
An Apple developer account. To enable push notifications in your app, you'll need a valid Apple developer account.
A physical iOS device. You'll need an iOS device to test your push notifications.

You can find a full and detailed set-up guide in the iOS docs on the Courier GitHub repository.

Push providers

Before we look at sending a test push notification, it’s worth noting that to enable push notification support you will need to configure a push provider. A push provider is a service that handles the delivery of push notifications to targeted devices, ensuring reliable and efficient message transmission.

Take a look at our GitHub page for more information. There you will find links to APNS (Apple Push Notification Service) and FCM (Firebase Cloud Messaging). Follow the links there to see more detailed information.

Enabling push notification capability

Another vital step is to enable push notification capability in your iOS app. Here's how to do that.

Create a new iOS app ID and a provisioning profile in the Apple Developer portal.
- Log in to the Apple Developer portal and create a new app ID for your app.
- Create a new provisioning profile for your app, which will allow it to access push notification services.
In Xcode, open your app project and select the project file from the project navigator.
Select your app target and click on the "Capabilities" tab.
Turn on the "Push Notifications" capability.
In the "Signing & Capabilities" tab, select the team for your app and choose the provisioning profile you created in step 1.

Once this is done, you’ll have enabled push notification capability in your iOS app and can start sending push notifications to your users through the Courier iOS SDK.

Setting up a notification service extension

So that you can better track your notifications, we recommend that you create a notification service extension in your iOS app.

A notification service extension is a type of iOS app extension that allows developers to track the delivery status of notifications and perform additional actions, such as modifying the content of a notification.

Setting up this extension allows Courier to accurately tell when your user receives a push notification when they are not using the app.

You can find a full setup guide here, on the Courier iOS SDK GitHub page. It won’t take long, and then Courier will be able to track delivery status in any state your app could be in.

Push notification permissions

The Courier iOS SDK needs to have push notification permissions granted by your users before it can access the push notification token. That’s where the requestNotificationPermission() function comes in.
Here's how it works:

if (await Courier.shared.requestNotificationPermission()) 
{ // Send some notification }

The requestNotificationPermission() function returns an authorization status that indicates whether the user has granted or denied permissions for push notifications.

You can read more about authorization status here.

Once your user has given access to receive notifications, a push notification device token is created by iOS and automatically synced to Courier.

Managing user state

Now that you've set up your notification service extension and handled permissions, it's time to focus on delivering a great user notification experience. One key part of this is keeping track of user state — the status of a user in relation to your app. This allows you to send users appropriate notifications based on whether they’re logged in or out. For instance, if a user is logged out, it wouldn't make sense to send them a notification about an activity that requires them to be logged in.

The Courier iOS SDK provides tools that help developers manage user state effectively and easily. By using the signIn() function provided by the SDK, developers can ensure that the user's push notification tokens and their state are kept in sync. Here's how to use the function:

await Courier.shared.signIn(
    accessToken: accessToken,
    userId: userId,
)

The accessToken can either be a Courier Auth Key used during development or a JWT (JSON Web Token) that should be used in a production app. You can create an access token by calling the Courier API as shown in the GitHub documentation. When the user signs out, you can use the signOut() function to clear their state.

The signIn() function saves the accessToken and userId to the native-level local storage, ensuring that the user's state persists between app sessions. This ensures that the user's push notification tokens are kept up to date.
By following these steps, you automatically sync push notification tokens and user state to Courier. This lets you ensure that push notifications are delivered at the right time and in the appropriate context for a better user experience.

Handling notification delivery

We've made it easy for you to monitor the delivery status of your notifications using the Courier iOS SDK via the onPushNotificationDelivered() function.

When a push notification is delivered to a user's device, onPushNotificationDelivered() is triggered automatically by the SDK if the app is in foreground. Here is an example implementation of the function in the AppDelegate class (the AppDelegate class is a key part of every iOS app and handles system-level events, including push notifications):

Courier analytics will track the delivery of this notification for you automatically.

class AppDelegate: CourierDelegate {

    override func pushNotificationDeliveredInForeground(message: [AnyHashable : Any]) -> UNNotificationPresentationOptions {
        print(message)
        return [.sound, .list, .banner, .badge] // Pass [] to hide any foreground presentation
    }
}

Note that this function will not be triggered when the app is in the "killed", "not running", or “background” state.

Handling a notification click

The pushNotificationClicked() function provided by the Courier iOS SDK can be used to handle user interaction with a notification inside your AppDelegate class. This function is called when the user clicks on a notification that was sent through Courier. Here's sample code for using the function:

Courier analytics will track the clicking of this notification for you automatically.

class AppDelegate: CourierDelegate {
  override func pushNotificationClicked(message: [AnyHashable : Any]) {
    print(message)
  }
}

In this example, the function simply prints out the content of the message payload. However, you can use the message to perform any number of actions in your app, such as opening a specific screen or executing a certain function.

Sending a test push

Now that you’ve set up your push notification infrastructure and know how to manage user state, you can start sending messages. The SDK allows you to send push notifications directly to a user ID without having to juggle tokens or manage a back end.

To send a test push notification, you can use the sendPush() function:

let messageId = await Courier.shared.sendPush(
    authKey: "a_courier_auth_key_that_should_only_be_used_for_testing",
    userId: "example_user",
    title: "Happy Holidays!",
    body: "Happy holidays from Courier.",
    providers: [.apns, .fcm],
)

Note that your user must have been given access to receive push notifications so that the push notification device tokens can be automatically synced to Courier and Courier can send a message to your user’s device. See “Push notification permissions” above for more details.

Conclusion

With just a few lines of code, you can streamline your push notification management and focus on building your product, thanks to the Courier iOS SDK.

By taking care of complex tasks such as token management and message delivery tracking, the SDK allows you to focus on building high-quality push notification experiences for your users.

If you’re an iOS developer, make sure to give the Courier iOS SDK a try and see how it can simplify and enhance your push notification workflow. Courier also has other SDKs available for Android, React Native, and Flutter. So if you're looking for a way to simplify your push notification management, check out Courier today.

Introducing Courier Preferences: The Fastest Way to Design the Best Preference Experience

Charla Bigelow — Thu, 23 Feb 2023 16:32:17 +0000

Notification preferences are important — especially if you’re building an application that sends dozens of notifications. Users want control over which kind of notifications they receive, and through what channels. That’s why it is essential to provide a well-designed preference experience that’s quick, intuitive, and guaranteed to respect your users’ chosen preferences.

With Courier, you can build great notification infrastructure effortlessly. But until now, preferences were handled separately, requiring engineers to spend a significant amount of time on both the back-end logic and the UI where users could select which notifications they want to receive and how.

As an engineer myself, I’ve had to build workflows like this several times in past projects & companies. But those days are over: we’re excited to announce general availability of Courier Preferences. With Courier Preferences, you can build a full notification Preference Center in no time. The clean interface, which comes with endless options for customization, lets users manage their preferences. Courier’s infrastructure will take care of the rest by integrating them into our core products that trigger sends.

(Within the Preference Center, users can comfortably opt in and out of notifications by topic and channel)

Whether you want to build a bespoke notification experience with the Preferences API, embed our pre-built UI components, or use the hosted preferences page that Courier provides out of the box for faster time to value, is entirely up to you.

"Courier turned something that takes months into days. We were able to unlock the ability for our users to opt in/out of notifications in a customized Preference Center within one day. It was easy."

Guilherme Samora, Senior Product Manager, Sastrify

In this post, we’ll look at how to implement the best preference experience for your users. We’ll talk about how Courier makes it easy to handle preference settings and logs, and how the new Preferences Designer makes preference management a walk in the park. But first, let’s briefly recap why it’s important to implement preferences for your users.

Notification preferences are a vital feature of any app

Aside from their core functionality of alerting your users to activity in the app that requires their attention, notifications can be used to increase users’ awareness of your product’s features, for marketing and other purposes.

But getting all these kinds of notifications from different organizations can quickly become annoying for users. To make sure they remain in control of their own notification experience, and to avoid them turning off all notifications from your app, it is vital that you implement notification preferences that are fine-grained and easy to use. And it’s just as important that you respect those preferences and only send your users the notifications they really want.

Building notification preferences for your app from scratch is hard, especially if you use more than one channel to communicate with your users. It requires a significant amount of time and engineering resources — and don’t forget the need for future maintenance. By letting Courier host your preference infrastructure, you can instead use those resources to focus on building your core product.

Here at Courier, we have spent quite some time thinking about what the best preference experience looks like. It needs to be clean, customizable, and easy to use for the end users. It also needs to offer sufficient transparency for compliance and record-keeping purposes on the back end. Since these requirements align across products, there is no need for every company to build their own. Instead, Courier Preferences lets you set up the notification experience that you want for your users in just a few hours.

How to design a good preference experience

You can now use the Preferences Designer in the Courier web interface to design the best preference experience for your users. (As an alternative to the Preferences Designer, you can use the Preferences API for a more native experience within your app — more on that later.)

Since most applications send out many different notifications, it can quickly become cumbersome for users to manually set preferences for every single option. For a better user experience, Courier groups notifications by subscription topics (formerly called “categories”). In addition, business tier Courier customers can bundle several topics by sections: as an example, you could set up two topics named “Feature launch” and “Product update” and file them both under a “Product” umbrella section, for even easier preference management.

Turning notifications on and off is not all, however. Notifications can be sent via different channels in Courier, such as email, SMS, and push notifications. Users can select which channels they prefer for each subscription topic. For instance, they might prefer to be notified via email about a new message or rating on a social media platform, but not about minor interactions such as likes. Conversely, they may want to activate multiple channels — like SMS, email, and Slack — if there’s an emergency, like a security breach.

As a developer, you can turn certain notifications on and off by default for different topics and channels. You can also set certain indispensable notification topics as required. By marking a notification topic as required (for example, "Reset Password"), it prevents your users from disabling notifications for that topic, while reassuring them that they’ll still receive such critical notifications even if they disable everything else.

Voilà: a user-facing Preference Center

In the Preferences Designer, you can preview how your users will see the Preference Center in their browser. The page is designed to be easily navigable: preferences for notification topics and channels can be turned on and off with the click of a mouse.

All of these features are available in our free tier. For more functionality, like multiple sections or the ability to remove the Courier watermark from the user-facing Preference Center, use our Business plan.

Your preference UI, hosted by Courier

You can now direct users to their personal Preference Center through a hyperlink in your notifications to them. In newer Courier workspaces, your notification templates will include this hyperlink by default. Otherwise, you can add the link manually.

By following the link, your users will be able to see and update their own notification preferences within the Preference Center. Note that this requires no login: by automatically encoding their user_id in the Preference Center hyperlink, it will be personalized to that user, and their preferences will be saved in their profile in the back end.

And that’s it: the easiest way to create the best customized preference experience, with only a few clicks in the Courier Preferences Designer.

Build your own interface via the Preferences API

You don’t have to use the hosted Preference Center — you can build your own, or even integrate notification controls elsewhere in your application. Have a look at the documentation for the Courier Preferences API to learn more.

Finally, you can choose the middle ground and embed Courier’s prebuilt component in your own preferences UI.

A user-friendly unsubscribe experience

Unsubscribing from unwanted notifications should be fast and easy — and you should make sure to respect your users’ preferences to avoid unnecessary frustration. Similar to the preferences hyperlink, you can easily embed an unsubscribe link in your notification template. By clicking on it, users can unsubscribe from topics that they’re not interested in.

Keeping a digital paper trail of your users’ preference history

Keeping logs of your users’ changes in preference settings is useful for debugging, compliance, and solving issues in customer support. Courier automatically logs all your users’ changes in notification preferences and lets you view them via the API or directly in the Courier web interface.

Let’s say, for instance, that a user isn’t receiving your notifications, even though they were enabled in their settings. You can now simply check the logs to determine where the error occurred. Conversely, a user might complain that they’re still receiving unwanted notifications after they thought they turned them off. By looking at the preference logs, you can see whether they indeed turned notifications off, or if they accidentally enabled them.

Get started with Courier Preferences today

Being able to offer users a fine-grained and intuitive preference experience saves companies a lot of time and puts them further ahead on their roadmap. We’re excited to make preference management easy and smooth for businesses.

To learn more and start designing the best preference experience for your audience, take a closer look at Courier Preferences and the docs. We’re sure your users will love it!

Tools and Techniques to Establish Your Data Team Early

Charla Bigelow — Tue, 21 Feb 2023 17:14:11 +0000

You can’t really invest in a data team too early. That’s something we learned as a small but growing team. We invested in a data team at an early stage, so we could establish product usage trends, create business insights, and identify areas to improve our product.

If you’re an early-stage startup, start building your data strategy team and architecture as soon as you can. You don’t have to go big—a one-person data team can make a massive difference to your success as you grow.

Hire a Generalist First

When it comes to launching your data team, you might be tempted to hire an expert from the largest brand name you possibly can. Our advice: find someone with early-stage startup experience and has worked with data at scale too.

There are wonderful people with brilliant minds working on large enterprise data teams, but these large teams often have their employees specialize in specific parts of their data platform. That makes sense when you have 10 data engineers on a team or when you have a large team of machine learning data scientists working on pricing algorithms. But when you’ve only got one data role for the entire organization, you need someone who can do a little bit of everything.

It’s important to first hire an all-rounder who can create data insights, develop business hypotheses, and create a scalable data architecture from scratch. You need someone ready to start building the data team from the ground up, preferably someone who can hire out the rest of your team once you’re ready to do so.

This first hire should be someone who has experience building (or at least working on) a data team at an early-stage startup. They need to be able to generate value quickly and have the business acumen to ask the right questions. They should be able to approach data in an 80/20 manner to deliver immediate results instead of diving into the hardest problems that you have.

For the data engineering side, it’s common to hire a consultant or contractor to help set up your architecture. We decided to complement our first hire with a consultant. This way, we have the best of both worlds – an expert in data engineering part time, and a generalist who can maintain data architecture on a day to day basis. We set up strong foundations and also kept our knowledge in house.

A Small Data Team Can Answer Big Questions

Even if you can’t hire right away for all the roles you want on your data team long term, you can do a lot with only one or two of the right people. The key is thinking in terms of scalability and efficiency. What helps your data team do more with less? And how will this work when your team is bigger?

Scalable analyses are extremely important with a small data team. By thinking ahead about how your processes and workflows will function as your team grows, you’ll save time and create valuable solutions for some of your employees’ most time-consuming issues.

For example, we immediately realized that our sales team had no visibility into prospective customer product usage, and it was going to come up often. So we built our sales reps a workspace dash so they can pull the data themselves. Our data team’s job is to enable data-driven decision-making. When we saw an opportunity for a one-time data investment that could lead to hundreds of saved hours on the sales side, we acted on it.

A small data team should also be focused on preventing issues in the future. If you only have the headcount for a one-person data team at the moment, keep them focused on your biggest problems but also budget time to maintain and scale your data architecture to reduce tech debt.

The Tools Our Data Team Uses

From the beginning, our goal was to be forward-thinking with every decision.

Like all startups, we wanted to generate immediate ROI. We use a centralized data warehouse that is our single source of truth – nothing hurts data teams more than having fragmented or untrustworthy data. We’re able to consolidate our data thanks to automations and integrations. This helps us provide valuable insights to the entire company with low lift.

We pipe in all of our data using ELT tools like Segment (which is also our data collection tool), Fivetran, and Snowflake external stages.

We use dbt to clean all of our raw data into a more usable format. For example, our dim_user table has ~20 tables powering it under the hood, that have a lot of critical info on our customers, such as how many notifications they send and what plan type they are on. By making this so readily available, our non-technical users can quickly draw business insights. We can quickly look at non-paying or self-serve customers that are sending a lot of notifications to identify business contract prospects. Our customer success team also built reports to look at the health of our business contract customers. We also use dbt to clean our data of sensitive information.

We use Census to send our warehouse data back to places such as HubSpot and Courier. This allows our sales and marketing teams to access this information on the platform that they are using on a daily basis.

Metabase is our BI tool. It allows us to create dashboards, write SQL queries, and provide a self-serve format for non-technical users. We’ve found that creating these kinds of self-serve data dashboards allows users to answer a lot of their own questions. They are quick to spin up without large investments upfront like teams that use Looker or Tableau.

For example, we have a KPI dash that shows the top metrics across the company. We can also track how individual workspaces are performing and identify workspaces that we can target for our sales team. We have also brought data-driven decision-making to our product development by deep-diving into our customers’ product usage. One example is that we found that a lot of our users were creating their own Courier instance instead of joining their colleague’s existing Courier instance. Using this insight, our product team went back to the drawing board to create a page that surfaces Courier workspaces that are created by the same business email domain so you can easily request access.

We also use Propel to power our in-app analytics to provide visibility for our end users. One way that we use Propel is to deliver template analytics for our Business-tier customers. Propel allows our engineers to easily put GraphQL visualizations on top of our metrics from our warehouse.

Our Data Team Is Evolving Again

Now, we’re entering a period of growth, so naturally, we’re evolving our data approach again. Our current goal is to enable our data scientists to build subject matter expertise while still maintaining centralized data standards.

Our current structure is centralized, with a senior analytics engineer reporting to the head of data. It works now since we’re still in the earlier stages of building out a data team. But when the team expands, we will be transitioning to a hybrid model.

Data scientists will cover certain business areas (like the product team), but they’ll still report to the Head of Data. This will allow the data scientists to build subject matter expertise while still maintaining centralized data standards as we continue to grow. Because the data team will always be changing and growing along with the rest of the organization, you need standards that will scale with the business.

If you’d like to learn more about how we approach data standardization, check out our blog post on how Courier became HIPAA compliant.

How to Send Invoice and Add Payment Reminder in Next.js with Courier API

Charla Bigelow — Wed, 15 Feb 2023 17:32:02 +0000

Background

A lot of open-source invoice management apps are built with Laravel. As a Javascript developer, I wanted to build the “React Solution” for devs that are familiar with React and Javascript.

A problem I found when building with services in Node.js is that there is no built-in mailer. So, I had to find a 3rd party service to do that for me. In this article, I will be integrating Courier to send emails for this project https://github.com/fazzaamiarso/invoys.

Pre-requisites

As this article isn't your typical follow-along (more like "please sit tight and see how I do it"), it's not mandatory to be familiar with all technologies used. However, familiarity with Typescript and Next.js will be beneficial for quicker understanding.

Technologies in this blog:

Typescript: type-safety and auto-completion are the best, right?
Next.js: a production-ready framework to build a full-stack app, even for beginners.
Prisma: a great ORM to work with databases. We use Prisma because of its type-safety and auto-completion, providing great developer experience with typescript added.
Trpc: enable us to easily build end-to-end type-safety between our Next.js client and server.
Courier API: a great service/platform to handle our notifications, such as email, SMS, and much more.

You can find the full source code here for reference.

Goals

Before building the features, let's define our goals.

Send invoice link to client's email.
Send a reminder a day before an invoice's due date.
Cancel an invoice due date reminder when the invoice is already paid.
Handling network errors.

Part 1: Setup Courier Platform

Let's head over to the Courier Dashboard. By default, it's in a production environment. Since I want to test things out, I'm going to change to the test environment by clicking the dropdown in the top-right corner.

We can copy all templates later to production or vice-versa.

Now, I will create a brand for my email notifications.

I'm just going to add a logo (beware that the logo width is fixed to 140px) on the header and social links on the footer. The designer UI is pretty straightforward, so here is the final result.

Don't forget to publish the changes.

Part 2: Send Invoice to Email

Currently, the send email button on the UI is doing nothing.

I'm going to create a courier.ts file in src/lib/ to keep all Courier-related code. Also, I will use courier node.js client library which already abstracted all Courier API endpoints to functions.

Before I build the functionality, let's create the email notification design within Courier's Designer and set up the Gmail provider.

On the email designer page, we will see that the created brand is already integrated. After that, let's design the template accordingly with the needed data. Here is the final result.

Notice the value with {} that becomes green, it means it's a variable that can be inserted dynamically. I also set the 'See Invoice' button (or action) with a variable.

Before I can use the template, I need to create a test event by clicking the preview tab. Then, it will show a prompt to name the event and set data in JSON format. That data field is what will populate the value of the green {} variables (the data can be set from code also). Since it's a test event, I will fill it with arbitrary values.

Next, I will publish the template so I can use it. Then, go to send tab. It will show the necessary code to send the email programmatically and the data will be populated with the previous test event that I created.

Backend

I will copy the test AUTH_TOKEN to the .env file and copy the snippet to src/lib/courier.ts.

const authToken = process.env.COURIER_AUTH_TOKEN;

// email to receive all sent notifications in DEVELOPMENT mode
const testEmail = process.env.COURIER_TEST_EMAIL;

const INVOICE_TEMPLATE_ID = <TEMPLATE_ID>;

const courierClient = CourierClient({
  authorizationToken: authToken,
});

Create a sendInvoice function that will be responsible for sending an email. To send an email from the code, I use the courierClient.send() function.

// src/lib/courier.ts

export const sendInvoice = async ({
  customerName,
  invoiceNumber,
  invoiceViewUrl,
  emailTo,
  productName,
  dueDate,
}: SendInvoice) => {

const recipientEmail = process.env.NODE_ENV === "production" ? emailTo : testEmail;

const { requestId } = await courierClient.send({
      message: {
        to: {
          email: recipientEmail,
        },
        template: INVOICE_TEMPLATE_ID,
        // Data for courier template designer
        data: {
          customerName,
          invoiceNumber,
          invoiceViewUrl,
          productName,
          dueDate,
        },
      },
    });
    return requestId
};

Define types for the sendInvoice function.

// src/lib/courier.ts

interface SendInvoice {
  productName: string;
  dueDate: string;
  customerName: string;
  invoiceNumber: string;
  invoiceViewUrl: string;
  emailTo: string;
}

Now that I can send the email, I will call it in the sendEmail trpc endpoint that resides in src/server/trpc/router/invoice.ts.

Just remember that trpc endpoint is a Next.js API route. In this case, sendEmail will be the same as calling the /api/trpc/sendEmail route with fetch under the hood. For more explanation https://trpc.io/docs/quickstart.

// src/server/trpc/router/invoice.ts
import { sendInvoice } from '@lib/courier';
import { dayjs } from '@lib/dayjs';

// .....SOMEWHERE BELOW
  sendEmail: protectedProcedure
    .input(
      z.object({
        customerName: z.string(),
        invoiceNumber: z.string(),
        invoiceViewUrl: z.string(),
        emailTo: z.string(),
        invoiceId: z.string(),
        productName: z.string(),
        dueDate: z.date(),
      })
    )
    .mutation(async ({ input }) => {
      const invoiceData = {
        ...input,
        dueDate: dayjs(input.dueDate).format('D MMMM YYYY'),
      };

      await sendInvoice(invoiceData);
    }),

For those who are unfamiliar with trpc, what I did is the same as handling a POST request. Let's break it down.

Trpc way of defining request input from client by validating with Zod. Here I define all data that are needed for the sendInvoice function.

.input(
      z.object({
        customerName: z.string(),
        invoiceNumber: z.string(),
        invoiceViewUrl: z.string(),
        emailTo: z.string(),
        invoiceId: z.string(),
        productName: z.string(),
        dueDate: z.date(),
      })
    )

Define a POST request handler (mutation).

// input from before
 .mutation(async ({ input }) => {
      const invoiceData = {
        ...input,
        // format a date to string with a defined format. 
        dueDate: dayjs(input.dueDate).format('D MMMM YYYY'), // ex.'2 January 2023'
      };

      // send the email
      await sendInvoice(invoiceData);
    }),

Frontend

Now, I can start to add the functionality to the send email button. I'm going to use the trpc.useMutation() function which is a thin wrapper of tanstack-query'suseMutation`.

Let's add the mutation function. On successful response, I want to send a success toast on UI.

`tsx
//src/pages/invoices/[invoiceId]/index.tsx
import toast from 'react-hot-toast';

const InvoiceDetail: NextPage = () => {
// calling the sendEmail trpc endpoint with tanstack-query.
const sendEmailMutation = trpc.invoice.sendEmail.useMutation({
onSuccess() {
toast.success('Email sent!');
}
});

}
`

I can just use the function as an inline handler, but I want to create a new handler for the button.

`ts
//src/pages/invoices/[invoiceId]/index.tsx

// still inside the InvoiceDetail component
const sendInvoiceEmail = () => {
const hostUrl = window.location.origin;

// prevent a user from spamming when the API call is not done.
if (sendEmailMutation.isLoading) return;

// send input data to `sendEmail` trpc endpoint
sendEmailMutation.mutate({
  customerName: invoiceDetail.customer.name,
  invoiceNumber: `#${invoiceDetail.invoiceNumber}`,
  invoiceViewUrl: `${hostUrl}/invoices/${invoiceDetail.id}/preview`,
  emailTo: invoiceDetail.customer.email,
  invoiceId: invoiceDetail.id,
  dueDate: invoiceDetail.dueDate,
  productName: invoiceDetail.name,
});

};
`

Now I can attach the handler to the send email button.

`ts
//src/pages/invoices/[invoiceId]/index.tsx

variant="primary"
onClick={sendInvoiceEmail}
isLoading={sendEmailMutation.isLoading}>
Send to Email

`

Here's the working UI.

Part 3: Send Payment Reminder

To schedule a reminder that will be sent a day before an invoice's due date, I'm going to use Courier's Automation API.

First, let's design the email template in Courier designer. As I already go through the process before, here is the final result.

Before adding the function, define the types for the parameter and refactor the types.

`ts
// src/lib/courier

interface CourierBaseData {
customerName: string;
invoiceNumber: string;
invoiceViewUrl: string;
emailTo: string;
}

interface SendInvoice extends CourierBaseData {
productName: string;
dueDate: string;
}

interface ScheduleReminder extends CourierBaseData {
scheduledDate: Date;
invoiceId: string;
}
`

Now, I add the scheduleReminder function to src/lib/courier

`ts
//src/pages/invoices/[invoiceId]/index.tsx

// check if the development environment is production
const IS_PROD = process.env.NODE_ENV === 'production';

const PAYMENT_REMINDER_TEMPLATE_ID = '';

export const scheduleReminder = async ({
scheduledDate,
emailTo,
invoiceViewUrl,
invoiceId,
customerName,
invoiceNumber,
}: ScheduleReminder) => {

// delay until a day before due date in production, else 20 seconds after sent for development
const delayUntilDate = IS_PROD
? scheduledDate
: new Date(Date.now() + SECOND_TO_MS * 20);

const recipientEmail = IS_PROD ? emailTo : testEmail;

// define the automation steps programmatically
const { runId } = await courierClient.automations.invokeAdHocAutomation({
automation: {
steps: [
// 1. Set delay for the next steps until given date in ISO string
{ action: 'delay', until: delayUntilDate.toISOString() },

      // 2. Send the email notification. Equivalent to `courierClient.send()`
      {
        action: 'send',
        message: {
          to: { email: recipientEmail },
          template: PAYMENT_REMINDER_TEMPLATE_ID,
          data: {
            invoiceViewUrl,
            customerName,
            invoiceNumber,
          },
        },
      },
    ],
  },
});

return runId;
};
`

To send the reminder, I will call scheduleReminder after a successful sendInvoice attempt. Let's modify the sendEmail trpc endpoint.

`ts
// src/server/trpc/router/invoice.ts

sendEmail: protectedProcedure
.input(..) // omitted for brevity
.mutation(async ({ input }) => {
// multiplier for converting day to milliseconds.
const DAY_TO_MS = 1000 * 60 * 60 * 24;

  // get a day before the due date
  const scheduledDate = new Date(input.dueDate.getTime() - DAY_TO_MS * 1);

  const invoiceData = {..}; //omitted for brevity

  await sendInvoice(invoiceData);

  //after the invoice is sent, schedule the reminder
  await scheduleReminder({
    ...invoiceData,
        scheduledDate,
  });
}

Now if I try to send an invoice by email, I should get a reminder 20 seconds later since I'm in the development environment.

Part 4: Cancel a reminder

Finally, all the features are ready. However, I got a problem, what if a client had paid before the scheduled date for payment reminder? Currently, the reminder email will still be sent. That's not a great user experience and potentially a confused client. Thankfully, Courier has an automation cancellation feature.

Let's add cancelAutomationWorkflow function that can cancel any automation workflow in src/lib/courier.ts.

`ts
export const cancelAutomationWorkflow = async ({
cancelation_token,
}: {
cancelation_token: string;
}) => {
const { runId } = await courierClient.automations.invokeAdHocAutomation({
automation: {
// define a cancel action, that sends a cancelation_token
steps: [{ action: 'cancel', cancelation_token }],
},
});

return runId;
};
`

What is a cancelation_token? It's a unique token that can be set to an automation workflow, so it's cancelable by sending a cancel action with a matching cancelation_token.

Add cancelation_token to scheduleReminder, I use the invoice's Id as a token.

`ts
// src/lib/courier.ts

export const scheduleReminder = async (..) => {
// ...omitted for brevity

const { runId } = await courierClient.automations.invokeAdHocAutomation({
automation: {
// add cancelation token here
cancelation_token: ${invoiceId}-reminder,
steps: [
{ action: 'delay', until: delayUntilDate.toISOString() },

// ... omitted for brevity
`

I will call cancelAutomationWorkflow when an invoice's status is updated to PAID in the updateStatus trpc endpoint.

`ts
// src/server/trpc/router/invoice.ts

updateStatus: protectedProcedure
.input(..) // omitted for brevity
.mutation(async ({ ctx, input }) => {
const { invoiceId, status } = input;

  // update an invoice's status in database
  const updatedInvoice = await ctx.prisma.invoice.update({
    where: { id: invoiceId },
    data: { status },
  });

  // cancel payment reminder automation workflow if the status is paid.
  if (updatedInvoice.status === 'PAID') {

    //call the cancel workflow to cancel the payment reminder for matching cancelation_token.
    await cancelAutomationWorkflow({
      cancelation_token: `${invoiceId}-reminder`,
    });
  }

  return updatedStatus;
}),

Here is the working UI.

Part 5: Error Handling

An important note when doing network requests is there are possibilities of failed requests/errors. I want to handle the error by throwing it to the client, so it can be reflected in UI.

On error, Courier API throws an error with CourierHttpClientError type by default. I will also have all functions' return value in src/lib/courier.ts consistent with the below format.

`ts
// On Success
type SuccessResponse = { data: any, error: null }

// On Error
type ErrorResponse = { data: any, error: string }
`

Now, I can handle errors by adding a try-catch block to all functions in src/lib/courier.ts.

`ts
try {
// ..function code

// modified return example
return { data: runId, error: null };

} catch (error) {
// make sure it's an error from Courier
if (error instanceof CourierHttpClientError) {
return { data: error.data, error: error.message };
} else {
return { data: null, error: "Something went wrong!" };
}
}
`

Let's see a handling example on the sendEmail trpc endpoint.

`ts
// src/server/trpc/router/invoice.ts

const { error: sendError } = await sendInvoice(..);
if (sendError) throw new TRPCClientError(sendError);

const { error: scheduleError } = await scheduleReminder(..);
if (scheduleError) throw new TRPCClientError(scheduleError);
`

Part 6: Go To Production

Now that all templates are ready, I will copy all assets in the test environment to production. Here is an example.

Conclusion

Finally, all the features are integrated with Courier. We've gone through a workflow of integrating Courier API to a Next.js application. Although it's in Next.js and trpc, the workflow will be pretty much the same with any other technology. I hope now you can integrate Courier into your application by yourself.

Get started now: https://app.courier.com/signup

About the Author

I'm Fazza Razaq Amiarso, a full-stack web developer from Indonesia. I'm also an Open Source enthusiast. I love to share my knowledge and learning on my blog. I occasionally help other developers on FrontendMentor in my free time.

Connect with me on LinkedIn.

Quick Links

🔗 Courier Docs

🔗 Contribute to Invoys

🔗 Invoys Motivation

Develop a Motivational QOTD with Courier and GPT2

Charla Bigelow — Mon, 13 Feb 2023 18:12:38 +0000

Motivational quotes were quite the rage back in the day when MMS & email forwarding were popular. I remember my parents forwarding me at the start of every morning. Fast forward to today, if you are lucky, you are part of some forward group on your messaging app of choice (Whatsapp, Telegram, etc.).

Inspired by the same idea, today we are going to build a service that sends our friends and family an AI generated motivational quote-of-the-day. Rather than hardcoding a list of motivational quotes, we are going to use a machine learning model to generate a quote on demand, so that we never run out of quotes to share!

Instructions

Part 1: Using AI to generate motivational quotes

OpenGPT2 and Language Models

OpenAI GPT-2 model was proposed in Language Models are Unsupervised Multitask Learners by Alec Radford, Jeffrey Wu, Rewon Child, David Luan, Dario Amodei and Ilya Sutskever. It’s a causal transformer pre-trained using language modeling on a very large corpus of ~40 GB of text data.

To simplify this, at a high level OpenAI GPT2 is a large language model that has been trained on massive amounts of data. This model can be used to predict the next token in a given sequence.

If that sounds too complicated, don't worry, you don't need to know any Machine Learning or AI to follow along with this project. Libraries such as Hugging Face make using this model in our app very easy.

Hugging Face

We'll use the Hugging Face library to load and serve the ML model that will generate the quotes for us. Hugging Face makes it very easy to use transformer models (of which GPT2 is a type) in our projects without any knowledge of ML or AI. As mentioned earlier, GPT2 is a general purpose language model which means that it is good at predicting generic text given an input sequence. In our case, we need a model more suited for generating quotes. To do that, we have two options:

We can fine-tune the GPT2 model by using our own text for which we'll need a good dataset of quotes.
Or we can find an already existing model which has been fine-tuned with some quotes.

Luckily, in our case there’s a fine-tuned model that has been trained on the 500k quotes dataset - https://huggingface.co/nandinib1999/quote-generator

With Hugging Face, using this model is as easy as as creating a tokenizer

from transformers import AutoTokenizer, AutoModelWithLMHead, pipeline

tokenizer = AutoTokenizer.from_pretrained("nandinib1999/quote-generator")

then, constructing a model from the pretrained model

model = AutoModelWithLMHead.from_pretrained("nandinib1999/quote-generator")

and finally, constructing the generator which we can use to generate the quote

generator = pipeline("text-generation", model=model, tokenizer=tokenizer)

# use a starting prompt
generator("Keep an open mind and")
[{'generated_text': 'Keep an open mind and a deep love for others'}]

Building an API to serve the model

Now that we have a way to generate quotes for us, we have to think about how we can use this in our app. There are multiple ways to go about building this.

Load the model everytime we want to run the script to send the script.
Create an API or service that serves this GPT2 model to generate quotes for us on demand.

A key plus point of the second option is that once the model is loaded the API can respond to us quickly and can be used in other applications as well. FWIW, the first option is a totally valid approach as well.

We can use Fast API to build a quick serving API. Here's what that looks like


# in file api.py

from pydantic import BaseModel
from fastapi import FastAPI, HTTPException
from transformers import AutoTokenizer, AutoModelWithLMHead, pipeline

## create the pipeline
tokenizer = AutoTokenizer.from_pretrained("nandinib1999/quote-generator")
model = AutoModelWithLMHead.from_pretrained("nandinib1999/quote-generator")
generator = pipeline("text-generation", model=model, tokenizer=tokenizer)

app = FastAPI()

class QuoteRequest(BaseModel):
    text: str

class QuoteResponse(BaseModel):
    text: str

### Serves the Model API to generate quote
@app.post("/generate", response_model=QuoteResponse)
async def generate(request: QuoteRequest):
    resp = generator(request.text)
    if not resp[0] and not resp[0]["generated_text"]:
        raise HTTPException(status_code=500, detail='Error in generation')
    return QuoteResponse(text=resp[0]["generated_text"])

Let's test it out

$ uvicorn api:app

INFO:     Started server process [40767]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Now we can start sending requests to the /generate endpoint that will generate a quote for us.

Part 2: Building the Quote Generator

Now that we have a way to generate quotes on demand, we can stop here and start working on sending this via Courier. But who are we kidding, no one reads text anymore! We can make this interesting by using a nice image and placing our quote on it to make it look like a poster.

Generate quote

Given our API, we can now do the following to generate a quote

from random import choice
# feel free to add more starting prompts for more variety
canned_seeds = ["Always remember to", "Start today with", "It is okay to"]
seed = choice(canned_seeds)
resp = requests.post('http://127.0.0.1:8000/generate', data=json.dumps({"text": seed}))
return resp.json()["text"]

Downloading the background image

The first challenge is getting a beautiful background image for our quote. For that, we'll use the Unsplash API that provides a nice endpoint to return a random image matching a query. Opening https://source.unsplash.com/random/800×800/?nature in our browser returns a nice nature image.

To keep things interesting, we can use different query terms such as stars, etc. Here's the how the code for downloading our background image looks like -

from random import choice
image_backgdrops = ['nature', 'stars', 'mountains', 'landscape']
backdrop = choice(image_backdrops)
response = requests.get("https://source.unsplash.com/random/800×800/?"+ backdrop, stream=True)
# write the output the img.png on our filesystem
with open('img.png', 'wb') as out_file:
    shutil.copyfileobj(response.raw, out_file)
del response

Creating the image with the quote

Ok, now we have our background image and a quote which means we can work on assembling the final image that will be sent to the recipients. At a high level we want to place some text on an image but even this simple task can be challenging. For starters, there are a number of questions for us to answer

How will the text be placed on the image?
What about wrapping the text?
What color should the text be so that it is visible on the background image?
How do we do this for images with varying widths and heights?

The answers to some of these questions are more complicated than others. To keep it simple, we'll put the text in the center, and do some wrapping so that it looks good. Finally, we'll use a light color text for now. For all image manipulation, we'll use Python Image Library (PIL) to make this easy for us.

# use the image we downloaded in the above step
img = Image.open("img.png")
width, height = img.size
image_editable = ImageDraw.Draw(img)

# wrap text
lines = textwrap.wrap(text, width=40)

# get the line count and generate a starting offset on y-axis
line_count = len(lines)
y_offset = height/2 - (line_count/2 * title_font.getbbox(lines[0])[3])

# for each line of text, we generate a (x,y) to calculate the positioning
for line in lines:
    (_, _, line_w, line_h) = title_font.getbbox(line)
    x = (width - line_w)/2
    image_editable.text((x,y_offset), line, (237, 230, 211), font=title_font)
    y_offset += line_h
img.save("result.jpg")
print("generated " + filename)
return filename

This generates the final image called result.jpg

Uploading the image

For the penultimate step, we need to upload the image so that we can use that with Courier. In this case, I'm using Firebase Storage but you can feel free to use whatever you like.

import firebase_admin
from firebase_admin import credentials
from firebase_admin import storage

cred = credentials.Certificate('serviceaccount.json')
firebase_admin.initialize_app(cred, {...})

bucket = storage.bucket()
blob = bucket.blob(filename)
blob.upload_from_filename(filename)
blob.make_public()
return blob.public_url

Step 3: Integrating with Courier

Finally, we have everything we need to start sending our awesome quotes to our friends and family. We can use Courier to create a good looking email template.

Start by creating an account.

Creating the template in Courier

Sending the message

Sending a message with Courier is as easy as it gets. While Courier has its own SDKs that can make integration easy, I prefer using their API endpoint to keep things simple. With my AUTH_TOKEN and TEMPLATE_ID in hand, we can use the following piece of code to send our image

import requests

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer {}".format(os.environ['COURIER_AUTH_TOKEN'])
}
message={
    "to": { "email": os.environ["COURIER_RECIPIENT"] },
    "data": {
        "date": datetime.today().strftime("%B %d, %Y"),
        "img": image_url ## this is image url we generated earlier
    },
    "routing": {
        "method": "single",
        "channels": [
            "email"
        ]
    },
    "template": os.environ["COURIER_TEMPLATE"]
}
requests.post("https://api.courier.com/send", json={"message": message}, headers=headers)

The API key can be found in Settings and the Template ID can be found in the template design's settings. And that's it!

Conclusions

This tutorial demonstrated how easy it is to get started with machine learning & Courier.

If you want to go ahead and improve this project, here are some interesting ideas to try

Better background image: Use a term from the generated quote to search for an image?
Better background color for the text: Use better colors for the text. One cool idea is to use the complimentary color from the image's main color. You can use k-means clustering to find that out.
Adding more channels : Extends this to messages on messaging clients and sms!

About the Author

Prakhar is a senior software engineer at Google where he works on building developer tools. He's a passionate open-source developer and loves playing the guitar in his free time.

Quick Links

🔗 Courier Docs

🔗 Hugging Face

🔗 Fast API

🔗 Unsplash API

I Owned a Major Product Feature as a PM Intern

Charla Bigelow — Fri, 09 Sep 2022 19:32:35 +0000

Preference management is an integral part of a great notification infrastructure, which makes it a very important piece of the puzzle here at Courier. This also means that there was a lot of learning and experience-building opportunity for the intern on the project, Denis Tatar. Denis’ internship was only a few months long, but he was able to make an enormous impact as the product manager for Courier’s Preferences feature.

We wanted to learn more about Denis’ experience, so we asked if he’d be willing to work on a writeup for us. Then what he came up with was so good, we thought it would be a good idea to share with all of you! This post will cover Denis’ workflow from planning to execution around the Preferences project as well as his experience working with the Courier team specifically. We’ll let Denis take it from here!

What was the problem?

The problem we experienced at Courier was that we’d offer Preferences (V3) to our customers, but the entire product feature’s strategy wasn’t fully fleshed out. I believe that V3 was a great stepping stone for V4, but fundamentally had flaws in certain parts of its strategy. Allowing only global opt-in/out is an example of this. Another problem was that V3 didn’t gain much traction, which I believe points back to the lack of a fully thought out strategy. In May, Preferences (V3) would only allow users to opt-in and out of their preferences of choice globally. V3 of Preferences only allowed our customers (and their customers) to opt-in/out of notifications, and customers globally could also decide if certain notifications were required or not. V3 helped give our customers the ability to start playing around with the idea of having preferences. However, globally opt/in out is a problem because it constrains end users’ notifications options. It was either all or nothing, no in-between. Similar in theory to the Pokemon saying, “Catch one, catch them all.” A problem with this, though, is inbox flooding. Global opt-in would allow for the concept of the end users’ inboxes becoming flooded with every product notification which is problematic because it can easily drive users away from your product.

Global opt-in/out was quickly resolved by allowing users to select what content they wanted to be notified of and the channels they’d prefer. This overall trend in the market is used by thousands of companies (B2B and B2C products), especially in the technology space.

Visibility became a serious issue with V3. End users never had the option to select what type of content and channel they wanted. Users would be asked if they were interested in receiving notifications in general. Not offering options is problematic as it constrains visibility on what you’ll receive through notifications. End users also don’t like surprises when it comes to product notifications. Having clarity is key because it enables end users to have control over their notifications.

With V4, we solved the visibility problem, which was the main “fail” from V3. Our customers and their end users now had the ability to control the content they received and the channels they would prefer.

V4 was a good way to strategically notify end users.

Plan

There were three phases we followed as a team when building Preferences.

1. Research
In phase one, I spent a decent amount of time looking at what is currently available in the market in terms of preference centers. I would constantly ask myself the following two questions:

“How does [insert company name] manage notifications? What does their preference center look like?”

These questions were key. They helped me dive into necessary research which helped me pick up on many important market trends. Out of all the trends found though, there was one that stood out the most.

2. Trend: Channel & content selection through a toggle/grid style layout for preference centers is a must have.

This trend became the backbone to our summer project. It was important to offer users preferences options.

During this phase, I read many case studies. I was surprised to see how many existed on this topic. Each one helped enlighten me with solutions for the problem we were tackling. I learned through other people’s mistakes, absorbing the valuable lessons.

Talking to customers was extremely helpful in this phase. I was able to hop on numerous calls with our customers and hear their perspectives on this problem. I would ask questions and show examples of what we had in mind for a solution. This helped tailor a POC. The better we understand our customers’ perspective, the easier it is to start designing something that they would use.

3. Designing a POC
I really enjoyed this phase. Watching research become an actual POC was incredible, and so fun. We took all the feedback I had gathered, then created several iterations of designs.

Once we created a POC, it was essential to go back to our customers and ensure that it was something they envisioned for Preferences. Our customers were also lovely people to work with, always there to provide their much-needed feedback.

Often, I would have a decent amount of brainstorming sessions with Ian. We’d look at our research and what our customers had to say, and combine these sources into a POC. It was an insightful process to be a part of.

This phase lasted several weeks until we finally landed on a POC that satisfied all of the customers we had spoken to since May 2022.

4. Building an MVP
Once we had a POC and fully completed designs, we began building our product feature. This phase taught me two vital lessons…

Being organized is extremely important.

and...

As a product manager, you need to stay one week ahead of your team.

While working at Courier and delegating tasks, I noticed that the more organized you were, the easier it was to work with others. My organizational skills would impact how clearly our designers and engineers understood our goals and individually delegated tasks. The more organized we were, the faster and more efficient we worked. Outlining the tasks our team needed to complete, and vocalizing why these tasks were necessary helped a lot. It brought clarity to everyone, including myself.

The second lesson here was given to me by our CEO,Troy. He taught me how important it was to think about the current and following week. Troy brought this up because, as a product manager, you want to keep your team informed on what projects and tasks are in the pipeline.. A product manager that isn’t in this mindset can quickly become a hindrance to their team. Taking on this mindset brought clarity and made me less stressed about our project. I would spend time planning each week,and estimating where the team should be at the end of each week (cycle).

These two lessons helped when we were building an MVP. We progressed through each week as a team, with each week’s tasks outlined, along with the weekly goals we’d needed to achieve. Working with the team at Courier was amazing, everyone was understanding and absolutely brilliant. What I loved the most was that everyone had an opinion. Engineers and designers would ask if specific tasks were priorities before building them, which allowed us to build the MVP and get it up and running quickly. These questions helped guide priorities and decision-making.

Execution: What I did exactly

Throughout this internship, every day was different. My week would involve speaking to customers, delegating tasks to our engineers and designers, and taking time to think ahead, two to three weeks ahead of the current week. I also worked closely with both engineers and designers, ensuring great synergy between both teams.

There were four core responsibilities that I embodied throughout my product manager internship at Courier:

Being the internal expert on what the market (customers & prospects) want within my realm of focus.

Being the internal expert on what my product feature already provides (and thus the delta to the above core responsibility).
The ability to prioritize the path that gets Courier from our current state to our desired state.

The ability to educate the rest of the company on the current product, the product being built, and our ultimate product vision so that everyone can be on the same page without being experts.
As the glue that ensures the team is working together on the right thing for the right reasons, their success is ultimately limited by my effectiveness in one and two. I cannot accurately educate teammates on what I don’t profoundly understand myself.

Troy was a fantastic mentor throughout my entire time at Courier. He brought these four core responsibilities to my attention, which became an integral part of my internship. What resonated with me the most was being the glue between all teams. At first, I looked at this concept and was intimidated by it. But, I had a blast easing myself into becoming this glue-like figure between teams. It definitely wasn’t something easy to pull off, but I enjoyed the challenge. I managed to make a lot of great friends along the way too!

What trade offs did I experience?

There were many trade-offs throughout my entire internship. The main ones I experienced were related to the following concept “make it work -> make it good -> make it fast,” which I often heard throughout my internship. There were many times when small features that could make our UI/UX stand out would actually slow down the team.

Trade-offs like these were necessary. They had me questioning whether we focus on the nitty gritty details, or do we put the feature aside and focus on making a product that functions and gets the job done? The latter part of that question was often chosen as our strategy. It’s tough to make these calls because you know the team can develop an outstanding product build with phenomenal UI/UX components, but our build must accomplish what it’s meant to do in the first place.

The main goal was to release our MVP, ensure we have customer feedback, improve any core features, and then focus on minor priorities that affect the UI/UX of this product.

What was it like working with the team?

I had a blast working with the Lifecycle team on Preferences. Everyone was so kind, and offered fantastic feedback. I’ve mentioned this numerous times around the office, and on calls with coworkers. Working at Courier didn’t feel like work; it felt like I was working on a side project with close friends. I genuinely think this is why I was able to produce the work I did at Courier, because of the environment. Courier is easy-going, extremely friendly, and results-driven.

Another thing I really loved about the team was that they always thought of me. If there were tasks that engineers or designers would do that was considered a ‘norm’ for them, they’d ask me if I’d like to give it a shot to see what it’s like. I have three examples of this.

When designing a specific tool tip for a part of the Preferences project, Ian (Senior Designer) during one of our calls, asked if I wanted a shot at designing a tool tip. This involved working with Frames in Figma, a concept I never worked with. I really enjoyed creating that tool tip. It made me feel included.

Every week the team would have our team Lifecycle planning meetings. We’d speak about tickets, and write them up. It was early on in my internship when Suhas (Senior Engineer) asked me if I wanted to try writing up several tickets on Linear. I was aware that this was something most PMs would normally do, but I had a lot of respect for Suhas for bringing this up, and was willing to teach me how to properly create tickets in Linear.
Once the team had something solidified for Preferences, I began to ask around internally to learn if there were any companies that would be interested in hearing about my project. Nathan (Account Executive), reached out to me to let me know about a customer interested in this product feature. Nathan encouraged me a TON when it came to communicating with this customer. I was able to step outside of my comfort zone because of Nathan’s encouragement. I’ve never gotten to speak to a customer before at any of my previous internship experiences, and I learned a lot about customers and the way they perceive Courier.

Note that these are just three examples from the many opportunities like this throughout my internship. I do want to give a big shoutout to Ian, Suhas, and Nathan. I appreciate you guys giving me opportunities to learn and grow, it means the world to me.

How did I work with designers?

I enjoyed working with Ian (Senior Designer). We’d have impromptu meetings through Slack’s ‘Huddle’ feature, (which was internally renamed to ‘Huggle’ because of a typo I once made that stuck). These meetings were really great for brainstorming and product design. Sometimes, Ian and I would have calls later at night because it was easier to come up with more creative ideas.. We’d have one to two hour sessions, and we’d come up with some really awesome UI/UX for Preferences. This is something I’ll never forget.

When working with Ian, I would try to make it as easy as possible. I would create a to-do list through Google docs or Slack, so both Ian and I would be aware of what needed to be completed every week.

During our calls, Ian and I would also talk about a lot of different topics not always directly related to work, which was great. This really helped build our friendship, making it so much easier to collaborate and come up with a clean UI/UX for Preferences. I often do a decent amount of product design outside of work hours, and Ian would always give me phenomenal advice on product design and on Figma!

How did I work with engineers?

I briefly touched on this, but when working with engineers, I would help create tickets, and organize what each week would look like. I helped our engineers whenever they were confused about anything related to Preferences, and would explain how I came up with specific names, why Ian and I would design certain parts of our product, and the goals behind these designs. Many of these answers came from my extensive research process with customers that were interested in Preferences.

While working with engineers, I learned a lot on how to properly break down tickets (eipcs) within Linear. I thought I had a firm grasp before working at Courier, but I learned a lot more after working with the Lifecycle team. The key to breaking down tickets is to be able to think about every single detail alongside engineers. Being in a small group while doing this was super important, because each individual helped bring up a very important perspective on how to break down tickets.

During my internship, Seth (Chief Technology Officer), Suhas (Senior Software Engineer), Christian (Software Engineer) encouraged me to speak to the Developer Experience team at Courier and show them our project. The main goal behind this was to test to see if the UI/UX of Preferences was intuitive, if the design made sense, and if the Developer Experience team understood the goal behind this product feature. I prepared a slide deck explaining our project in its entirety. This was a great experience because it helped me prepare on how to sell Preferences to our customers. Giving insightful presentations about products and “selling” your product to customers is such an important and overlooked skill for product managers. Speaking to folks internally helped me practice and refine this skill, as well..

How did I solve the problem?

Before V4 Preferences, customers weren’t given the option of choosing what content they’d like to hear about, and how they’d like to hear about it. With V4 Preferences, users now can voice their opinions on both of these matters. This new product feature makes it possible for customers to choose what they like, and want to hear about. Specifically through their channels preference.

Gone are the days of inbox cluttering and customers becoming aggravated with the amount of notifications they receive. Preferences minimizes the frustration that end users experience with their notifications.

Want to apply for a role at Courier? Check out our careers page. To check out what Denis helped build in action, request a demo here and ask to see the Preferences feature.

Build a WebAssembly Language for Fun and Profit: Code Generation

Charla Bigelow — Fri, 02 Sep 2022 15:54:06 +0000

by Andrew Youngwerth

The final phase of our compiler is code generation. This phase takes the AST and converts it
to a set of executable instructions. In our case, WebAssembly. To accomplish this, we are going
to use a popular WebAssembly compiler toolchain called binaryen.

Binaryen does most of the heavy compiling tasks for us. Tricky optimizations like dead-code removal, code folding, and more are all handled out of the box. Thanks to binaryen, we can make a powerful language with very little code.

This is the third article in the Build a programming language series. If you’re just starting out, start with the first post here before continuing on.

The Compile function

One of the trickiest tasks in code generation is what to call the code generation function. For this article, I have opted to call the main function compile. The compile function will take our root AST (a BlockNode) and return a new binaryen.Module. The binaryen.Module exposes functions that can optimize and emit wasm in various formats.

Here's the outline:

// src/compiler.mts
import binaryen from "binaryen";
import { AstNode, BlockNode, IdentifierNode } from "./types/index.mjs";

export const compile = (block: BlockNode): binaryen.Module => {
  // Creates a new binaryen module that our helper functions will fill in
  const mod = new binaryen.Module();

  // The function map is used to track all the functions and their types. More on this later
  const functionMap = generateFunctionMap(block);

  // This function registers all the standard library functions we'll include with our language.
  // This includes functions like add, subtract, etc.
  registerStandardFunctions(mod, functionMap);

  // This is where the magic happens. Because `BlockNode` is an expression, this
  // function can recursively compile every instruction in a wispy program file
  compileExpression({
    expression: block,
    mod,
    functionMap,
    parameters: new Map(),
  });

  // Finally, we return the binaryen module
  return mod;
};

Generating A Function Map

Next we define the generateFunctionMap function. This function crawls the entire expression
tree to find and register function definitions. Its important we do this before actually
compiling the functions as some functions may call other functions before they've been defined.

The return type of generateFunctionMap is a map where the key is the function name and the
value is an object containing all the important information about the function the compiler
needs to know about. For now, all we need is returnType.

Here’s the return type definition:

// src/compiler.mts
type FunctionMap = Map<string, { returnType: number }>;

Now that we have defined our return type, we can define the actual function:

// src/compiler.mts
const generateFunctionMap = (block: BlockNode): FunctionMap => {
  // Preview the first node (i.e. expression) of the block
  const firstNode = block.expressions[0];

  // If the first node is an identifier and the identifier is "fn", then we know this block represents a function definition.
  if (isNodeType(firstNode, "identifier") && firstNode.identifier === "fn") {
    // Grab the function identifier / name, and it's return type. This is the second expression of
    // the function definition, a typed identifier.
    const { identifier, returnType } = getFunctionIdentifier(block); // We'll define this next

    // Return the function map
    return new Map([
      [identifier, { returnType }],

      // It's possible this function may contain function definitions inside of it. So we
      // We put all the remaining expressions of the function into a new block and scan it
      // then we merge the resulting map with this one.
      ...generateFunctionMap({ type: "block", expressions: block.expressions.slice(3) }),
    ]);
  }

  // A block can contain multiple expressions. So, we must scan each one to see if it is a function
  // definition. The root `BlockNode` for instance, will almost always have multiple functions.
  return block.expressions.reduce((map, expression) => {
    // Only block expressions can be functions
    if (expression.type === "block") {
      return new Map([...map, ...generateFunctionMap(expression)]);
    }

    // We can ignore all other expression
    return map;
  }, new Map());
};

Onto getFunctionIdentifier we called earlier. This function is simple. It takes a BlockNode, ensures that the second identifier is a TypedIdentifierNode, and then returns the identifier
and return type:

// src/compiler.mts
const getFunctionIdentifier = (block: BlockNode) => {
  // Grab the second expression
  const node = block.expressions[1];

  // Ensure the expression is a typed identifier
  if (!isNodeType(node, "typed-identifier")) {
    throw new Error("Expected typed function name");
  }

  return {
    identifier: node.identifier,

    // We have to map the return type to a type binaryen understands.
    returnType: mapBinaryenType(node.typeIdentifier),
  };
};

As noted in the getFunctionIdentifier function, Binaryen doesn't understand what type
the string typeIdentifier is. To handle this we have to map our defined types to binaryen types. For now, we'll just support i32 and f32. Thankfully binaryen uses the same nomenclature we do. So the map function is pretty simple:

// src/compiler.mts
const mapBinaryenType = (typeIdentifier: string): binaryen.Type => {
  if (typeIdentifier === "i32") return binaryen.i32;
  if (typeIdentifier === "f32") return binaryen.f32;
  throw new Error(`Unsupported type ${typeIdentifier}`);
};

getFunctionIdentifier Made a call to a new function, isNodeType. This function is
essentially the same concept as the isTokenType function we defined in the parsing article, only for ASTNode instead of Token.

Here's the definition:

// src/compiler.mts
export const isNodeType = <T extends AstNode["type"]>(
  item: unknown,
  type: T
): item is Extract<AstNode, { type: T }> => {
  return (
    // Ensure the type exists
    !!item &&
    // Ensure the type is an object
    typeof item === "object" &&
    // Cast the type as a record, so TypeScript doesn't get mad at us and then compare the
    // type field with the type parameter. If they are equal, we know the node is the
    // the type we were looking for.
    (item as Record<string, unknown>)["type"] === type;
  )
};

With the mapper finished we can start generating some code.

Compiling Expressions

The compileExpression function is where we really start to make use of binaryen to model
the generated machine code. Because of the tree structure of an, ahem, abstract syntax tree,
compileExpression is highly recursive. This is one of my favorite things about programming
languages, their patterns tend to lend themselves to elegant recursive functions with high
levels of code re-use.

Let's start with defining the parameters of compileExpression. We will need to pass the
binaryen.Module and the functionMap we created earlier, the actual expression we are
compiling, and any parameters of the function this expression may be a part of (if it's inside)
of a function. When there are more than two parameters of a function it can be difficult
to visually keep track of what is what. So I like to make it clear by grouping them together
in an object. This enforces labeling the parameters on call and as a result, improves code
readability.

Here's the interface of that object:

// src/compiler.mts
interface CompileExpressionOpts {
  expression: AstNode;
  mod: binaryen.Module;
  functionMap: FunctionMap; // We defined this earlier
  parameters: ParameterMap; // Defined below.
}

// A map where the key is the parameter identifier and the value is the important information
// required by binaryen to fetch the parameter down the line
type ParameterMap = Map<string, { index: number; type: number }>;

Now that we have the options for compileExpression defined, we can define the actual function. compileExpression takes CompileExpressionOpts as a parameter and returns a number. The job of this function is to take an expression and determine what type of expression it is, from there it can pass the expression to another compiler function that can handle that specific type of expression.

Why return a number? When we build an expression with binaryen it returns a number as an identifier for that expression. This allows us to compile an expression ahead of time and then reference that expression later down the line.

Here's the definition:

// src/compiler.mts
const compileExpression = (opts: CompileExpressionOpts): number => {
  // Grab the expression and the binaryen module (mod) from the options.
  // The other fields are used by child function calls
  const { expression, mod } = opts;

  // Map the expression node to it's corresponding specific compiler
  if (isNodeType(expression, "block")) return compileBlock({ ...opts, expression });

  // Numbers are simple enough to compiler that we can just inline the compiler here.
  // They are represented as constants
  if (isNodeType(expression, "int")) return mod.i32.const(expression.value);
  if (isNodeType(expression, "float")) return mod.f32.const(expression.value);

  if (isNodeType(expression, "identifier")) return compileIdentifier({ ...opts, expression });

  // Throw a helpful error message if we don't recognize the expression
  throw new Error(`Unrecognized expression ${expression.type}`);
};

Let's define the compileBlock functions. Because this function is also compiling an expression,
we can re-use the previously defined CompileExpressionOpts, but we'll narrow the expression
field to the BlockNode type, since we know we are compiling a block by the time this function is called:

interface CompileBlockOpts extends CompileExpressionOpts {
  expression: BlockNode;
}

const compileBlock = (opts: CompileBlockOpts): number => {
  // We re-map the expression field to block here for clarity.
  const { expression: block, mod } = opts;

  // When a block has multiple expressions and the first one is an identifier, that means
  // the block is actually a function call.
  if (isNodeType(block.expressions[0], "identifier") && block.expressions.length > 1) {
    // If it is a function call, transfer responsibility to the `compileFunctionCall` function (defined next)
    return compileFunctionCall(opts);
  }

  // This is where the recursive beauty starts to show. Since every value of a block
  // is an expression, we can map each one back to the compileExpression function.
  const expressions = block.expressions.map((expression) => {
    return compileExpression({ ...opts, expression });
  });

  // Now we generate the machine code by calling the block function of binaryen
  // This function takes a block name, an array of compiled expressions, and a block return type.
  // Named blocks are mostly useful for looping constructs like `for` and `while`. In this
  // case we can pass null as we're not compiling a loop construct. Additionally, we can
  // pass `auto` as the type since binaryen is smart enough to determine the return type
  // of blocks automatically.
  return mod.block(null, expressions, binaryen.auto);
};

Note: If you're curious to see how looping works in binaryen / WebAssembly works, check out my blog post on the subject here. Spoiler alert, its pretty weird.

The last simple expression we'll compile in this section is the identifier expression. If
compileExpression was passed a lone IdentifierNode it means that the expression evaluates
to the value of the identifier. In wispy, we don't have variables and function identifiers are
caught before the could've been passed here. That means the only thing IdentifierNode can
resolve to is a parameter.

Here's the definition:

interface CompileIdentifierOpts extends CompileExpressionOpts {
  expression: IdentifierNode;
}

const compileIdentifier = (opts: CompileIdentifierOpts): number => {
  // We remap expression to node to keep our lines a little shorter
  const { expression: node, parameters, mod } = opts;

  // Since we know the identifier has to be a parameter, we look it up in our
  // parameter map. Don't worry, we'll define the parameter map in the next section
  const info = parameters.get(node.identifier);
  if (!info) {
    throw new Error(`Unrecognized identifier ${node.identifier}`);
  }

  // Finally, we use the local.get instruction to return the parameter value.
  // Binaryen needs to know the parameters index and type. We'll get into
  // the index when we define our parameter mapping function.
  return mod.local.get(info.index, info.type);
};

The final expression type left to compile is a function call. This is interesting enough
to warrant its own section.

Compiling Function Calls

In wispy function calls are blocks with multiple expressions where the first expression is an
identifier. The job of compileFunction is to determine which function is being called, what
its parameters and return type are, and finally, building the call instruction with binaryen.

Here's the definition:

// src/compiler.mts

// Because function calls are blocks, we can re-use CompileBlockOpts
const compileFunctionCall = (opts: CompileBlockOpts): number => {
  const { expression, functionMap, mod } = opts;

  // The first expression of a function call is the functions identifier
  const identifierNode = expression.expressions[0];

  // Here we just ensure the identifierNode is *actually* an identifier. Otherwise we throw an error.
  if (!isNodeType(identifierNode, "identifier")) {
    throw new Error("Expected identifier when compiling function call");
  }

  // Next we create a reference to what the actual identifier is
  const identifier = identifierNode.identifier;

  // If the identifier is "fn", the function we are calling is the function to define functions!
  // That's right! Functions are created by another function. Pretty neat if you ask me.
  if (identifier === "fn") return compileFunction(opts); // We'll define this next

  // Ifs are special functions. They may or may not have an else block. Binaryen needs to know
  // if the else block exists at compile time, so we have a special if compiler for this.
  if (identifier === "if") return compileIf(opts); // We'll define this later

  // Every other function is either part of the standard library, or is defined
  // within the wispy code itself.
  const functionInfo = functionMap.get(identifier);
  if (!functionInfo) {
    throw new Error(`Function ${identifier} not found`);
  }

  const params = expression.expressions
    // Every other expression in the block are parameters to the function, so we compile them
    // and then pass them to the call
    .slice(1)
    .map((expression) => compileExpression({ ...opts, expression }));

  // Now we use binaryen to construct the call expression. The first parameter
  // is the functions identifier, the second are the compiled parameter expression,
  // and the third is the return type which has already been determined by generateFunctionMap
  return mod.call(identifier, params, functionInfo.returnType);
};

Let's define the compileIf function before we move onto the compileFunction... function.

// src/compiler.mts

const compileIf = (opts: CompileBlockOpts): number => {
  const { expression, mod } = opts;

  // The first expression, expression.expressions[0], is the "if" identifier, we don't need
  // to do anything with it since we already know we are compiling an if expression

  // The second expression is the if condition
  const conditionNode = expression.expressions[1];

  // The third expression is the ifTrueNode, it's what is executed if the conditionNode evaluates to
  // true
  const ifTrueNode = expression.expressions[2];

  // Finally the fourth expression (which may or may not exist) is what is executed if the condition
  // evaluates to false
  const ifFalseNode = expression.expressions[3];

  // Compile the condition expression
  const condition = compileExpression({ ...opts, expression: conditionNode });

  // Compile the ifTrue Expression
  const ifTrue = compileExpression({ ...opts, expression: ifTrueNode });

  // Check to see if the ifFalseNode exists, if it does, compile it, otherwise set ifFalse to undefined
  const ifFalse = ifFalseNode ? compileExpression({ ...opts, expression: ifFalseNode }) : undefined;

  // Finally we use binaryen to compile the if expression
  return mod.if(condition, ifTrue, ifFalse);
};

Compiling Function Definitions

Function definitions are a whole lot like function calls, so the function structure is pretty similar.
We take CompileBlockOpts and return a number (the binaryen expression reference).

Here's the definition:

// src/compiler.mts

const compileFunction = (opts: CompileBlockOpts): number => {
  const { expression: block, mod } = opts;

  // We need to tell binaryen what the identifier and return type of the function is
  // Thankfully, we already wrote a function for that, getFunctionIdentifier. We
  // could also have just looked up this information with the functionMap, but
  // this is more fun.
  const { identifier, returnType } = getFunctionIdentifier(block);

  // Next we grab the function parameters. This is the third expression of the function
  const { parameters, parameterTypes } = getFunctionParameters(block); // Defined later

  // The rest of the expressions in the function are the functions block. So we create
  // a new BlockNode from the remaining expression.
  const body = compileBlock({
    ...opts,
    expression: {
      type: "block",
      expressions: block.expressions.slice(3),
    },

    // We need to pass the parameters of this function, so they can be referenced in child
    // expressions
    parameters,
  });

  // Now we register the function with binaryen. Binaryen takes the function identifier,
  // an array of parameter types (each item being the type of parameter in order),
  // the function's return type, a list of variable types (wispy doesn't have any, so we pass an empty array)
  // and finally the compiled body of the function.
  mod.addFunction(identifier, parameterTypes, returnType, [], body);

  // To make things easy we export every single function defined in a wispy file
  // so it can be called by the WebAssembly host.
  mod.addFunctionExport(identifier, identifier);

  // Because function definitions are *technically* expressions that can be a part of another function
  // body, we need to return an expression pointer. For this, we just return a nop (do nothing instruction),
  // to make things consistent.
  return mod.nop();
};

Now, let's define the getFunctionParameters function. This function takes the function BlockNode, that is, the entire unmodified function definition, and extracts its parameters. The function returns two values, parameters and parameterTypes.

The first returned value, parameters, is a map where the key is the parameter identifier, and the value is the information needed to access the parameter down the line within the function body.

The second returned value is an array of binaryen types. There is one type for each defined parameter, and they must remain in the order they are defined. This is because binaryen doesn't reference parameters by their names, instead it references them by the index of the array in which they are defined. Don't worry if this is confusing to you, the code should make things a little more clear. If you need, refer to the compileIdentifier definition, to get a better
understanding of how this works in practice.

Here's the definition:

// src/compiler.mts

type ParameterMap = Map<string, { index: number; type: number }>;

const getFunctionParameters = (block: BlockNode) => {
  // The parameters are defined in the third expression of the function definition
  const node = block.expressions[2];

  // Check to make sure the third expression is a block
  if (!isNodeType(node, "block")) {
    throw new Error("Expected function parameters");
  }

  // Now we reduce the parameters into a parameter map, and a list of binaryen types
  const { parameters, types } = node.expressions.reduce(
    (prev, node, index) => {
      // First, ensure that the node is a typed-identifier. Every parameter must be a
      // typed identifier, therefore, every node in this reducer must be a typed identifier.
      if (!isNodeType(node, "typed-identifier")) {
        throw new Error("All parameters must be typed");
      }

      // Determine the correct binaryen type of the parameter
      const type = mapBinaryenType(node.typeIdentifier);

      // Add the parameter's type to the list of types we've defined so far
      const types = [type, ...prev.types];

      // Now add the parameter to the parameter map. We save the parameters index and type.
      // The index and type is used binaryen to access the parameter when it is used
      // later in the function body
      const parameters = new Map([[node.identifier, { index, type }], ...prev.parameters]);

      // Return updated parameters map and types array
      return {
        parameters,
        types,
      };
    },
    // Here we are setting the starting values for our reducer function and casting the default
    // type so typescript can correctly infer the `prev` parameter type
    { parameters: new Map(), types: [] } as {
      parameters: ParameterMap;
      types: number[];
    }
  );

  // Finally we return the parameter map and the parameterTypes
  return {
    parameters,

    // Note: parameterTypes is a number, instead of an array of numbers as you'd expect.
    // So we have to use binaryen.createType to create a new type that is referenced
    // the mod.addFunction function. This is one inconsistency with the binaryen API. Parameters
    // are defined as a number, and variables are defined as an array of numbers. I'm sure there
    // is a reason for this, but I don't know what that reason is.
    parameterTypes: binaryen.createType(types),
  };
};

Now all that's left is to define the standard library. This part of the code isn't super interesting.
We are essentially just mapping primitive WebAssembly instructions to a name to be referenced
within wispy.

Here's the definitions. The only important information is the name we are associating with each
instruction:

// src/compiler.mts

const registerStandardFunctions = (mod: binaryen.Module, map: FunctionMap) => {
  const { i32, f32 } = binaryen;
  const { i32: i32m, f32: f32m } = mod;
  const common = { mod, map };
  registerLogicFunction({ name: "lt_i32", type: i32, operator: i32m.lt_s, ...common });
  registerLogicFunction({ name: "gt_i32", type: i32, operator: i32m.gt_s, ...common });
  registerLogicFunction({ name: "eq_i32", type: i32, operator: i32m.eq, ...common });
  registerLogicFunction({ name: "lt_f32", type: f32, operator: f32m.lt, ...common });
  registerLogicFunction({ name: "gt_f32", type: f32, operator: f32m.gt, ...common });
  registerLogicFunction({ name: "eq_f32", type: f32, operator: f32m.eq, ...common });
  registerMathFunction({ name: "add_i32", type: i32, operator: i32m.add, ...common });
  registerMathFunction({ name: "sub_i32", type: i32, operator: i32m.sub, ...common });
  registerMathFunction({ name: "mul_i32", type: i32, operator: i32m.mul, ...common });
  registerMathFunction({ name: "add_f32", type: f32, operator: f32m.add, ...common });
  registerMathFunction({ name: "sub_f32", type: f32, operator: f32m.sub, ...common });
  registerMathFunction({ name: "mul_f32", type: f32, operator: f32m.mul, ...common });
  registerMathFunction({ name: "div_f32", type: f32, operator: f32m.div, ...common });
};

const registerMathFunction = (opts: {
  mod: binaryen.Module;
  name: string;
  type: number;
  operator: (left: number, right: number) => number;
  map: FunctionMap;
}) => {
  const { mod, name, type, operator, map } = opts;
  return registerBinaryFunction({
    mod,
    name,
    paramType: type,
    returnType: type,
    operator,
    map,
  });
};

const registerLogicFunction = (opts: {
  mod: binaryen.Module;
  name: string;
  type: number;
  operator: (left: number, right: number) => number;
  map: FunctionMap;
}) => {
  const { mod, name, type, operator, map } = opts;
  return registerBinaryFunction({
    mod,
    name,
    paramType: type,
    returnType: binaryen.i32,
    operator,
    map,
  });
};

const registerBinaryFunction = (opts: {
  mod: binaryen.Module;
  name: string;
  paramType: number;
  returnType: number;
  operator: (left: number, right: number) => number;
  map: FunctionMap;
}) => {
  const { mod, name, paramType, returnType, operator, map } = opts;
  mod.addFunction(
    name,
    binaryen.createType([paramType, paramType]),
    returnType,
    [],
    mod.block(
      null,
      [operator(mod.local.get(0, paramType), mod.local.get(1, paramType))],
      binaryen.auto
    )
  );
  map.set(name, { returnType });
};

By now src/compiler.mts should look something like this. With that, our compiler is finished. It's time to execute some wispy!

Putting It All Together

Now that we have finished our compiler, we can finally run our code.

First, replace the contents of src/index.mts with this:

// src/index.mts

#!/usr/bin/env node
import { readFileSync } from "fs";
import { compile } from "./compiler.mjs";
import { lex } from "./lexer.mjs";
import { parse } from "./parser.mjs";

const file = process.argv[2];
const input = readFileSync(file, "utf8");

const tokens = lex(input);
const ast = parse(tokens);

// !! New !!
const mod = compile(ast);

// This is sneakily where the code gen is *actually* happening
const binary = mod.emitBinary();

// Use the standard WebAssembly API to convert the wasm binary to a compiled module
// our host NodeJS/v8 can use
const compiled = new WebAssembly.Module(binary);

// Build the instance, here you would add any external functions you might want to import into
// the WebAssembly module
const instance = new WebAssembly.Instance(compiled, {});

// Finally, run the main function and log the result. We have to cast instance.exports to any
// The standard TypeScript types appear to be wrong.
console.log((instance.exports as any).main());

Now build and run project:

npx tsc
wispy example.wispy

If all goes well (and you passed the number 15 to fib), you should see the number 610 in the
output of your console. If so, you've done it, you've made a working WebAssembly language. Congrats!

A full copy of the wispy language implementation is available under an open-source license at https://github.com/drew-y/wispy.

Build a WebAssembly Language for Fun and Profit: Parsing

Charla Bigelow — Fri, 26 Aug 2022 15:56:00 +0000

By Andrew Youngwerth

In the last post of this series on how to build a WebAssembly programming language, we constructed a lexer. In this post, we’ll cover the next phase of our compiler, parsing. Parsing is the portion of our compiler that takes the token stream generated by the lexer and converts it into an abstract syntax tree (AST).

An AST is a tree-like data structure that organizes the tokens into a logical hierarchy that can more easily be translated into machine code. Thankfully, because wispy is an S-expression language, our code is essentially already an AST. Take the following stream of tokens:

“(“, “add”, “3”, “(“, “sub”, “2”, “1”, “)”, “)”

Each set of parentheses represents a subtree, where the first token is the operator node and the following tokens are its operands. If we run into another opening parenthesis before the current set is closed, we know it represents an operand that itself is a subtree. The above stream of tokens would be organized into a tree that looks like this:

If you're interested in writing a parser for a more complex C-like syntax, see my previous Building A Programming Language series.

More About AST

As we did with the lexer, we'll start by defining our types. These types will define the structure of our AST. Each type represents a “Node”, the circle from our diagram in the intro. Here are the basic nodes. We'll gloss over them, as they aren't a lot different from the tokens we defined in the lexer:

// src/types/ast.mts

export type IntNode = {
  type: "int";
  value: number;
};

export type FloatNode = {
  type: "float";
  value: number;
};

export type IdentifierNode = {
  type: "identifier";
  identifier: string;
};

export type TypedIdentifierNode = {
  type: "typed-identifier";
  // Note that here, we break down the identifier into its components
  identifier: string;
  typeIdentifier: string;
};

A new concept to the AST is the BlockNode. A BlockNode is an expression made up of a group of other nodes.

For example, (add 1 2) is a block of three nodes:

An identifier that evaluates to a function, add.
An Int that simply evaluates to the number 1.
An Int that simply evaluates to the number 2.

How the block itself gets evaluated is up to the compiler. We'll get to that in the next post.

Here's the definition:

// src/types/ast.mts

export type BlockNode = {
  type: "block";
  expressions: AstNode[];
};

Finally, we define the AstNode. Like the Token type from the lexer, AstNode is a discriminated union that can be one of any other node we previously defined:

export type AstNode = IntNode | FloatNode | IdentifierNode | TypedIdentifierNode | BlockNode;

You may have noticed that BlockNode has an array of AstNodes, Since AstNode can be a BlockNode, BlockNodes can contain child BlockNodes. In other words, BlockNode is a recursive type. This ability to recursively represent children that can have children is the foundation of our AST. It's where the tree in AST is allowed to form.

At this point src/types/ast.mts is finished and should look like this file.

Now export the types from src/types/index.mts as we did with the token types:

// src/types/index.mts
export * from "./token.mjs";
export * from "./ast.mjs";

Constructing the AST

Now that we've defined the AST, it's time to build one.

Create a new src/parser.mts file and add all the imports we'll use:

// src/parser.mts
import {
  Token,
  IdentifierNode,
  TypedIdentifierNode,
  IdentifierToken,
  TypedIdentifierToken,
  FloatToken,
  FloatNode,
  IntToken,
  IntNode,
  AstNode,
  BlockNode,
} from "./types/index.mjs";

Now we can define our top level parse function. The parse function takes the tokens generated by the lexer and returns a BlockNode that acts as our tree’s root.

// src/parser.mts
export const parse = (tokens: Token[]): BlockNode => {
  const blocks: BlockNode[] = [];

  // This loop is run as long as there are tokens to consume
  while (tokens.length) {
    // consumeTokenTree converts an array of tokens into a tree of tokens, more on that later.
    const tree = consumeTokenTree(tokens);

    // parseBlock turns our new tree of tokens into an actual BlockNode, recursively. More on that later as well.
    blocks.push(parseBlock(tree));
  }

  // Finally we return the top level BlockNode
  return {
    type: "block",
    expressions: blocks,
  };
};

Next we define the consumeTokenTree function. consumeTokenTree converts a flat array of tokens, into a tree of tokens.

Given this wispy expression:

(add (sub 3 1) (sub 5 2))

The lexer will produce this array of tokens:

// Note: I've simplified the Token format to just be strings to keep things short
["(", "add", "(", "sub", "3", "1", ")", "(", "sub", "5", "2", ")", ")"];

consumeTokenTree will take that flat array and turn it into a tree. This is as simple as putting every token in between a set of bracket tokens () into an array. So our token array from above becomes this token tree:

["add", [, "sub", "3", "1"], ["sub", "5", "2"]];

Here's the actual definition of consumeTokenTree:

// src/parser.mts

// This is token besides for the bracket tokens
export type NonBracketToken = Exclude<Token, "parenthesis" | "square-bracket">;

// The token tree is made of NonBracketTokens and other TokenTrees
export type TokenTree = (NonBracketToken | TokenTree)[];

const consumeTokenTree = (tokens: Token[]): TokenTree => {
  const tree: TokenTree = [];

  // Ensures the first token is a left bracket and then discards it, defined below this function.
  consumeLeftBracket(tokens);

  while (tokens.length) {
    // Preview the next token
    const token = tokens[0];

    // Check to see if the next token is a left bracket.
    if (token.type === "bracket" && getBracketDirection(token) === "left") {
      // If it is, we just ran into a sub-TokenTree. So we can simply call this function within
      // itself. Gotta love recursion.
      tree.push(consumeTokenTree(tokens));
      continue;
    }

    // Check to see if the next token is a right bracket
    if (token.type === "bracket" && getBracketDirection(token) === "right") {
      // If it is, we just found the end of the tree on our current level
      tree.shift(); // Discard the right bracket
      break; // Break the loop
    }

    // If the token isn't a bracket, it can simply be added to the tree on this level
    tree.push(token);

    // Consume / discard the token from the main tokens array
    tokens.shift();
  }

  // Return the tree. Don't forget to check out the helper functions below!
  return tree;
};

const consumeLeftBracket = (tokens: Token[]) => {
  const bracketDirection = getBracketDirection(tokens[0]);

  if (bracketDirection !== "left") {
    throw new Error("Expected left bracket");
  }

  return tokens.shift();
};

const getBracketDirection = (token: Token): "left" | "right" => {
  if (token.type !== "bracket") {
    throw new Error(`Expected bracket, got ${token.type}`);
  }

  // If we match a left bracket return left
  if (/[\(\[]/.test(token.value)) return "left";

  // Otherwise return right
  return "right";
};

Now that we have a token tree, we need to turn it into a block. To do so, we create aparseBlock function that takes the tree as its input and returns a BlockNode:

const parseBlock = (block?: TokenTree): BlockNode => {
  return {
    type: "block",
    // This is where the recursive magic happens
    expressions: block.map(parseExpression),
  };
};

As you may have noticed, parseBlock maps each item of the tree with a yet to be writtenparseExpression function. parseExpression takes either a TokenTree or a NonBracketToken and transforms it to its corresponding AstNode type.

Here's the definition:

const parseExpression = (expression?: TokenTree | NonBracketToken): AstNode => {
  // If the expression is an Array, we were passed another TokenTree, so we can
  // pass the expression back to the parseBlock function
  if (expression instanceof Array) {
    return parseBlock(expression);
  }

  // The mapping here is pretty straight forward. Match the token 
 type and pass the
  // expression on to a more specific expression parser.
  if (isTokenType(expression, "identifier")) return parseIdentifier(expression);
  if (isTokenType(expression, "typed-identifier")) return parseTypedIdentifier(expression);
  if (isTokenType(expression, "float")) return parseFloatToken(expression);
  if (isTokenType(expression, "int")) return parseIntToken(expression);

  throw new Error(`Unrecognized expression ${JSON.stringify(expression)}`);
};

Let's define the isTokenType function. This function is pretty neat and demonstrates one of the most powerful features of TypeScript, custom type guards. Simply put, isTokenType tests the expression and narrows down the type to a specific TokenType. This allows TypeScript to be certain we are passing the correct tokens to their corresponding parser functions down the line.

Here's the definition:

export const isTokenType = <T extends Token["type"]>(
  item: TokenTree | NonBracketToken | undefined,
  type: T
): item is Extract<Token, { type: T }> => {
  return isToken(item) && item.type === type;
};

const isToken = (item?: TokenTree | NonBracketToken): item is NonBracketToken => {
  return !(item instanceof Array);
};

There's a lot happening there, so let's walk through it. First up, we have a generic definition, <T extends Token["type"]>. This is essentially saying that T must be one of the possible values
of the Token.type field. Typescript is smart enough to know that means T must be one of "int" | "float" | "identifier" | "typed-identifier" | "bracket.

The next interesting piece of code is the return type predicate item is Extract<Token, { type: T }>. This predicate tells TypeScript that if the return value of isTokenType is true, then item must be the Token whose type matches the string passed as the type parameter.

In practice that means that if we were to pass an unknown Token to isTokenType, typescript will be able to correctly narrow the value to a more specific token, like IntToken.

Now that we have our custom type guard defined, we can define the actual token parsers. The first three are simple; they essentially just return a copy or slightly modified copy of the token:

const parseFloatToken = (float: FloatToken): FloatNode => ({ ...float });

const parseIntToken = (int: IntToken): IntNode => ({ ...int });

const parseIdentifier = (identifier: IdentifierToken): IdentifierNode => {
  return {
    type: "identifier",
    identifier: identifier.value,
  };
};

The final parser is the parseTypedIdentifier. Remember that a typed identifier takes the form identifier:type. Parsing it is as
simple as splitting the string by the colon. The first value
of the returned array is the identifier, the second is the type.

Here's the definition:

const parseTypedIdentifier = (identifier: TypedIdentifierToken): TypedIdentifierNode => {
  const vals = identifier.value.split(":");

  return {
    type: "typed-identifier",
    identifier: vals[0],
    typeIdentifier: vals[1],
  };
};

Here’s the finished file

That's all the code required for a working parser. Before we move on, let's update the main src/index.mts file to view the output of the parser:

// src/index.mts
#!/usr/bin/env node
import { readFileSync } from "fs";
import { lex } from "./lexer.mjs";
import { parse } from "./parser.mjs";

const file = process.argv[2];
const input = readFileSync(file, "utf8");

const tokens = lex(input);
const ast = parse(tokens);
console.log(JSON.stringify(tokens, undefined, 2));

Build and run project:

npx tsc
wispy example.wispy

If all goes well, the output should look like this.

With that, the parser is finished. We can now convert the stream of tokens from the lexer into an AST. In the next post, we can get into the juicy bits: generating and running machine-readable code.

Request a demo today to see how Courier works to make product notifications delightful!

DEV Community: Charla Bigelow

How to Create an Automated SMS Notification System

Introduction

Send with SMS

Integrate SMS API

Create Your Notification(s)

Create an Automation

Set up user preferences

Best Practices for SMS Notifications

A. Timing and frequency of SMS notifications

B. Personalizing the SMS notifications for each recipient

C. Measuring the success of SMS notifications with analytics

D. Improving the SMS notification strategy based on recipient engagement

Conclusion

New Datadog integration for Courier notification logs and metrics

The fastest way to pull your notification data into Datadog

Use cases

Notification metrics and logs

Feature-specific metrics and logs

What data can be sent to Datadog from Courier?

Metrics

Logs

Setting up the Datadog integration

Next steps

Streamline your workflow with CourierJS: Our new client-side SDK

Client-side vs. Server-side SDKs

Discover the advantages of CourierJS

Ready to get started? Using CourierJS is a breeze

Exploring the new API calls in Courier's client-side SDK

The identify call

Subscribing and unsubscribing from lists

Conclusion

Introducing the new and improved Automations designer

What is Courier?

What are Courier automations?

The elements of a Courier automation

Triggers

Actions

Branching logic

Why the new version of the Courier automations designer helps you

How to use the automations designer

The automations API

Details for existing users of the automations designer

Differences between the old and new automations designer UIs

What you need to do to migrate to the new version of automations

Get started

Simplifying notifications with the Courier iOS SDK

Token management

Getting started with Courier's iOS SDK

Push providers

Enabling push notification capability

Setting up a notification service extension

Push notification permissions

Managing user state

Handling notification delivery

Handling a notification click

Sending a test push

Conclusion

Introducing Courier Preferences: The Fastest Way to Design the Best Preference Experience

Notification preferences are a vital feature of any app

How to design a good preference experience

Voilà: a user-facing Preference Center

Your preference UI, hosted by Courier

Build your own interface via the Preferences API

A user-friendly unsubscribe experience

Keeping a digital paper trail of your users’ preference history

Get started with Courier Preferences today

Tools and Techniques to Establish Your Data Team Early

Hire a Generalist First

A Small Data Team Can Answer Big Questions

The Tools Our Data Team Uses

Our Data Team Is Evolving Again

How to Send Invoice and Add Payment Reminder in Next.js with Courier API

Background

Pre-requisites

Goals

Part 1: Setup Courier Platform

Part 2: Send Invoice to Email

Backend

Frontend

The `identify` call