@upyo/core 0.2.0-dev.22 → 0.2.0-dev.26

package/README.md

@@ -6,8 +6,15 @@
 [![JSR][JSR badge]][JSR]
 [![npm][npm badge]][npm]
 
-Shared types and interfaces for [Upyo], a simple and cross-runtime library for
-sending email messages.
+Core types and interfaces for [Upyo], a cross-runtime email library that
+provides a unified, type-safe API for sending emails across Node.js, Deno, Bun,
+and edge functions.
+
+The *@upyo/core* package provides the foundational types and interfaces that all
+Upyo transport implementations use.  It defines the common `Message`, `Address`,
+`Transport`, and `Receipt` types that enable seamless switching between
+different email providers while maintaining consistent type safety and
+error handling.
 
 [JSR]: https://jsr.io/@upyo/core
 [JSR badge]: https://jsr.io/badges/@upyo/core
@@ -16,6 +23,18 @@ sending email messages.
 [Upyo]: https://upyo.org/
 
 
+Features
+--------
+
+ - *Universal types*: Common interfaces for all email transports
+ - *Type-safe messaging*: Comprehensive TypeScript definitions for email
+   messages
+ - *Attachment support*: File attachment handling
+ - *Cross-runtime compatibility*: Works on Node.js, Deno, Bun,
+   and edge functions
+ - *Zero dependencies*: Lightweight with no external dependencies
+
+
 Installation
 ------------
 
@@ -26,3 +45,135 @@ yarn add     @upyo/core
 deno add jsr:@upyo/core
 bun  add     @upyo/core
 ~~~~
+
+
+Usage
+-----
+
+### Creating messages
+
+The `createMessage()` function provides a convenient way to create email
+messages:
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+
+const message = createMessage({
+  from: "sender@example.com",
+  to: ["recipient@example.net", "another@example.org"],
+  cc: "copy@example.com",
+  subject: "Hello from Upyo!",
+  content: {
+    text: "This is a plain text message.",
+    html: "<p>This is an <strong>HTML</strong> message.</p>",
+  },
+  priority: "high",
+});
+~~~~
+
+### Adding attachments
+
+Attachments can be added using the standard [`File`] API:
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+
+const message = createMessage({
+  from: "sender@example.com",
+  to: "recipient@example.net",
+  subject: "Document attached",
+  content: { text: "Please find the document attached." },
+  attachments: [
+    new File(
+      [await fetch("document.pdf").then(r => r.arrayBuffer())],
+      "document.pdf",
+      { type: "application/pdf" }
+    ),
+  ],
+});
+~~~~
+
+[`File`]: https://developer.mozilla.org/en-US/docs/Web/API/File
+
+### Handling receipts
+
+All transport operations return `Receipt` objects that use discriminated unions
+for type-safe error handling:
+
+~~~~ typescript
+import type { Receipt } from "@upyo/core";
+
+function handleReceipt(receipt: Receipt) {
+  if (receipt.successful) {
+    console.log("Message sent with ID:", receipt.messageId);
+  } else {
+    console.error("Send failed:", receipt.errorMessages.join(", "));
+  }
+}
+~~~~
+
+### Implementing custom transports
+
+The `Transport` interface defines the contract for all email providers:
+
+~~~~ typescript
+import type { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+class MyCustomTransport implements Transport {
+  async send(message: Message, options?: TransportOptions): Promise<Receipt> {
+    // Implementation details...
+    return { successful: true, messageId: "12345" };
+  }
+
+  async *sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt> {
+    for await (const message of messages) {
+      yield await this.send(message, options);
+    }
+  }
+}
+~~~~
+
+
+Related packages
+----------------
+
+The `@upyo/core` package is the foundation for all Upyo transport
+implementations:
+
+| Package             | JSR                            | npm                            | Description                                       |
+| ------------------- | ------------------------------ | ------------------------------ | ------------------------------------------------- |
+| @upyo/smtp          | [JSR][jsr:@upyo/smtp]          | [npm][npm:@upyo/smtp]          | SMTP transport for any mail server                |
+| @upyo/mailgun       | [JSR][jsr:@upyo/mailgun]       | [npm][npm:@upyo/mailgun]       | [Mailgun] HTTP API transport                      |
+| @upyo/sendgrid      | [JSR][jsr:@upyo/sendgrid]      | [npm][npm:@upyo/sendgrid]      | [SendGrid] HTTP API transport                     |
+| @upyo/ses           | [JSR][jsr:@upyo/ses]           | [npm][npm:@upyo/ses]           | [Amazon SES] HTTP API transport                   |
+| @upyo/mock          | [JSR][jsr:@upyo/mock]          | [npm][npm:@upyo/mock]          | Mock transport for testing                        |
+| @upyo/opentelemetry | [JSR][jsr:@upyo/opentelemetry] | [npm][npm:@upyo/opentelemetry] | [OpenTelemetry] observability for Upyo transports |
+
+[jsr:@upyo/smtp]: https://jsr.io/@upyo/smtp
+[npm:@upyo/smtp]: https://www.npmjs.com/package/@upyo/smtp
+[jsr:@upyo/mailgun]: https://jsr.io/@upyo/mailgun
+[npm:@upyo/mailgun]: https://www.npmjs.com/package/@upyo/mailgun
+[jsr:@upyo/sendgrid]: https://jsr.io/@upyo/sendgrid
+[npm:@upyo/sendgrid]: https://www.npmjs.com/package/@upyo/sendgrid
+[jsr:@upyo/ses]: https://jsr.io/@upyo/ses
+[npm:@upyo/ses]: https://www.npmjs.com/package/@upyo/ses
+[jsr:@upyo/mock]: https://jsr.io/@upyo/mock
+[npm:@upyo/mock]: https://www.npmjs.com/package/@upyo/mock
+[jsr:@upyo/opentelemetry]: https://jsr.io/@upyo/opentelemetry
+[npm:@upyo/opentelemetry]: https://www.npmjs.com/package/@upyo/opentelemetry
+[Mailgun]: https://www.mailgun.com/
+[SendGrid]: https://sendgrid.com/
+[Amazon SES]: https://aws.amazon.com/ses/
+[OpenTelemetry]: https://opentelemetry.io/
+
+
+Documentation
+-------------
+
+For comprehensive documentation, examples, and guides, visit
+*<https://upyo.org/>*.
+
+API reference documentation is available on JSR: *<https://jsr.io/@upyo/core>*.

package/dist/address.cjs

@@ -128,7 +128,28 @@ function isValidDomainPart(domainPart) {
 		return false;
 	}
 }
+/**
+* Type guard function that checks if a given value is a valid email address.
+*
+* @example
+* ```ts
+* import { isEmailAddress } from "@upyo/core/address";
+*
+* const userInput = "user@example.com";
+* if (isEmailAddress(userInput)) {
+*   // TypeScript now knows userInput is EmailAddress type
+*   console.log(userInput); // Type: `${string}@${string}`
+* }
+* ```
+*
+* @param email The value to check
+* @returns `true` if the value is a valid email address, `false` otherwise
+*/
+function isEmailAddress(email) {
+	return typeof email === "string" && isValidEmail(email);
+}
 
 //#endregion
 exports.formatAddress = formatAddress;
+exports.isEmailAddress = isEmailAddress;
 exports.parseAddress = parseAddress;

package/dist/address.d.cts

@@ -1,4 +1,9 @@
 //#region src/address.d.ts
+/**
+ * A type alias for email address strings that must contain an @ symbol.
+ * @since 0.2.0
+ */
+type EmailAddress = `${string}@${string}`;
 /**
  * A pair of name (which is optional) and email address.
  */
@@ -10,7 +15,7 @@ interface Address {
   /**
    * The email address itself.
    */
-  readonly address: string;
+  readonly address: EmailAddress;
 }
 /**
  * Formats an address object into a string representation.  This function is
@@ -64,5 +69,23 @@ declare function formatAddress(address: Address): string;
  *          or `undefined` if the input is invalid.
  */
 declare function parseAddress(address: string): Address | undefined;
+/**
+ * Type guard function that checks if a given value is a valid email address.
+ *
+ * @example
+ * ```ts
+ * import { isEmailAddress } from "@upyo/core/address";
+ *
+ * const userInput = "user@example.com";
+ * if (isEmailAddress(userInput)) {
+ *   // TypeScript now knows userInput is EmailAddress type
+ *   console.log(userInput); // Type: `${string}@${string}`
+ * }
+ * ```
+ *
+ * @param email The value to check
+ * @returns `true` if the value is a valid email address, `false` otherwise
+ */
+declare function isEmailAddress(email: unknown): email is EmailAddress;
 //#endregion
-export { Address, formatAddress, parseAddress };
+export { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress };

package/dist/address.d.ts

@@ -1,4 +1,9 @@
 //#region src/address.d.ts
+/**
+ * A type alias for email address strings that must contain an @ symbol.
+ * @since 0.2.0
+ */
+type EmailAddress = `${string}@${string}`;
 /**
  * A pair of name (which is optional) and email address.
  */
@@ -10,7 +15,7 @@ interface Address {
   /**
    * The email address itself.
    */
-  readonly address: string;
+  readonly address: EmailAddress;
 }
 /**
  * Formats an address object into a string representation.  This function is
@@ -64,5 +69,23 @@ declare function formatAddress(address: Address): string;
  *          or `undefined` if the input is invalid.
  */
 declare function parseAddress(address: string): Address | undefined;
+/**
+ * Type guard function that checks if a given value is a valid email address.
+ *
+ * @example
+ * ```ts
+ * import { isEmailAddress } from "@upyo/core/address";
+ *
+ * const userInput = "user@example.com";
+ * if (isEmailAddress(userInput)) {
+ *   // TypeScript now knows userInput is EmailAddress type
+ *   console.log(userInput); // Type: `${string}@${string}`
+ * }
+ * ```
+ *
+ * @param email The value to check
+ * @returns `true` if the value is a valid email address, `false` otherwise
+ */
+declare function isEmailAddress(email: unknown): email is EmailAddress;
 //#endregion
-export { Address, formatAddress, parseAddress };
+export { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress };

package/dist/address.js

@@ -127,6 +127,26 @@ function isValidDomainPart(domainPart) {
 		return false;
 	}
 }
+/**
+* Type guard function that checks if a given value is a valid email address.
+*
+* @example
+* ```ts
+* import { isEmailAddress } from "@upyo/core/address";
+*
+* const userInput = "user@example.com";
+* if (isEmailAddress(userInput)) {
+*   // TypeScript now knows userInput is EmailAddress type
+*   console.log(userInput); // Type: `${string}@${string}`
+* }
+* ```
+*
+* @param email The value to check
+* @returns `true` if the value is a valid email address, `false` otherwise
+*/
+function isEmailAddress(email) {
+	return typeof email === "string" && isValidEmail(email);
+}
 
 //#endregion
-export { formatAddress, parseAddress };
+export { formatAddress, isEmailAddress, parseAddress };

package/dist/index.cjs

@@ -7,4 +7,5 @@ exports.comparePriority = require_priority.comparePriority;
 exports.createMessage = require_message.createMessage;
 exports.formatAddress = require_address.formatAddress;
 exports.isAttachment = require_attachment.isAttachment;
+exports.isEmailAddress = require_address.isEmailAddress;
 exports.parseAddress = require_address.parseAddress;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Address, formatAddress, parseAddress } from "./address.cjs";
+import { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress } from "./address.cjs";
 import { Attachment, isAttachment } from "./attachment.cjs";
 import { Priority, comparePriority } from "./priority.cjs";
 import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.cjs";
 import { Receipt } from "./receipt.cjs";
 import { Transport, TransportOptions } from "./transport.cjs";
-export { Address, Attachment, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, parseAddress };
+export { Address, Attachment, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { Address, formatAddress, parseAddress } from "./address.js";
+import { Address, EmailAddress, formatAddress, isEmailAddress, parseAddress } from "./address.js";
 import { Attachment, isAttachment } from "./attachment.js";
 import { Priority, comparePriority } from "./priority.js";
 import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.js";
 import { Receipt } from "./receipt.js";
 import { Transport, TransportOptions } from "./transport.js";
-export { Address, Attachment, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, parseAddress };
+export { Address, Attachment, EmailAddress, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { formatAddress, parseAddress } from "./address.js";
+import { formatAddress, isEmailAddress, parseAddress } from "./address.js";
 import { isAttachment } from "./attachment.js";
 import { createMessage } from "./message.js";
 import { comparePriority } from "./priority.js";
 
-export { comparePriority, createMessage, formatAddress, isAttachment, parseAddress };
+export { comparePriority, createMessage, formatAddress, isAttachment, isEmailAddress, parseAddress };

package/dist/message.d.cts

@@ -20,19 +20,19 @@ interface Message {
   /**
    * The email addresses of the recipient of the message.
    */
-  readonly recipients: Address[];
+  readonly recipients: readonly Address[];
   /**
    * The email addresses of the carbon copy (CC) recipients of the message.
    */
-  readonly ccRecipients: Address[];
+  readonly ccRecipients: readonly Address[];
   /**
    * The email addresses of the blind carbon copy (BCC) recipients of the message.
    */
-  readonly bccRecipients: Address[];
+  readonly bccRecipients: readonly Address[];
   /**
    * The email addresses of the reply-to recipients of the message.
    */
-  readonly replyRecipients: Address[];
+  readonly replyRecipients: readonly Address[];
   /**
    * The attachments included in the email message.  These are files that
    * are sent along with the email, such as documents, images, or other
@@ -40,7 +40,7 @@ interface Message {
    * object, which contains information about the attachment such as its
    * filename, content type, and content ID.
    */
-  readonly attachments: Attachment[];
+  readonly attachments: readonly Attachment[];
   /**
    * The subject of the email message.  This is typically a brief summary
    * of the content of the email, and is used to help the recipient identify
@@ -67,7 +67,7 @@ interface Message {
   /**
    * The tags associated with the email message.
    */
-  readonly tags: string[];
+  readonly tags: readonly string[];
   /**
    * The headers of the email message.  This is represented by
    * the {@link ImmutableHeaders} type, which is a supertype of

package/dist/message.d.ts

@@ -20,19 +20,19 @@ interface Message {
   /**
    * The email addresses of the recipient of the message.
    */
-  readonly recipients: Address[];
+  readonly recipients: readonly Address[];
   /**
    * The email addresses of the carbon copy (CC) recipients of the message.
    */
-  readonly ccRecipients: Address[];
+  readonly ccRecipients: readonly Address[];
   /**
    * The email addresses of the blind carbon copy (BCC) recipients of the message.
    */
-  readonly bccRecipients: Address[];
+  readonly bccRecipients: readonly Address[];
   /**
    * The email addresses of the reply-to recipients of the message.
    */
-  readonly replyRecipients: Address[];
+  readonly replyRecipients: readonly Address[];
   /**
    * The attachments included in the email message.  These are files that
    * are sent along with the email, such as documents, images, or other
@@ -40,7 +40,7 @@ interface Message {
    * object, which contains information about the attachment such as its
    * filename, content type, and content ID.
    */
-  readonly attachments: Attachment[];
+  readonly attachments: readonly Attachment[];
   /**
    * The subject of the email message.  This is typically a brief summary
    * of the content of the email, and is used to help the recipient identify
@@ -67,7 +67,7 @@ interface Message {
   /**
    * The tags associated with the email message.
    */
-  readonly tags: string[];
+  readonly tags: readonly string[];
   /**
    * The headers of the email message.  This is represented by
    * the {@link ImmutableHeaders} type, which is a supertype of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/core",
-  "version": "0.2.0-dev.22+3cc9fea3",
+  "version": "0.2.0-dev.26+8f57766a",
   "description": "Simple email sending library for Node.js, Deno, Bun, and edge functions",
   "keywords": [
     "email",