@clonecommand/cloud 0.0.1

package/README.md

@@ -0,0 +1,65 @@
+# @clonecommand/cloud
+
+The official SDK for CloneCommand managed services. This library simplifies integration with ephemeral preview environments and provides access to CloneCommand Cloud services.
+
+## Installation
+
+```bash
+npm install @clonecommand/cloud
+```
+
+## 🔐 Login Service: OAuth Proxy
+
+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.
+
+The **CloneCommand Login Service** acts as a trusted intermediary, providing a single, stable redirect URL for all your environments.
+
+### 1. Initialize the SDK
+
+For client-side applications (e.g., Vite, Nuxt), initialize the SDK with your Project ID. 
+
+```typescript
+import { ccc } from '@clonecommand/cloud';
+
+ccc.init({
+  projectId: 'your-project-id' // Found in your CloneCommand Dashboard
+});
+```
+
+> [!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()`.
+
+```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.*
+
+### 🤖 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)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export interface CCCConfig {
+    projectId?: string;
+    baseUrl?: string;
+}
+export declare class CloneCommandCloud {
+    private config;
+    init(config: CCCConfig): void;
+    private get projectId();
+    private get baseUrl();
+    private get serviceToken();
+    /**
+     * Internal helper to make authenticated requests to the CloneCommand API.
+     * This is used by server-side methods (e.g., image uploads).
+     */
+    private request;
+    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
+         */
+        proxy: (originalUrl: string) => string;
+    };
+}
+export declare const ccc: CloneCommandCloud;

package/dist/index.js

@@ -0,0 +1,60 @@
+export class CloneCommandCloud {
+    config = {};
+    init(config) {
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+    }
+    get projectId() {
+        return this.config.projectId;
+    }
+    get baseUrl() {
+        return this.config.baseUrl || 'https://graph.clonecommand.com';
+    }
+    get serviceToken() {
+        return typeof process !== 'undefined' ? process.env.CC_TOKEN : undefined;
+    }
+    /**
+     * Internal helper to make authenticated requests to the CloneCommand API.
+     * This is used by server-side methods (e.g., image uploads).
+     */
+    async request(path, options = {}) {
+        const token = this.serviceToken;
+        const headers = new Headers(options.headers);
+        if (token) {
+            headers.set('Authorization', `Bearer ${token}`);
+        }
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`CloneCommand API Error: ${error}`);
+        }
+        return response.json();
+    }
+    get login() {
+        return {
+            /**
+             * 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
+             */
+            proxy: (originalUrl) => {
+                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.");
+                }
+                const encodedUrl = encodeURIComponent(originalUrl);
+                return `${this.baseUrl}/login/proxy/start?projectId=${pid}&url=${encodedUrl}`;
+            }
+        };
+    }
+}
+export const ccc = new CloneCommandCloud();

package/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@clonecommand/cloud",
+    "version": "0.0.1",
+    "type": "module",
+    "description": "The official SDK for CloneCommand managed services",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc -w"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.0.0"
+    }
+}