{"id":27634730,"url":"https://github.com/codyadam/rclone-rc","last_synced_at":"2025-04-23T19:21:27.758Z","repository":{"id":283116691,"uuid":"948640016","full_name":"CodyAdam/rclone-rc","owner":"CodyAdam","description":"A fully typed TypeScript API client for rclone's Remote Control (RC) interface.","archived":false,"fork":false,"pushed_at":"2025-03-25T15:40:46.000Z","size":280,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T00:49:22.783Z","etag":null,"topics":["api","library","npm","openapi","rclone","rclone-client","rest","typescript","zod"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/rclone-rc","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodyAdam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-14T17:32:12.000Z","updated_at":"2025-03-25T15:40:44.000Z","dependencies_parsed_at":"2025-03-18T17:39:25.052Z","dependency_job_id":null,"html_url":"https://github.com/CodyAdam/rclone-rc","commit_stats":null,"previous_names":["codyadam/rclone-rc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodyAdam%2Frclone-rc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodyAdam%2Frclone-rc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodyAdam%2Frclone-rc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodyAdam%2Frclone-rc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodyAdam","download_url":"https://codeload.github.com/CodyAdam/rclone-rc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250497102,"owners_count":21440256,"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","library","npm","openapi","rclone","rclone-client","rest","typescript","zod"],"created_at":"2025-04-23T19:21:26.874Z","updated_at":"2025-04-23T19:21:27.745Z","avatar_url":"https://github.com/CodyAdam.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rclone-rc\n\nA fully type-safe TypeScript API client for [Rclone's Remote Control](https://rclone.org/rc/) (RC) interface, powered by [@ts-rest](https://github.com/ts-rest/ts-rest) and [Zod](https://github.com/colinhacks/zod).\n\n*Tested with **Rclone v1.70.0***\n\n## ⚠️ Work in Progress\n\nThis library is currently under active development. Check out the [current status](current-status.md) for a list of implemented commands.\n\nConsider contributing if you need a specific command:\n\n1. Check `src/api/index.ts` for current implementation\n2. Add your needed command following the same pattern\n3. Open a Pull Request\n\n## ✨ Features\n\n- **🔒 Fully Type-Safe**: End-to-end type safety for all API calls, including async operations\n- **📄 OpenAPI Support**: Generated spec for integration with any language/client\n- **🧩 Framework Agnostic**: Works with any fetch client\n- **🚀 Async Operations**: First-class support for Rclone's async operations\n- **✅ Runtime Validation**: Uses Zod to validate types at runtime\n- **💪 HTTP Status Handling**: Error responses handled through typed status codes\n\n## Installation\n\n```bash\n# Using npm\nnpm install rclone-rc\n\n# Using yarn\nyarn add rclone-rc\n\n# Using pnpm\npnpm add rclone-rc\n```\n\n## Usage\n\n### Basic Client\n\n```typescript\nimport { createClient } from 'rclone-rc';\n\nconst api = createClient({\n  baseUrl: 'http://localhost:5572',\n  username: 'your-username', // Optional if running with --rc-no-auth\n  password: 'your-password', // Optional if running with --rc-no-auth\n});\n\ntry {\n  // Get rclone version with typed response\n  const { status, body } = await api.version();\n\n  if (status === 200) {\n    console.log('Rclone version:', body.version); // typed\n  } else if (status === 500) {\n    console.log('Error:', body.error); // also typed\n  }\n\n  // List files with type-safe parameters and response\n  const files = await api.list({\n    body: { fs: 'remote:path', remote: '' }\n  });\n\n  if (files.status === 200) {\n    console.log('Files:', files.body.list);\n  }\n} catch (error) {\n  // Only network errors will throw exceptions\n  console.error('Network error:', error);\n}\n```\n\n### Error Handling\n\nThis library handles errors in two ways:\n\n1. **HTTP Status Errors**: Returned as typed responses with appropriate status codes\n2. **Network Errors**: Thrown as exceptions when server is unreachable\n\n### Async Operations\n\nFor long-running operations:\n\n```typescript\nimport { createClient, createAsyncClient } from 'rclone-rc';\n\nconst api = createClient({ baseUrl: 'http://localhost:5572' });\nconst asyncApi = createAsyncClient({ baseUrl: 'http://localhost:5572' });\n\ntry {\n  // Start async job\n  const job = await asyncApi.list({\n    body: {\n      fs: 'remote:path',\n      remote: '',\n      _async: true, // You need to pass this flag to the async client\n    }\n  });\n\n  // Access job ID and check status\n  const jobId = job.body.jobid;\n  // Check job status using the non-async client\n  const status = await api.jobStatus({ body: { jobid: jobId } });\n\n  if (status.status === 200 \u0026\u0026 status.body.finished) {\n    console.log('Job output:', status.body.output);\n  }\n} catch (error) {\n  console.error('Network error:', error);\n}\n```\n\n## Runtime Type Validation\n\nZod validates both request and response types at runtime:\n\n- **Request validation**: Parameters, body, and query are validated before sending\n- **Response validation**: Can be disabled with `validateResponse: false` in client options\n  ```typescript\n  const api = createClient({\n    baseUrl: 'http://localhost:5572',\n    validateResponse: false, // true by default\n  });\n  ```\n\n## OpenAPI Integration\n\nGenerate an OpenAPI specification for use with other languages and tools:\n\n```typescript\nimport { generateOpenApi } from '@ts-rest/open-api';\nimport { rcloneContract } from 'rclone-rc';\n\nconst openApiDocument = generateOpenApi(rcloneContract, {\n  info: { title: 'Rclone RC API', version: '1.0.0' }\n});\n```\n\nAccess the raw OpenAPI specifications at:\n- https://raw.githubusercontent.com/CodyAdam/rclone-rc/main/openapi.json\n- https://raw.githubusercontent.com/CodyAdam/rclone-rc/main/async.openapi.json\n\n## Development\n\n```bash\npnpm install     # Install dependencies\npnpm build       # Build the project\npnpm test        # Run tests\npnpm lint        # Lint code\npnpm format      # Format code\npnpm openapi     # Generate OpenAPI spec\n```\n\n## Requirements\n\n- Node.js 18+\n- TypeScript 5.0+\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodyadam%2Frclone-rc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodyadam%2Frclone-rc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodyadam%2Frclone-rc/lists"}