cosmos-cloud-sdk 0.22.0-unstable04

package/README.md

@@ -0,0 +1,139 @@
+# cosmos-cloud-sdk
+
+JavaScript/TypeScript SDK for the [Cosmos Server](https://github.com/azukaar/cosmos-server) API.
+
+## Install
+
+```bash
+npm install cosmos-cloud-sdk
+```
+
+## Quick Start
+
+```js
+const { createClient } = require('cosmos-cloud-sdk');
+// or: import { createClient } from 'cosmos-cloud-sdk';
+
+const cosmos = createClient({
+  baseUrl: 'https://my-cosmos.example.com',
+  token: 'cosmos_abc123...',
+});
+
+// List containers
+const containers = await cosmos.docker.list();
+console.log(containers.data);
+
+// List users
+const users = await cosmos.users.list();
+
+// Get server status
+const status = await cosmos.getStatus();
+```
+
+## API Reference
+
+### `createClient({ baseUrl, token })`
+
+Creates a Cosmos API client.
+
+- `baseUrl` — Your Cosmos server URL (e.g. `https://my-cosmos.example.com`)
+- `token` — API token (starts with `cosmos_`)
+
+Returns an object with namespaced API methods:
+
+### Namespaces
+
+| Namespace | Description |
+|-----------|-------------|
+| `cosmos.docker` | Containers, volumes, networks, images |
+| `cosmos.users` | User management, 2FA, notifications |
+| `cosmos.config` | Server configuration, routes, DNS |
+| `cosmos.storage` | Disks, mounts, RAID, SnapRAID |
+| `cosmos.constellation` | VPN devices, tunnels |
+| `cosmos.cron` | Job management |
+| `cosmos.backups` | Backup & restore |
+| `cosmos.metrics` | Metrics & events |
+| `cosmos.market` | Marketplace |
+| `cosmos.rclone` | Cloud storage (rclone) |
+| `cosmos.apiTokens` | API token management |
+| `cosmos.auth` | Login, logout, sudo |
+
+### Top-level methods
+
+| Method | Description |
+|--------|-------------|
+| `cosmos.getStatus()` | Server status |
+| `cosmos.isOnline()` | Check connectivity |
+| `cosmos.restartServer()` | Restart server |
+| `cosmos.forceAutoUpdate()` | Force update |
+| `cosmos.terminal(cmd?)` | Host terminal (WebSocket) |
+| `cosmos.uploadImage(file, name)` | Upload image |
+| `cosmos.checkHost(host)` | DNS check |
+| `cosmos.getDNS(host)` | DNS lookup |
+
+### Examples
+
+```js
+// Docker
+const containers = await cosmos.docker.list();
+await cosmos.docker.manageContainer('my-app', 'stop');
+await cosmos.docker.manageContainer('my-app', 'start');
+const logs = await cosmos.docker.getContainerLogs('my-app', 'error', 100);
+
+// Streaming (image pull with progress)
+await cosmos.docker.pullImage('nginx:latest', (line) => {
+  console.log('Progress:', line);
+});
+
+// Users
+await cosmos.users.create({ nickname: 'bob', password: '...' });
+const user = await cosmos.users.get('bob');
+
+// Config
+const config = await cosmos.config.get();
+await cosmos.config.set(config.data);
+await cosmos.config.updateDNS({ dnsPort: '53' });
+
+// API tokens
+const tokens = await cosmos.apiTokens.list();
+const newToken = await cosmos.apiTokens.create({
+  name: 'my-automation',
+  readOnly: true,
+});
+
+// Backups
+const snapshots = await cosmos.backups.listSnapshots('daily');
+await cosmos.backups.restoreBackup('daily', { snapshotId: 'abc', target: '/data' });
+
+// WebSocket (terminal)
+const ws = cosmos.docker.attachTerminal('my-container');
+ws.onmessage = (e) => console.log(e.data);
+```
+
+## More Examples
+
+See the [examples directory](./examples/index.md) for full, runnable scripts covering dashboards, CI/CD deployments, container management, and backups.
+
+## Response Format
+
+All methods return the raw API response:
+
+```js
+{
+  status: 'OK',
+  data: { /* endpoint-specific data */ },
+  message: '...'
+}
+```
+
+On error, a `CosmosError` is thrown with `message`, `status`, and `code` properties.
+
+## Requirements
+
+- Node.js 18+ (uses built-in `fetch`)
+- Works in browsers too (bundled as ESM and CJS)
+- WebSocket support requires `ws` package in Node.js < 22
+
+## Version
+
+The SDK version is synced with the Cosmos Server version.

package/dist/index.d.mts

@@ -0,0 +1,437 @@
+interface ApiResponse<T = any> {
+    status: string;
+    data: T;
+    message?: string;
+    code?: string;
+}
+type ApiFetch = (path: string, options?: RequestInit) => Promise<Response>;
+
+declare function createApiClient(baseUrl?: string, token?: string | null): {
+    apiFetch: ApiFetch;
+    createWs: (path: string) => WebSocket;
+};
+
+interface LoginRequest {
+    username: string;
+    password: string;
+}
+interface UserMe {
+    Nickname: string;
+    Email: string;
+    Role: number;
+    MFAState: number;
+}
+
+interface User {
+    Nickname: string;
+    Email: string;
+    Role: number;
+    RegisterKey: string;
+    RegisterKeyExp: string;
+    RegisteredAt: string;
+    LastPasswordChangedAt: string;
+    CreatedAt: string;
+    LastLogin: string;
+    MFAState: number;
+    Link?: string;
+}
+
+interface Route {
+    Name: string;
+}
+type Operation = 'replace' | 'move_up' | 'move_down' | 'delete' | 'add';
+
+interface ContainerState {
+    Status: string;
+    Running: boolean;
+    Paused: boolean;
+    Restarting: boolean;
+    Dead: boolean;
+    Pid: number;
+    ExitCode: number;
+    StartedAt: string;
+    FinishedAt: string;
+    [key: string]: any;
+}
+interface Container {
+    ID: string;
+    Name: string;
+    Image: string;
+    Created: string;
+    State: ContainerState;
+    Config: {
+        Hostname: string;
+        Image: string;
+        Env: string[];
+        Cmd: string[];
+        Labels: Record<string, string>;
+        ExposedPorts: Record<string, object>;
+        [key: string]: any;
+    };
+    HostConfig: any;
+    NetworkSettings: any;
+    Mounts: any[];
+    [key: string]: any;
+}
+interface DockerNetwork {
+    ID: string;
+    Name: string;
+    Driver: string;
+    Scope: string;
+    Internal: boolean;
+    Attachable: boolean;
+    Labels: Record<string, string>;
+    [key: string]: any;
+}
+interface DockerVolume {
+    Name: string;
+    Driver: string;
+    Mountpoint: string;
+    Labels: Record<string, string>;
+    Scope: string;
+    Options: Record<string, string>;
+    [key: string]: any;
+}
+
+interface MarketApp {
+    Name: string;
+    Description: string;
+    Url: string;
+    LongDescription: string;
+    Tags: string[];
+    Repository: string;
+    Image: string;
+    Screenshots: string[];
+    Icon: string;
+    Compose: string;
+    SupportedArchitectures: string[];
+    [key: string]: any;
+}
+interface MarketResult {
+    Showcase: MarketApp[];
+    All: Record<string, MarketApp[]>;
+}
+
+interface CreateAPITokenRequest {
+    name: string;
+    description?: string;
+    readOnly?: boolean;
+    ipWhitelist?: string[];
+    restrictToConstellation?: boolean;
+}
+interface CreateAPITokenResponse {
+    token: string;
+    name: string;
+}
+interface APITokenConfig {
+    Name: string;
+    Description?: string;
+    Owner?: string;
+    TokenHash: string;
+    Permissions: number[];
+    IPWhitelist?: string[];
+    RestrictToConstellation: boolean;
+    CreatedAt: string;
+}
+
+interface ConstellationDevice {
+    Nickname: string;
+    DeviceName: string;
+    PublicKey: string;
+    IP: string;
+    IsLighthouse: boolean;
+    IsRelay: boolean;
+    Blocked: boolean;
+    Fingerprint: string;
+    PublicHostname: string;
+    Port: string;
+    [key: string]: any;
+}
+
+interface CronJob {
+    Disabled: boolean;
+    Scheduler: string;
+    Cancellable: boolean;
+    Name: string;
+    Crontab: string;
+    Running: boolean;
+    LastStarted: string;
+    LastRun: string;
+    LastRunSuccess: boolean;
+    Container: string;
+    Resource: string;
+}
+
+interface DiskInfo {
+    Path: string;
+    Name: string;
+    Size: number;
+    Used: number;
+    [key: string]: any;
+}
+interface MountRequest {
+    path: string;
+    mountPoint: string;
+    permanent: boolean;
+    netDisk?: boolean;
+    chown?: string;
+}
+interface UnmountRequest {
+    mountPoint: string;
+    permanent: boolean;
+    chown?: string;
+}
+interface MergeRequest {
+    Branches: string[];
+    MountPoint: string;
+    Permanent: boolean;
+    Chown?: string;
+    Opts?: string;
+}
+interface SnapRAIDConfig {
+    Name: string;
+    Enabled: boolean;
+    Data: Record<string, string>;
+    Parity: string[];
+    SyncCrontab: string;
+    ScrubCrontab: string;
+    CheckOnFix: boolean;
+}
+interface RaidCreateRequest {
+    name: string;
+    level: string;
+    devices: string[];
+    spares?: string[];
+    metadata?: string;
+}
+
+interface BackupConfig {
+    name: string;
+    source: string;
+    repository: string;
+    password: string;
+    crontab?: string;
+    tags?: string[];
+    exclude?: string[];
+    autoStopContainers?: boolean;
+}
+interface RestoreConfig {
+    snapshotId: string;
+    target: string;
+    include?: string[];
+}
+
+declare function createClient({ baseUrl, token }: {
+    baseUrl: string;
+    token: string;
+}): {
+    auth: {
+        login: (values: LoginRequest) => Promise<ApiResponse>;
+        logout: () => Promise<ApiResponse>;
+        me: () => Promise<UserMe>;
+        sudo: (values: {
+            password: string;
+        }) => Promise<ApiResponse>;
+    };
+    users: {
+        list: () => Promise<ApiResponse<User[]>>;
+        create: (values: Partial<User> & {
+            password?: string;
+        }) => Promise<ApiResponse>;
+        register: (values: {
+            nickname: string;
+            password: string;
+            registerKey?: string;
+        }) => Promise<ApiResponse>;
+        invite: (values: {
+            nickname: string;
+            email?: string;
+        }) => Promise<ApiResponse>;
+        edit: (nickname: string, values: Partial<User>) => Promise<ApiResponse>;
+        get: (nickname: string) => Promise<ApiResponse<User>>;
+        deleteUser: (nickname: string) => Promise<ApiResponse>;
+        new2FA: (nickname: string) => Promise<ApiResponse>;
+        check2FA: (values: string) => Promise<ApiResponse>;
+        reset2FA: (values: string) => Promise<ApiResponse>;
+        resetPassword: (values: {
+            nickname: string;
+            password?: string;
+        }) => Promise<ApiResponse>;
+        getNotifs: () => Promise<ApiResponse>;
+        readNotifs: (notifs: string[]) => Promise<ApiResponse>;
+    };
+    config: {
+        get: () => Promise<ApiResponse<any>>;
+        set: (values: any) => Promise<ApiResponse<any>>;
+        restart: () => Promise<Response>;
+        rawUpdateRoute: (routeName: string, operation: Operation, newRoute?: Route) => Promise<ApiResponse>;
+        replaceRoute: (routeName: string, newRoute: Route) => Promise<ApiResponse>;
+        moveRouteUp: (routeName: string) => Promise<ApiResponse>;
+        moveRouteDown: (routeName: string) => Promise<ApiResponse>;
+        deleteRoute: (routeName: string) => Promise<ApiResponse>;
+        addRoute: (newRoute: Route) => Promise<ApiResponse>;
+        canSendEmail: () => Promise<any>;
+        getBackup: () => Promise<ApiResponse<any>>;
+        getDashboard: () => Promise<ApiResponse<any>>;
+        updateDNS: (dnsConfig: {
+            dnsPort?: string;
+            dnsFallback?: string;
+            dnsBlockBlacklist?: boolean;
+            dnsAdditionalBlocklists?: string[];
+            customDNSEntries?: {
+                Type: string;
+                Key: string;
+                Value: string;
+            }[];
+        }) => Promise<ApiResponse<any>>;
+    };
+    docker: {
+        list: () => Promise<ApiResponse<Container[]>>;
+        get: (containerName: string) => Promise<ApiResponse<Container>>;
+        newDB: () => Promise<ApiResponse>;
+        secure: (id: string, res: string) => Promise<ApiResponse>;
+        manageContainer: (containerId: string, action: string) => Promise<ApiResponse>;
+        volumeList: () => Promise<ApiResponse<DockerVolume[]>>;
+        volumeDelete: (name: string) => Promise<ApiResponse>;
+        networkList: () => Promise<ApiResponse<DockerNetwork[]>>;
+        networkDelete: (name: string) => Promise<ApiResponse>;
+        getContainerLogs: (containerId: string, searchQuery?: string, limit?: number, lastReceivedLogs?: string, errorOnly?: string) => Promise<ApiResponse>;
+        updateContainer: (containerId: string, values: any) => Promise<ApiResponse>;
+        listContainerNetworks: (containerId: string) => Promise<ApiResponse<DockerNetwork[]>>;
+        createNetwork: (values: {
+            Name: string;
+            Driver?: string;
+            [key: string]: any;
+        }) => Promise<ApiResponse>;
+        attachNetwork: (containerId: string, networkId: string) => Promise<ApiResponse>;
+        detachNetwork: (containerId: string, networkId: string) => Promise<ApiResponse>;
+        createVolume: (values: {
+            Name: string;
+            Driver?: string;
+            [key: string]: any;
+        }) => Promise<ApiResponse>;
+        attachTerminal: (containerId: string, readonly?: boolean) => WebSocket;
+        createTerminal: (containerId: string) => WebSocket;
+        createService: (serviceData: any, onProgress: (line: string) => void) => Promise<ReadableStream>;
+        pullImage: (imageName: string, onProgress: (line: string) => void, ifMissing?: boolean) => Promise<ReadableStream>;
+        autoUpdate: (id: string, toggle: string) => Promise<ApiResponse>;
+        updateContainerImage: (containerName: string, onProgress: (line: string) => void) => Promise<ReadableStream>;
+        exportContainer: (containerId: string, values: any) => Promise<ApiResponse>;
+        migrateHost: (values: any) => Promise<ApiResponse>;
+    };
+    market: {
+        list: () => Promise<ApiResponse<MarketResult>>;
+    };
+    constellation: {
+        list: () => Promise<ApiResponse<any>>;
+        addDevice: (device: any) => Promise<ApiResponse<any>>;
+        resyncDevice: (device: any) => Promise<ApiResponse<any>>;
+        restart: () => Promise<ApiResponse<any>>;
+        getConfig: () => Promise<ApiResponse<any>>;
+        getLogs: () => Promise<ApiResponse<any>>;
+        reset: () => Promise<ApiResponse<any>>;
+        connect: (file: any) => Promise<unknown>;
+        block: (nickname: any, devicename: any, block: any) => Promise<ApiResponse<any>>;
+        ping: () => Promise<ApiResponse<any>>;
+        create: (deviceName: any, isLighthouse: any, hostname: any, ipRange: any) => Promise<ApiResponse<any>>;
+        pingDevice: (deviceId: any) => Promise<ApiResponse<any>>;
+        tunnels: () => Promise<ApiResponse<any>>;
+        editDevice: (device: any) => Promise<ApiResponse<any>>;
+        getNextIP: () => Promise<ApiResponse<any>>;
+    };
+    metrics: {
+        get: (metarr: string[]) => Promise<ApiResponse>;
+        reset: () => Promise<ApiResponse>;
+        list: () => Promise<ApiResponse<Record<string, string>>>;
+        events: (from: string, to: string, search?: string, query?: string, page?: string, logLevel?: string) => Promise<ApiResponse>;
+    };
+    storage: {
+        mounts: {
+            list: () => Promise<ApiResponse>;
+            mount: ({ path, mountPoint, permanent, netDisk, chown }: MountRequest) => Promise<ApiResponse>;
+            unmount: ({ mountPoint, permanent, chown }: UnmountRequest) => Promise<ApiResponse>;
+            merge: (args: MergeRequest) => Promise<ApiResponse>;
+        };
+        disks: {
+            list: () => Promise<ApiResponse<DiskInfo[]>>;
+            smartDef: () => Promise<ApiResponse>;
+            format({ disk, format, password }: {
+                disk: string;
+                format: string;
+                password?: string;
+            }, onProgress: (line: string) => void): Promise<ReadableStream>;
+        };
+        snapRAID: {
+            create: (args: Partial<SnapRAIDConfig>) => Promise<ApiResponse>;
+            update: (name: string, args: Partial<SnapRAIDConfig>) => Promise<ApiResponse>;
+            delete: (name: string) => Promise<ApiResponse>;
+            list: (args?: any) => Promise<ApiResponse<SnapRAIDConfig[]>>;
+            sync: (name: string) => Promise<ApiResponse>;
+            fix: (name: string) => Promise<ApiResponse>;
+            enable: (name: string, enable: boolean) => Promise<ApiResponse>;
+            scrub: (name: string) => Promise<ApiResponse>;
+        };
+        raid: {
+            list: () => Promise<ApiResponse>;
+            create: ({ name, level, devices, spares, metadata }: RaidCreateRequest) => Promise<ApiResponse>;
+            delete: (name: string) => Promise<ApiResponse>;
+            status: (name: string) => Promise<ApiResponse>;
+            addDevice: (name: string, device: string) => Promise<ApiResponse>;
+            replaceDevice: (name: string, oldDevice: string, newDevice: string) => Promise<ApiResponse>;
+            resize: (name: string) => Promise<ApiResponse>;
+        };
+        newFolder: (storage: string, path: string, folder: string) => Promise<ApiResponse>;
+        listDir: (storage: string, path: string) => Promise<ApiResponse>;
+    };
+    cron: {
+        listen: () => WebSocket;
+        list: () => Promise<ApiResponse<Record<string, Record<string, CronJob>>>>;
+        run: (scheduler: string, name: string) => Promise<ApiResponse>;
+        stop: (scheduler: string, name: string) => Promise<ApiResponse>;
+        get: (scheduler: string, name: string) => Promise<ApiResponse<CronJob>>;
+        deleteJob: (name: string) => Promise<ApiResponse>;
+        runningJobs: () => Promise<ApiResponse>;
+    };
+    rclone: {
+        create: (data: any) => Promise<any>;
+        list: () => Promise<any>;
+        listRemotes: () => Promise<any>;
+        deleteRemote: (remoteName: string) => Promise<any>;
+        update: (data: any) => Promise<any>;
+        coreStats: (remoteName: string, remotePath?: string) => Promise<any>;
+        stats: (remoteName: string) => Promise<any>;
+        pingStorage: (remoteName: string) => Promise<any>;
+        restart: () => Promise<ApiResponse>;
+    };
+    backups: {
+        listSnapshots: (name: string) => Promise<ApiResponse<any>>;
+        listFolders: (name: string, snapshot: string, path?: string) => Promise<ApiResponse<any>>;
+        restoreBackup: (name: string, config: RestoreConfig) => Promise<ApiResponse<any>>;
+        addBackup: (config: BackupConfig) => Promise<ApiResponse<any>>;
+        removeBackup: (name: string, deleteRepo?: boolean) => Promise<ApiResponse<any>>;
+        listRepo: () => Promise<ApiResponse<any>>;
+        listSnapshotsFromRepo: (name: string) => Promise<ApiResponse<any>>;
+        forgetSnapshot: (name: string, snapshot: string, deleteRepo?: boolean) => Promise<ApiResponse<any>>;
+        editBackup: (config: BackupConfig) => Promise<ApiResponse<any>>;
+        backupNow: (name: string) => Promise<ApiResponse<any>>;
+        forgetNow: (name: string) => Promise<ApiResponse<any>>;
+        subfolderRestoreSize: (name: string, snapshot: string, path: string) => Promise<ApiResponse<any>>;
+        unlockRepository: (name: string) => Promise<ApiResponse<any>>;
+        repoStats: (name: string) => Promise<ApiResponse<any>>;
+    };
+    apiTokens: {
+        list: () => Promise<ApiResponse<Record<string, APITokenConfig>>>;
+        create: (request: CreateAPITokenRequest) => Promise<ApiResponse<CreateAPITokenResponse>>;
+        remove: (name: string) => Promise<ApiResponse>;
+    };
+    getStatus: () => Promise<ApiResponse<any>>;
+    isOnline: () => Promise<any>;
+    uploadImage: (file: any, name: string) => Promise<ApiResponse<any>>;
+    restartServer: () => Promise<ApiResponse<any>>;
+    terminal: (startCmd?: string) => WebSocket;
+    forceAutoUpdate: () => Promise<ApiResponse<any>>;
+    checkHost: (host: string) => Promise<any>;
+    getDNS: (host: string) => Promise<any>;
+};
+
+export { type APITokenConfig, type ApiFetch, type ApiResponse, type BackupConfig, type ConstellationDevice, type Container, type ContainerState, type CreateAPITokenRequest, type CreateAPITokenResponse, type CronJob, type DiskInfo, type DockerNetwork, type DockerVolume, type LoginRequest, type MarketApp, type MarketResult, type MergeRequest, type MountRequest, type Operation, type RaidCreateRequest, type RestoreConfig, type Route, type SnapRAIDConfig, type UnmountRequest, type User, type UserMe, createApiClient, createClient };