De nombreuses applications de gestion de factures open source sont construites avec Laravel. En tant que développeur Javascript, je voulais créer la "Solution React" pour les développeurs qui connaissent React et Javascript.  Un problème que j'ai trouvé lors de la construction avec des services dans Node.js est qu'il n'y a pas de courrier intégré. J'ai donc dû trouver un service tiers pour le faire pour moi. Dans cet article, j'intégrerai   pour envoyer des e-mails pour ce projet   . Courier https://github.com/fazzaamiarso/invoys  Conditions préalables  Étant donné que cet article n'est pas votre suivi habituel (plutôt du genre « veuillez patienter et voyez comment je le fais »), il n'est pas obligatoire de se familiariser avec toutes les technologies utilisées. Cependant, la familiarité avec Typescript et Next.js sera bénéfique pour une compréhension plus rapide.  Technologies dans ce blog :    : la sécurité de type et l'auto-complétion sont les meilleures, n'est-ce pas ? Typescript    : un framework prêt pour la production pour créer une application full-stack, même pour les débutants. Next.js    : un excellent ORM pour travailler avec des bases de données. Nous utilisons Prisma en raison de sa sécurité de type et de sa saisie semi-automatique, offrant une excellente expérience de développement avec l'ajout de texte dactylographié. Prisma    : nous permet de construire facilement une sécurité de type de bout en bout entre notre client et notre serveur Next.js. Trpc  Courier API : un excellent service/plate-forme pour gérer nos notifications, telles que les e-mails, les SMS et bien plus encore.  Vous pouvez trouver le   pour référence. code source complet ici  Buts  Avant de construire les fonctionnalités, définissons nos objectifs.  Envoyer le lien de la facture à l'e-mail du client.  Envoyez un rappel un jour avant la date d'échéance d'une facture.  Annuler un rappel de date d'échéance de facture lorsque la facture est déjà payée.  Gestion des erreurs réseau.  Partie 1 : Configurer la plate-forme de messagerie  Passons au tableau de bord Courier. Par défaut, c'est dans un environnement de production. Puisque je veux tester des choses, je vais passer à l'environnement de test en cliquant sur le menu déroulant dans le coin supérieur droit.   Nous pouvons copier tous les modèles plus tard en production ou vice-versa.  Maintenant, je vais créer une   pour mes notifications par e-mail.  marque  Je vais juste ajouter un logo (attention la largeur du logo est fixée à 140px) sur le header et des liens sociaux sur le footer. L'interface utilisateur du concepteur est assez simple, voici donc le résultat final.   N'oubliez pas de publier les modifications.  Partie 2 : Envoyer la facture par e-mail  Actuellement, le bouton d'envoi d'e-mail sur l'interface utilisateur ne fait rien.  Je vais créer un fichier   dans   pour conserver tout le code lié à Courier. De plus, j'utiliserai   qui a déjà résumé tous les points de terminaison de l'API Courier en fonctions. courier.ts src/lib/ la bibliothèque client courier node.js  Avant de créer la fonctionnalité, créons la conception de la notification par e-mail dans Courier's Designer et configurons le fournisseur Gmail.  Sur la page du concepteur d'email, nous verrons que la marque créée est déjà intégrée. Après cela, concevons le modèle en conséquence avec les données nécessaires. Voici le résultat final.   Remarquez la valeur avec   qui devient verte, cela signifie que c'est une variable qui peut être insérée dynamiquement. J'ai également défini le bouton (ou l'action) "Voir la facture" avec une variable. {}  Avant de pouvoir utiliser le modèle, je dois créer un   en cliquant sur l'onglet Aperçu. Ensuite, il affichera une invite pour nommer l'événement et définir   au format JSON. Ce champ de données est ce qui remplira la valeur des variables vertes   (les données peuvent également être définies à partir du code). Puisqu'il s'agit d'un événement de test, je vais le remplir avec des valeurs arbitraires. événement test data {}  Ensuite, je publierai le modèle afin que je puisse l'utiliser. Ensuite, allez dans l'onglet envoyer. Il affichera le code nécessaire pour envoyer l'e-mail par programmation et les   seront renseignées avec l'   précédent que j'ai créé.  data événement de test  Backend  Je vais copier le test   dans le fichier   et copier l'extrait dans   . AUTH_TOKEN .env 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, });  Créez une fonction   qui sera responsable de l'envoi d'un e-mail. Pour envoyer un email depuis le code, j'utilise la fonction   . sendInvoice courierClient.send()   // 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 };  Définissez des types pour la fonction   . sendInvoice   // src/lib/courier.ts interface SendInvoice { productName: string; dueDate: string; customerName: string; invoiceNumber: string; invoiceViewUrl: string; emailTo: string; }  Maintenant que je peux envoyer l'e-mail, je vais l'appeler dans le point de terminaison   trpc qui réside dans   . sendEmail src/server/trpc/router/invoice.ts        route        N'oubliez pas que le point de terminaison trpc est une route d'API Next.js. Dans ce cas, sendEmail sera identique à l'appel de la /api/trpc/sendEmail avec fetch sous le capot. Pour plus d'explications   . 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); }),  Pour ceux qui ne connaissent pas trpc, ce que j'ai fait est identique à la gestion d'une requête   . Décomposons-le. POST  Manière Trpc de définir   en validant avec Zod. Ici, je définis toutes les données nécessaires à la fonction   . l'entrée de requête du client sendInvoice   .input( z.object({ customerName: z.string(), invoiceNumber: z.string(), invoiceViewUrl: z.string(), emailTo: z.string(), invoiceId: z.string(), productName: z.string(), dueDate: z.date(), }) )  Définissez un gestionnaire de requête   (mutation). POST   // 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); }),  L'extrémité avant  Maintenant, je peux commencer à ajouter la fonctionnalité au bouton d'envoi d'e-mail. Je vais utiliser la fonction   qui est un fin wrapper de useMutation`   . trpc.useMutation() tanstack-query's  Ajoutons la fonction de mutation. En cas de réponse positive, je souhaite envoyer un toast de réussite sur l'interface utilisateur.   //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!'); } }); }  Je peux simplement utiliser la fonction comme gestionnaire en ligne, mais je souhaite créer un nouveau gestionnaire pour le bouton.   //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, }); };  Maintenant, je peux attacher le gestionnaire au bouton d'envoi d'e-mail.   //src/pages/invoices/[invoiceId]/index.tsx <Button variant="primary" onClick={sendInvoiceEmail} isLoading={sendEmailMutation.isLoading}> Send to Email </Button>  Voici l'interface utilisateur de travail.  Partie 3 : Envoyer un rappel de paiement  Pour programmer un rappel qui sera envoyé un jour avant la date d'échéance d'une facture, je vais utiliser   . l'API d'automatisation de Courier  Tout d'abord, concevons le modèle d'e-mail dans Courier Designer. Comme je suis déjà passé par le processus avant, voici le résultat final.  Avant d'ajouter la fonction, définissez les types du paramètre et refactorisez les types.   // 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; }  Maintenant, j'ajoute la fonction   à  scheduleReminder src/lib/courier   //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; };  Pour envoyer le rappel, j'appellerai   après une tentative réussie   . Modifions le point de terminaison   trpc. scheduleReminder sendInvoice sendEmail   // 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, }); }  Maintenant, si j'essaie d'envoyer une facture par e-mail, je devrais recevoir un rappel 20 secondes plus tard puisque je suis dans l'environnement de développement.  Partie 4 : Annuler un rappel  Enfin, toutes les fonctionnalités sont prêtes. Cependant, j'ai un problème, que se passe-t-il si un client a payé avant la date prévue pour le rappel de paiement ? Actuellement, l'e-mail de rappel sera toujours envoyé. Ce n'est pas une excellente expérience utilisateur et potentiellement un client confus. Heureusement, Courier dispose d'une fonction d'annulation d'automatisation.  Ajoutons la fonction   qui peut annuler tout workflow d'automatisation dans   . cancelAutomationWorkflow src/lib/courier.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; };  Qu'est-ce qu'un jeton d'annulation ? Il s'agit d'un jeton unique qui peut être défini sur un flux de travail d'automatisation. Il peut donc être annulé en envoyant une action   avec un   correspondant. cancel cancelation_token  Ajoutez cancelation_token à   , j'utilise l'identifiant de la facture comme jeton. scheduleReminder   // 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  J'appellera   lorsque le statut d'une facture est mis à jour sur   dans le point de terminaison trpc   . cancelAutomationWorkflow PAID updateStatus   // 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; }),  Voici l'interface utilisateur de travail.  Partie 5 : Gestion des erreurs  Une remarque importante lors des requêtes réseau est qu'il existe des possibilités d'échec des requêtes/erreurs. Je veux gérer l'erreur en la lançant au client, afin qu'elle puisse être reflétée dans l'interface utilisateur.  En cas d'erreur, l'API Courier génère une erreur avec le type   par défaut. J'aurai également la valeur de retour de toutes les fonctions dans   conformément au format ci-dessous. CourierHttpClientError src/lib/courier.ts   // On Success type SuccessResponse = { data: any, error: null } // On Error type ErrorResponse = { data: any, error: string }  Maintenant, je peux gérer les erreurs en ajoutant un bloc   à toutes les fonctions dans   . try-catch src/lib/courier.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!" }; } }  Voyons un exemple de manipulation sur le point de terminaison   trpc. sendEmail   // 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);  Partie 6 : Passer à la production  Maintenant que tous les modèles sont prêts, je vais copier tous les actifs de l'environnement de test vers la production. Voici un exemple.  Conclusion  Enfin, toutes les fonctionnalités sont intégrées à Courier. Nous avons suivi un workflow d'intégration de l'API Courier à une application Next.js. Bien que ce soit dans Next.js et trpc, le flux de travail sera à peu près le même avec n'importe quelle autre technologie. J'espère maintenant que vous pourrez intégrer Courier dans votre application par vous-même.  Commencez dès maintenant :  https://app.courier.com/signup  A propos de l'auteur  Je suis Fazza Razaq Amiarso, un développeur web full-stack d'Indonésie. Je suis aussi un passionné de l'Open Source. J'aime partager mes connaissances et mon apprentissage   . J'aide occasionnellement d'autres développeurs sur   pendant mon temps libre. sur mon blog FrontendMentor  Connectez-vous avec moi sur   . LinkedIn  Liens rapides  🔗  Documents de messagerie  🔗  Contribuer aux Invoys  🔗  Invoys Motivation  Également publié   . ici

This story contains new, firsthand information uncovered by the writer.

Orchestrate Unlimited Notifications From 1 API | Sign-up today!

Courier simplifies triggering and sending notifications from your app with one API and drag and drop UI.


2021 - HackerNoon Contributor of the Year - SOFTWARE-ARCHITECTURE

2022 - HackerNoon Contributor of the Year - Business Strategy

2022 - HackerNoon Contributor of the Year - Digital Transformation

2022 - HackerNoon Contributor of the Year - Graphql

2022 - HackerNoon Contributor of the Year - Rest Api

2022 - HackerNoon Contributor of the Year - Software Architecture

2022 - Tech Ceo of the Year

2021 - HackerNoon Contributor of the Year - APP-DEVELOPMENT

Nominated for 2022 - HackerNoon Contributor of the Year - Rest Api

Nominated for 2022 - Tech Ceo of the Year

Nominated for 2022 - HackerNoon Contributor of the Year - Digital Transformation

Nominated for 2022 - HackerNoon Contributor of the Year - Graphql

Nominated for 2022 - HackerNoon Contributor of the Year - Business Strategy

Nominated for 2022 - HackerNoon Contributor of the Year - Software Architecture

Cet audio est produit dans la langue originale de l'histoire !

Envoi d'une facture et ajout d'un rappel de paiement dans Next.js avec l'API Courier

About Author

COMMENTAIRES

ÉTIQUETTES

CET ARTICLE A ÉTÉ PARU DANS

Related Stories

Le modèle Bitcoin UTXO, alimentant un écosystème unique

Des forums aux flux : comment les algorithmes des réseaux sociaux façonnent l'interaction numérique

Télégramme : le pont de Crypto Island vers le continent

Guide de l'architecte pour créer une architecture de référence pour un datalake IA/ML

Le modèle Bitcoin UTXO, alimentant un écosystème unique

Des forums aux flux : comment les algorithmes des réseaux sociaux façonnent l'interaction numérique

Télégramme : le pont de Crypto Island vers le continent

Guide de l'architecte pour créer une architecture de référence pour un datalake IA/ML

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps