aliendrive-sdk 1.0.0

package/README.md

@@ -0,0 +1,132 @@
+# aliendrive-sdk
+
+Official Node.js SDK for the [AlienDrive](https://drive.moltenalien.com) API. S3-like interface for cloud file storage.
+
+## Install
+
+```bash
+npm install aliendrive-sdk
+```
+
+## Quick Start
+
+```javascript
+const { AlienDrive } = require('aliendrive-sdk');
+
+const drive = new AlienDrive({
+    endpoint: 'https://drive.moltenalien.com',
+    apiKey: 'mcd_your_api_key_here',
+});
+
+// Upload
+await drive.putObject({
+    Key: 'photos/vacation.jpg',
+    Body: Buffer.from('...'),
+    ContentType: 'image/jpeg',
+});
+
+// Download
+const file = await drive.getObject({ Key: 'photos/vacation.jpg' });
+console.log(file.Body); // Buffer
+
+// List
+const list = await drive.listObjects({ Prefix: 'photos/' });
+console.log(list.Contents); // [{ Key, Size, ContentType, ... }]
+
+// Delete
+await drive.deleteObject({ Key: 'photos/vacation.jpg' });
+```
+
+## API
+
+### `new AlienDrive({ endpoint, apiKey })`
+
+Create a client instance.
+
+| Param | Type | Description |
+|---|---|---|
+| `endpoint` | `string` | API URL, e.g. `https://drive.moltenalien.com` |
+| `apiKey` | `string` | Your API key (starts with `mcd_`) |
+
+### `putObject({ Key, Body, ContentType? })`
+
+Upload a file. Folders in the path are auto-created.
+
+```javascript
+await drive.putObject({
+    Key: 'reports/2026/q1.pdf',
+    Body: fs.readFileSync('q1.pdf'),
+    ContentType: 'application/pdf',
+});
+```
+
+### `getObject({ Key })`
+
+Download a file. Returns `{ Body, ContentType, ContentLength, ETag, LastModified }`.
+
+```javascript
+const { Body } = await drive.getObject({ Key: 'reports/2026/q1.pdf' });
+fs.writeFileSync('q1.pdf', Body);
+```
+
+### `headObject({ Key })`
+
+Get file metadata without downloading.
+
+```javascript
+const meta = await drive.headObject({ Key: 'reports/2026/q1.pdf' });
+console.log(meta.ContentLength); // file size in bytes
+```
+
+### `listObjects({ Prefix?, MaxKeys? })`
+
+List files and folders. Returns S3-compatible response with `Contents` and `CommonPrefixes`.
+
+```javascript
+const list = await drive.listObjects({ Prefix: 'reports/' });
+list.Contents.forEach(f => console.log(f.Key, f.Size));
+list.CommonPrefixes.forEach(f => console.log(f.Prefix)); // subfolders
+```
+
+### `deleteObject({ Key })`
+
+Delete a file. Returns `204` even if key doesn't exist (S3 behavior).
+
+### `uploadFile(localPath, remotePath?)`
+
+Convenience: upload a local file with auto-detected MIME type.
+
+```javascript
+await drive.uploadFile('./photo.jpg', 'photos/photo.jpg');
+```
+
+### `downloadFile(remotePath, localPath)`
+
+Convenience: download to a local file.
+
+```javascript
+await drive.downloadFile('photos/photo.jpg', './photo.jpg');
+```
+
+## TypeScript
+
+Full type definitions included. Works with both `require()` and TypeScript imports.
+
+```typescript
+import { AlienDrive } from 'aliendrive-sdk';
+```
+
+## Get an API Key
+
+1. Sign up at [drive.moltenalien.com](https://drive.moltenalien.com)
+2. Go to Settings
+3. Create an API key
+4. Copy it (shown only once)
+
+## API Docs
+
+Full API documentation at [drive.moltenalien.com/api-docs](https://drive.moltenalien.com/api-docs)
+
+## License
+
+MIT

package/aliendrive.d.ts

@@ -0,0 +1,109 @@
+export interface AlienDriveConfig {
+    /** API endpoint, e.g. "https://drive.moltenalien.com" */
+    endpoint: string;
+    /** API key, e.g. "mcd_..." */
+    apiKey: string;
+}
+
+export interface PutObjectParams {
+    /** Object key/path, e.g. "Documents/report.pdf" */
+    Key: string;
+    /** File content */
+    Body: Buffer | string | ArrayBuffer | ReadableStream;
+    /** MIME type (default: "application/octet-stream") */
+    ContentType?: string;
+}
+
+export interface PutObjectResult {
+    ETag: string;
+    Key: string;
+}
+
+export interface GetObjectParams {
+    /** Object key/path */
+    Key: string;
+}
+
+export interface GetObjectResult {
+    Body: Buffer;
+    ContentType: string;
+    ContentLength: number;
+    ETag: string;
+    LastModified: string;
+}
+
+export interface HeadObjectParams {
+    Key: string;
+}
+
+export interface HeadObjectResult {
+    ContentType: string | null;
+    ContentLength: number;
+    ETag: string | null;
+    LastModified: string | null;
+}
+
+export interface ListObjectsParams {
+    /** Filter by prefix, e.g. "Documents/" */
+    Prefix?: string;
+    /** Max results (default 1000) */
+    MaxKeys?: number;
+}
+
+export interface ListObjectsResult {
+    Name: string;
+    Prefix: string;
+    MaxKeys: number;
+    KeyCount: number;
+    Contents: Array<{
+        Key: string;
+        Size: number;
+        ContentType: string;
+        LastModified: string;
+        ETag: string;
+    }>;
+    CommonPrefixes: Array<{
+        Prefix: string;
+    }>;
+    IsTruncated: boolean;
+}
+
+export interface DeleteObjectParams {
+    Key: string;
+}
+
+export interface DeleteObjectResult {
+    DeleteMarker: boolean;
+}
+
+export interface UploadFileResult extends PutObjectResult {}
+
+export interface DownloadFileResult {
+    size: number;
+    path: string;
+}
+
+export declare class AlienDrive {
+    constructor(config: AlienDriveConfig);
+
+    /** Upload a file (like S3 PutObject) */
+    putObject(params: PutObjectParams): Promise<PutObjectResult>;
+
+    /** Download a file (like S3 GetObject) */
+    getObject(params: GetObjectParams): Promise<GetObjectResult>;
+
+    /** Get file metadata (like S3 HeadObject) */
+    headObject(params: HeadObjectParams): Promise<HeadObjectResult>;
+
+    /** List objects at a prefix (like S3 ListObjectsV2) */
+    listObjects(params?: ListObjectsParams): Promise<ListObjectsResult>;
+
+    /** Delete a file (like S3 DeleteObject) */
+    deleteObject(params: DeleteObjectParams): Promise<DeleteObjectResult>;
+
+    /** Upload a local file by path */
+    uploadFile(localPath: string, remotePath?: string): Promise<UploadFileResult>;
+
+    /** Download to a local file */
+    downloadFile(remotePath: string, localPath: string): Promise<DownloadFileResult>;
+}

package/aliendrive.js

@@ -0,0 +1,158 @@
+/**
+ * AlienDrive SDK — S3-like client for the AlienDrive API
+ *
+ * Usage:
+ *   const drive = new AlienDrive({ endpoint: 'https://drive.moltenalien.com', apiKey: 'mcd_...' });
+ *   await drive.putObject({ Key: 'docs/file.txt', Body: Buffer.from('hello') });
+ *   const data = await drive.getObject({ Key: 'docs/file.txt' });
+ *   const list = await drive.listObjects({ Prefix: 'docs/' });
+ *   await drive.deleteObject({ Key: 'docs/file.txt' });
+ */
+
+class AlienDrive {
+    constructor({ endpoint, apiKey }) {
+        this.endpoint = endpoint.replace(/\/$/, '');
+        this.apiKey = apiKey;
+    }
+
+    async _fetch(path, opts = {}) {
+        const url = `${this.endpoint}${path}`;
+        const headers = { 'Authorization': `Bearer ${this.apiKey}`, ...opts.headers };
+        const res = await fetch(url, { ...opts, headers });
+        return res;
+    }
+
+    /**
+     * Upload a file — like S3 PutObject
+     * @param {Object} params
+     * @param {string} params.Key - e.g. "Documents/report.pdf"
+     * @param {Buffer|string|ReadableStream} params.Body - file content
+     * @param {string} [params.ContentType] - MIME type
+     */
+    async putObject({ Key, Body, ContentType = 'application/octet-stream' }) {
+        const res = await this._fetch(`/api/v1/objects?key=${encodeURIComponent(Key)}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': ContentType },
+            body: Body,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(`PutObject failed (${res.status}): ${err.error}`);
+        }
+        return res.json();
+    }
+
+    /**
+     * Download a file — like S3 GetObject
+     * @param {Object} params
+     * @param {string} params.Key - e.g. "Documents/report.pdf"
+     * @returns {{ Body: Buffer, ContentType: string, ContentLength: number, ETag: string, LastModified: string }}
+     */
+    async getObject({ Key }) {
+        const res = await this._fetch(`/api/v1/objects?key=${encodeURIComponent(Key)}`, {
+            redirect: 'follow',
+        });
+        if (!res.ok) {
+            throw new Error(`GetObject failed (${res.status}): NoSuchKey`);
+        }
+        const contentType = res.headers.get('content-type') || 'application/octet-stream';
+        const contentLength = parseInt(res.headers.get('content-length') || '0');
+        const etag = res.headers.get('etag') || '';
+        const lastModified = res.headers.get('last-modified') || '';
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return {
+            Body: buffer,
+            ContentType: contentType,
+            ContentLength: contentLength,
+            ETag: etag,
+            LastModified: lastModified,
+        };
+    }
+
+    /**
+     * Get file metadata — like S3 HeadObject
+     * @param {Object} params
+     * @param {string} params.Key
+     */
+    async headObject({ Key }) {
+        const res = await this._fetch(`/api/v1/objects?key=${encodeURIComponent(Key)}`, {
+            method: 'HEAD',
+        });
+        if (!res.ok) {
+            throw new Error(`HeadObject failed (${res.status}): NoSuchKey`);
+        }
+        return {
+            ContentType: res.headers.get('content-type'),
+            ContentLength: parseInt(res.headers.get('content-length') || '0'),
+            ETag: res.headers.get('etag'),
+            LastModified: res.headers.get('last-modified'),
+        };
+    }
+
+    /**
+     * List objects — like S3 ListObjectsV2
+     * @param {Object} [params]
+     * @param {string} [params.Prefix] - e.g. "Documents/"
+     * @param {number} [params.MaxKeys] - max results (default 1000)
+     */
+    async listObjects({ Prefix = '', MaxKeys = 1000 } = {}) {
+        const params = new URLSearchParams();
+        if (Prefix) params.set('prefix', Prefix);
+        if (MaxKeys) params.set('maxKeys', String(MaxKeys));
+        const qs = params.toString();
+
+        const res = await this._fetch(`/api/v1/objects${qs ? '?' + qs : ''}`);
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(`ListObjects failed (${res.status}): ${err.error}`);
+        }
+        return res.json();
+    }
+
+    /**
+     * Delete a file — like S3 DeleteObject
+     * @param {Object} params
+     * @param {string} params.Key
+     */
+    async deleteObject({ Key }) {
+        const res = await this._fetch(`/api/v1/objects?key=${encodeURIComponent(Key)}`, {
+            method: 'DELETE',
+        });
+        if (res.status !== 204 && !res.ok) {
+            throw new Error(`DeleteObject failed (${res.status})`);
+        }
+        return { DeleteMarker: true };
+    }
+
+    // ── Convenience methods ──
+
+    /**
+     * Upload a local file
+     */
+    async uploadFile(localPath, remotePath) {
+        const fs = require('fs');
+        const path = require('path');
+        const mime = {
+            '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif',
+            '.pdf': 'application/pdf', '.txt': 'text/plain', '.html': 'text/html',
+            '.json': 'application/json', '.xml': 'application/xml',
+            '.zip': 'application/zip', '.mp4': 'video/mp4', '.mp3': 'audio/mpeg',
+        };
+        const ext = path.extname(localPath).toLowerCase();
+        const body = fs.readFileSync(localPath);
+        const key = remotePath || path.basename(localPath);
+        return this.putObject({ Key: key, Body: body, ContentType: mime[ext] || 'application/octet-stream' });
+    }
+
+    /**
+     * Download to a local file
+     */
+    async downloadFile(remotePath, localPath) {
+        const fs = require('fs');
+        const data = await this.getObject({ Key: remotePath });
+        fs.writeFileSync(localPath, data.Body);
+        return { size: data.ContentLength, path: localPath };
+    }
+}
+
+module.exports = { AlienDrive };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "aliendrive-sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for the AlienDrive API — S3-like cloud storage",
+  "main": "aliendrive.js",
+  "types": "aliendrive.d.ts",
+  "files": [
+    "aliendrive.js",
+    "aliendrive.d.ts"
+  ],
+  "keywords": [
+    "aliendrive",
+    "cloud-storage",
+    "s3",
+    "file-storage",
+    "object-storage",
+    "drive",
+    "api",
+    "sdk"
+  ],
+  "author": "MoltenAlien",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moltenalien/aliendrive-sdk"
+  },
+  "homepage": "https://drive.moltenalien.com/api-docs",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}