@clonecommand/cloud 0.0.1 → 0.0.3

package/README.md

@@ -1,65 +1,32 @@
 # @clonecommand/cloud
 
-The official SDK for CloneCommand managed services. This library simplifies integration with ephemeral preview environments and provides access to CloneCommand Cloud services.
+The official SDK for CloneCommand managed services.
 
-## Installation
-
-```bash
-npm install @clonecommand/cloud
-```
-
-## 🔐 Login Service: OAuth Proxy
+This library simplifies integration with ephemeral preview environments and provides access to CloneCommand Cloud services like Login Proxy, Storage, and Email.
 
-OAuth providers (LinkedIn, Google, GitHub, etc.) require a strict whitelist of redirect URLs. This makes testing on dynamic, branch-specific preview environments (`*.clonecommand.app`) difficult.
+## Documentation
 
-The **CloneCommand Login Service** acts as a trusted intermediary, providing a single, stable redirect URL for all your environments.
+Full documentation is available in the [`docs/`](./docs/README.md) directory.
 
-### 1. Initialize the SDK
+- [**🔐 Login**](./docs/login.md) - OAuth Proxy for consistent redirect URIs.
+- [**📦 Storage**](./docs/storage.md) - Managed file hosting.
+- [**📧 Email**](./docs/email.md) - Send and receive emails.
 
-For client-side applications (e.g., Vite, Nuxt), initialize the SDK with your Project ID. 
-
-```typescript
-import { ccc } from '@clonecommand/cloud';
+## Installation
 
-ccc.init({
-  projectId: 'your-project-id' // Found in your CloneCommand Dashboard
-});
+```bash
+npm install @clonecommand/cloud
 ```
 
-> [!NOTE]
-> In managed CloneCommand deployments, your Project ID and Service Tokens are automatically detected—no manual initialization is required for server-side operations.
-
-### 2. Wrap your Login URL
-
-Instead of redirecting directly to the OAuth provider, wrap your generated URL with `ccc.login.proxy()`.
+## Quick Start
 
 ```typescript
-// Before
-const loginUrl = 'https://www.linkedin.com/oauth/v2/authorization?...';
-window.location.href = loginUrl;
-
-// After (Works on localhost, preview branches, and production!)
 import { ccc } from '@clonecommand/cloud';
 
-const loginUrl = 'https://www.linkedin.com/oauth/v2/authorization?...';
-window.location.href = ccc.login.proxy(loginUrl);
-```
-
-### ⚠️ The "Redirect URI Paradox" (Important Quirk)
-When using the proxy, the OAuth provider sees the **Proxy Callback URL** as your application's redirect URI.
-
-1. **Provider Config**: In your OAuth provider settings (e.g., LinkedIn Developer Portal), you **only** need to whitelist this single URL:
-   `https://graph.clonecommand.com/login/proxy/callback`
-
-2. **Backend Token Exchange**: When your application receives the `code` and you call the provider's API to swap it for an `access_token`, you **must** use that same proxy callback URL as the `redirect_uri` parameter:
-   ```typescript
-   // Even if your app is on localhost:3000, you MUST use the proxy callback here
-   const redirect_uri = 'https://graph.clonecommand.com/login/proxy/callback';
-   ```
-   *CloneCommand handles the final hop back to your specific environment automatically.*
+// Initialize (optional in managed environments)
+ccc.init({ projectId: '...' });
 
-### 🤖 Why this is great for Agents
-Using `ccc.login.proxy()` ensures that any new feature you build will have working authentication immediately upon deployment to a preview environment, without requiring human intervention to update provider settings.
-
----
-Built with ❤️ by [CloneCommand](https://clonecommand.com)
+// Use services
+const file = await ccc.storage.importFileFromUrl('...');
+const messageId = await ccc.email.send({ to: '...', subject: '...' });
+```

package/dist/email/index.d.ts

@@ -0,0 +1,69 @@
+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;
+}
+export declare class EmailClient {
+    private ccc;
+    constructor(ccc: CloneCommandCloud);
+    /**
+     * Get email configuration for the project.
+     */
+    getConfig(projectId?: string): Promise<EmailConfig | null>;
+    /**
+     * Enable email service for a domain.
+     */
+    enable(domainId: string, projectId?: string): Promise<EmailConfig>;
+    /**
+     * Send an email.
+     */
+    send(options: SendEmailOptions, projectId?: string): Promise<string>;
+    /**
+     * Get inbound emails.
+     */
+    getInbound(options?: {
+        limit?: number;
+        before?: Date;
+    }, projectId?: string): Promise<InboundEmail[]>;
+    /**
+     * Get a specific email by ID.
+     */
+    get(emailId: string): Promise<InboundEmail | null>;
+    /**
+     * Mark an email as read.
+     */
+    markAsRead(emailId: string): Promise<boolean>;
+    /**
+     * Delete an email.
+     */
+    delete(emailId: string): Promise<boolean>;
+}

package/dist/email/index.js

@@ -0,0 +1,213 @@
+export class EmailClient {
+    ccc;
+    constructor(ccc) {
+        this.ccc = ccc;
+    }
+    /**
+     * Get email configuration for the project.
+     */
+    async getConfig(projectId) {
+        const pid = projectId || this.ccc.projectId;
+        if (!pid)
+            throw new Error("projectId is required");
+        const query = `
+            query EmailConfig($projectId: ID!) {
+                emailConfig(projectId: $projectId) {
+                    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 }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.emailConfig;
+    }
+    /**
+     * Enable email service for a domain.
+     */
+    async enable(domainId, projectId) {
+        const pid = projectId || this.ccc.projectId;
+        if (!pid)
+            throw new Error("projectId is required");
+        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;
+    }
+    /**
+     * Send an email.
+     */
+    async send(options, projectId) {
+        const pid = projectId || this.ccc.projectId;
+        if (!pid)
+            throw new Error("projectId is required");
+        const query = `
+            mutation SendEmail($projectId: ID!, $email: SendEmailInput!) {
+                sendEmail(projectId: $projectId, email: $email)
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: {
+                    projectId: pid,
+                    email: {
+                        from: options.from,
+                        to: Array.isArray(options.to) ? options.to : [options.to],
+                        subject: options.subject,
+                        html: options.html,
+                        text: options.text
+                    }
+                }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.sendEmail;
+    }
+    /**
+     * Get inbound emails.
+     */
+    async getInbound(options = {}, projectId) {
+        const pid = projectId || this.ccc.projectId;
+        if (!pid)
+            throw new Error("projectId is required");
+        const query = `
+            query InboundEmails($projectId: ID!, $limit: Int, $before: DateTime) {
+                inboundEmails(projectId: $projectId, limit: $limit, before: $before) {
+                    id
+                    projectId
+                    sender
+                    recipient
+                    subject
+                    snippet
+                    receivedAt
+                    isRead
+                    hasAttachments
+                }
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: {
+                    projectId: pid,
+                    limit: options.limit,
+                    before: options.before
+                }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.inboundEmails;
+    }
+    /**
+     * Get a specific email by ID.
+     */
+    async get(emailId) {
+        const query = `
+            query Email($id: ID!) {
+                email(id: $id) {
+                    id
+                    projectId
+                    sender
+                    recipient
+                    subject
+                    snippet
+                    body
+                    receivedAt
+                    isRead
+                    hasAttachments
+                }
+            }
+        `;
+        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;
+    }
+    /**
+     * Mark an email as read.
+     */
+    async markAsRead(emailId) {
+        const query = `
+            mutation MarkEmailAsRead($emailId: ID!) {
+                markEmailAsRead(emailId: $emailId)
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: { emailId }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.markEmailAsRead;
+    }
+    /**
+     * Delete an email.
+     */
+    async delete(emailId) {
+        const query = `
+            mutation DeleteEmail($emailId: ID!) {
+                deleteEmail(emailId: $emailId)
+            }
+        `;
+        const result = await this.ccc.request('/graphql', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                variables: { emailId }
+            })
+        });
+        if (result.errors)
+            throw new Error(result.errors[0].message);
+        return result.data.deleteEmail;
+    }
+}

package/dist/index.d.ts

@@ -2,17 +2,29 @@ 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';
 export declare class CloneCommandCloud {
     private config;
     init(config: CCCConfig): void;
-    private get projectId();
-    private get baseUrl();
-    private get serviceToken();
+    get projectId(): string | undefined;
+    get baseUrl(): string;
+    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).
      */
-    private request;
+    request(path: string, options?: RequestInit): Promise<any>;
     get login(): {
         /**
          * Wraps a standard OAuth authorization URL with the CloneCommand Proxy.
@@ -24,5 +36,44 @@ export declare class CloneCommandCloud {
          */
         proxy: (originalUrl: string) => string;
     };
+    get storage(): {
+        /**
+         * Import a file from a URL and upload 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
+         *
+         * @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
+         *
+         * @example
+         * const buffer = fs.readFileSync('image.png');
+         * const file = await ccc.storage.importFileFromBuffer(buffer, 'image/png');
+         */
+        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
+         *
+         * @example
+         * const url = ccc.storage.getFileUrl('abc-123-def', 'my-project');
+         * // => https://my-project.clonecommand.media/abc-123-def/original
+         */
+        getFileUrl: (fileId: string, projectSlug?: string) => string;
+    };
+    get email(): EmailClient;
 }
 export declare const ccc: CloneCommandCloud;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { EmailClient } from './email/index.js';
 export class CloneCommandCloud {
     config = {};
     init(config) {
@@ -7,13 +8,33 @@ export class CloneCommandCloud {
         };
     }
     get projectId() {
-        return this.config.projectId;
+        if (this.config.projectId)
+            return this.config.projectId;
+        if (typeof process !== 'undefined' && process.env.CC_PROJECT_ID)
+            return process.env.CC_PROJECT_ID;
+        // Fallback: Extract from Token (JWT)
+        const token = this.serviceToken;
+        if (token) {
+            try {
+                const parts = token.split('.');
+                if (parts.length === 3) {
+                    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf-8'));
+                    if (payload.projectId) {
+                        return payload.projectId;
+                    }
+                }
+            }
+            catch (e) {
+                // Ignore parse errors
+            }
+        }
+        return undefined;
     }
     get baseUrl() {
         return this.config.baseUrl || 'https://graph.clonecommand.com';
     }
     get serviceToken() {
-        return typeof process !== 'undefined' ? process.env.CC_TOKEN : undefined;
+        return typeof process !== 'undefined' ? process.env.CC_PROJECT_TOKEN : undefined;
     }
     /**
      * Internal helper to make authenticated requests to the CloneCommand API.
@@ -49,12 +70,146 @@ export class CloneCommandCloud {
                 const pid = this.projectId;
                 if (!pid) {
                     throw new Error("CloneCommand: projectId is required. Provide it in ccc.init({ projectId }) " +
-                        "or set the CLONECOMMAND_PROJECT_ID environment variable.");
+                        "or set the CC_PROJECT_ID environment variable.");
                 }
                 const encodedUrl = encodeURIComponent(originalUrl);
                 return `${this.baseUrl}/login/proxy/start?projectId=${pid}&url=${encodedUrl}`;
             }
         };
     }
+    get storage() {
+        return {
+            /**
+             * Import a file from a URL and upload 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
+             *
+             * @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 }).");
+                }
+                const query = `
+                    mutation UploadFileFromUrl($projectId: String!, $url: String!, $contentType: String) {
+                        uploadFileFromUrl(projectId: $projectId, url: $url, contentType: $contentType) {
+                            id
+                            projectId
+                            fileId
+                            originalFilename
+                            contentType
+                            sizeBytes
+                            extension
+                            publicUrl
+                            createdAt
+                        }
+                    }
+                `;
+                const result = await this.request('/graphql', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        query,
+                        variables: { projectId: pid, url, contentType },
+                    }),
+                });
+                if (result.errors) {
+                    throw new Error(`Upload failed: ${result.errors[0].message}`);
+                }
+                return result.data.uploadFileFromUrl;
+            },
+            /**
+             * 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
+             *
+             * @example
+             * const buffer = fs.readFileSync('image.png');
+             * const file = await ccc.storage.importFileFromBuffer(buffer, 'image/png');
+             */
+            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.");
+                }
+                const query = `
+                    mutation UploadFileFromBuffer($projectId: String!, $buffer: String!, $contentType: String!, $filename: String!) {
+                        uploadFileFromBuffer(projectId: $projectId, buffer: $buffer, contentType: $contentType, filename: $filename) {
+                            id
+                            projectId
+                            fileId
+                            originalFilename
+                            contentType
+                            sizeBytes
+                            extension
+                            publicUrl
+                            createdAt
+                        }
+                    }
+                `;
+                const result = await this.request('/graphql', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        query,
+                        variables: {
+                            projectId: pid,
+                            buffer: buffer.toString('base64'),
+                            contentType,
+                            filename
+                        },
+                    }),
+                });
+                if (result.errors) {
+                    throw new Error(`Upload failed: ${result.errors[0].message}`);
+                }
+                return result.data.uploadFileFromBuffer;
+            },
+            /**
+             * 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
+             *
+             * @example
+             * const url = ccc.storage.getFileUrl('abc-123-def', 'my-project');
+             * // => https://my-project.clonecommand.media/abc-123-def/original
+             */
+            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 }).");
+                }
+                // Note: This returns the default projectslug.clonecommand.media URL
+                // Custom domains are handled server-side
+                return `https://${slug}.clonecommand.media/${fileId}/original`;
+            },
+        };
+    }
+    get email() {
+        return new EmailClient(this);
+    }
 }
 export const ccc = new CloneCommandCloud();

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,23 +1,26 @@
 {
     "name": "@clonecommand/cloud",
-    "version": "0.0.1",
+    "version": "0.0.3",
     "type": "module",
     "description": "The official SDK for CloneCommand managed services",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "docs"
     ],
     "publishConfig": {
         "access": "public"
     },
     "scripts": {
         "build": "tsc",
-        "dev": "tsc -w"
+        "dev": "tsc -w",
+        "test:features": "npx ts-node --esm scripts/test-cloud-features.ts",
+        "test:manual": "npx tsx scripts/test-manual.ts"
     },
     "license": "MIT",
     "devDependencies": {
         "typescript": "^5.0.0"
     }
-}
+}