{"_id":"@angelengineering/downloader","_rev":"2-890e93ef90581cd0d768d6a42367680c","name":"@angelengineering/downloader","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.1":{"name":"@angelengineering/downloader","version":"1.0.1","description":"Add a plugin description","main":"index","typings":"index.d.ts","nativescript":{"platforms":{"ios":"6.0.0","android":"6.0.0"}},"repository":{"type":"git","url":"git+https://github.com/AngelEngineering/nativescript-plugins.git"},"keywords":["NativeScript","JavaScript","TypeScript","iOS","Android"],"author":{"name":"Angel Engineering","email":"info@angelengineering.com"},"bugs":{"url":"https://github.com/AngelEngineering/nativescript-plugins/issues"},"license":"Apache-2.0","homepage":"https://github.com/AngelEngineering/nativescript-plugins/blob/main/packages/downloader/README.md","bootstrapper":"@nativescript/plugin-seed","types":"./index.d.d.ts","gitHead":"c471f3235062c7b5545fcfdaa1e42cf84bffcf42","_id":"@angelengineering/downloader@1.0.1","_nodeVersion":"16.16.0","_npmVersion":"8.11.0","dist":{"integrity":"sha512-QA1jpRYEkhTb5SfqBs2GRA/fH4KyEPFTLPrwELtnI2Ftcaoq/oN5ORQMUMaUMnW0UgzM1CYCc+f7kiRELYag+w==","shasum":"ff9ea89c9bf188e27807f2a6542e9536927b01cb","tarball":"https://registry.npmjs.org/@angelengineering/downloader/-/downloader-1.0.1.tgz","fileCount":13,"unpackedSize":89648,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICjcYjv0Woc7JV7M1Ap0pvYB4MU8LEPv792TMPj1mY7HAiEAgkRKs4x3U+Loy/RWj9E24zKcBWvehnfhDzlF2bxdxEA="}]},"_npmUser":{"name":"angelengineering","email":"angel@angelengineering.com"},"directories":{},"maintainers":[{"name":"angelengineering","email":"angel@angelengineering.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/downloader_1.0.1_1684434138905_0.3406979258013676"},"_hasShrinkwrap":false},"1.1.0":{"name":"@angelengineering/downloader","version":"1.1.0","description":"File download plugin for Nativescript applications.","main":"index","typings":"index.d.ts","nativescript":{"platforms":{"ios":"6.0.0","android":"6.0.0"}},"repository":{"type":"git","url":"git+https://github.com/AngelEngineering/nativescript-plugins.git"},"keywords":["NativeScript","JavaScript","TypeScript","iOS","Android"],"author":{"name":"Angel Engineering","email":"info@angelengineering.com"},"bugs":{"url":"https://github.com/AngelEngineering/nativescript-plugins/issues"},"license":"Apache-2.0","homepage":"https://github.com/AngelEngineering/nativescript-plugins/blob/main/packages/downloader/README.md","bootstrapper":"@nativescript/plugin-seed","types":"./index.d.d.ts","gitHead":"14c2409c890c1e7bcacbac54d618a629d83a96b7","_id":"@angelengineering/downloader@1.1.0","_nodeVersion":"16.19.1","_npmVersion":"8.19.3","dist":{"integrity":"sha512-FI7/L4+V1K3u/a4MdLrBnUy3cyeKDBNIWiNtXXqVKCrJ3z8u1idLo71T6qF3NZ0GLA9u/4SXVx0ZWPLGiDLOJg==","shasum":"6733516729c5cbc574efa16e308b41550d51e692","tarball":"https://registry.npmjs.org/@angelengineering/downloader/-/downloader-1.1.0.tgz","fileCount":13,"unpackedSize":92757,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD/UIFGEufk70xu7ZfMOSp+tfPBXYvJmbTvECk1FjM/GwIgTwpnukj71WkEukSHYt3jJrZT5c7YAz8/SC6bhlVwppo="}]},"_npmUser":{"name":"angelengineering","email":"angel@angelengineering.com"},"directories":{},"maintainers":[{"name":"angelengineering","email":"angel@angelengineering.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/downloader_1.1.0_1694287972132_0.44749000431799435"},"_hasShrinkwrap":false},"1.2.0":{"name":"@angelengineering/downloader","version":"1.2.0","description":"File download plugin for Nativescript applications","main":"index","typings":"index.d.ts","nativescript":{"platforms":{"ios":"6.0.0","android":"6.0.0"}},"repository":{"type":"git","url":"git+https://github.com/AngelEngineering/nativescript-plugins.git"},"keywords":["NativeScript","JavaScript","TypeScript","iOS","Android"],"author":{"name":"Angel Engineering","email":"info@angelengineering.com"},"bugs":{"url":"https://github.com/AngelEngineering/nativescript-plugins/issues"},"license":"Apache-2.0","homepage":"https://github.com/AngelEngineering/nativescript-plugins/blob/main/packages/downloader/README.md","bootstrapper":"@nativescript/plugin-seed","types":"./index.d.d.ts","gitHead":"db26a4d6086bf55003e3b1baad1aba7ca0e30c1c","_id":"@angelengineering/downloader@1.2.0","_nodeVersion":"16.19.1","_npmVersion":"8.19.3","dist":{"integrity":"sha512-jEOo8+xvK3SCVToNTpAd1bZW0wXKVtys/UnvHiPI95yVE74cXDnOCDj6CkMwdl83GqBFbX569IWM8vjwq5ukow==","shasum":"f345b730eba99738606308644d00d41f2a4ca4cd","tarball":"https://registry.npmjs.org/@angelengineering/downloader/-/downloader-1.2.0.tgz","fileCount":13,"unpackedSize":93434,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIDPVSk6CYJzzjpTzK86iR9CQ2qGYNpLoY3sPl58wgdzhAiAHfl2zRI6R4TZaBHHxkCaYTnCLj7rTgabnFMflntx+cg=="}]},"_npmUser":{"name":"angelengineering","email":"angel@angelengineering.com"},"directories":{},"maintainers":[{"name":"angelengineering","email":"angel@angelengineering.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/downloader_1.2.0_1713643631142_0.10751658323922508"},"_hasShrinkwrap":false}},"time":{"created":"2023-05-18T18:22:18.820Z","1.0.1":"2023-05-18T18:22:19.110Z","modified":"2024-04-20T20:07:11.498Z","1.1.0":"2023-09-09T19:32:52.282Z","1.2.0":"2024-04-20T20:07:11.290Z"},"maintainers":[{"name":"angelengineering","email":"angel@angelengineering.com"}],"description":"File download plugin for Nativescript applications","homepage":"https://github.com/AngelEngineering/nativescript-plugins/blob/main/packages/downloader/README.md","keywords":["NativeScript","JavaScript","TypeScript","iOS","Android"],"repository":{"type":"git","url":"git+https://github.com/AngelEngineering/nativescript-plugins.git"},"author":{"name":"Angel Engineering","email":"info@angelengineering.com"},"bugs":{"url":"https://github.com/AngelEngineering/nativescript-plugins/issues"},"license":"Apache-2.0","readme":"# @angelengineering/downloader\n\n# NativeScript Downloader ![apple](https://cdn3.iconfinder.com/data/icons/picons-social/57/16-apple-32.png) ![android](https://cdn4.iconfinder.com/data/icons/logos-3/228/android-32.png)\n\n[![npm](https://img.shields.io/npm/v/@angelengineering/downloader?style=flat-square)](https://www.npmjs.com/package/@angelengineering/downloader)\n\nThis downloader plugin exports class _Downloader_ that has a single function `download()`.\n\nFor **iOS**, _Downloader_ uses `NSURLSession` to initiate a download from a valid URL.\n\nFor **Android**, _Downloader_ uses `DownloadManager` to initiate a download from a valid URL.\n\n\n## Contents\n\n- [NativeScript Downloader](#nativescript-downloader)\n  - [Contents](#contents)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [Supported Downloader Options](#supported-downloader-options)\n  - [Android Specifics](#android-specifics)\n  - [iOS Specifics](#ios-specifics)\n  - [Acknowledgements](#acknowledgements)\n  - [License](#license)\n\n## Installation\n\n```bash\nnpm install @angelengineering/downloader --save\n```\nOR\n```bash\nns plugin add @angelengineering/downloader\n```\n\n## Usage\n\nThe best way to understand how to use the plugin is to study the demo app included in this repo. You can see how the plugin is used in a TypeScript application page by looking at `apps/demo/src/plugin-demos/downloader.ts`.\n\n1. Import the plugin.\n\n```javascript\nimport { Downloader, DownloadOptions, MessageData } from '@angelengineering/downloader';\n```\n\n2. Create a downloader instance.\n\n```javascript\nconst dp = new Downloader();\n```\n\n3. Download a file. \n```javascript\nconst dlfile = await dp.download({ url: 'https://some.domain.com/file.txt' });\n```\nThe only required option is the URL to be downloaded. You can also pass other options as listed in [DownloadOptions](#supported-downloader-options) below before starting the download. \n\nYou can listen to events emitted by the download during operation in case you want to update a download status message/indicator or handle an error. Upon success, the plugin will return a File reference to the downloaded file located in the app cache directory for Android and the app document's directory for iOS, which can then be used directly by the dev without extra permissions for any other operations on the file.\n\n```javascript\ndp.on(Downloader.DOWNLOAD_STARTED, (payload: MessageData) => {\n  console.log('started', payload?.data?.contentLength);\n});\ndp.on(Downloader.DOWNLOAD_PROGRESS, (payload: MessageData) => {\n  console.log(' >>>>>  ', payload?.data?.progress, payload?.data?.url, payload?.data?.destinationFilename);\n});\ndp.on(Downloader.DOWNLOAD_COMPLETE, (payload: MessageData) => {\n  console.log('finished', payload?.data?.filepath);\n});\ndp.on(Downloader.DOWNLOAD_ERROR, (payload: MessageData) => {\n  console.log('ERROR!', payload?.data);\n});\ndp.download({ url: 'https://some.domain.com/file.txt' }).then((file: File) => {\n  if (!file) {\n    return console.error('Failed to download file!');\n  }\n  console.log('Finished downloading file ', file.path);\n});\n```\n\n## Supported Downloader Options\n\n```javascript\ninterface DownloadOptions {\n  url: string; //must be a valid url, usually https unless you allow http in your app\n  request?: RequestOptions; //request header strings to be passed to the https connection\n  destinationPath?: string; //must be a valid path for app to create a new file (existing directory with valid filename)\n  destinationFilename?: string; //must be a string like XXXX[].[YYYYYY] without any path preceding\n  copyPicker?: boolean; //present user with UI to choose destination directory to save a copy of download\n  copyGallery?: boolean; //iOS only, if download has a recognized image/video file name extension, save a copy to iOS Photos but make sure to request permission first! Ignored on Android\n  copyDownloads?: boolean; //Android only, adds a copy to device Downloads directory using legacy DIRECTORY_DOWNLOADS, or MediaStore for 29+. Ignored on iOS\n  notification?: boolean; //Android-only. Show system notification for download success/failure. defaults to false\n}\n```\n\n\nFor both platforms, the plugin will attempt to download the file with the filename/path supplied by the user in options, or try to find a filename to use from the url. In either case, if a file already exists at any of the output paths where a copy is being saved, it will instead append a '-#' to the filename before saving to ensure there is no conflict.\n\n### Android Specifics\n\nAndroid apps will download files by default to the app's cache directory, which is the only directory supported by DownloadManager and no special permissions are necessary. This will correspond to android.content.Context.getExternalCacheDir() if the device has an sd card, or android.content.Context.getCacheDir() if not. This file can then be used directly for other purposes in the app without any additional permissions/requests.\n\nBy default, the plugin disabled Android system notifications of downloads, which also requires you to add that permission to the Android Manifest like so:\n\n```xml\n<manifest ... >\n  <uses-permission android:name=\"android.permission.DOWNLOAD_WITHOUT_NOTIFICATION\"/>\n```\n\nYou can choose to enable these notifications which will show the user progress and completion/failure Android notifications.\n\nAndroid version of the plugin supports two destination copy approaches:\n\n1. `copyPicker` will first download the file to the default cache directory, and then present the user with a picker UI so that they select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice.\n\n2. `copyDownloads` will save a copy to the device's Download directory in case the user wants to use that file in another application from an easy to find location. API versions > 28 use MediaStore, and no extra permissions are necessary. For API versions 28 and below, you'll need to ensure you have Android Manifest permissions defined using:\n\n```xml\n<manifest ... >\n  <uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>\n  <uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>\n```\nTested and working on Android API 25-34.\n\n### iOS Specifics\n\niOS applications will download files by default to the application's documents directory, which is defined in Nativescript as `knownFolders.documents()` and does not require any extra permissions from the user. This also has the advantage of being the location where the application can make these files visible to other apps once it has been configured as a document provider.\n\n\nThe iOS version of the plugin supports two destination copy approaches: \n1. `copyPicker` will first download the file to the application documents directory, and then present the user with a picker UI so that they can select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice. Note: This is only available on iOS 14+\n\n2. `copyGallery` will attempt to save a copy to the device's Photos Gallery if the file is determined ot an image or video. This approach requires the user to have granted photo library permission so make sure to request it first in your app. \nYour app might be rejected from the Apple App Store if you do not provide a description about why you need this permission. The default message \"Requires access to photo library.\" might not be enough for the App Store reviewers. You can customize it by editing the `app/App_Resources/iOS/Info.plist` file in your app and adding something like the following:\n\n    ```xml\n    <key>NSPhotoLibraryUsageDescription</key>\n    <string>Requires access to save downloaded media to photo library.</string>\n    ```\n\n> **NOTE**: if you do use the perms plugin in a production app, make sure to read their README.md first, as using this plugin in production apps will require you to add all iOS Info.plist permission strings to avoid being rejected by automatic processing since the plugin includes code for all permission types.\n\nTested and working on iOS 12.x-17.x with caveats noted above. \n## Acknowledgements\n\nThis plugin was inspired by https://github.com/tobydeh/nativescript-download-progress\n\n## License\n\nApache License Version 2.0\n","readmeFilename":"README.md"}