Guide

Tutorial

Product News

Courier Updates

User Experience

Product Management

Integrations

Engineering

Live Streaming

Notifications Landscape

Courier

Mike Miller

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.

![iOS push notifications with Courier](//images.ctfassets.net/z7iqk1q8njt4/3rUcQDOobYWo1ZWJPFVwnH/d687bb8df008f348d2f18e38f38b091d/Simplifying_Notifications_with_the_Courier_iOS_SDK.png)

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](https://github.com/trycourier/courier-ios "Courier iOS SDK"), you'll need a few things:
- __[Xcode](https://developer.apple.com/xcode/ "Xcode - Apple Developers")__. 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](https://github.com/trycourier/courier-ios#installation "Courier iOS SDK installation"). 

## 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](https://github.com/trycourier/courier-ios#3-configure-push-provider "Courier iOS SDK") 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.

1. 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.
2. In Xcode, open your app project and select the project file from the project navigator.
3. Select your app target and click on the "Capabilities" tab.
4. Turn on the "Push Notifications" capability.
5. 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](https://github.com/trycourier/courier-ios#add-the-notification-service-extension-recommended "Courier iOS SDK"), 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:

```javascript
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](https://developer.apple.com/documentation/usernotifications/unauthorizationstatus "Apple Developer Documentation").

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:

```javascript
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](https://github.com/trycourier/courier-ios#going-to-production "Courier iOS SDK"). 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.

```javascript
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.

```javascript
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: 

```javascript
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](https://github.com/trycourier/courier-android "Courier Android SDK"), [React Native](https://github.com/trycourier/courier-react-native "Courier React Native SDK"), and [Flutter](https://github.com/trycourier/courier-flutter "Courier Flutter SDK"). So if you're looking for a way to simplify your push notification management, check out [Courier](https://www.courier.com/ "Powerful Notifications System - Courier") today.


Build exceptional notification experiences in web and mobile apps.

Watch, develop, learn!

This article gives an overview of how Courier's iOS SDK simplifies token management and provides instructions on how to get started using it.

Simplifying notifications with the Courier iOS SDK

courier-ios-thumbnail

Push notifications have become an essential part of modern mobile apps, allowing you to keep your users engaged and informed. However, implementing push for different platforms can be a complex and time-consuming task, requiring developers to set up and handle token management, testing, and other logistical details.

![android-push-notifications-with-courier](//images.ctfassets.net/z7iqk1q8njt4/BcgXAW07Ghb9mNeg8qEsG/1cda3781bd576d943d5f0fc3fe5c5b53/android-push-notifications-with-courier.png)

Courier's Android Mobile Notifications Software Development Kit (SDK) is designed to make it easy for you to implement push notifications in your mobile apps. The SDK provides a set of tools that simplify the process of managing user state, handling tokens, and sending test notifications. Some of these terms may be unfamiliar, but we’ll explain them in this article and show you how to use the SDK.
Before diving into how to use the Courier Android SDK, first let's touch on the benefits it provides. Later, we will go into more depth.
- __Manage tokens easily__: The SDK simplifies the process of handling tokens, which can be a complex and time-consuming task for developers to set up and manage. When implementing push notifications, developers need to handle token management, which involves generating and storing unique identifiers for each device that can receive notifications.
- __Manage user state effectively__: The SDK also simplifies the process of managing user state, which refers to the current status or context of a user within an app.
- __Send test notifications__: The SDK includes tools that enable developers to send test notifications, ensuring that their notifications are working as intended before they go live. This can save time and prevent potential issues.

By providing these tools, the Courier Android SDK helps developers streamline the process of implementing push notifications in their apps. With these benefits in mind, let's move on to how to get started with the SDK.

## Getting started with Courier
To get started with the [Courier Android SDK](https://github.com/trycourier/courier-android "Courier Android SDK"), you will need to have the following:
1. [Android Studio](https://developer.android.com/studio "Download Android Studio") or any other development environment that supports Android development. The SDK supports Java, Kotlin, and Firebase Cloud Messaging.
2. A valid [Firebase project](https://support.google.com/firebase/answer/6399760?hl=en "What is a Firebase project?"). Although the Courier SDK itself doesn’t need a Firebase account, if you want to send push notifications to your app you will need a Firebase account.
3. A physical Android device for testing. Testing push notifications with or without the Courier SDK does not work well with emulators.
4. [A Courier account](https://app.courier.com/signup "Sign up for Courier"). You need an account in order to use the SDK.
5. The SDK. Once you have the other prerequisites, you can download the SDK and include it in your project. 

To install the Courier Android SDK have a look at the [step-by-step guide](https://github.com/trycourier/courier-android#installation "How to install the Courier Android SDK") on our GitHub page.

Once you’ve successfully set up the Courier SDK in your Android app, let's dive into some of the features of the SDK. 

A note to the developers amongst you: Some of the functions that we will cover below depend on an `AppCompatActivity`, just something to keep in mind as we move forward.

![start-sending-push-notifications-with-courier](//images.ctfassets.net/z7iqk1q8njt4/6kOEIFCijPy7s3bK5vMH2O/6d100f9471cb83fd06e3603c9c4d55a4/start-sending-push-notifications-with-courier.png)

## Managing user state
Before we think about sending notifications, it's important to consider the user state. This is the status of a user in relation to your app, e.g., signed in or out. This can impact the user's experience with your app. For instance, if your user is signed out, they shouldn’t be receiving notifications as if they are still signed in.
For an optimal user experience, it's best to keep the user's push notification tokens in sync with their state. Most of this is handled automatically by Courier.
In order to manage the user state in your app, you can use the functions provided by Courier. By calling the `Courier.shared.signIn()` function, you can ensure that the user's push notification tokens and their state are kept in sync.

```javascript
Courier.shared.signIn(
  accessToken = authKey_or_accessToken,
  userId = userId
)
```

The accessToken can either be a Courier Auth Key used during development or a [JWT (JSON Web Token)](https://jwt.io/introduction "JSON Web Token Introduction") that should be used in your production app.

When the user signs out, you can use the `Courier.shared.signOut()` function to clear their state.

```javascript
Courier.shared.signOut()
```

By following these steps, the FCM (Firebase Cloud Messaging) tokens on Android will be automatically synced to Courier, making it easier for you to manage the user's state and send relevant and timely push notifications.

## Push notification permissions
To make a great user experience, you’ll need to request push notification permissions at the right time in your user’s flow. Finding the code to request these permissions can be difficult. . Courier makes it easy to check permissions with the `requestNotificationPermission()` function.

```javascript
if (requestNotificationPermission()) {
  //Send some notification
}
```

The `requestNotificationPermission()` function returns a Boolean that tells us if the user has permissions on or off. Then, you can continue with your code, perhaps sending a test notification to the device to make sure everything is working well for the user experience you are building. In newer versions of Android (version 33 and up) this will present a popup asking your users for push notifications permissions. In older versions of android, this will always return true.

## Simple delivery tracking
Courier has an `onPushNotificationDelivered()` function, which is triggered when a push notification is delivered to the device. This is useful for keeping track of delivery status.

```javascript
override fun onPushNotificationDelivered(message: RemoteMessage) {
  print(message)
}
```

Bear in mind that this function will only be triggered when the app is in the foreground or potentially background state. It will not be called when the app is in the "killed" or "not running" state. It also must be inside of a `CourierActivity` (which is a subclass of `AppCompatActivity`).

## Message received?
You know how to check if the notification was delivered, but what if you want to know when the user interacts with it? That’s where the `onPushNotificationClicked()` function comes in. This function is triggered when the user taps on a push notification. You can use this function to handle what happens when the user interacts with the notification and must also be inside of a `CourierActivity` (which is a subclass of `AppCompatActivity`)

```javascript
override fun onPushNotificationClicked(message: RemoteMessage) {
  print(message)
}
```

In the example above, we are simply printing a message, but you can replace it with your own logic such as opening a specific activity or displaying some interface component.

## Sending a test push
With permissions handled, and some understanding of how we can track the status of our notifications, lets see how sending notifications works. 
Courier enables you to send push notifications directly to a user's ID via the SDK, without the need to make a direct call to Firebase from your backend or through a raw HTTP call. This ID is the userId you register data with in Courier. This should probably match the user IDs you use in your existing authentication system. For now, let’s look at how you can use the `sendPush()` function to send test push notifications. 
Here's how to send a test push.

```json
val messageId = Courier.shared.sendPush(
  authKey: 'a_courier_auth_key_only_for_testing',
  userId: 'example_user',
  title: 'Hello!',
  body: 'This is a push message from Courier 🐣',
  providers: [CourierProvider.fcm],
)
 ```

This code will send a push notification to every valid token for the given userId and providers (e.g., FCM) that you declare. So be careful and make sure to only use it for testing purposes.
It's important to note that the authKey you use in this example is for testing purposes only and should not be used in production.

## Let's talk about tokens
One of the most challenging aspects of push notifications is managing tokens: unique identifiers that are used to identify a specific device for push notifications. They are typically generated and managed by the operating system's push notification service, such as [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging "Firebase Cloud Messaging") for Android and [Apple Push Notification Service (APNS)](https://developer.apple.com/notifications/ "Notifications Overview") for iOS.
To send push notifications to a specific device or user, you must use the device's token. Your app needs to store tokens securely on the back end and associate them with the relevant user or device. Additionally, tokens should be regularly updated, as they can change or expire. Token management also includes handling token deletion when a device or user unsubscribes from push notifications or uninstalls the app.
Setting up your own token management infrastructure can require iteration between front-end (or mobile) and back-end developers. This back-and-forth can take several days or even a month, between designers, mobile engineers building the functionality into the app, and then the back-end engineer building the infrastructure to make it work.
Courier takes care of all of the above for you! You don’t need to learn all the logistics of token management, because Courier's mobile SDKs automatically takes push notification tokens, stores them in Courier, and automatically invalidates tokens that expire, allowing you to focus on building your product.

## Conclusion
In this post you have seen how Courier streamlines the hassle of handling push notifications. It takes care of token generation, storage, and removal, allowing you to concentrate on building your app without worrying about the technicalities of token management. You’ve seen how the SDK is user-friendly, with a straightforward setup and integration process that can be completed with just a few lines of code, even in existing projects.
Courier has other SDKs available. Whether you're working with [Android](https://github.com/trycourier/courier-android "Courier Android SDK"), [iOS](https://github.com/trycourier/courier-ios "Courier iOS SDK"), [React Native](https://github.com/trycourier/courier-react-native "Courier React Native SDK") or [Flutter](https://github.com/trycourier/courier-flutter "Courier Flutter SDK"), Courier has an SDK that can help streamline your push notification process. So, if you're looking for a way to simplify your push notification management, give Courier a try.

Courier's Android Mobile Notifications Software Development Kit (SDK) is designed to make it easy for you to implement push notifications in your mobile apps.

Building Android push notifications with Firebase and Courier’s SDK

Android logo with path to Courier Android SDK

Courier Android SDK thumbnail

Prakhar Srivastav

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!

![QOTD Final Project](//images.ctfassets.net/z7iqk1q8njt4/1R04JX4FjNAccZFLrmr9SF/467f50f89c928e7665e81ee25fb69c19/qotd_pic_1.png)

## 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](https://huggingface.co) make using this model in our app very easy.

#### Hugging Face

We'll use the [Hugging Face](https://huggingface.co/) 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:

1. We can fine-tune the GPT2 model by using our own text for which we'll need a good dataset of quotes.
2. 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

```python
from transformers import AutoTokenizer, AutoModelWithLMHead, pipeline

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

then, constructing a model from the pretrained model

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

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

```python
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.

1. Load the model everytime we want to run the script to send the script.
2. 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](https://fastapi.tiangolo.com/) to build a quick serving API. Here's what that looks like

```python

# 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

```sh
$ 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.

![QOTD Part 2](//images.ctfassets.net/z7iqk1q8njt4/1TXDqA7VRfbwZRNDH76Kms/f6cce20ca8d4f5aaa9ecd313976488a3/qotd2.png)

### 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](http://courier.com/). 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

```py
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 - 

```py
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

1. How will the text be placed on the image?
2. What about wrapping the text?
3. What color should the text be so that it is visible on the background image?
4. 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.

```py
# 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.

```py
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.](https://app.courier.com/signup)

#### Creating the template in Courier

![QOTD Courier Email Template Preview](//images.ctfassets.net/z7iqk1q8njt4/NvMlJ4UVAaWZHzIOooG0P/879d8e96f866f09d7a5d0b582a79562a/qotd3.png)

#### 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

```py
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](https://app.courier.com/settings) and the Template ID can be found in the [template design's](https://app.courier.com/designer) 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](https://prakhar.me) 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](https://www.courier.com/docs/)

🔗 [Hugging Face](https://huggingface.co/)

🔗 [Fast API](https://fastapi.tiangolo.com/)

🔗 [Unsplash API](https://unsplash.com/developers)

Courier is a notification service that centralizes all of your templates and messaging channels in one place which increases visibility and reduces engineering time. 

Start Routing Notifications Today!

QOTD Header

Courier and OpenGPT2 in action: build a service that sends friends and family an AI generated motivational quote of the day.

QOTD Thumbnail

Develop a Motivational QOTD with Courier and GPT2

Fazza Profile

Fazza Razaq Amiarso

## 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](https://www.courier.com/) to send emails for this project [https://github.com/fazzaamiarso/invoys](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](https://www.typescriptlang.org/): type-safety and auto-completion are the best, right? 
- [Next.js](https://nextjs.org/): a production-ready framework to build a full-stack app, even for beginners.
- [Prisma](https://www.prisma.io/): 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](https://trpc.io/): 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](https://github.com/fazzaamiarso/invoys/tree/bc231301c92bb07692a3388bb50d76d61603a41f) for reference.

### Goals
Before building the features, let's define our goals.
1. Send invoice link to client's email.
2. Send a reminder a day before an invoice's due date.
3. Cancel an invoice due date reminder when the invoice is already paid.
4. 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**](https://www.courier.com/docs/getting-started/courier-concepts/#brands) for my email notifications.

![go to brand](https://i.imgur.com/1Us0dzC.gif)

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. 

<img src="https://i.imgur.com/sFrofll.png" alt="brand template" width="500px" />

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](https://github.com/trycourier/courier-node) 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.

<img src="https://i.imgur.com/qFhHvAP.png" alt="email template final" width="500px" />

<img src="https://i.imgur.com/B6vKjpH.png" alt="action button" width="500px" />

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. 

<img src="https://i.imgur.com/PMGcVQq.png" alt="code snippet" width="500px" />

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

```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.

```ts
// 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.

```ts
// 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](https://trpc.io/docs/quickstart).

```ts
// 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.

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

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

2. Define a `POST` request handler (mutation).

```ts
// 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's `useMutation`.

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.

```tsx
//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.

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

<Button
   variant="primary"
   onClick={sendInvoiceEmail}
   isLoading={sendEmailMutation.isLoading}>
   Send to Email
</Button>
```

Here's the working UI.

<img src="https://i.imgur.com/ush8wdI.gif" alt="working ui" width="500px" />

### 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](https://www.courier.com/docs/automations/). 

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

<img src="https://i.imgur.com/4l6shqK.png" alt="payment reminder template" width="500px" />

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

```tsx
// 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`

```tsx
//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 = '<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.

```tsx
// 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.

<img src="https://i.imgur.com/MfwQ6F0.png" alt="with payment reminder" />

### 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.

<img src="https://i.imgur.com/jnLk4Tg.gif" alt="cancel log" width="500px" />

### 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.

<img src="https://i.imgur.com/Mr3bmuH.gif" alt="copy assets to production" width="500px" />

## 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](https://fazzaamiarso.me/). I occasionally help other developers on [FrontendMentor](https://www.frontendmentor.io/profile/fazzaamiarso) in my free time.

Connect with me on [LinkedIn](https://www.linkedin.com/in/fazzaamiarso/).

## Quick Links

🔗 [Courier Docs](https://www.courier.com/docs/)

🔗 [Contribute to Invoys](https://github.com/fazzaamiarso/invoys)

🔗 [Invoys Motivation](https://fazzaamiarso.me/projects/invoys)

Abstract bank vault with gold coins and locked up boxes guarded by Courier's logo.

Invoys Header

Invoice management tutorial by Courier community developer

Invoys Thumbnail

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

nica-headshot

Nočnica Mellifera

Recently I had a chance to talk to [DevOps
Minneapolis](https://devopsdays.org/events/2022-minneapolis/welcome/) about the [true nature of user experience](https://www.youtube.com/watch?v=C0nqIYxMPUI). The audience found this information to be particularly interesting, so I thought it would be helpful to share it with a wider audience. This post will be the first in a series of three posts that will discuss user experience beyond your app’s UI and how you can optimize it. 

So where is your user experience? More generally, where does your application happen? For those of us who work in SaaS, the answer is simple: the application occurs inside the application interface. Whether we’re selling business tools or teaching Spanish, the application happens when our users access the UI.

![image1](//images.ctfassets.net/z7iqk1q8njt4/7fjNtDXh4kd1X705WbeUMI/1c56d888e770e3c9cd1f5b5c88e8ac0d/image1.jpg)
*Your UX is inside your application… right?*

When we talk about our users having a good experience, that much-vaunted UX, the things we’re tweaking will be inside this application. We have several specialists who worry about user experience. Whether that’s UX thinking about existing users or data and product people making sure the experience for new users is frictionless.

![UX wireframes](//images.ctfassets.net/z7iqk1q8njt4/2rwQGF8vmim0Zm0H1j0Tmn/d0c5031862d85d08998fe012b7740054/image2.png)

I don’t mean to trivialize this process: it’s much more than tweaking colors and moving buttons by a pixel. Those tasked with UX often have to ask the most basic questions: what do our users want, and what’s the best way to give it to them? This matters because however cool our technology is behind the scenes, if the user doesn’t have a good experience with it, they’re unlikely to return.

This article argues that there’s a more important user experience than the one inside your app. In fact, your app has a whole interface that has more impact on your users, that touches them more deeply than your application interface.

## It’s your notifications
![iphone notifications](//images.ctfassets.net/z7iqk1q8njt4/9UViH6p0qPhaiKC69gflN/d87cc815b893a46664348d1876a63be4/image3.jpg)
*This is where your notifications really happen.*

Many of our favorite apps largely interact with us through notifications, the examples are everywhere. 
* Tools for observability and security most frequently have all our interaction starting with notifications. After all, we're probably not checking our APM tools until we know something is wrong. 
* For social media applications, the best moment we experience with them is seeing that X number of people loved our post. 
* And for communication and collaboration applications the notifications should have most of the information that people want you to see.

In fact, I’d argue that for many of our most valued tools and services, most of our interface, for good or ill, is through notifications. Notifications bring you into the application. They provide reassurance, warnings, anxiety, or annoying notifications about sales of pizza. Notifications are your application. 

I mention all this because I believe that your UX is in danger. Primarily, the experience of notifications has been ceded to teams outside of the product team. Instead of our product team controlling notifications, it’s the operations or marketing/growth teams that control most of the notifications we send.

Let me show you far we have strayed from g-d’s light:

## The tale of the signup campaign
The time after a user creates an account is critical for any SaaS tool. Even when users sign up and immediately start using the product, there will be features or extended use cases that we, the developers, want them to try.

Put yourself in the shoes of a product team that’s trying to improve the rate at which new sign ups become committed users. In (almost) all product teams, we’ll realize that we want to get in touch with users after they sign up to encourage them to keep going with our product.

The platform doubtlessly sends a signup confirmation, and we start by tweaking that. We get our new copy and links to the operations team, or platform dev, and they change the post-signup email. But soon, we want more. First off: we don’t really want to email users the instant they sign up, we’d like to wait at least a few hours, to let the platform feel a bit familiar first. Then we’d like to follow up after a few days, and a few days after that.

Even better, we, the product team, would like to customize these messages a bit, depending on their team size, what license they have, etc. 
The operations team, who implement all outbound notifications, is rightfully a bit frustrated by this. They’re used to solving bugs and feature requests for the platform, not tweaking an email. Scheduling? Audience customization? This sounds like a job for….

## The CRM, where for a time it was good
With all the need for custom targeting, a good first solution is to have a signup get sent as an event to a Customer Relationship Management (CRM) tool like Salesforce. From there, it’s easy to start a ‘signup campaign.’ Since the CRM should know things like the org size and license level of the user, the messages can be nicely customized.

And for a time, it was good. However, trouble starts when we go one step further with targeting and customization.

You see, our signup campaign encourages users to use certain features, like say Reports Export. We want to tell the users about the feature, demo it for them, walk them through the concept. “Please” our emails beg, “export your reports, with the Reports Export.”

This message will seem super weird if the user has already used Reports Export. So we, the product team, go to whomever runs the CRM and say ‘can we cancel this email if they’ve used Reports Export.’ Of course, the CRM doesn’t know that. So we end up back with platform engineering, asking them to send an event to the CRM when someone first uses Reports Export. 

The ‘quick and dirty’ solution of CRM wasn’t a durable solution to our problem.

### The problem is a ceding of territory
The inherent problem in the scenario above is a ceding of territory by the product team. If the product team wanted to move a button, or change the order of a toolbar, it wouldn’t make sense for the marketing team to say ‘no.’ But when we want to send a correctly targeted sign-up campaign, our reliance on our CRM means Marketing has to say ‘no’ to a better user experience.

Similarly, we wouldn’t let ops or platform engineering keep us from adding a helpful tooltip, but we are letting them keep us from sending a helpful email to the right users.

## What we can do to solve the problem
The problem here is a lack of tooling, either external or internal. Every new notification stream requires engineering time, and that means  technical limitations keep us from delivering the experience our users deserve.

Whether it’s by using Courier or an internal spike to create a messaging microservice, you want to develop a robust set of features that make it easy to send multiple notification types direct from your platform.


birds build around a nest in a tree, but not inside it

ux-not-in-app-header

Your app has a whole other interface that has more impact on your users, that provides a deeper user experience than your application interface.

Your UX isn't in your app: the importance of notifications

ux-not-in-app-thumbnail

Building a Great UX Outside of your App

Drew smiling in front of the ocean on a beach

Drew_headshot

Drew Youngwerth

The golden ratio is displayed in curving, bright red plant leaves in a dense, dark forest.

wasm-code-generation-header

The final phase of our compiler is code generation. This phase takes the AST and converts it to a set of executable instructions.

Build a WebAssembly Language for Fun and Profit: Code Generation

wasm-code-generation-thumbnail

In the [last post](https://www.courier.com/blog/build-a-webassembly-language-lexing/) 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](https://en.wikipedia.org/wiki/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:

![AST explanation](//images.ctfassets.net/z7iqk1q8njt4/1PWW9Be4KZd8fHeVnwpMGR/45932ae1bd61df370190c56294cefddc/image1.png)

If you're interested in writing a parser for a more complex C-like syntax, see my previous [Building A Programming Language](https://drew.ltd/blog/posts/2019-7-24.html) 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:

```ts
// 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:

1. An identifier that evaluates to a function, `add`.
2. An Int that simply evaluates to the number `1`.
3. 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:

```ts
// 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:

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

You may have noticed that `BlockNode` has an array of `AstNode`s, Since `AstNode` _can be_ a `BlockNode`, `BlockNode`s 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](https://github.com/drew-y/wispy/blob/0b03f9237aa4b1d9d07856ebc347927a444bb2d2/src/types/ast.mts).

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

```ts
// 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:

```ts
// 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.

```ts
// 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:

```ts
// 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:

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

Here's the actual definition of `consumeTokenTree`:

```ts
// 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 a
`parseBlock` function that takes the tree as its input and returns a `BlockNode`:

```ts
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 written
`parseExpression` function. `parseExpression` takes either a `TokenTree` or a `NonBracketToken` and transforms it to its corresponding `AstNode` type. 

Here's the definition:

```ts
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](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates). 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:

```ts
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:

```ts
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:

```ts
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](https://github.com/drew-y/wispy/blob/main/src/parser.mts)

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:

```ts
// 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:

```bash
npx tsc
wispy example.wispy
```

If all goes well, the output should look like [this](https://github.com/drew-y/wispy/blob/58d5872f8d927358c1f8f70ebb4dda6d9458a8c8/example_ast_output.json).

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.

A space pilot sits in front of a control panel, looking at a swirl representing the golden ratio. 

parsing-header

The this second post, we’ll cover the next phase of our compiler, parsing, to take the token stream generated by the lexer and convert it to an AST.

Courier [Engineering]

Build your first notification in minutes

Build your first notification in minutes

Platform

Use Cases

Explore

Company