@clonecommand/cloud 0.0.2 → 0.0.4

package/README.md

@@ -4,6 +4,13 @@ The official SDK for CloneCommand managed services.
 
 This library simplifies integration with ephemeral preview environments and provides access to CloneCommand Cloud services like Login Proxy, Storage, and Email.
 
+### 🤖 Agent Ready
+This package is designed to be easily consumed by AI agents and LLMs. It features:
+- **Full TypeScript Definitions**: All methods, arguments, and return types are strictly typed.
+- **Rich JSDoc**: Comprehensive comments and examples to help agents understand the intent behind every function.
+- **Clean API Surface**: A logical, singleton-based structure that is easy to navigate.
+
+
 ## Documentation
 
 Full documentation is available in the [`docs/`](./docs/README.md) directory.

package/dist/email/index.d.ts

@@ -1,69 +1,76 @@
-import { CloneCommandCloud } from '../index.js';
-export interface EmailConfig {
-    id: string;
-    projectId: string;
-    domainId: string;
-    isEnabled: boolean;
-    sesIdentityArn?: string;
-    sesVerificationStatus?: string;
-    dkimTokens?: string;
-}
-export interface InboundEmail {
-    id: string;
-    projectId: string;
-    sender: string;
-    recipient: string;
-    subject: string;
-    snippet: string;
-    bucketPath: string;
-    receivedAt: string;
-    isRead: boolean;
-    hasAttachments: boolean;
-    rawSize: number;
-    threadId?: string;
-    messageId?: string;
-    inReplyTo?: string;
-    references?: string;
-}
-export interface SendEmailOptions {
-    from?: string;
-    to: string | string[];
-    subject: string;
-    html?: string;
-    text?: string;
-}
+import { CloneCommandCloud } from "..";
+import { EmailConfig, InboundEmail, SendEmailOptions } from "./types";
+/**
+ * Client for interacting with CloneCommand Email services.
+ */
 export declare class EmailClient {
     private ccc;
     constructor(ccc: CloneCommandCloud);
     /**
-     * Get email configuration for the project.
+     * Retrieves the email configuration 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.
      */
-    getConfig(projectId?: string): Promise<EmailConfig | null>;
+    getConfig(): Promise<EmailConfig | null>;
     /**
-     * Enable email service for a domain.
+     * 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, projectId?: string): Promise<EmailConfig>;
+    enable(domainId: string): Promise<EmailConfig>;
     /**
-     * Send an email.
+     * Sends an email message.
+     *
+     * @param options - The email content and recipient details.
+     * @returns A promise resolving to the Message-ID of the sent email.
+     * @throws Error if sending fails.
+     *
+     * @example
+     * await ccc.email.send({
+     *   to: 'user@example.com',
+     *   subject: 'Hello',
+     *   text: 'This is a test'
+     * });
      */
-    send(options: SendEmailOptions, projectId?: string): Promise<string>;
+    send(options: SendEmailOptions): Promise<string>;
     /**
-     * Get inbound emails.
+     * Retrieves a list of inbound emails received by the project.
+     *
+     * @param options - Filtering and pagination options (limit, before).
+     * @returns A promise resolving to an array of InboundEmail previews.
      */
     getInbound(options?: {
         limit?: number;
         before?: Date;
-    }, projectId?: string): Promise<InboundEmail[]>;
+    }): Promise<InboundEmail[]>;
     /**
-     * Get a specific email by ID.
+     * Retrieves the full details of a specific inbound email, including the body.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to the full InboundEmail object, or null if not found.
      */
     get(emailId: string): Promise<InboundEmail | null>;
     /**
-     * Mark an email as read.
+     * Marks an inbound email as read.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to true if successful.
      */
     markAsRead(emailId: string): Promise<boolean>;
     /**
-     * Delete an email.
+     * Deletes an inbound email permanently.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to true if successful.
      */
     delete(emailId: string): Promise<boolean>;
+    /**
+     * Refreshes the email verification status for the current project.
+     *
+     * @returns A promise resolving to the status string.
+     */
+    refreshEmailVerificationStatus(): Promise<string>;
 }

package/dist/email/index.js

@@ -1,15 +1,21 @@
+/**
+ * Client for interacting with CloneCommand Email services.
+ */
 export class EmailClient {
     ccc;
     constructor(ccc) {
         this.ccc = ccc;
     }
     /**
-     * Get email configuration for the project.
+     * Retrieves the email configuration 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.
      */
-    async getConfig(projectId) {
-        const pid = projectId || this.ccc.projectId;
+    async getConfig() {
+        const pid = this.ccc.projectId;
         if (!pid)
-            throw new Error("projectId is required");
+            throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
         const query = `
             query EmailConfig($projectId: ID!) {
                 emailConfig(projectId: $projectId) {
@@ -35,12 +41,16 @@ export class EmailClient {
         return result.data.emailConfig;
     }
     /**
-     * Enable email service for a domain.
+     * 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, projectId) {
-        const pid = projectId || this.ccc.projectId;
+    async enable(domainId) {
+        const pid = this.ccc.projectId;
         if (!pid)
-            throw new Error("projectId is required");
+            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) {
@@ -66,12 +76,23 @@ export class EmailClient {
         return result.data.enableEmail;
     }
     /**
-     * Send an email.
+     * Sends an email message.
+     *
+     * @param options - The email content and recipient details.
+     * @returns A promise resolving to the Message-ID of the sent email.
+     * @throws Error if sending fails.
+     *
+     * @example
+     * await ccc.email.send({
+     *   to: 'user@example.com',
+     *   subject: 'Hello',
+     *   text: 'This is a test'
+     * });
      */
-    async send(options, projectId) {
-        const pid = projectId || this.ccc.projectId;
+    async send(options) {
+        const pid = this.ccc.projectId;
         if (!pid)
-            throw new Error("projectId is required");
+            throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
         const query = `
             mutation SendEmail($projectId: ID!, $email: SendEmailInput!) {
                 sendEmail(projectId: $projectId, email: $email)
@@ -99,12 +120,15 @@ export class EmailClient {
         return result.data.sendEmail;
     }
     /**
-     * Get inbound emails.
+     * Retrieves a list of inbound emails received by the project.
+     *
+     * @param options - Filtering and pagination options (limit, before).
+     * @returns A promise resolving to an array of InboundEmail previews.
      */
-    async getInbound(options = {}, projectId) {
-        const pid = projectId || this.ccc.projectId;
+    async getInbound(options = {}) {
+        const pid = this.ccc.projectId;
         if (!pid)
-            throw new Error("projectId is required");
+            throw new Error("projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
         const query = `
             query InboundEmails($projectId: ID!, $limit: Int, $before: DateTime) {
                 inboundEmails(projectId: $projectId, limit: $limit, before: $before) {
@@ -137,7 +161,10 @@ export class EmailClient {
         return result.data.inboundEmails;
     }
     /**
-     * Get a specific email by ID.
+     * Retrieves the full details of a specific inbound email, including the body.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to the full InboundEmail object, or null if not found.
      */
     async get(emailId) {
         const query = `
@@ -169,7 +196,10 @@ export class EmailClient {
         return result.data.email;
     }
     /**
-     * Mark an email as read.
+     * Marks an inbound email as read.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to true if successful.
      */
     async markAsRead(emailId) {
         const query = `
@@ -190,7 +220,10 @@ export class EmailClient {
         return result.data.markEmailAsRead;
     }
     /**
-     * Delete an email.
+     * Deletes an inbound email permanently.
+     *
+     * @param emailId - The unique ID of the email.
+     * @returns A promise resolving to true if successful.
      */
     async delete(emailId) {
         const query = `
@@ -210,4 +243,25 @@ export class EmailClient {
             throw new Error(result.errors[0].message);
         return result.data.deleteEmail;
     }
+    /**
+     * Refreshes the email verification status for the current project.
+     *
+     * @returns A promise resolving to the status string.
+     */
+    async refreshEmailVerificationStatus() {
+        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', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query: `mutation RefreshVerification($projectId: ID!) { refreshEmailVerificationStatus(projectId: $projectId) }`,
+                variables: { projectId: pid }
+            })
+        });
+        if (status.errors)
+            throw new Error(status.errors[0].message);
+        return status.data.refreshEmailVerificationStatus;
+    }
 }

package/dist/email/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+export interface InboundEmail {
+    /** Unique ID of the email. */
+    id: string;
+    /** Project ID this email belongs to. */
+    projectId: string;
+    /** The email address of the sender. */
+    sender: string;
+    /** The email address of the recipient. */
+    recipient: string;
+    /** The subject line of the email. */
+    subject: string;
+    /** A short snippet/preview of the email content. */
+    snippet: string;
+    /** The full HTML or text body of the email (only available in detailed view). */
+    body?: string;
+    /** The path to the raw email file in storage. */
+    bucketPath: string;
+    /** ISO timestamp when the email was received. */
+    receivedAt: string;
+    /** Whether the email has been marked as read. */
+    isRead: boolean;
+    /** Whether the email contains attachments. */
+    hasAttachments: boolean;
+    /** Total size of the raw email in bytes. */
+    rawSize: number;
+    /** Thread ID for grouping related emails. */
+    threadId?: string;
+    /** Standard Message-ID header. */
+    messageId?: string;
+    /** In-Reply-To header. */
+    inReplyTo?: string;
+    /** References header. */
+    references?: 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[];
+    /** The subject line. */
+    subject: string;
+    /** The HTML body of the email. */
+    html?: string;
+    /** The plain text body of the email. */
+    text?: string;
+}

package/dist/email/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,79 +1,100 @@
-export interface CCCConfig {
-    projectId?: string;
-    baseUrl?: string;
-}
-export interface StorageFile {
-    id: string;
-    projectId: string;
-    fileId: string;
-    originalFilename?: string;
-    contentType: string;
-    sizeBytes?: number;
-    extension?: string;
-    publicUrl: string;
-    createdAt: string;
-}
 import { EmailClient } from './email/index.js';
+import { CCCConfig, StorageFile } from './types.js';
+/**
+ * The main client for interacting with CloneCommand managed services.
+ * This class provides access to storage, email, and authentication features.
+ */
 export declare class CloneCommandCloud {
     private config;
+    private _email;
+    /**
+     * Initializes the SDK with configuration options.
+     *
+     * @param config - The configuration object.
+     */
     init(config: CCCConfig): void;
+    /**
+     * Returns the current project ID.
+     * Resolution order:
+     * 1. Manual config via `init()`
+     * 2. `CC_PROJECT_ID` environment variable
+     * 3. Extracted from the `CC_PROJECT_TOKEN` JWT.
+     */
     get projectId(): string | undefined;
+    /**
+     * The base URL for API requests.
+     */
     get baseUrl(): string;
+    /**
+     * The service token used for authentication.
+     * Resolution order:
+     * 1. Manual config via `init()`
+     * 2. `CC_PROJECT_TOKEN` environment variable.
+     */
     get serviceToken(): string | undefined;
     /**
      * Internal helper to make authenticated requests to the CloneCommand API.
-     * This is used by server-side methods (e.g., image uploads).
+     *
+     * @param path - The API path (e.g., '/graphql').
+     * @param options - Standard RequestInit options.
+     * @returns A promise resolving to the JSON response.
+     * @throws Error if the request fails or returns a non-OK status.
+     */
+    request<T = any>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Login and authentication utilities.
      */
-    request(path: string, options?: RequestInit): Promise<any>;
     get login(): {
         /**
          * Wraps a standard OAuth authorization URL with the CloneCommand Proxy.
          * This allows ephemeral preview environments (*.clonecommand.app) to handle
          * OAuth redirects without constant provider configuration changes.
          *
-         * @param originalUrl The standard OAuth authorization URL
-         * @returns The proxied URL to redirect the user to
+         * @param originalUrl - The standard OAuth authorization URL.
+         * @returns The proxied URL to redirect the user to.
+         * @throws Error if projectId is not configured.
          */
         proxy: (originalUrl: string) => string;
     };
+    /**
+     * Storage and file management utilities.
+     */
     get storage(): {
         /**
-         * Import a file from a URL and upload it to CloneCommand Storage.
+         * Imports a file from a URL and uploads it to CloneCommand Storage.
          *
-         * @param url The URL of the file to import
-         * @param contentType Optional content type (auto-detected if not provided)
-         * @returns StorageFile object with publicUrl
+         * @param url - The URL of the file to import.
+         * @param contentType - Optional content type (auto-detected if not provided).
+         * @returns A promise resolving to the StorageFile record.
          *
          * @example
          * const file = await ccc.storage.importFileFromUrl('https://example.com/image.png');
-         * console.log(file.publicUrl); // https://media.clonecommand.com/:projectId/:fileId/original.png
          */
         importFileFromUrl: (url: string, contentType?: string) => Promise<StorageFile>;
         /**
-         * Import a file from a Buffer and upload it to CloneCommand Storage.
-         *
-         * @param buffer The file buffer
-         * @param contentType The content type of the file
-         * @returns StorageFile object with publicUrl
+         * Uploads a file from a memory buffer.
          *
-         * @example
-         * const buffer = fs.readFileSync('image.png');
-         * const file = await ccc.storage.importFileFromBuffer(buffer, 'image/png');
+         * @param buffer - The file contents as a Buffer.
+         * @param contentType - The MIME type of the file.
+         * @param filename - Optional filename.
+         * @returns A promise resolving to the StorageFile record.
          */
         importFileFromBuffer: (buffer: Buffer, contentType: string, filename?: string) => Promise<StorageFile>;
         /**
-         * Get the public URL for a file.
-         *
-         * @param fileId The file ID
-         * @param projectSlug Optional project slug (uses projectId from config if not provided)
-         * @returns The public URL
+         * Generates a public URL for a given file ID.
          *
-         * @example
-         * const url = ccc.storage.getFileUrl('abc-123-def', 'my-project');
-         * // => https://my-project.clonecommand.media/abc-123-def/original
+         * @param fileId - The unique file ID.
+         * @param projectSlug - Optional project slug (automatically resolved from projectId if not provided).
+         * @returns The public URL string.
          */
         getFileUrl: (fileId: string, projectSlug?: string) => string;
     };
+    /**
+     * Access to email services.
+     */
     get email(): EmailClient;
 }
+/**
+ * Singleton instance of the CloneCommandCloud client.
+ */
 export declare const ccc: CloneCommandCloud;

package/dist/index.js

@@ -1,12 +1,29 @@
 import { EmailClient } from './email/index.js';
+/**
+ * The main client for interacting with CloneCommand managed services.
+ * This class provides access to storage, email, and authentication features.
+ */
 export class CloneCommandCloud {
     config = {};
+    _email = null;
+    /**
+     * Initializes the SDK with configuration options.
+     *
+     * @param config - The configuration object.
+     */
     init(config) {
         this.config = {
             ...this.config,
             ...config,
         };
     }
+    /**
+     * Returns the current project ID.
+     * Resolution order:
+     * 1. Manual config via `init()`
+     * 2. `CC_PROJECT_ID` environment variable
+     * 3. Extracted from the `CC_PROJECT_TOKEN` JWT.
+     */
     get projectId() {
         if (this.config.projectId)
             return this.config.projectId;
@@ -30,15 +47,28 @@ export class CloneCommandCloud {
         }
         return undefined;
     }
+    /**
+     * The base URL for API requests.
+     */
     get baseUrl() {
         return this.config.baseUrl || 'https://graph.clonecommand.com';
     }
+    /**
+     * The service token used for authentication.
+     * Resolution order:
+     * 1. Manual config via `init()`
+     * 2. `CC_PROJECT_TOKEN` environment variable.
+     */
     get serviceToken() {
-        return typeof process !== 'undefined' ? process.env.CC_PROJECT_TOKEN : undefined;
+        return this.config.serviceToken || (typeof process !== 'undefined' ? process.env.CC_PROJECT_TOKEN : undefined);
     }
     /**
      * Internal helper to make authenticated requests to the CloneCommand API.
-     * This is used by server-side methods (e.g., image uploads).
+     *
+     * @param path - The API path (e.g., '/graphql').
+     * @param options - Standard RequestInit options.
+     * @returns A promise resolving to the JSON response.
+     * @throws Error if the request fails or returns a non-OK status.
      */
     async request(path, options = {}) {
         const token = this.serviceToken;
@@ -56,6 +86,9 @@ export class CloneCommandCloud {
         }
         return response.json();
     }
+    /**
+     * Login and authentication utilities.
+     */
     get login() {
         return {
             /**
@@ -63,43 +96,40 @@ export class CloneCommandCloud {
              * This allows ephemeral preview environments (*.clonecommand.app) to handle
              * OAuth redirects without constant provider configuration changes.
              *
-             * @param originalUrl The standard OAuth authorization URL
-             * @returns The proxied URL to redirect the user to
+             * @param originalUrl - The standard OAuth authorization URL.
+             * @returns The proxied URL to redirect the user to.
+             * @throws Error if projectId is not configured.
              */
             proxy: (originalUrl) => {
                 const pid = this.projectId;
                 if (!pid) {
-                    throw new Error("CloneCommand: projectId is required. Provide it in ccc.init({ projectId }) " +
-                        "or set the CC_PROJECT_ID environment variable.");
+                    throw new Error("CloneCommand: projectId is required but could not be resolved from CC_PROJECT_TOKEN or environment. " +
+                        "Provide it in ccc.init({ projectId }) or set the CC_PROJECT_ID environment variable.");
                 }
                 const encodedUrl = encodeURIComponent(originalUrl);
                 return `${this.baseUrl}/login/proxy/start?projectId=${pid}&url=${encodedUrl}`;
             }
         };
     }
+    /**
+     * Storage and file management utilities.
+     */
     get storage() {
         return {
             /**
-             * Import a file from a URL and upload it to CloneCommand Storage.
+             * Imports a file from a URL and uploads it to CloneCommand Storage.
              *
-             * @param url The URL of the file to import
-             * @param contentType Optional content type (auto-detected if not provided)
-             * @returns StorageFile object with publicUrl
+             * @param url - The URL of the file to import.
+             * @param contentType - Optional content type (auto-detected if not provided).
+             * @returns A promise resolving to the StorageFile record.
              *
              * @example
              * const file = await ccc.storage.importFileFromUrl('https://example.com/image.png');
-             * console.log(file.publicUrl); // https://media.clonecommand.com/:projectId/:fileId/original.png
              */
             importFileFromUrl: async (url, contentType) => {
-                const token = this.serviceToken;
                 const pid = this.projectId;
-                if (!token) {
-                    throw new Error("CloneCommand Storage: CC_PROJECT_TOKEN is required. " +
-                        "Ensure your service is deployed via CloneCommand or use 'clones run' for local development.");
-                }
                 if (!pid) {
-                    throw new Error("CloneCommand Storage: projectId is required. " +
-                        "Set CC_PROJECT_ID environment variable or call ccc.init({ projectId }).");
+                    throw new Error("CloneCommand Storage: projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
                 }
                 const query = `
                     mutation UploadFileFromUrl($projectId: String!, $url: String!, $contentType: String) {
@@ -118,9 +148,7 @@ export class CloneCommandCloud {
                 `;
                 const result = await this.request('/graphql', {
                     method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                    },
+                    headers: { 'Content-Type': 'application/json' },
                     body: JSON.stringify({
                         query,
                         variables: { projectId: pid, url, contentType },
@@ -132,24 +160,17 @@ export class CloneCommandCloud {
                 return result.data.uploadFileFromUrl;
             },
             /**
-             * Import a file from a Buffer and upload it to CloneCommand Storage.
+             * Uploads a file from a memory buffer.
              *
-             * @param buffer The file buffer
-             * @param contentType The content type of the file
-             * @returns StorageFile object with publicUrl
-             *
-             * @example
-             * const buffer = fs.readFileSync('image.png');
-             * const file = await ccc.storage.importFileFromBuffer(buffer, 'image/png');
+             * @param buffer - The file contents as a Buffer.
+             * @param contentType - The MIME type of the file.
+             * @param filename - Optional filename.
+             * @returns A promise resolving to the StorageFile record.
              */
             importFileFromBuffer: async (buffer, contentType, filename = 'file') => {
-                const token = this.serviceToken;
                 const pid = this.projectId;
-                if (!token) {
-                    throw new Error("CloneCommand Storage: CC_PROJECT_TOKEN is required.");
-                }
                 if (!pid) {
-                    throw new Error("CloneCommand Storage: projectId is required.");
+                    throw new Error("CloneCommand Storage: projectId could not be resolved. Ensure CC_PROJECT_TOKEN is set.");
                 }
                 const query = `
                     mutation UploadFileFromBuffer($projectId: String!, $buffer: String!, $contentType: String!, $filename: String!) {
@@ -185,31 +206,33 @@ export class CloneCommandCloud {
                 return result.data.uploadFileFromBuffer;
             },
             /**
-             * Get the public URL for a file.
+             * Generates a public URL for a given file ID.
              *
-             * @param fileId The file ID
-             * @param projectSlug Optional project slug (uses projectId from config if not provided)
-             * @returns The public URL
-             *
-             * @example
-             * const url = ccc.storage.getFileUrl('abc-123-def', 'my-project');
-             * // => https://my-project.clonecommand.media/abc-123-def/original
+             * @param fileId - The unique file ID.
+             * @param projectSlug - Optional project slug (automatically resolved from projectId if not provided).
+             * @returns The public URL string.
              */
             getFileUrl: (fileId, projectSlug) => {
                 const pid = this.projectId;
                 const slug = projectSlug || pid;
                 if (!slug) {
-                    throw new Error("CloneCommand Storage: projectId or projectSlug is required. " +
-                        "Set CC_PROJECT_ID environment variable or call ccc.init({ projectId }).");
+                    throw new Error("CloneCommand Storage: projectId or projectSlug could not be resolved.");
                 }
-                // Note: This returns the default projectslug.clonecommand.media URL
-                // Custom domains are handled server-side
                 return `https://${slug}.clonecommand.media/${fileId}/original`;
             },
         };
     }
+    /**
+     * Access to email services.
+     */
     get email() {
-        return new EmailClient(this);
+        if (!this._email) {
+            this._email = new EmailClient(this);
+        }
+        return this._email;
     }
 }
+/**
+ * Singleton instance of the CloneCommandCloud client.
+ */
 export const ccc = new CloneCommandCloud();

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Configuration for the CloneCommand Cloud SDK.
+ */
+export interface CCCConfig {
+    /**
+     * The unique identifier for your project.
+     * Can also be set via the `CC_PROJECT_ID` environment variable.
+     */
+    projectId?: string;
+    /**
+     * The base URL for the CloneCommand API.
+     * Defaults to `https://graph.clonecommand.com`.
+     */
+    baseUrl?: string;
+    /**
+     * The service token for authentication.
+     * Can also be set via the `CC_PROJECT_TOKEN` environment variable.
+     */
+    serviceToken?: string;
+}
+/**
+ * Represents a file stored in CloneCommand Storage.
+ */
+export interface StorageFile {
+    /** Unique ID of the storage record. */
+    id: string;
+    /** Project ID this file belongs to. */
+    projectId: string;
+    /** The underlying storage provider's file ID. */
+    fileId: string;
+    /** Original filename if available. */
+    originalFilename?: string;
+    /** MIME type of the file. */
+    contentType: string;
+    /** Size of the file in bytes. */
+    sizeBytes?: number;
+    /** File extension. */
+    extension?: string;
+    /** Publicly accessible URL for the file. */
+    publicUrl: string;
+    /** ISO timestamp when the file was uploaded. */
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/README.md

@@ -0,0 +1,23 @@
+# CloneCommand Cloud SDK Documentation
+
+Welcome to the `@clonecommand/cloud` SDK documentation.
+
+## Modules
+
+- [**🔐 Login**](./login.md): OAuth Proxy service for preview environments.
+- [**📦 Storage**](./storage.md): Managed file hosting with CDN and custom domains.
+- [**📧 Email**](./email.md): Managed email sending and receiving with inbound processing.
+
+## Quick Start
+
+```typescript
+import { ccc } from '@clonecommand/cloud';
+
+// 1. Initialize (Optional in managed environments)
+ccc.init({ projectId: 'your-project-id' });
+
+// 2. Use services
+const loginUrl = ccc.login.proxy('https://google.com/oauth...');
+const file = await ccc.storage.importFileFromUrl('...');
+const config = await ccc.email.getConfig();
+```

package/docs/email.md

@@ -0,0 +1,65 @@
+# 📧 CloneCommand Email Service
+
+Managed email sending and receiving with inbound processing and domain verification.
+
+## Features
+
+- **Send Emails**: Send transactional emails via Amazon SES (managed backend).
+- **Inbound Processing**: Receive emails, store them in GCS, and access them via API.
+- **Domain Verification**: Automates DNS verification for custom domains.
+
+## Usage
+
+### Getting Configuration
+
+Check if email is enabled for the current project.
+
+```typescript
+import { ccc } from '@clonecommand/cloud';
+
+const config = await ccc.email.getConfig();
+
+if (config?.isEnabled) {
+  console.log('Email is active!');
+}
+```
+
+### Sending Emails
+
+Send simple text or HTML emails.
+
+```typescript
+const messageId = await ccc.email.send({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Welcome to our platform</h1>',
+  text: 'Welcome to our platform'
+});
+```
+
+### Retrieving Inbound Emails
+
+Fetch the latest emails received by the project's inbound address.
+
+```typescript
+const emails = await ccc.email.getInbound({ limit: 5 });
+
+for (const email of emails) {
+  console.log(`Received from: ${email.sender}`);
+  console.log(`Subject: ${email.subject}`);
+  
+  // Fetch full details including body
+  const fullEmail = await ccc.email.get(email.id);
+  console.log(fullEmail.body);
+}
+```
+
+## 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.
+
+## Authentication
+
+Requires the `CC_PROJECT_TOKEN` environment variable, automatically injected in CloneCommand deployments.

package/docs/login.md

@@ -0,0 +1,54 @@
+# 🔐 CloneCommand Login Service (OAuth Proxy)
+
+The **CloneCommand Login Service** acts as a trusted intermediary for OAuth flows, solving the "Redirect URI Paradox" in preview environments.
+
+## Why is this needed?
+
+OAuth providers (Google, GitHub, LinkedIn, etc.) require whitelisting specific Redirect URIs. This is problematic for:
+1.  **Preview Environments**: Each pull request creates a unique URL (e.g., `pr-123.clonecommand.app`). You can't whitelist infinite dynamic URLs.
+2.  **Local Development**: Managing `localhost` vs production URLs often leads to config drift.
+
+## How it works
+
+Instead of redirecting users directly to the OAuth provider, you redirect them to the **CloneCommand Proxy**. The proxy handles the redirection to the provider using a single, stable callback URL (`https://graph.clonecommand.com/login/proxy/callback`), and then redirects the user back to your specific environment.
+
+## Usage
+
+### 1. Wrap your Authorization URL
+
+```typescript
+import { ccc } from '@clonecommand/cloud';
+
+const originalUrl = 'https://github.com/login/oauth/authorize?client_id=...';
+const proxyUrl = ccc.login.proxy(originalUrl);
+
+window.location.href = proxyUrl;
+```
+
+### 2. Configure your OAuth Provider
+
+Whitelist **only** this URL in your provider's developer console:
+
+`https://graph.clonecommand.com/login/proxy/callback`
+
+### 3. Handle the Callback
+
+When exchanging the `code` for an access token on your backend, you **must** use the proxy callback URL as the `redirect_uri`, regardless of where your app is actually running.
+
+```typescript
+// Backend code to exchange code for token
+const response = await fetch('https://github.com/login/oauth/access_token', {
+  method: 'POST',
+  body: JSON.stringify({
+    client_id: '...',
+    client_secret: '...',
+    code: req.query.code,
+    redirect_uri: 'https://graph.clonecommand.com/login/proxy/callback' // <--- CRITICAL
+  })
+});
+```
+
+## Agent Notes
+
+- **Stability**: This feature ensures that authentication flows work immediately in any new environment an agent creates.
+- **Zero Config**: No need to ask the user to update their OAuth provider settings when deploying new branches.

package/docs/storage.md

@@ -0,0 +1,40 @@
+# 📦 CloneCommand Storage Service
+
+Managed file storage with global CDN, automatic SSL, and custom domain support.
+
+## Usage
+
+### Uploading Files
+
+The `importFileFromUrl` method allows you to upload assets from external sources (e.g., social media avatars, public APIs) directly to your project's storage bucket.
+
+```typescript
+import { ccc } from '@clonecommand/cloud';
+
+const file = await ccc.storage.importFileFromUrl('https://example.com/image.png');
+
+console.log(file);
+// {
+//   id: "...",
+//   fileId: "xyz-123",
+//   publicUrl: "https://my-project.clonecommand.media/xyz-123/original.png",
+//   ...
+// }
+```
+
+### Retrieving File URLs
+
+Generate the public CDN URL for a file using its `fileId`.
+
+```typescript
+const url = ccc.storage.getFileUrl('xyz-123');
+// -> https://my-project.clonecommand.media/xyz-123/original
+```
+
+## Custom Domains
+
+If your project has a custom media domain configured (e.g., `cdn.myapp.com`), `getFileUrl` and `importFileFromUrl` will automatically return URLs using that domain.
+
+## Authentication
+
+Storage operations require the `CC_PROJECT_TOKEN` environment variable, which is automatically injected in CloneCommand deployments. For local development, use `clones run`.

package/package.json

@@ -1,13 +1,24 @@
 {
     "name": "@clonecommand/cloud",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "type": "module",
     "description": "The official SDK for CloneCommand managed services",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./email": {
+            "types": "./dist/email/index.d.ts",
+            "import": "./dist/email/index.js"
+        }
+    },
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "docs"
     ],
     "publishConfig": {
         "access": "public"