@clonecommand/cloud 0.0.7 → 0.0.10

package/dist/email/index.d.ts

@@ -1,5 +1,5 @@
 import { CloneCommandCloud } from "..";
-import { InboundEmail, SendEmailOptions } from "./types";
+import { InboundEmail, SendEmailOptions, EmailAttachment } from "./types";
 /**
  * Client for interacting with CloneCommand Email services.
  */
@@ -21,7 +21,8 @@ export declare class EmailClient {
      *
      * @example
      * await ccc.email.send({
-     *   to: 'user@example.com',
+     *   from: { name: 'Support', address: 'support@mail.example.com' },
+     *   to: [{ name: 'User', address: 'user@example.com' }],
      *   subject: 'Hello',
      *   text: 'This is a test'
      * });
@@ -58,4 +59,51 @@ export declare class EmailClient {
      * @returns A promise resolving to true if successful.
      */
     delete(emailId: string): Promise<boolean>;
+    /**
+     * Sends a raw MIME-formatted email.
+     * This is useful for sending emails with attachments, like calendar invites.
+     *
+     * @param rawMessage - The full MIME message as a string, including headers and body.
+     * @returns A promise resolving to the Message-ID of the sent email.
+     * @throws Error if sending fails.
+     *
+     * @example
+     * const boundary = `----=_Part_${Date.now()}`;
+     * const rawMessage = `From: events@mail.yourdomain.com
+     * To: user@example.com
+     * Subject: Meeting Invite
+     * MIME-Version: 1.0
+     * Content-Type: multipart/mixed; boundary="${boundary}"
+     *
+     * --${boundary}
+     * Content-Type: text/plain
+     *
+     * You're invited to a meeting.
+     *
+     * --${boundary}
+     * Content-Type: text/calendar; method=REQUEST; name="invite.ics"
+     * Content-Disposition: attachment; filename="invite.ics"
+     *
+     * BEGIN:VCALENDAR
+     * ...
+     * END:VCALENDAR
+     * --${boundary}--`;
+     *
+     * await ccc.email.sendRaw(rawMessage);
+     */
+    sendRaw(rawMessage: string): Promise<string>;
+    /**
+     * Retrieves the attachments from a specific inbound email.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to an array of attachments.
+     *
+     * @example
+     * const attachments = await ccc.email.getAttachments(emailId);
+     * for (const att of attachments) {
+     *   const content = Buffer.from(att.content, 'base64');
+     *   console.log(`${att.filename}: ${att.contentType}, ${att.size} bytes`);
+     * }
+     */
+    getAttachments(emailId: string): Promise<EmailAttachment[]>;
 }

package/dist/email/index.js

@@ -43,7 +43,8 @@ export class EmailClient {
      *
      * @example
      * await ccc.email.send({
-     *   to: 'user@example.com',
+     *   from: { name: 'Support', address: 'support@mail.example.com' },
+     *   to: [{ name: 'User', address: 'user@example.com' }],
      *   subject: 'Hello',
      *   text: 'This is a test'
      * });
@@ -57,6 +58,13 @@ export class EmailClient {
                 sendEmail(projectId: $projectId, email: $email)
             }
         `;
+        const normalize = (to) => {
+            if (typeof to === 'string')
+                return { address: to };
+            return to;
+        };
+        const toList = Array.isArray(options.to) ? options.to : [options.to];
+        const normalizedTo = toList.map(normalize);
         const result = await this.ccc.request('/graphql', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -66,7 +74,7 @@ export class EmailClient {
                     projectId: pid,
                     email: {
                         from: options.from,
-                        to: Array.isArray(options.to) ? options.to : [options.to],
+                        to: normalizedTo,
                         subject: options.subject,
                         html: options.html,
                         text: options.text
@@ -202,4 +210,95 @@ export class EmailClient {
             throw new Error(result.errors[0].message);
         return result.data.deleteEmail;
     }
+    /**
+     * Sends a raw MIME-formatted email.
+     * This is useful for sending emails with attachments, like calendar invites.
+     *
+     * @param rawMessage - The full MIME message as a string, including headers and body.
+     * @returns A promise resolving to the Message-ID of the sent email.
+     * @throws Error if sending fails.
+     *
+     * @example
+     * const boundary = `----=_Part_${Date.now()}`;
+     * const rawMessage = `From: events@mail.yourdomain.com
+     * To: user@example.com
+     * Subject: Meeting Invite
+     * MIME-Version: 1.0
+     * Content-Type: multipart/mixed; boundary="${boundary}"
+     *
+     * --${boundary}
+     * Content-Type: text/plain
+     *
+     * You're invited to a meeting.
+     *
+     * --${boundary}
+     * Content-Type: text/calendar; method=REQUEST; name="invite.ics"
+     * Content-Disposition: attachment; filename="invite.ics"
+     *
+     * BEGIN:VCALENDAR
+     * ...
+     * END:VCALENDAR
+     * --${boundary}--`;
+     *
+     * await ccc.email.sendRaw(rawMessage);
+     */
+    async sendRaw(rawMessage) {
+        const pid = this.ccc.projectId;
+        if (!pid)
+            throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
+        const query = `
+            mutation SendRawEmail($projectId: ID!, $rawMessage: String!) {
+                sendRawEmail(projectId: $projectId, rawMessage: $rawMessage)
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: { projectId: pid, rawMessage }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.sendRawEmail;
+    }
+    /**
+     * Retrieves the attachments from a specific inbound email.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to an array of attachments.
+     *
+     * @example
+     * const attachments = await ccc.email.getAttachments(emailId);
+     * for (const att of attachments) {
+     *   const content = Buffer.from(att.content, 'base64');
+     *   console.log(`${att.filename}: ${att.contentType}, ${att.size} bytes`);
+     * }
+     */
+    async getAttachments(emailId) {
+        const query = `
+            query Email($id: ID!) {
+                email(id: $id) {
+                    attachments {
+                        filename
+                        contentType
+                        size
+                        content
+                    }
+                }
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: { id: emailId }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.email?.attachments || [];
+    }
 }

package/dist/email/types.d.ts

@@ -35,17 +35,25 @@ export interface InboundEmail {
     /** References header. */
     references?: string;
 }
+/**
+ * Represents an email address with an optional display name.
+ */
+export interface EmailAddress {
+    /** The display name of the account (e.g., "John Doe"). */
+    name?: string;
+    /** The raw email address (e.g., "john@example.com"). */
+    address: string;
+}
 /**
  * Options for sending an email.
  */
 export interface SendEmailOptions {
     /**
      * The sender address. Must be a verified domain.
-     * Use "Name <email@domain.com>" or just "email@domain.com".
      */
-    from?: string;
-    /** The recipient(s). Can be a string or an array of strings. */
-    to: string | string[];
+    from?: EmailAddress;
+    /** The recipient(s). Can be a string, an EmailAddress object, or an array of either. */
+    to: string | EmailAddress | (string | EmailAddress)[];
     /** The subject line. */
     subject: string;
     /** The HTML body of the email. */
@@ -53,3 +61,16 @@ export interface SendEmailOptions {
     /** The plain text body of the email. */
     text?: string;
 }
+/**
+ * Represents an email attachment.
+ */
+export interface EmailAttachment {
+    /** The filename of the attachment. */
+    filename: string;
+    /** The MIME type of the attachment. */
+    contentType: string;
+    /** The size of the attachment in bytes. */
+    size: number;
+    /** The content of the attachment, Base64 encoded. */
+    content: string;
+}

package/docs/email.md

@@ -5,7 +5,9 @@ Managed email sending and receiving with inbound processing and domain verificat
 ## Features
 
 - **Send Emails**: Send transactional emails via Amazon SES (managed backend).
+- **Send Raw Emails**: Send MIME-formatted emails with attachments (e.g., calendar invites).
 - **Inbound Processing**: Receive emails, store them in GCS, and access them via API.
+- **Attachment Support**: Extract and download attachments from inbound emails.
 - **Domain Verification**: Automates DNS verification for custom domains.
 
 ## Usage
@@ -37,6 +39,43 @@ const messageId = await ccc.email.send({
 });
 ```
 
+### Sending Raw Emails (with Attachments)
+
+Send MIME-formatted emails for advanced use cases like calendar invites.
+
+```typescript
+// Construct a MIME message with an attachment
+const boundary = `----=_Part_${Date.now()}`;
+const rawMessage = `From: events@mail.yourdomain.com
+To: user@example.com
+Subject: Meeting Invite
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="${boundary}"
+
+--${boundary}
+Content-Type: text/plain; charset="utf-8"
+
+You have been invited to a meeting.
+
+--${boundary}
+Content-Type: text/calendar; method=REQUEST; name="invite.ics"
+Content-Disposition: attachment; filename="invite.ics"
+
+BEGIN:VCALENDAR
+VERSION:2.0
+METHOD:REQUEST
+BEGIN:VEVENT
+UID:event-123@yourapp.com
+DTSTART:20260210T100000Z
+DTEND:20260210T110000Z
+SUMMARY:Team Meeting
+END:VEVENT
+END:VCALENDAR
+--${boundary}--`;
+
+const messageId = await ccc.email.sendRaw(rawMessage);
+```
+
 ### Retrieving Inbound Emails
 
 Fetch the latest emails received by the project's inbound address.
@@ -54,12 +93,35 @@ for (const email of emails) {
 }
 ```
 
+### Retrieving Attachments
+
+Get attachments from an inbound email.
+
+```typescript
+const attachments = await ccc.email.getAttachments(emailId);
+
+for (const att of attachments) {
+  console.log(`${att.filename}: ${att.contentType}, ${att.size} bytes`);
+  
+  // Decode the Base64 content
+  const content = Buffer.from(att.content, 'base64');
+  
+  // For calendar responses, parse the ICS
+  if (att.contentType.includes('calendar')) {
+    const icsText = content.toString('utf-8');
+    console.log('Calendar data:', icsText);
+  }
+}
+```
+
 ## Agent Capabilities
 
 The email service is designed to be easily used by AI agents to build automated workflows:
 - **Auto-Reply Bots**: Poll `getInbound()` and `send()` replies.
 - **Verification flows**: Trigger emails and read the verification codes from the inbox.
+- **Calendar Workflows**: Send calendar invites with `sendRaw()` and process responses via `getAttachments()`.
 
 ## Authentication
 
 Requires the `CC_PROJECT_TOKEN` environment variable, automatically injected in CloneCommand deployments.
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@clonecommand/cloud",
-    "version": "0.0.7",
+    "version": "0.0.10",
     "type": "module",
     "description": "The official SDK for CloneCommand managed services",
     "main": "dist/index.js",
@@ -33,4 +33,4 @@
     "devDependencies": {
         "typescript": "^5.0.0"
     }
-}
+}