@clonecommand/cloud 0.0.2 → 0.0.3

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,14 @@
 {
     "name": "@clonecommand/cloud",
-    "version": "0.0.2",
+    "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"