# AMP Download Runtime

[![npm version](https://badge.fury.io/js/%40ampproject%2Ftoolbox-runtime-fetch.svg)](https://badge.fury.io/js/%40ampproject%2Ftoolbox-runtime-fetch)

The AMP Download Runtime tool fetches a complete, compiled AMP runtime and saves it to disk. You can use this tool to fetch [AMP Project releases](https://github.com/ampproject/amphtml/releases) from `cdn.ampproject.org` or direct it to download an AMP runtime hosted elsewhere.

Special handling is included for amp-geo. For hosting environments that [dynamically modify `amp-geo.js`](https://github.com/ampproject/amphtml/blob/main/spec/amp-cache-guidelines.md#guidelines-adding-a-new-cache-to-the-amp-ecosystem) when served, this tool restores the content to its unpatched state.

## Installation

Install via:

```sh
npm install @ampproject/toolbox-runtime-fetch --save
```

## Options

- `dest` (required `string`): Specify the destination directory where the AMP runtime should be saved. The runtime will be downloaded to an RTV-specific path under `dest`.
- `clear` (optional `boolean`): Remove all contents from the destination directory before saving the AMP runtime. Defaults to `true`.
- `rtv` (optional `string`): Specify the runtime version to download. Defaults to the latest production version available.
- `ampUrlPrefix` (optional `string`): Specify the URL where the AMP runtime is hosted. Defaults to `https://cdn.ampproject.org`.

Note: When downloading [AMP Project releases](https://github.com/ampproject/amphtml/releases), the runtime version (`rtv`) is obtained by prepending `01` (production) or `00` (canary) to the version. For example, the `rtv` for production release `2003101714470` is `012003101714470`.

## Usage

Basic usage:

```js
const downloadRuntime = require('@ampproject/toolbox-runtime-fetch');

let result;

// Download the latest AMP Project release to /tmp/amp/rtv/<rtv>,
// where <rtv> is detected automatically
result = await downloadRuntime.getRuntime({
  dest: '/tmp/amp' // Windows filesystem paths are also supported
});

// Download a specific version of the AMP runtime from Bing
result = await downloadRuntime.getRuntime({
  dest: '/tmp/amp' // Windows filesystem paths are also supported
  rtv: '011912201827130',
  ampPrefixUrl: 'https://www.bing-amp.com'
});

/**
 * The object returned from getRuntime() includes the success or failure status,
 * as well as data about the AMP runtime that was downloaded:
 * {
 *   status: {boolean} Overall AMP runtime download status
 *   error: {string} Error message on failure
 *   count: {number} Number of files in the AMP runtime
 *   url: {string} URL to AMP runtime
 *   dest: {string} Path to directory where AMP runtime was downloaded
 *   rtv: {string} Runtime version of AMP runtime
 * }
 */
```