@clonecommand/cloud 0.0.4 → 0.0.10

package/dist/email/index.d.ts

@@ -1,5 +1,5 @@
 import { CloneCommandCloud } from "..";
-import { EmailConfig, InboundEmail, SendEmailOptions } from "./types";
+import { InboundEmail, SendEmailOptions, EmailAttachment } from "./types";
 /**
  * Client for interacting with CloneCommand Email services.
  */
@@ -7,20 +7,11 @@ export declare class EmailClient {
     private ccc;
     constructor(ccc: CloneCommandCloud);
     /**
-     * Retrieves the email configuration for the current project.
+     * Checks if the email service is enabled for the current project.
      *
-     * @returns A promise resolving to the EmailConfig or null if not found.
-     * @throws Error if projectId is missing or the API returns an error.
+     * @returns A promise resolving to true if enabled, false otherwise.
      */
-    getConfig(): Promise<EmailConfig | null>;
-    /**
-     * Enables the email service for a specific domain.
-     *
-     * @param domainId - The ID of the domain to enable email for.
-     * @returns A promise resolving to the updated EmailConfig.
-     * @throws Error if activation fails.
-     */
-    enable(domainId: string): Promise<EmailConfig>;
+    isEnabled(): Promise<boolean>;
     /**
      * Sends an email message.
      *
@@ -30,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'
      * });
@@ -68,9 +60,50 @@ export declare class EmailClient {
      */
     delete(emailId: string): Promise<boolean>;
     /**
-     * Refreshes the email verification status for the current project.
+     * 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.
      *
-     * @returns A promise resolving to the status string.
+     * @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`);
+     * }
      */
-    refreshEmailVerificationStatus(): Promise<string>;
+    getAttachments(emailId: string): Promise<EmailAttachment[]>;
 }

package/dist/email/index.js

@@ -7,24 +7,18 @@ export class EmailClient {
         this.ccc = ccc;
     }
     /**
-     * Retrieves the email configuration for the current project.
+     * Checks if the email service is enabled for the current project.
      *
-     * @returns A promise resolving to the EmailConfig or null if not found.
-     * @throws Error if projectId is missing or the API returns an error.
+     * @returns A promise resolving to true if enabled, false otherwise.
      */
-    async getConfig() {
+    async isEnabled() {
         const pid = this.ccc.projectId;
         if (!pid)
             throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
         const query = `
-            query EmailConfig($projectId: ID!) {
+            query EmailStatus($projectId: ID!) {
                 emailConfig(projectId: $projectId) {
-                    id
-                    projectId
-                    domainId
                     isEnabled
-                    sesVerificationStatus
-                    dkimTokens
                 }
             }
         `;
@@ -38,42 +32,7 @@ export class EmailClient {
         });
         if (result.errors)
             throw new Error(result.errors[0].message);
-        return result.data.emailConfig;
-    }
-    /**
-     * Enables the email service for a specific domain.
-     *
-     * @param domainId - The ID of the domain to enable email for.
-     * @returns A promise resolving to the updated EmailConfig.
-     * @throws Error if activation fails.
-     */
-    async enable(domainId) {
-        const pid = this.ccc.projectId;
-        if (!pid)
-            throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
-        const query = `
-            mutation EnableEmail($projectId: ID!, $domainId: ID!) {
-                enableEmail(projectId: $projectId, domainId: $domainId) {
-                    id
-                    projectId
-                    domainId
-                    isEnabled
-                    sesVerificationStatus
-                    dkimTokens
-                }
-            }
-        `;
-        const result = await this.ccc.request('/graphql', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                query,
-                variables: { projectId: pid, domainId }
-            })
-        });
-        if (result.errors)
-            throw new Error(result.errors[0].message);
-        return result.data.enableEmail;
+        return !!result.data.emailConfig?.isEnabled;
     }
     /**
      * Sends an email message.
@@ -84,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'
      * });
@@ -98,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' },
@@ -107,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
@@ -244,24 +211,94 @@ export class EmailClient {
         return result.data.deleteEmail;
     }
     /**
-     * Refreshes the email verification status for the current project.
+     * 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"
      *
-     * @returns A promise resolving to the status string.
+     * BEGIN:VCALENDAR
+     * ...
+     * END:VCALENDAR
+     * --${boundary}--`;
+     *
+     * await ccc.email.sendRaw(rawMessage);
      */
-    async refreshEmailVerificationStatus() {
+    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 status = await this.ccc.request('/graphql', {
+        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: `mutation RefreshVerification($projectId: ID!) { refreshEmailVerificationStatus(projectId: $projectId) }`,
-                variables: { projectId: pid }
+                query,
+                variables: { projectId: pid, rawMessage }
             })
         });
-        if (status.errors)
-            throw new Error(status.errors[0].message);
-        return status.data.refreshEmailVerificationStatus;
+        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

@@ -1,22 +1,3 @@
-/**
- * Configuration for the email service.
- */
-export interface EmailConfig {
-    /** Unique ID for the email configuration. */
-    id: string;
-    /** Project ID this configuration belongs to. */
-    projectId: string;
-    /** The domain ID associated with this email service. */
-    domainId: string;
-    /** Whether the email service is currently enabled. */
-    isEnabled: boolean;
-    /** The Amazon SES Identity ARN. */
-    sesIdentityArn?: string;
-    /** Current verification status in SES. */
-    sesVerificationStatus?: string;
-    /** DKIM verification tokens as a JSON string. */
-    dkimTokens?: string;
-}
 /**
  * Represents an inbound email received by the system.
  */
@@ -54,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. */
@@ -72,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,22 +5,24 @@ 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
 
-### Getting Configuration
+### Checking Status
 
-Check if email is enabled for the current project.
+Check if the email service is enabled and ready to use for the current project.
 
 ```typescript
 import { ccc } from '@clonecommand/cloud';
 
-const config = await ccc.email.getConfig();
+const enabled = await ccc.email.isEnabled();
 
-if (config?.isEnabled) {
-  console.log('Email is active!');
+if (enabled) {
+  console.log('Email is active and ready to send!');
 }
 ```
 
@@ -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.4",
+    "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"
     }
-}
+}