{"_id":"@astracollab/js","name":"@astracollab/js","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@astracollab/js","description":"Official AstraCollab JavaScript SDK for Node.js and browser environments","version":"0.0.1","private":false,"author":{"name":"AstraCollab"},"license":"MIT","keywords":["astracollab","storage","api","sdk","nodejs","browser"],"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"repository":{"type":"git","url":"git+https://github.com/astracollab/astracollab.git","directory":"packages/js"},"scripts":{"dev":"tsup --watch","build":"tsup","lint":"biome check --write --unsafe .","lint:ci":"biome check --unsafe .","test":"vitest","test:ci":"vitest run --coverage","type-check":"tsc --noEmit"},"types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js","import":"./dist/index.mjs"}},"engines":{"node":">=18.0.0"},"dependencies":{"axios":"^1.6.0"},"devDependencies":{"@biomejs/biome":"1.9.4","@types/node":"22.13.11","@vitest/coverage-v8":"3.0.9","tsup":"8.4.0","typescript":"5.8.2","vitest":"3.0.9"},"peerDependencies":{},"pnpm":{"overrides":{"micromatch@<4.0.8":">=4.0.8"},"onlyBuiltDependencies":["@biomejs/biome","@swc/core","esbuild","lefthook"]},"_id":"@astracollab/js@0.0.1","gitHead":"df563603fa1da1e464c64ef195a3221e27c6b873","bugs":{"url":"https://github.com/astracollab/astracollab/issues"},"homepage":"https://github.com/astracollab/astracollab#readme","_nodeVersion":"20.16.0","_npmVersion":"10.8.1","dist":{"integrity":"sha512-DbI7iCsAko4ZOOmeiYAzHpLSK9Tnexu2KUQ6T/Q0QFlSDPnbLLUJIgCSKDi3BO6liTVOjZjqs8D0pql7wpZxsQ==","shasum":"14e6be7d3057220579e3c755c4e64ac3e37566a5","tarball":"https://registry.npmjs.org/@astracollab/js/-/js-0.0.1.tgz","fileCount":9,"unpackedSize":54058,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGoC4d960a48Vy8jbVnK9dtQHIfkMBnP6UlURkCMMr2YAiBE7KDOLeR1MwZFGRi0ZpvIKaWmFKAkrAruyszY33Xkrg=="}]},"_npmUser":{"name":"dailyhelix","email":"e.wambugu192@gmail.com"},"directories":{},"maintainers":[{"name":"dailyhelix","email":"e.wambugu192@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/js_0.0.1_1756745161375_0.9096305811486471"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-01T16:46:01.273Z","0.0.1":"2025-09-01T16:46:01.567Z","modified":"2025-09-01T16:46:01.853Z"},"maintainers":[{"name":"dailyhelix","email":"e.wambugu192@gmail.com"}],"description":"Official AstraCollab JavaScript SDK for Node.js and browser environments","homepage":"https://github.com/astracollab/astracollab#readme","keywords":["astracollab","storage","api","sdk","nodejs","browser"],"repository":{"type":"git","url":"git+https://github.com/astracollab/astracollab.git","directory":"packages/js"},"author":{"name":"AstraCollab"},"bugs":{"url":"https://github.com/astracollab/astracollab/issues"},"license":"MIT","readme":"# @astracollab/js\n\nOfficial AstraCollab JavaScript SDK for Node.js and browser environments. Perfect for server-side applications, CLI tools, and browser-based file management.\n\n## Installation\n\n```bash\nnpm install @astracollab/js\n```\n\n## Quick Start\n\n### Basic Usage\n\n```javascript\nimport { AstraCollabClient } from '@astracollab/js';\n\nconst client = new AstraCollabClient({\n  apiKey: 'your-api-key-here'\n});\n\n// List files\nconst files = await client.listFiles();\nconsole.log('Files:', files);\n\n// Upload a file\nconst fileId = await client.uploadFile({\n  file: fileObject,\n  fileName: 'example.jpg',\n  folderId: 'optional-folder-id'\n});\nconsole.log('File uploaded:', fileId);\n```\n\n### Node.js Example\n\n```javascript\nimport { AstraCollabClient } from '@astracollab/js';\nimport fs from 'fs';\n\nconst client = new AstraCollabClient({\n  apiKey: process.env.ASTRACOLLAB_API_KEY\n});\n\n// Upload a file from the filesystem\nconst fileBuffer = fs.readFileSync('./example.jpg');\nconst file = new Blob([fileBuffer], { type: 'image/jpeg' });\n\nconst fileId = await client.uploadFile({\n  file,\n  fileName: 'example.jpg',\n  folderId: 'my-folder'\n});\n\nconsole.log('File uploaded with ID:', fileId);\n```\n\n## API Reference\n\n### Constructor\n\n```javascript\nconst client = new AstraCollabClient(config);\n```\n\n**Parameters:**\n- `config.apiKey` (string, required): Your AstraCollab API key\n- `config.baseURL` (string, optional): API base URL (defaults to `https://api.astracollab.app/v1`)\n- `config.timeout` (number, optional): Request timeout in milliseconds (defaults to 30000)\n\n### File Management\n\n#### List Files\n\n```javascript\nconst files = await client.listFiles(folderId);\n```\n\n**Parameters:**\n- `folderId` (string, optional): Folder ID to list files from\n\n**Returns:** Array of file objects\n\n#### Upload File\n\n```javascript\nconst fileId = await client.uploadFile(options);\n```\n\n**Parameters:**\n- `options.file` (File|Blob, required): File to upload\n- `options.fileName` (string, optional): Custom file name\n- `options.folderId` (string, optional): Folder to upload to\n- `options.orgId` (string, optional): Organization ID\n- `options.onProgress` (function, optional): Progress callback\n\n**Returns:** File ID string\n\n#### Download File\n\n```javascript\nconst fileBuffer = await client.downloadFile(fileId);\n```\n\n**Parameters:**\n- `fileId` (string, required): ID of the file to download\n\n**Returns:** ArrayBuffer containing file data\n\n#### Get File Details\n\n```javascript\nconst file = await client.getFile(fileId);\n```\n\n**Parameters:**\n- `fileId` (string, required): ID of the file\n\n**Returns:** File object with metadata\n\n#### Delete File\n\n```javascript\nawait client.deleteFile(fileId);\n```\n\n**Parameters:**\n- `fileId` (string, required): ID of the file to delete\n\n### Folder Management\n\n#### List Folders\n\n```javascript\nconst folders = await client.listFolders(parentFolderId);\n```\n\n**Parameters:**\n- `parentFolderId` (string, optional): Parent folder ID\n\n**Returns:** Array of folder objects\n\n#### Create Folder\n\n```javascript\nconst folder = await client.createFolder(options);\n```\n\n**Parameters:**\n- `options.name` (string, required): Folder name\n- `options.parentFolderId` (string, optional): Parent folder ID\n\n**Returns:** Created folder object\n\n#### Delete Folder\n\n```javascript\nawait client.deleteFolder(folderId);\n```\n\n**Parameters:**\n- `folderId` (string, required): ID of the folder to delete\n\n### API Key Management\n\n#### List API Keys\n\n```javascript\nconst keys = await client.listApiKeys();\n```\n\n**Returns:** Array of API key objects\n\n#### Create API Key\n\n```javascript\nconst key = await client.createApiKey(options);\n```\n\n**Parameters:**\n- `options.name` (string, required): API key name\n\n**Returns:** Created API key object\n\n#### Revoke API Key\n\n```javascript\nawait client.revokeApiKey(keyId);\n```\n\n**Parameters:**\n- `keyId` (string, required): API key ID to revoke\n\n### Billing\n\n#### Get Billing Info\n\n```javascript\nconst billing = await client.getBillingInfo();\n```\n\n**Returns:** Billing information object\n\n#### Get Usage History\n\n```javascript\nconst usage = await client.getUsageHistory();\n```\n\n**Returns:** Array of usage history records\n\n### Multipart Upload (Large Files)\n\n#### Start Multipart Upload\n\n```javascript\nconst multipartResponse = await client.startMultipartUpload(options);\n```\n\n**Parameters:**\n- `options.fileName` (string, required): File name\n- `options.fileType` (string, required): File MIME type\n- `options.fileSize` (number, required): File size in bytes\n- `options.totalChunks` (number, required): Number of chunks\n- `options.folderId` (string, optional): Folder ID\n\n**Returns:** Multipart upload response with presigned URLs\n\n#### Complete Multipart Upload\n\n```javascript\nawait client.completeMultipartUpload(options);\n```\n\n**Parameters:**\n- `options.uploadId` (string, required): Upload ID\n- `options.key` (string, required): File key\n- `options.parts` (array, required): Array of uploaded parts with ETags\n- `options.fileId` (string, required): File ID\n\n## Examples\n\n### Upload Multiple Files\n\n```javascript\nimport { AstraCollabClient } from '@astracollab/js';\n\nconst client = new AstraCollabClient({\n  apiKey: 'your-api-key-here'\n});\n\nconst files = [\n  { name: 'file1.jpg', data: file1Blob },\n  { name: 'file2.pdf', data: file2Blob },\n  { name: 'file3.txt', data: file3Blob }\n];\n\nfor (const file of files) {\n  try {\n    const fileId = await client.uploadFile({\n      file: file.data,\n      fileName: file.name,\n      folderId: 'my-folder'\n    });\n    console.log(`Uploaded ${file.name} with ID: ${fileId}`);\n  } catch (error) {\n    console.error(`Failed to upload ${file.name}:`, error);\n  }\n}\n```\n\n### Progress Tracking\n\n```javascript\nconst fileId = await client.uploadFile({\n  file: fileBlob,\n  fileName: 'large-file.zip',\n  onProgress: (progress) => {\n    console.log(`Upload progress: ${progress}%`);\n  }\n});\n```\n\n### Error Handling\n\n```javascript\ntry {\n  const files = await client.listFiles();\n  console.log('Files:', files);\n} catch (error) {\n  if (error.status === 401) {\n    console.error('Authentication failed. Check your API key.');\n  } else if (error.status === 429) {\n    console.error('Rate limit exceeded. Try again later.');\n  } else {\n    console.error('An error occurred:', error.message);\n  }\n}\n```\n\n### CLI Tool Example\n\n```javascript\n#!/usr/bin/env node\nimport { AstraCollabClient } from '@astracollab/js';\nimport fs from 'fs';\n\nconst client = new AstraCollabClient({\n  apiKey: process.env.ASTRACOLLAB_API_KEY\n});\n\nasync function uploadFile(filePath) {\n  try {\n    const fileBuffer = fs.readFileSync(filePath);\n    const fileName = filePath.split('/').pop();\n    const file = new Blob([fileBuffer]);\n\n    const fileId = await client.uploadFile({\n      file,\n      fileName\n    });\n\n    console.log(`✅ File uploaded successfully!`);\n    console.log(`📁 File ID: ${fileId}`);\n    console.log(`🔗 View at: https://app.astracollab.app/files/${fileId}`);\n  } catch (error) {\n    console.error('❌ Upload failed:', error.message);\n    process.exit(1);\n  }\n}\n\n// Usage: node upload.js path/to/file.jpg\nconst filePath = process.argv[2];\nif (!filePath) {\n  console.error('Please provide a file path');\n  process.exit(1);\n}\n\nuploadFile(filePath);\n```\n\n### Browser Example\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n    <title>AstraCollab File Upload</title>\n</head>\n<body>\n    <input type=\"file\" id=\"fileInput\" multiple>\n    <button onclick=\"uploadFiles()\">Upload Files</button>\n    <div id=\"progress\"></div>\n\n    <script type=\"module\">\n        import { AstraCollabClient } from 'https://unpkg.com/@astracollab/js@latest/dist/index.mjs';\n\n        const client = new AstraCollabClient({\n            apiKey: 'your-api-key-here'\n        });\n\n        window.uploadFiles = async function() {\n            const fileInput = document.getElementById('fileInput');\n            const progressDiv = document.getElementById('progress');\n            \n            const files = Array.from(fileInput.files);\n            \n            for (const file of files) {\n                try {\n                    const fileId = await client.uploadFile({\n                        file,\n                        fileName: file.name,\n                        onProgress: (progress) => {\n                            progressDiv.innerHTML = `Uploading ${file.name}: ${progress}%`;\n                        }\n                    });\n                    \n                    progressDiv.innerHTML += `<br>✅ ${file.name} uploaded (ID: ${fileId})`;\n                } catch (error) {\n                    progressDiv.innerHTML += `<br>❌ Failed to upload ${file.name}: ${error.message}`;\n                }\n            }\n        };\n    </script>\n</body>\n</html>\n```\n\n## Error Handling\n\nThe SDK throws `AstraCollabError` for various scenarios:\n\n```javascript\ntry {\n  const files = await client.listFiles();\n} catch (error) {\n  switch (error.status) {\n    case 401:\n      console.error('Invalid API key');\n      break;\n    case 403:\n      console.error('Insufficient permissions');\n      break;\n    case 404:\n      console.error('Resource not found');\n      break;\n    case 429:\n      console.error('Rate limit exceeded');\n      break;\n    default:\n      console.error('An error occurred:', error.message);\n  }\n}\n```\n\n## Configuration\n\n### Update Configuration\n\n```javascript\n// Update API key\nclient.updateConfig({ apiKey: 'new-api-key' });\n\n// Update base URL\nclient.updateConfig({ baseURL: 'https://custom-api.astracollab.app/v1' });\n\n// Update timeout\nclient.updateConfig({ timeout: 60000 });\n```\n\n### Get Current Configuration\n\n```javascript\nconst config = client.getConfig();\nconsole.log('Current config:', config);\n```\n\n## Best Practices\n\n1. **Environment Variables**: Store API keys in environment variables\n2. **Error Handling**: Always implement proper error handling\n3. **Progress Tracking**: Use progress callbacks for large file uploads\n4. **Rate Limiting**: Respect API rate limits in your application\n5. **File Validation**: Validate files before upload (size, type, etc.)\n\n## Browser Support\n\nThe SDK works in all modern browsers that support:\n- ES6 modules\n- Fetch API\n- FormData\n- Blob API\n\n## Node.js Support\n\nRequires Node.js 18+ for full functionality.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nNeed help with the JavaScript SDK?\n\n- **Documentation**: [docs.astracollab.app](https://docs.astracollab.app)\n- **Examples**: Check our [examples page](https://docs.astracollab.app/sdk/examples)\n- **API Reference**: Browse the [complete API documentation](https://docs.astracollab.app/api-reference/introduction)\n- **Support**: Email us at elias@thenextcreatives.com\n","readmeFilename":"README.md","_rev":"1-663e14ae89aaae15eac2c677c848fb51"}