{"_id":"p-api-os","_rev":"2-97fd939b1b61a0bbcac1880538e7c059","name":"p-api-os","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.2":{"name":"p-api-os","version":"0.0.2","author":"","license":"ISC","_id":"p-api-os@0.0.2","maintainers":[{"name":"peibaba","email":"1431011536@qq.com"}],"dist":{"shasum":"39861b8483098fc1c1574a6c0a955688eb609386","tarball":"https://registry.npmjs.org/p-api-os/-/p-api-os-0.0.2.tgz","fileCount":6,"integrity":"sha512-6QoCcA46NFwn5FHsB0cbMsDm3qnGQMN3mJiAjz0kG6OBUijYeWGjrcQaPzzpPpTi4WitIUZxskYqaZ2ZPf8e7Q==","signatures":[{"sig":"MEQCIAzGA8pK+XGJNh2xNO9JACs4soBSSdE5o20UgyzDSurUAiBVDqJkL1m/a3PojrQEc84hXRHp6u68aSFugmsoUfH1bA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49058},"main":"./dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"d0b9c7ba2d9dd988218cbd91e3ab53133dfbe1fe","scripts":{"build":"tsup"},"_npmUser":{"name":"peibaba","email":"1431011536@qq.com"},"_npmVersion":"11.9.0","description":"统一云存储 SDK，封装阿里云 OSS、火山引擎 TOS、腾讯云 COS，**只需改 `type` 即可切换厂商**。","directories":{},"_nodeVersion":"24.14.0","dependencies":{"ali-oss":"^6.23.0","cos-nodejs-sdk-v5":"^2.15.4","@volcengine/tos-sdk":"^2.9.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"8.4.0","ts-node":"10.9.2","typescript":"5.8.3","@types/node":"25.6.0","@types/lodash":"4.17.16","javascript-obfuscator":"4.1.1"},"_npmOperationalInternal":{"tmp":"tmp/p-api-os_0.0.2_1780667547199_0.8588121161928599","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"p-api-os","version":"0.0.3","main":"./dist/index.cjs","module":"./dist/index.mjs","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"}},"types":"dist/index.d.ts","scripts":{"build":"tsup"},"author":"","license":"ISC","description":"统一云存储 SDK，封装阿里云 OSS、火山引擎 TOS、腾讯云 COS，**只需改 `type` 即可切换厂商**。","devDependencies":{"@types/lodash":"4.17.16","@types/node":"25.6.0","javascript-obfuscator":"4.1.1","ts-node":"10.9.2","tsup":"8.4.0","typescript":"5.8.3"},"dependencies":{"@volcengine/tos-sdk":"^2.9.1","ali-oss":"^6.23.0","cos-nodejs-sdk-v5":"^2.15.4"},"type":"module","gitHead":"bae3c4cfb07ac277e3f5af0c4fbf5bf80976e2e3","_id":"p-api-os@0.0.3","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-FvXVS287cb4QFTWI4h3XXhZ2mhhZ5qSFkYpGyCZBdN755kymvGClzegTehWeiPQmNj0r2fnTKFAURd+3OHr2hg==","shasum":"f406c3136a2cfa0de795206655fac83c52571180","tarball":"https://registry.npmjs.org/p-api-os/-/p-api-os-0.0.3.tgz","fileCount":6,"unpackedSize":51068,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCR8csjs3QebroWDJbXkNx0xM0hPoD5THUTSocJ2G13PwIgZePab/uO7AtoV5H/knwfuwTjhOmAAUIpE3kR1jw96CM="}]},"_npmUser":{"name":"peibaba","email":"1431011536@qq.com"},"directories":{},"maintainers":[{"name":"peibaba","email":"1431011536@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/p-api-os_0.0.3_1780668617446_0.8484489040167233"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T13:52:27.142Z","modified":"2026-06-05T14:10:17.753Z","0.0.2":"2026-06-05T13:52:27.353Z","0.0.3":"2026-06-05T14:10:17.625Z"},"license":"ISC","description":"统一云存储 SDK，封装阿里云 OSS、火山引擎 TOS、腾讯云 COS，**只需改 `type` 即可切换厂商**。","maintainers":[{"name":"peibaba","email":"1431011536@qq.com"}],"readme":"# p-api-os\n\n统一云存储 SDK，封装阿里云 OSS、火山引擎 TOS、腾讯云 COS，**只需改 `type` 即可切换厂商**。\n\n## 安装\n\n```bash\nnpm install p-api-os\n```\n\n本库不内置各厂商 SDK，需按需安装：\n\n```bash\n# 阿里云 OSS\nnpm install ali-oss\n\n# 火山引擎 TOS\nnpm install @volcengine/tos-sdk\n\n# 腾讯云 COS\nnpm install cos-nodejs-sdk-v5\n```\n\n## 快速开始\n\n```ts\nimport { createStorage } from 'p-api-os'\n\nconst storage = createStorage({\n  type: 'oss',                    // 改这里切换：'oss' | 'tos' | 'cos'\n  accessKeyId: 'your-access-key',\n  accessKeySecret: 'your-secret',\n  region: 'oss-cn-hangzhou',\n  bucket: 'my-bucket',\n})\n\n// 上传\nawait storage.upload_file('images/photo.png', fileBuffer)\n\n// 下载\nconst { buffer, contentType, name } = await storage.download_file('images/photo.png')\n\n// 获取签名访问 URL\nconst url = storage.get_sign_url('images/photo.png', { expires: 3600 })\n\n// 获取前端直传令牌\nconst token = await storage.get_upload_token('uploads/file.png', { maxSize: 104857600 })\n```\n\n## 厂商配置\n\n### 阿里云 OSS\n\n```ts\nconst storage = createStorage({\n  type: 'oss',\n  accessKeyId: 'LTAI5t...',       // AccessKey ID\n  accessKeySecret: '...',         // AccessKey Secret\n  region: 'oss-cn-hangzhou',      // OSS 地域\n  bucket: 'my-bucket',\n})\n```\n\n### 火山引擎 TOS\n\n```ts\nconst storage = createStorage({\n  type: 'tos',\n  accessKeyId: 'AKLT...',         // AccessKey ID\n  accessKeySecret: '...',         // AccessKey Secret\n  region: 'cn-beijing',           // TOS 地域\n  endpoint: 'tos-cn-beijing.volces.com',\n  bucket: 'my-bucket',\n})\n```\n\n### 腾讯云 COS\n\n```ts\nconst storage = createStorage({\n  type: 'cos',\n  accessKeyId: 'AKID...',         // SecretId\n  accessKeySecret: '...',         // SecretKey\n  region: 'ap-guangzhou',         // COS 地域\n  bucket: 'mybucket-1250000000',  // 桶名（含 APPID）\n})\n```\n\n## API 参考\n\n### upload_file(key, body)\n\n上传文件，返回上传的 key。\n\n```ts\nconst uploadedKey = await storage.upload_file('path/to/file.png', buffer)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| key | `string` | 对象存储路径 |\n| body | `Buffer` | 文件内容 |\n\n返回值：`Promise<string>` — 上传的文件 key。\n\n---\n\n### download_file(key)\n\n下载文件。\n\n```ts\nconst { buffer, contentType, name } = await storage.download_file('path/to/file.png')\n```\n\n返回 `DownloadResult`：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| buffer | `Buffer` | 文件内容 |\n| contentType | `string` | 如 `image/png`，缺失时默认 `application/octet-stream` |\n| name | `string` | 从 key 中提取的文件名（含后缀） |\n\n---\n\n### copy_file(sourceKey, targetKey)\n\n复制文件，返回目标 key。\n\n```ts\nconst targetKey = await storage.copy_file('src/path.png', 'dst/path.png')\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| sourceKey | `string` | 源文件路径 |\n| targetKey | `string` | 目标文件路径 |\n\n---\n\n### delete_file(keys)\n\n删除文件，返回被删除的 key 列表。支持单个或批量。\n\n```ts\n// 单个\nconst deleted = await storage.delete_file('path/to/file.png')\n\n// 批量\nconst deleted = await storage.delete_file(['file1.png', 'file2.png'])\n```\n\n返回值：`Promise<string[]>`\n\n---\n\n### move_file(sourceKey, targetDir, options?)\n\n移动文件（先 copy 再 delete）。\n\n```ts\n// 移动（保留源文件）\nconst newPath = await storage.move_file('old/file.png', 'new-dir/')\n\n// 移动并删除源文件\nconst newPath = await storage.move_file('old/file.png', 'new-dir/', {\n  removeSource: true,\n})\n```\n\n返回新路径 `string`。\n\n---\n\n### get_sign_url(key, options?)\n\n生成带签名的临时访问 URL。\n\n```ts\nconst url = storage.get_sign_url('path/to/file.png')\nconst url = storage.get_sign_url('path/to/file.png', {\n  expires: 7200,   // 过期时间（秒），默认 3600\n  zoom: 50,        // OSS 图片缩放，仅 OSS 支持\n})\n```\n\n---\n\n### get_upload_token(key, options?)\n\n获取前端直传令牌，用于浏览器端直接上传到云存储。\n\n```ts\nconst token = await storage.get_upload_token('uploads/avatar.png', {\n  expires: 3600,           // 令牌有效期（秒），默认 3600\n  maxSize: 104857600,      // 最大文件大小（字节），OSS 默认 100MB\n})\n```\n\n返回 `UploadTokenResult`（各厂商字段略有差异）：\n\n```ts\n// OSS 返回\n{ host, signature, policy, bucket, OSSAccessKeyId, success_action_status, key }\n\n// TOS 返回\n{ host, ...res }\n\n// COS 返回\n{ host, url }   // url 为预签名 PUT URL\n```\n\n---\n\n### get_file_info(key)\n\n获取文件元信息（不下载内容）。\n\n```ts\nconst { size, contentType } = await storage.get_file_info('path/to/file.png')\n```\n\n返回 `FileInfo`：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| size | `number` | 文件大小（字节） |\n| contentType | `string` | 如 `image/png` |\n\n---\n\n### set_content_type(key, contentType)\n\n修改文件的 Content-Type，返回文件 key。\n\n```ts\nconst key = await storage.set_content_type('path/to/file.png', 'image/webp')\n```\n\n返回值：`Promise<string>`\n\n---\n\n## 类型导出\n\n除了 `createStorage` 工厂函数，也可直接导入具体实现和类型：\n\n```ts\nimport {\n  OssStorage,\n  TosStorage,\n  CosStorage,\n} from 'p-api-os'\n\nimport type {\n  ICloudStorage,\n  StorageConfig,\n  OssConfig,\n  TosConfig,\n  CosConfig,\n  DownloadResult,\n  FileInfo,\n  SignedUrlOptions,\n  UploadTokenOptions,\n  UploadTokenResult,\n  MoveOptions,\n} from 'p-api-os'\n\n// 直接实例化\nconst storage = new OssStorage({ type: 'oss', ... })\n```\n\n## 错误处理\n\n所有异步方法在参数校验失败时直接抛出 `Error`（如 `key` 为空）。调用云厂商 SDK 时，错误会透传抛出，调用方应自行 try/catch：\n\n```ts\ntry {\n  await storage.download_file('nonexistent.png')\n} catch (err) {\n  console.error('操作失败:', err)\n}\n```\n\n> 火山引擎 TOS 在 catch 时还会通过 `console.log` 输出详细错误信息，方便排查。\n","readmeFilename":"README.md"}