@upyo/core 0.2.0-dev.22 → 0.2.0-dev.24
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +153 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,8 +6,15 @@
|
|
|
6
6
|
[![JSR][JSR badge]][JSR]
|
|
7
7
|
[![npm][npm badge]][npm]
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
sending
|
|
9
|
+
Core types and interfaces for [Upyo], a cross-runtime email library that
|
|
10
|
+
provides a unified, type-safe API for sending emails across Node.js, Deno, Bun,
|
|
11
|
+
and edge functions.
|
|
12
|
+
|
|
13
|
+
The *@upyo/core* package provides the foundational types and interfaces that all
|
|
14
|
+
Upyo transport implementations use. It defines the common `Message`, `Address`,
|
|
15
|
+
`Transport`, and `Receipt` types that enable seamless switching between
|
|
16
|
+
different email providers while maintaining consistent type safety and
|
|
17
|
+
error handling.
|
|
11
18
|
|
|
12
19
|
[JSR]: https://jsr.io/@upyo/core
|
|
13
20
|
[JSR badge]: https://jsr.io/badges/@upyo/core
|
|
@@ -16,6 +23,18 @@ sending email messages.
|
|
|
16
23
|
[Upyo]: https://upyo.org/
|
|
17
24
|
|
|
18
25
|
|
|
26
|
+
Features
|
|
27
|
+
--------
|
|
28
|
+
|
|
29
|
+
- *Universal types*: Common interfaces for all email transports
|
|
30
|
+
- *Type-safe messaging*: Comprehensive TypeScript definitions for email
|
|
31
|
+
messages
|
|
32
|
+
- *Attachment support*: File attachment handling
|
|
33
|
+
- *Cross-runtime compatibility*: Works on Node.js, Deno, Bun,
|
|
34
|
+
and edge functions
|
|
35
|
+
- *Zero dependencies*: Lightweight with no external dependencies
|
|
36
|
+
|
|
37
|
+
|
|
19
38
|
Installation
|
|
20
39
|
------------
|
|
21
40
|
|
|
@@ -26,3 +45,135 @@ yarn add @upyo/core
|
|
|
26
45
|
deno add jsr:@upyo/core
|
|
27
46
|
bun add @upyo/core
|
|
28
47
|
~~~~
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
Usage
|
|
51
|
+
-----
|
|
52
|
+
|
|
53
|
+
### Creating messages
|
|
54
|
+
|
|
55
|
+
The `createMessage()` function provides a convenient way to create email
|
|
56
|
+
messages:
|
|
57
|
+
|
|
58
|
+
~~~~ typescript
|
|
59
|
+
import { createMessage } from "@upyo/core";
|
|
60
|
+
|
|
61
|
+
const message = createMessage({
|
|
62
|
+
from: "sender@example.com",
|
|
63
|
+
to: ["recipient@example.net", "another@example.org"],
|
|
64
|
+
cc: "copy@example.com",
|
|
65
|
+
subject: "Hello from Upyo!",
|
|
66
|
+
content: {
|
|
67
|
+
text: "This is a plain text message.",
|
|
68
|
+
html: "<p>This is an <strong>HTML</strong> message.</p>",
|
|
69
|
+
},
|
|
70
|
+
priority: "high",
|
|
71
|
+
});
|
|
72
|
+
~~~~
|
|
73
|
+
|
|
74
|
+
### Adding attachments
|
|
75
|
+
|
|
76
|
+
Attachments can be added using the standard [`File`] API:
|
|
77
|
+
|
|
78
|
+
~~~~ typescript
|
|
79
|
+
import { createMessage } from "@upyo/core";
|
|
80
|
+
|
|
81
|
+
const message = createMessage({
|
|
82
|
+
from: "sender@example.com",
|
|
83
|
+
to: "recipient@example.net",
|
|
84
|
+
subject: "Document attached",
|
|
85
|
+
content: { text: "Please find the document attached." },
|
|
86
|
+
attachments: [
|
|
87
|
+
new File(
|
|
88
|
+
[await fetch("document.pdf").then(r => r.arrayBuffer())],
|
|
89
|
+
"document.pdf",
|
|
90
|
+
{ type: "application/pdf" }
|
|
91
|
+
),
|
|
92
|
+
],
|
|
93
|
+
});
|
|
94
|
+
~~~~
|
|
95
|
+
|
|
96
|
+
[`File`]: https://developer.mozilla.org/en-US/docs/Web/API/File
|
|
97
|
+
|
|
98
|
+
### Handling receipts
|
|
99
|
+
|
|
100
|
+
All transport operations return `Receipt` objects that use discriminated unions
|
|
101
|
+
for type-safe error handling:
|
|
102
|
+
|
|
103
|
+
~~~~ typescript
|
|
104
|
+
import type { Receipt } from "@upyo/core";
|
|
105
|
+
|
|
106
|
+
function handleReceipt(receipt: Receipt) {
|
|
107
|
+
if (receipt.successful) {
|
|
108
|
+
console.log("Message sent with ID:", receipt.messageId);
|
|
109
|
+
} else {
|
|
110
|
+
console.error("Send failed:", receipt.errorMessages.join(", "));
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
~~~~
|
|
114
|
+
|
|
115
|
+
### Implementing custom transports
|
|
116
|
+
|
|
117
|
+
The `Transport` interface defines the contract for all email providers:
|
|
118
|
+
|
|
119
|
+
~~~~ typescript
|
|
120
|
+
import type { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
|
|
121
|
+
|
|
122
|
+
class MyCustomTransport implements Transport {
|
|
123
|
+
async send(message: Message, options?: TransportOptions): Promise<Receipt> {
|
|
124
|
+
// Implementation details...
|
|
125
|
+
return { successful: true, messageId: "12345" };
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
async *sendMany(
|
|
129
|
+
messages: Iterable<Message> | AsyncIterable<Message>,
|
|
130
|
+
options?: TransportOptions,
|
|
131
|
+
): AsyncIterable<Receipt> {
|
|
132
|
+
for await (const message of messages) {
|
|
133
|
+
yield await this.send(message, options);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
~~~~
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
Related packages
|
|
141
|
+
----------------
|
|
142
|
+
|
|
143
|
+
The `@upyo/core` package is the foundation for all Upyo transport
|
|
144
|
+
implementations:
|
|
145
|
+
|
|
146
|
+
| Package | JSR | npm | Description |
|
|
147
|
+
| ------------------- | ------------------------------ | ------------------------------ | ------------------------------------------------- |
|
|
148
|
+
| @upyo/smtp | [JSR][jsr:@upyo/smtp] | [npm][npm:@upyo/smtp] | SMTP transport for any mail server |
|
|
149
|
+
| @upyo/mailgun | [JSR][jsr:@upyo/mailgun] | [npm][npm:@upyo/mailgun] | [Mailgun] HTTP API transport |
|
|
150
|
+
| @upyo/sendgrid | [JSR][jsr:@upyo/sendgrid] | [npm][npm:@upyo/sendgrid] | [SendGrid] HTTP API transport |
|
|
151
|
+
| @upyo/ses | [JSR][jsr:@upyo/ses] | [npm][npm:@upyo/ses] | [Amazon SES] HTTP API transport |
|
|
152
|
+
| @upyo/mock | [JSR][jsr:@upyo/mock] | [npm][npm:@upyo/mock] | Mock transport for testing |
|
|
153
|
+
| @upyo/opentelemetry | [JSR][jsr:@upyo/opentelemetry] | [npm][npm:@upyo/opentelemetry] | [OpenTelemetry] observability for Upyo transports |
|
|
154
|
+
|
|
155
|
+
[jsr:@upyo/smtp]: https://jsr.io/@upyo/smtp
|
|
156
|
+
[npm:@upyo/smtp]: https://www.npmjs.com/package/@upyo/smtp
|
|
157
|
+
[jsr:@upyo/mailgun]: https://jsr.io/@upyo/mailgun
|
|
158
|
+
[npm:@upyo/mailgun]: https://www.npmjs.com/package/@upyo/mailgun
|
|
159
|
+
[jsr:@upyo/sendgrid]: https://jsr.io/@upyo/sendgrid
|
|
160
|
+
[npm:@upyo/sendgrid]: https://www.npmjs.com/package/@upyo/sendgrid
|
|
161
|
+
[jsr:@upyo/ses]: https://jsr.io/@upyo/ses
|
|
162
|
+
[npm:@upyo/ses]: https://www.npmjs.com/package/@upyo/ses
|
|
163
|
+
[jsr:@upyo/mock]: https://jsr.io/@upyo/mock
|
|
164
|
+
[npm:@upyo/mock]: https://www.npmjs.com/package/@upyo/mock
|
|
165
|
+
[jsr:@upyo/opentelemetry]: https://jsr.io/@upyo/opentelemetry
|
|
166
|
+
[npm:@upyo/opentelemetry]: https://www.npmjs.com/package/@upyo/opentelemetry
|
|
167
|
+
[Mailgun]: https://www.mailgun.com/
|
|
168
|
+
[SendGrid]: https://sendgrid.com/
|
|
169
|
+
[Amazon SES]: https://aws.amazon.com/ses/
|
|
170
|
+
[OpenTelemetry]: https://opentelemetry.io/
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
Documentation
|
|
174
|
+
-------------
|
|
175
|
+
|
|
176
|
+
For comprehensive documentation, examples, and guides, visit
|
|
177
|
+
*<https://upyo.org/>*.
|
|
178
|
+
|
|
179
|
+
API reference documentation is available on JSR: *<https://jsr.io/@upyo/core>*.
|