{"id":28885343,"url":"https://github.com/willvin313/caprover-api-js","last_synced_at":"2026-05-08T00:41:30.239Z","repository":{"id":299435859,"uuid":"1002969990","full_name":"willvin313/caprover-api-js","owner":"willvin313","description":"An unofficial TypeScript-based, promise-driven Node.js library for interacting with the CapRover API.","archived":false,"fork":false,"pushed_at":"2025-06-16T14:57:50.000Z","size":61,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-16T15:29:21.192Z","etag":null,"topics":["api","api-rest","automation","caprover","captain","client","deploy","deployment","docker","nodejs","paas","sdk","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willvin313.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T12:25:47.000Z","updated_at":"2025-06-16T14:57:53.000Z","dependencies_parsed_at":"2025-06-16T15:40:54.827Z","dependency_job_id":null,"html_url":"https://github.com/willvin313/caprover-api-js","commit_stats":null,"previous_names":["willvin313/caprover-api-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/willvin313/caprover-api-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willvin313%2Fcaprover-api-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willvin313%2Fcaprover-api-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willvin313%2Fcaprover-api-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willvin313%2Fcaprover-api-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willvin313","download_url":"https://codeload.github.com/willvin313/caprover-api-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willvin313%2Fcaprover-api-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261029280,"owners_count":23099722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","automation","caprover","captain","client","deploy","deployment","docker","nodejs","paas","sdk","typescript"],"created_at":"2025-06-20T22:30:44.456Z","updated_at":"2026-05-08T00:41:30.233Z","avatar_url":"https://github.com/willvin313.png","language":"TypeScript","funding_links":["https://github.com/sponsors/willvin313"],"categories":[],"sub_categories":[],"readme":"# CapRover API for Node.js\n\n![GitHub top language](https://img.shields.io/github/languages/top/willvin313/caprover-api-js)\n[![npm version](https://img.shields.io/npm/v/caprover-api-js.svg)](https://www.npmjs.com/package/caprover-api-js)\n![build status](https://img.shields.io/github/actions/workflow/status/willvin313/caprover-api-js/.github%2Fworkflows%2Fnpm-publish.yml)\n[![npm downloads](https://img.shields.io/npm/dm/caprover-api-js.svg)](https://www.npmjs.com/package/caprover-api-js)\n![npm bundle size](https://img.shields.io/bundlephobia/min/caprover-api-js)\n[![license](https://img.shields.io/npm/l/caprover-api-js.svg)](./LICENSE)\n\n\u003c!-- [![npm bundle size](https://img.shields.io/bundlephobia/min/caprover-api-js)](https://www.npmjs.com/package/caprover-api-js)\n[![Node.js version](https://img.shields.io/node/v/caprover-api-js)](https://www.npmjs.com/package/caprover-api-js) --\u003e\n\nAn **UNOFFICIAL** TypeScript-based, promise-driven Node.js library for interacting with the CapRover API.\n\nThis library is a port of the excellent Python library [caprover-api](https://github.com/ak4zh/Caprover-API) by *ak4zh* and aims to provide similar functionality for the JavaScript ecosystem.\n\n## Features\n\n- Fully typed with TypeScript for a great developer experience\n- Modern async/await syntax\n- Manages the authentication token automatically\n- Provides methods for all common CapRover operations:\n  - App management (list, get, create, update, delete)\n  - Deploying from an image, Dockerfile, or one-click app repository\n  - Managing custom domains and SSL certificates\n  - Creating and downloading server backups\n- Includes a built-in retry mechanism for network-related errors\n\n## Installation\n\nYou can install the library using npm or yarn.\n\n```bash\nnpm install caprover-api-js\n```\n\n```bash\nyarn add caprover-api-js\n```\n\n## Usage\n\nAll methods are asynchronous and return a Promise. It is recommended to use the async/await syntax inside a try/catch block.\n\n### Import\n\n```typescript\nimport { CaproverAPI } from 'caprover-api-js';\n```\n\n OR\n\n```typescript\nconst { CaproverAPI } = require('caprover-api-js');\n```\n\n### Initialization\n\nUnlike the Python version, the constructor is private. You must use the static `CaproverAPI.create()` method to initialize the client. This method handles the asynchronous login process and returns a fully authenticated instance.\n\n```typescript\nasync function main() {\n    try {\n        console.log('Connecting to CapRover...');\n        const api = await CaproverAPI.create({\n            dashboardUrl: 'https://captain.your-domain.com',\n            password: 'your-super-secret-password',\n        });\n        console.log('Successfully connected!');\n\n        // You can now use the 'api' object to interact with CapRover\n    } catch (error) {\n        console.error('Failed to connect or execute command:', (error as Error).message);\n    }\n}\n\nmain();\n```\n\n### List Apps\n\nFetches all application definitions from your CapRover instance.\n\n```typescript\n// (inside an async function after initialization)\n\nconst appListResponse = await api.listApps();\nconst apps = appListResponse.data.appDefinitions;\n\nconsole.log('Available applications:');\napps.forEach(app =\u003e {\n    console.log(`- ${app.appName} (Instances: ${app.instanceCount})`);\n});\n```\n\n### Create \u0026 Deploy a New App (from Docker Image)\n\nThis example shows a full lifecycle: create an app, update its configuration, and deploy Nginx to it.\n\n```typescript\n// (inside an async function after initialization)\nconst newAppName = 'my-nginx-app';\n\ntry {\n    console.log(`Creating new app: ${newAppName}`);\n    await api.createApp(newAppName, false); // hasPersistentData = false\n\n    console.log('Updating app environment variables...');\n    await api.updateApp(newAppName, {\n        envVars: [{ key: 'NGINX_VERSION', value: 'latest' }]\n    });\n\n    console.log(`Deploying nginx image to ${newAppName}...`);\n    await api.deployApp(newAppName, { imageName: 'nginx:latest' });\n\n    console.log('Deployment successful!');\n} catch (error) {\n    console.error(`Failed to deploy ${newAppName}:`, (error as Error).message);\n}\n```\n\n### Deploy a One-Click App\n\nYou can easily deploy any app from the official one-click-apps repository.\n\n```typescript\n// (inside an async function after initialization)\nconst appName = 'my-portainer';\n\ntry {\n    console.log(`Deploying Portainer from one-click repository...`);\n    await api.deployOneClickApp(\n        'portainer', // The name of the app in the repository\n        appName,     // The name you want to give the app on your server\n        {}           // An object for any required app variables (Portainer needs none)\n    );\n    console.log('Portainer deployed successfully!');\n} catch (error) {\n    console.error(`Failed to deploy Portainer:`, (error as Error).message);\n}\n```\n\n### Delete an App\n\nThis will permanently delete an application. This action is irreversible.\n\n```typescript\n// (inside an async function after initialization)\nconst appToDelete = 'my-nginx-app';\n\ntry {\n    console.log(`Deleting app: ${appToDelete}`);\n    await api.deleteApp(appToDelete); // To also delete volumes, use: api.deleteApp(appToDelete, true)\n    console.log('App deleted successfully.');\n} catch (error) {\n    console.error(`Failed to delete ${appToDelete}:`, (error as Error).message);\n}\n```\n\n### Create a Server Backup\n\nThis creates a full server backup and downloads it to a local file.\n\n```typescript\n// (inside an async function after initialization)\n\ntry {\n    console.log('Starting server backup...');\n    // You can optionally provide a file name, e.g., api.createBackup('my-backup.tar')\n    const backupPath = await api.createBackup();\n    console.log(`Backup successfully saved to: ${backupPath}`);\n} catch (error) {\n    console.error('Failed to create backup:', (error as Error).message);\n}\n```\n\n## Key Differences from the Python Library\n\nIf you are coming from the Python version, here are the main changes to be aware of:\n\n- **Asynchronous by Default**: Every API call returns a Promise. You must use `await` to get the result.\n- **camelCase Naming**: All methods and properties use camelCase (e.g., `listApps`) instead of snake_case (e.g., `list_apps`).\n- **Static create Method**: You must initialize the library with `await CaproverAPI.create()` instead of calling a class constructor directly.\n- **Error Handling**: Errors are thrown via Promise rejections. Use a try/catch block to handle them.\n- **Response Structure**: All successful API calls return a response object with the following structure:\n\n```typescript\n{\n  status: number,\n  description: string,\n  data: { ... } // The actual payload is here\n}\n```\n\nYou will typically access the result via the `.data` property (e.g., `(await api.listApps()).data.appDefinitions`).\n\n## Contributing\n\nContributions are welcome! If you'd like to contribute, please feel free to fork the repository and submit a pull request.\n\n### Running Tests\n\nTo run the test suite locally:\n\n1. Clone the repository\n2. Install development dependencies: `npm install`\n3. Run the tests: `npm test`\n\n## Be a Sponsor\n\n- \u003chttps://github.com/sponsors/willvin313\u003e\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillvin313%2Fcaprover-api-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillvin313%2Fcaprover-api-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillvin313%2Fcaprover-api-js/lists"}