{"_id":"@ashkiani/s3-file-utils","_rev":"2-796522b81026f3b38ff01e8a961445f5","name":"@ashkiani/s3-file-utils","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@ashkiani/s3-file-utils","version":"1.0.0","keywords":["aws","s3","file-listing","signed-url","presigned-url","s3-folder","aws-sdk","nodejs","s3-utils","file-browser"],"author":{"name":"Siavash Ashkiani"},"license":"MIT","_id":"@ashkiani/s3-file-utils@1.0.0","maintainers":[{"name":"ashkiani","email":"ashkiani@yahoo.com"}],"homepage":"https://github.com/ashkiani/s3-file-utils#readme","bugs":{"url":"https://github.com/ashkiani/s3-file-utils/issues"},"dist":{"shasum":"6e664778b4a057439da5ee0834d9173ac2f75952","tarball":"https://registry.npmjs.org/@ashkiani/s3-file-utils/-/s3-file-utils-1.0.0.tgz","fileCount":5,"integrity":"sha512-CnhUb4hZ6c1frT6lcF1Y9O7lStDZfVclcjn5VqnePODkqPK6r00MZHAkFnP25IEyzkgdVKhxaiQrHfNmmHC12g==","signatures":[{"sig":"MEUCIH+zsUso/8ScU5/OWga1hyI6hSUnvOnSxbM515+hiBvdAiEAhqnuZNNOrGpu8MNQxFQfPIZ9Qpwb4t368/vx4gOWBLQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6354},"main":"index.js","gitHead":"0330db5f7501bd4ba23acd7ae60eae7c5c9b750a","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"ashkiani","email":"ashkiani@yahoo.com"},"repository":{"url":"git+https://github.com/ashkiani/s3-file-utils.git","type":"git"},"_npmVersion":"9.2.0","description":"List files in an S3 folder and generate signed URLs using AWS SDK v3.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"dotenv":"^16.5.0","@aws-sdk/client-s3":"^3.808.0","@aws-sdk/s3-request-presigner":"^3.808.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/s3-file-utils_1.0.0_1747179186532_0.002055314524104901","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@ashkiani/s3-file-utils","version":"1.1.0","description":"List files in an S3 folder and generate signed URLs using AWS SDK v3.","main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"git+https://github.com/ashkiani/s3-file-utils.git"},"keywords":["aws","s3","file-listing","signed-url","presigned-url","s3-folder","aws-sdk","nodejs","s3-utils","file-browser"],"author":{"name":"Siavash Ashkiani"},"license":"MIT","bugs":{"url":"https://github.com/ashkiani/s3-file-utils/issues"},"homepage":"https://github.com/ashkiani/s3-file-utils#readme","dependencies":{"@aws-sdk/client-s3":"^3.808.0","@aws-sdk/s3-request-presigner":"^3.808.0","dotenv":"^16.5.0"},"gitHead":"43b0519a37d4edc593dc994c40357a89c10eb802","_id":"@ashkiani/s3-file-utils@1.1.0","_nodeVersion":"20.19.4","_npmVersion":"9.2.0","dist":{"integrity":"sha512-OjsvI7xeD3AWUyXagHu2wHNBQljlxbOq2TLk+/AAztg9AckwMrWJ4Wrw8mqYvRHNzIvqOlp5eTlub+Og++qRgQ==","shasum":"a01fd2ee7885bf13b7b03154d2b165e0723fc4d6","tarball":"https://registry.npmjs.org/@ashkiani/s3-file-utils/-/s3-file-utils-1.1.0.tgz","fileCount":5,"unpackedSize":8232,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDvoBQ5JEGSvBBJoVTKyqFpxGqBTu0ZDADULIYmC+dk0AIhAKZHqlQ0ezs4DMF58jBLrapmsSwORi5oJLWXVydBFh6W"}]},"_npmUser":{"name":"ashkiani","email":"ashkiani@yahoo.com"},"directories":{},"maintainers":[{"name":"ashkiani","email":"ashkiani@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/s3-file-utils_1.1.0_1759867024065_0.7095283990311809"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-13T23:33:06.431Z","modified":"2025-10-07T19:57:04.444Z","1.0.0":"2025-05-13T23:33:06.706Z","1.1.0":"2025-10-07T19:57:04.250Z"},"bugs":{"url":"https://github.com/ashkiani/s3-file-utils/issues"},"author":{"name":"Siavash Ashkiani"},"license":"MIT","homepage":"https://github.com/ashkiani/s3-file-utils#readme","keywords":["aws","s3","file-listing","signed-url","presigned-url","s3-folder","aws-sdk","nodejs","s3-utils","file-browser"],"repository":{"type":"git","url":"git+https://github.com/ashkiani/s3-file-utils.git"},"description":"List files in an S3 folder and generate signed URLs using AWS SDK v3.","maintainers":[{"name":"ashkiani","email":"ashkiani@yahoo.com"}],"readme":"# @ashkiani/s3-file-utils\n\nAWS S3 utility functions for Node.js — list files in a folder, generate pre-signed download URLs, and **read objects as text/JSON** (BOM-tolerant) using AWS SDK v3.\n\nThis module helps backend applications interact with Amazon S3: listing folder contents, securely linking to files via expiring signed URLs, and fetching JSON files directly from S3.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @ashkiani/s3-file-utils\n```\n\n---\n\n## 🛠 Usage\n\n1. Set your environment variables:\n\n```env\nAWS_REGION=us-east-1\nURL_EXPIRES_IN=3600\n```\n\n2. Use the module in your code:\n\n```js\nconst s3Utils = require('@ashkiani/s3-file-utils');\n\nconst bucket = \"my-bucket\";\nconst folder = \"documents/\";\n\nconst files = await s3Utils.listFilesInFolder(bucket, folder);\nconsole.log(\"Files:\", files);\n\nconst signedUrl = await s3Utils.genSignedUrl(bucket, `${folder}${files[0]}`);\nconsole.log(\"Download URL:\", signedUrl);\n\nconst text = await s3Utils.getObjectText(bucket, `${folder}readme.txt`);\nconsole.log(\"Text:\", text);\n\nconst json = await s3Utils.getJson(bucket, `${folder}config.json`);\nconsole.log(\"JSON:\", json);\n```\n\n---\n\n## 📘 API\n\n### `listFilesInFolder(bucketName, folderPath)`\n\nLists all files (not folders) in a specific S3 folder.\n\n* `bucketName` — Your S3 bucket name.\n* `folderPath` — Must end with `/`, e.g., `\"reports/2024/\"`.\n* Returns: `Promise<string[]>` sorted alphabetically.\n\n### `genSignedUrl(bucket, fileKey)`\n\nGenerates a signed URL for a specific file in the bucket.\n\n* `bucket` — S3 bucket name.\n* `fileKey` — Full key including folder path.\n* Returns: `Promise<string>` — A temporary download URL.\n\n### `getObjectText(bucket, key)`\n\nRetrieves an object from S3 and returns its contents as UTF-8 text.\n\n* `bucket` — S3 bucket name.  \n* `key` — Full key (path) to the object.  \n* Returns: `Promise<string>`\n\n### `getJson(bucket, key)`\n\nRetrieves an object from S3, reads it as UTF-8 text, removes any UTF-8 BOM if present, and parses it as JSON.\n\n* `bucket` — S3 bucket name.  \n* `key` — Full key (path) to the JSON file.  \n* Returns: `Promise<any>`\n\n---\n\n## 💡 Notes\n\n* Uses AWS SDK v3 (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`).\n* Pre-signed URL expiration is controlled via `URL_EXPIRES_IN` environment variable (in seconds).\n* Folder names must end with a `/` to properly scope the listing.\n* Files are filtered to exclude subfolders and folder markers.\n* getObjectText returns the object as UTF-8 without modifying content (no BOM stripping).\n* getJson first removes a leading UTF-8 BOM (if present) and then parses; this avoids JSON.parse errors from Windows/.NET-saved files.\n\n---\n\n🧾 Changelog\n\n1.1.0\nAdded getObjectText and getJson (BOM-tolerant S3 reads).\n\n1.0.0\nInitial release with listFilesInFolder and genSignedUrl.\n\n---\n\n## 📄 License\n\nMIT © Siavash Ashkiani","readmeFilename":"README.md"}