@agentuity/core 1.0.32 → 1.0.34

package/src/services/{email.ts → email/service.ts}

@@ -1,6 +1,7 @@
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException } from './_util.ts';
-import { safeStringify } from '../json.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException } from '../_util.ts';
+import { safeStringify } from '../../json.ts';
+import { z } from 'zod';
 
 /**
  * An email address registered with the Agentuity email service.
@@ -8,56 +9,73 @@ import { safeStringify } from '../json.ts';
  * Email addresses are created under the `@agentuity.email` domain and can receive
  * inbound emails (forwarded to configured destinations) and send outbound emails.
  */
-export interface EmailAddress {
+export const EmailAddressSchema = z.object({
 	/**
 	 * Unique identifier for the email address.
 	 *
 	 * @remarks Prefixed with `eaddr_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the email address.'),
 
 	/**
 	 * The full email address (e.g., `support@agentuity.email`).
 	 */
-	email: string;
+	email: z.string().describe('The full email address (e.g., `support@agentuity.email`).'),
 
 	/**
 	 * Provider-specific configuration (e.g., inbound routing config).
 	 *
 	 * @remarks Opaque to callers — the structure is managed by the platform.
 	 */
-	config?: Record<string, unknown>;
+	config: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Provider-specific configuration (e.g., inbound routing config).'),
 
 	/**
 	 * ID of the user who registered this address.
 	 */
-	created_by?: string;
+	created_by: z.string().optional().describe('ID of the user who registered this address.'),
 
 	/**
 	 * ISO 8601 timestamp when the address was created.
 	 */
-	created_at: string;
+	created_at: z.string().describe('ISO 8601 timestamp when the address was created.'),
 
 	/**
 	 * ISO 8601 timestamp when the address was last updated.
 	 */
-	updated_at?: string;
+	updated_at: z
+		.string()
+		.optional()
+		.describe('ISO 8601 timestamp when the address was last updated.'),
 
 	/**
 	 * Total number of inbound emails received at this address.
 	 */
-	inbound_count?: number;
+	inbound_count: z
+		.number()
+		.optional()
+		.describe('Total number of inbound emails received at this address.'),
 
 	/**
 	 * Total number of outbound emails sent from this address.
 	 */
-	outbound_count?: number;
+	outbound_count: z
+		.number()
+		.optional()
+		.describe('Total number of outbound emails sent from this address.'),
 
 	/**
 	 * ISO 8601 timestamp of the most recent inbound or outbound email activity.
 	 */
-	last_activity?: string;
-}
+	last_activity: z
+		.string()
+		.optional()
+		.describe('ISO 8601 timestamp of the most recent inbound or outbound email activity.'),
+});
+
+export type EmailAddress = z.infer<typeof EmailAddressSchema>;
 
 /**
  * A destination configuration for an email address.
@@ -65,18 +83,18 @@ export interface EmailAddress {
  * When an inbound email is received at the parent address, the platform forwards
  * it to each configured destination via an HTTP request.
  */
-export interface EmailDestination {
+export const EmailDestinationSchema = z.object({
 	/**
 	 * Unique identifier for the destination.
 	 *
 	 * @remarks Prefixed with `edst_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the destination.'),
 
 	/**
 	 * The destination type. Currently only `'url'` is supported.
 	 */
-	type: string;
+	type: z.string().describe("The destination type. Currently only `'url'` is supported."),
 
 	/**
 	 * Destination-specific configuration.
@@ -91,18 +109,26 @@ export interface EmailDestination {
 	 * }
 	 * ```
 	 */
-	config?: Record<string, unknown>;
+	config: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Destination-specific configuration.'),
 
 	/**
 	 * ISO 8601 timestamp when the destination was created.
 	 */
-	created_at: string;
+	created_at: z.string().describe('ISO 8601 timestamp when the destination was created.'),
 
 	/**
 	 * ISO 8601 timestamp when the destination was last updated.
 	 */
-	updated_at?: string;
-}
+	updated_at: z
+		.string()
+		.optional()
+		.describe('ISO 8601 timestamp when the destination was last updated.'),
+});
+
+export type EmailDestination = z.infer<typeof EmailDestinationSchema>;
 
 /**
  * Connection settings for an email protocol (IMAP or POP3).
@@ -110,32 +136,34 @@ export interface EmailDestination {
  * Used to configure a mail client for accessing an Agentuity email address
  * via standard mail protocols.
  */
-export interface EmailProtocolConfig {
+export const EmailProtocolConfigSchema = z.object({
 	/**
 	 * The mail server hostname.
 	 */
-	host: string;
+	host: z.string().describe('The mail server hostname.'),
 
 	/**
 	 * The mail server port number.
 	 */
-	port: number;
+	port: z.number().describe('The mail server port number.'),
 
 	/**
 	 * TLS mode (e.g., `'starttls'`, `'ssl'`, `'none'`).
 	 */
-	tls: string;
+	tls: z.string().describe("TLS mode (e.g., `'starttls'`, `'ssl'`, `'none'`)."),
 
 	/**
 	 * The authentication username (typically the address ID).
 	 */
-	username: string;
+	username: z.string().describe('The authentication username (typically the address ID).'),
 
 	/**
 	 * The authentication password.
 	 */
-	password: string;
-}
+	password: z.string().describe('The authentication password.'),
+});
+
+export type EmailProtocolConfig = z.infer<typeof EmailProtocolConfigSchema>;
 
 /**
  * Full connection configuration for accessing an email address via IMAP and POP3 protocols.
@@ -143,222 +171,252 @@ export interface EmailProtocolConfig {
  * Returned by {@link EmailService.getConnectionConfig} to allow external mail clients
  * to connect to an Agentuity email address.
  */
-export interface EmailConnectionConfig {
+export const EmailConnectionConfigSchema = z.object({
 	/**
 	 * The full email address these settings are for.
 	 */
-	email: string;
+	email: z.string().describe('The full email address these settings are for.'),
 
 	/**
 	 * IMAP protocol connection settings.
 	 */
-	imap: EmailProtocolConfig;
+	imap: EmailProtocolConfigSchema.describe('IMAP protocol connection settings.'),
 
 	/**
 	 * POP3 protocol connection settings.
 	 */
-	pop3: EmailProtocolConfig;
-}
+	pop3: EmailProtocolConfigSchema.describe('POP3 protocol connection settings.'),
+});
+
+export type EmailConnectionConfig = z.infer<typeof EmailConnectionConfigSchema>;
 
 /**
  * An inbound email message received at an Agentuity email address.
  */
-export interface EmailInbound {
+export const EmailInboundSchema = z.object({
 	/**
 	 * Unique identifier for the inbound email.
 	 *
 	 * @remarks Prefixed with `einb_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the inbound email.'),
 
 	/**
 	 * The sender's email address.
 	 */
-	from: string;
+	from: z.string().describe("The sender's email address."),
 
 	/**
 	 * The recipient email address (comma-separated if multiple).
 	 */
-	to: string;
+	to: z.string().describe('The recipient email address (comma-separated if multiple).'),
 
 	/**
 	 * The email subject line.
 	 */
-	subject?: string;
+	subject: z.string().optional().describe('The email subject line.'),
 
 	/**
 	 * Plain text body of the email.
 	 */
-	text?: string;
+	text: z.string().optional().describe('Plain text body of the email.'),
 
 	/**
 	 * HTML body of the email.
 	 */
-	html?: string;
+	html: z.string().optional().describe('HTML body of the email.'),
 
 	/**
 	 * ISO 8601 timestamp when the email was received.
 	 */
-	received_at?: string;
+	received_at: z.string().optional().describe('ISO 8601 timestamp when the email was received.'),
 
 	/**
 	 * Raw email headers as key-value pairs.
 	 */
-	headers?: Record<string, unknown>;
+	headers: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Raw email headers as key-value pairs.'),
 
 	/**
 	 * Array of stored attachment metadata with S3 locations.
 	 */
-	attachments?: EmailStoredAttachment[];
-}
+	attachments: z
+		.array(z.lazy(() => EmailStoredAttachmentSchema))
+		.optional()
+		.describe('Array of stored attachment metadata with S3 locations.'),
+});
+
+export type EmailInbound = z.infer<typeof EmailInboundSchema>;
 
 /**
  * An outbound email message sent from an Agentuity email address.
  */
-export interface EmailOutbound {
+export const EmailOutboundSchema = z.object({
 	/**
 	 * Unique identifier for the outbound email.
 	 *
 	 * @remarks Prefixed with `eout_`.
 	 */
-	id: string;
+	id: z.string().describe('Unique identifier for the outbound email.'),
 
 	/**
 	 * The sender's email address (must be owned by the organization).
 	 */
-	from: string;
+	from: z.string().describe("The sender's email address (must be owned by the organization)."),
 
 	/**
 	 * The recipient email addresses (comma-separated).
 	 */
-	to: string;
+	to: z.string().describe('The recipient email addresses (comma-separated).'),
 
 	/**
 	 * The email subject line.
 	 */
-	subject?: string;
+	subject: z.string().optional().describe('The email subject line.'),
 
 	/**
 	 * Plain text body of the email.
 	 */
-	text?: string;
+	text: z.string().optional().describe('Plain text body of the email.'),
 
 	/**
 	 * HTML body of the email.
 	 */
-	html?: string;
+	html: z.string().optional().describe('HTML body of the email.'),
 
 	/**
 	 * Delivery status: `'pending'`, `'success'`, or `'failed'`.
 	 *
 	 * @remarks Emails are sent asynchronously, so the initial status is always `'pending'`.
 	 */
-	status?: string;
+	status: z
+		.string()
+		.optional()
+		.describe("Delivery status: `'pending'`, `'success'`, or `'failed'`."),
 
 	/**
 	 * Error message if the delivery failed.
 	 */
-	error?: string;
+	error: z.string().optional().describe('Error message if the delivery failed.'),
 
 	/**
 	 * ISO 8601 timestamp when the send was initiated.
 	 */
-	created_at?: string;
+	created_at: z.string().optional().describe('ISO 8601 timestamp when the send was initiated.'),
 
 	/**
 	 * Custom email headers that were included.
 	 */
-	headers?: Record<string, unknown>;
+	headers: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Custom email headers that were included.'),
 
 	/**
 	 * Array of stored attachment metadata with S3 locations.
 	 */
-	attachments?: EmailStoredAttachment[];
-}
+	attachments: z
+		.array(z.lazy(() => EmailStoredAttachmentSchema))
+		.optional()
+		.describe('Array of stored attachment metadata with S3 locations.'),
+});
+
+export type EmailOutbound = z.infer<typeof EmailOutboundSchema>;
 
 /**
  * An email attachment to include when sending an outbound email.
  */
-export interface EmailAttachment {
+export const EmailAttachmentSchema = z.object({
 	/**
 	 * The filename for the attachment
 	 */
-	filename: string;
+	filename: z.string().describe('The filename for the attachment'),
 
 	/**
 	 * The base64-encoded content of the attachment
 	 */
-	content: string;
+	content: z.string().describe('The base64-encoded content of the attachment'),
 
 	/**
 	 * The MIME content type of the attachment
 	 */
-	contentType?: string;
-}
+	contentType: z.string().optional().describe('The MIME content type of the attachment'),
+});
+
+export type EmailAttachment = z.infer<typeof EmailAttachmentSchema>;
 
 /**
  * A stored email attachment with S3 location metadata.
  * Returned by inbound/outbound email queries — different from EmailAttachment used for sending.
  */
-export interface EmailStoredAttachment {
+export const EmailStoredAttachmentSchema = z.object({
 	/** The original filename */
-	filename: string;
+	filename: z.string().describe('The original filename'),
 	/** The MIME content type */
-	content_type?: string;
+	content_type: z.string().optional().describe('The MIME content type'),
 	/** File size in bytes */
-	size: number;
+	size: z.number().describe('File size in bytes'),
 	/** The S3 bucket name where the attachment is stored */
-	bucket: string;
+	bucket: z.string().describe('The S3 bucket name where the attachment is stored'),
 	/** The S3 object key */
-	key: string;
+	key: z.string().describe('The S3 object key'),
 	/** Optional pre-signed download URL */
-	url?: string;
-}
+	url: z.string().optional().describe('Optional pre-signed download URL'),
+});
+
+export type EmailStoredAttachment = z.infer<typeof EmailStoredAttachmentSchema>;
 
 /**
  * Parameters for sending an email
  */
-export interface EmailSendParams {
+export const EmailSendParamsSchema = z.object({
 	/**
 	 * The sender email address (must be owned by the organization)
 	 */
-	from: string;
+	from: z.string().describe('The sender email address (must be owned by the organization)'),
 
 	/**
 	 * The recipient email addresses
 	 */
-	to: string[];
+	to: z.array(z.string()).describe('The recipient email addresses'),
 
 	/**
 	 * The email subject
 	 */
-	subject: string;
+	subject: z.string().describe('The email subject'),
 
 	/**
 	 * Plain text email body
 	 */
-	text?: string;
+	text: z.string().optional().describe('Plain text email body'),
 
 	/**
 	 * HTML email body
 	 */
-	html?: string;
+	html: z.string().optional().describe('HTML email body'),
 
 	/**
 	 * File attachments
 	 */
-	attachments?: EmailAttachment[];
+	attachments: z.array(EmailAttachmentSchema).optional().describe('File attachments'),
 
 	/**
 	 * Custom email headers (e.g., In-Reply-To, References for threading)
 	 */
-	headers?: Record<string, string>;
-}
+	headers: z
+		.record(z.string(), z.string())
+		.optional()
+		.describe('Custom email headers (e.g., In-Reply-To, References for threading)'),
+});
+
+export type EmailSendParams = z.infer<typeof EmailSendParamsSchema>;
 
 /**
  * Parameters for querying email activity time-series data.
  */
-export interface EmailActivityParams {
+export const EmailActivityParamsSchema = z.object({
 	/**
 	 * Number of days of activity to retrieve.
 	 *
@@ -366,43 +424,51 @@ export interface EmailActivityParams {
 	 *
 	 * @default 7
 	 */
-	days?: number; // min 7, max 365, default 7
-}
+	days: z.number().min(7).max(365).default(7).describe('Number of days of activity to retrieve.'), // min 7, max 365, default 7
+});
+
+export type EmailActivityParams = z.infer<typeof EmailActivityParamsSchema>;
 
 /**
  * A single data point in the email activity time-series.
  */
-export interface EmailActivityDataPoint {
+export const EmailActivityDataPointSchema = z.object({
 	/**
 	 * The date in `YYYY-MM-DD` format.
 	 */
-	date: string; // "2026-02-28"
+	date: z.string().describe('The date in `YYYY-MM-DD` format.'), // "2026-02-28"
 
 	/**
 	 * Number of inbound emails received on this date.
 	 */
-	inbound: number;
+	inbound: z.number().describe('Number of inbound emails received on this date.'),
 
 	/**
 	 * Number of outbound emails sent on this date.
 	 */
-	outbound: number;
-}
+	outbound: z.number().describe('Number of outbound emails sent on this date.'),
+});
+
+export type EmailActivityDataPoint = z.infer<typeof EmailActivityDataPointSchema>;
 
 /**
  * Result of an email activity query containing daily time-series data.
  */
-export interface EmailActivityResult {
+export const EmailActivityResultSchema = z.object({
 	/**
 	 * Array of daily activity data points, ordered chronologically.
 	 */
-	activity: EmailActivityDataPoint[];
+	activity: z
+		.array(EmailActivityDataPointSchema)
+		.describe('Array of daily activity data points, ordered chronologically.'),
 
 	/**
 	 * The number of days of data returned.
 	 */
-	days: number;
-}
+	days: z.number().describe('The number of days of data returned.'),
+});
+
+export type EmailActivityResult = z.infer<typeof EmailActivityResultSchema>;
 
 /**
  * Email service for managing email addresses, destinations, and sending/receiving emails
@@ -743,7 +809,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async createAddress(localPart: string): Promise<EmailAddress> {
-		const url = buildUrl(this.#baseUrl, '/email/2025-03-17/addresses');
+		const url = buildUrl(this.#baseUrl, '/email/addresses');
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'POST',
@@ -778,7 +844,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async listAddresses(): Promise<EmailAddress[]> {
-		const url = buildUrl(this.#baseUrl, '/email/2025-03-17/addresses');
+		const url = buildUrl(this.#baseUrl, '/email/addresses');
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -814,7 +880,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async getAddress(id: string): Promise<EmailAddress | null> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/addresses/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/addresses/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -855,10 +921,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async getConnectionConfig(id: string): Promise<EmailConnectionConfig | null> {
-		const url = buildUrl(
-			this.#baseUrl,
-			`/email/2025-03-17/addresses/${encodeURIComponent(id)}/connection`
-		);
+		const url = buildUrl(this.#baseUrl, `/email/addresses/${encodeURIComponent(id)}/connection`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -893,7 +956,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async deleteAddress(id: string): Promise<void> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/addresses/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/addresses/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'DELETE',
@@ -940,7 +1003,7 @@ export class EmailStorageService implements EmailService {
 	): Promise<EmailDestination> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/email/2025-03-17/addresses/${encodeURIComponent(addressId)}/destinations`
+			`/email/addresses/${encodeURIComponent(addressId)}/destinations`
 		);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
@@ -980,7 +1043,7 @@ export class EmailStorageService implements EmailService {
 	async listDestinations(addressId: string): Promise<EmailDestination[]> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/email/2025-03-17/addresses/${encodeURIComponent(addressId)}/destinations`
+			`/email/addresses/${encodeURIComponent(addressId)}/destinations`
 		);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
@@ -1020,7 +1083,7 @@ export class EmailStorageService implements EmailService {
 	async deleteDestination(addressId: string, destinationId: string): Promise<void> {
 		const url = buildUrl(
 			this.#baseUrl,
-			`/email/2025-03-17/addresses/${encodeURIComponent(addressId)}/destinations/${encodeURIComponent(destinationId)}`
+			`/email/addresses/${encodeURIComponent(addressId)}/destinations/${encodeURIComponent(destinationId)}`
 		);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
@@ -1073,7 +1136,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async send(params: EmailSendParams): Promise<EmailOutbound> {
-		const url = buildUrl(this.#baseUrl, '/email/2025-03-17/outbound/send');
+		const url = buildUrl(this.#baseUrl, '/email/outbound/send');
 		const signal = AbortSignal.timeout(30_000);
 
 		// Transform attachments to API format (snake_case)
@@ -1144,10 +1207,7 @@ export class EmailStorageService implements EmailService {
 			queryParams.set('address_id', addressId);
 		}
 		const queryString = queryParams.toString();
-		const url = buildUrl(
-			this.#baseUrl,
-			`/email/2025-03-17/inbound${queryString ? `?${queryString}` : ''}`
-		);
+		const url = buildUrl(this.#baseUrl, `/email/inbound${queryString ? `?${queryString}` : ''}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -1186,7 +1246,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async getInbound(id: string): Promise<EmailInbound | null> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/inbound/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/inbound/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -1221,7 +1281,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async deleteInbound(id: string): Promise<void> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/inbound/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/inbound/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'DELETE',
@@ -1265,10 +1325,7 @@ export class EmailStorageService implements EmailService {
 			queryParams.set('address_id', addressId);
 		}
 		const queryString = queryParams.toString();
-		const url = buildUrl(
-			this.#baseUrl,
-			`/email/2025-03-17/outbound${queryString ? `?${queryString}` : ''}`
-		);
+		const url = buildUrl(this.#baseUrl, `/email/outbound${queryString ? `?${queryString}` : ''}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -1309,7 +1366,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async getOutbound(id: string): Promise<EmailOutbound | null> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/outbound/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/outbound/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'GET',
@@ -1344,7 +1401,7 @@ export class EmailStorageService implements EmailService {
 	 * ```
 	 */
 	async deleteOutbound(id: string): Promise<void> {
-		const url = buildUrl(this.#baseUrl, `/email/2025-03-17/outbound/${encodeURIComponent(id)}`);
+		const url = buildUrl(this.#baseUrl, `/email/outbound/${encodeURIComponent(id)}`);
 		const signal = AbortSignal.timeout(30_000);
 		const res = await this.#adapter.invoke<unknown>(url, {
 			method: 'DELETE',