# phastly
functional fastly api with promises. A simple, minimal node.js fastly api wrapper. Sends the requests out and gives you back promises which resolve to the parsed object.

This library seeks to be developer friendly by providing promises and mapping each endpoint to a function for you, hopefully resulting in less time reading documentation: less fat-fingering of URLs, less forgetting http verbs.

For information on request parameters and response formats, please read: <https://docs.fastly.com/api/>

Currently in development and does not immediately seek to cover all endpoints but open to it. Pull requests and feature requests welcome.

Tested with node4+

## Style - Why do most functions end in "P"?

This denotes a promise is being returned. It is an opinionated style that I've adopted because unless you are using an IDE with really good type hinting you don't always know when a promise is being returned or not. And unlike other javascript types promises cannot and should not be silently coerced into their resolved value. Functions returning promises are always treated differently so this naming convention makes this behavior obvious.

## Usage

If set, phastly will automatically use the environment variable `process.env.FASTLY_API_KEY`. Or set/change the key with function `setApiKey()`

This is a great project for populating env variables from a file: <https://www.npmjs.com/package/dotenv>

### Promises

```js
import * as fastly from 'phastly'
// or
// const fastly = require('phastly')

function setupP(name) {
  return fastly.createServiceP(name)
  .then((service) => {
    // use service here
  })
}
```

### Async/Await
```js
import * as fastly from 'phastly'

async function setupP(name) {
  let service = await fastly.createServiceP(name)

  const backendData = {
    name: service.name,
    address: `foobarbaz.storage.googleapis.com`,
    hostname: `foobarbaz.storage.googleapis.com`,
    port: 443,
  }

  const p1 = fastly.createBackendP(service.id, 1, backendData)

  const domainData = {
    name: `foobarbaz.global.ssl.fastly.net`,
    comment: 'generated by my app'
  }

  const p2 = fastly.createDomainP(service.id, 1, domainData)

  const settingsData = {
    'general.default_host': `foobarbaz.storage.googleapis.com`
  }

  const p3 = fastly.updateSettingsP(service.id, 1, settingsData)

  await Promise.all([p1, p2, p3])

  return fastly.activateServiceVersionP(service.id, 1)
}
```

## API Reference
phastly module.


* [phastly](#module_phastly)
    * [.sendP(options)](#module_phastly.sendP) ⇒ <code>Promise</code>
    * [.purgeP(serviceId, key, [soft])](#module_phastly.purgeP) ⇒ <code>Promise</code>
    * [.purgeUrlP(url, [soft])](#module_phastly.purgeUrlP) ⇒ <code>Promise</code>
    * [.purgeAllP(serviceId)](#module_phastly.purgeAllP) ⇒ <code>Promise</code>
    * [.createBackendP(serviceId, version, data)](#module_phastly.createBackendP) ⇒ <code>Promise</code>
    * [.deleteBackendP(serviceId, version, name)](#module_phastly.deleteBackendP) ⇒ <code>Promise</code>
    * [.createServiceP(name)](#module_phastly.createServiceP) ⇒ <code>Promise</code>
    * [.updateServiceP(params)](#module_phastly.updateServiceP) ⇒ <code>Promise</code>
    * [.createServiceVersionP(serviceId)](#module_phastly.createServiceVersionP) ⇒ <code>Promise</code>
    * [.updateServiceVersionP(serviceId, version, data)](#module_phastly.updateServiceVersionP) ⇒ <code>Promise</code>
    * [.validateServiceVersionP(serviceId, version)](#module_phastly.validateServiceVersionP) ⇒ <code>Promise</code>
    * [.activateServiceVersionP(serviceId, version)](#module_phastly.activateServiceVersionP) ⇒ <code>Promise</code>
    * [.deactivateServiceVersionP(serviceId, version)](#module_phastly.deactivateServiceVersionP) ⇒ <code>Promise</code>
    * [.cloneServiceVersion(serviceId, version)](#module_phastly.cloneServiceVersion) ⇒ <code>Promise</code>
    * [.lockServiceVersion(serviceId, version)](#module_phastly.lockServiceVersion) ⇒ <code>Promise</code>
    * [.deleteServiceP(serviceId)](#module_phastly.deleteServiceP) ⇒ <code>Promise</code>
    * [.renameServiceP(serviceId, newName)](#module_phastly.renameServiceP) ⇒ <code>Promise</code>
    * [.filterActiveVersion(versions)](#module_phastly.filterActiveVersion) ⇒ <code>Object</code>
    * [.ListServicesP()](#module_phastly.ListServicesP) ⇒ <code>Promise</code>
    * [.getServiceP(serviceId)](#module_phastly.getServiceP) ⇒ <code>Promise</code>
    * [.getServiceByNameP(name)](#module_phastly.getServiceByNameP) ⇒ <code>Promise</code>
    * [.getServiceDetailsP(serviceId)](#module_phastly.getServiceDetailsP) ⇒ <code>Promise</code>
    * [.getServiceDomainsP(service)](#module_phastly.getServiceDomainsP) ⇒ <code>Promise</code>
    * [.createDomainP(serviceId, version, data)](#module_phastly.createDomainP) ⇒ <code>Promise</code>
    * [.checkAllDomainsP(serviceId, version)](#module_phastly.checkAllDomainsP) ⇒ <code>Promise</code>
    * [.createRequestSettingP(serviceId, version, settings)](#module_phastly.createRequestSettingP) ⇒ <code>Promise</code>
    * [.updateSettingsP(serviceId, version, settings)](#module_phastly.updateSettingsP) ⇒ <code>Promise</code>
    * [.setApiKey(key)](#module_phastly.setApiKey)

<a name="module_phastly.sendP"></a>

### phastly.sendP(options) ⇒ <code>Promise</code>
Wrapper to send a fastly api request. Use this if the endpoint you need hasn't been mapped to a function.

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolving to response  

| Param | Type | Description |
| --- | --- | --- |
| options | <code>Object</code> |  |
| options.params | <code>Object</code> | parameters to upload with encoding: application/x-www-form-urlencoded |
| options.baseUrl | <code>string</code> | fastly api baseUrl (default: 'https://api.fastly.com') |
| options.endpoint | <code>string</code> | fastly api endpoint e.g. 'service/${serviceId}/version/${version}/backend' (default: '') |
| options.headers | <code>Object</code> | add to or overwrite the default headers (default: {'Fastly-Key', Accept}) |
| options.method | <code>string</code> | the http method (default: GET) |
| options.timeout | <code>number</code> | the connection timeout in ms (default: 5000) |

<a name="module_phastly.purgeP"></a>

### phastly.purgeP(serviceId, key, [soft]) ⇒ <code>Promise</code>
Instant Purge a particular service of items tagged with a Surrogate Key. Soft Purging sets an object's TTL to 0s, forcing revalidation. For best results, Soft Purging should be used in conjuction with stale_while_revalidate and stale_if_error.

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| serviceId | <code>string</code> |  |  |
| key | <code>string</code> |  |  |
| [soft] | <code>Boolean</code> | <code>false</code> | sets an object's TTL to 0s |

<a name="module_phastly.purgeUrlP"></a>

### phastly.purgeUrlP(url, [soft]) ⇒ <code>Promise</code>
Instant Purge an individual URL. Soft Purging sets an object's TTL to 0s, forcing revalidation. For best results, Soft Purging should be used in conjuction with stale_while_revalidate and stale_if_error.

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Default |
| --- | --- | --- |
| url | <code>string</code> |  | 
| [soft] | <code>Boolean</code> | <code>false</code> | 

<a name="module_phastly.purgeAllP"></a>

### phastly.purgeAllP(serviceId) ⇒ <code>Promise</code>
Instant Purge everything from a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 

<a name="module_phastly.createBackendP"></a>

### phastly.createBackendP(serviceId, version, data) ⇒ <code>Promise</code>
Create a backend for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| data | <code>Object</code> | keys are backend object keys |

<a name="module_phastly.deleteBackendP"></a>

### phastly.deleteBackendP(serviceId, version, name) ⇒ <code>Promise</code>
Delete the backend for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| name | <code>string</code> | name of backend |

<a name="module_phastly.createServiceP"></a>

### phastly.createServiceP(name) ⇒ <code>Promise</code>
Create a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| name | <code>string</code> | 

<a name="module_phastly.updateServiceP"></a>

### phastly.updateServiceP(params) ⇒ <code>Promise</code>
Update a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| params | <code>Object</code> | key/values of paramters to update |

<a name="module_phastly.createServiceVersionP"></a>

### phastly.createServiceVersionP(serviceId) ⇒ <code>Promise</code>
Create a version for a particular service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 

<a name="module_phastly.updateServiceVersionP"></a>

### phastly.updateServiceVersionP(serviceId, version, data) ⇒ <code>Promise</code>
Update a particular version for a particular service.

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| data | <code>Object</code> | keys are service object keys |

<a name="module_phastly.validateServiceVersionP"></a>

### phastly.validateServiceVersionP(serviceId, version) ⇒ <code>Promise</code>
Validate the version for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.activateServiceVersionP"></a>

### phastly.activateServiceVersionP(serviceId, version) ⇒ <code>Promise</code>
Activate the current version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.deactivateServiceVersionP"></a>

### phastly.deactivateServiceVersionP(serviceId, version) ⇒ <code>Promise</code>
Deactivate the current version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.cloneServiceVersion"></a>

### phastly.cloneServiceVersion(serviceId, version) ⇒ <code>Promise</code>
Clone the current configuration into a new version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.lockServiceVersion"></a>

### phastly.lockServiceVersion(serviceId, version) ⇒ <code>Promise</code>
Locks the specified version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.deleteServiceP"></a>

### phastly.deleteServiceP(serviceId) ⇒ <code>Promise</code>
Delete a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 

<a name="module_phastly.renameServiceP"></a>

### phastly.renameServiceP(serviceId, newName) ⇒ <code>Promise</code>
Rename a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| newName | <code>string</code> | 

<a name="module_phastly.filterActiveVersion"></a>

### phastly.filterActiveVersion(versions) ⇒ <code>Object</code>
helper function - get active version from a fastly version list

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Object</code> - version information  

| Param | Type | Description |
| --- | --- | --- |
| versions | <code>Array.&lt;Object&gt;</code> | of the service |

<a name="module_phastly.ListServicesP"></a>

### phastly.ListServicesP() ⇒ <code>Promise</code>
List services

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  
<a name="module_phastly.getServiceP"></a>

### phastly.getServiceP(serviceId) ⇒ <code>Promise</code>
Get a service by id

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 

<a name="module_phastly.getServiceByNameP"></a>

### phastly.getServiceByNameP(name) ⇒ <code>Promise</code>
Get a service by name

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | name of service |

<a name="module_phastly.getServiceDetailsP"></a>

### phastly.getServiceDetailsP(serviceId) ⇒ <code>Promise</code>
List detailed information on a specified service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 

<a name="module_phastly.getServiceDomainsP"></a>

### phastly.getServiceDomainsP(service) ⇒ <code>Promise</code>
List the domains within a service

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to deserialized response  

| Param | Type | Description |
| --- | --- | --- |
| service | <code>string</code> | id |

<a name="module_phastly.createDomainP"></a>

### phastly.createDomainP(serviceId, version, data) ⇒ <code>Promise</code>
Create a domain for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| data | <code>Object</code> | fastly domain object |

<a name="module_phastly.checkAllDomainsP"></a>

### phastly.checkAllDomainsP(serviceId, version) ⇒ <code>Promise</code>
Check all domains' DNS for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type |
| --- | --- |
| serviceId | <code>string</code> | 
| version | <code>number</code> | 

<a name="module_phastly.createRequestSettingP"></a>

### phastly.createRequestSettingP(serviceId, version, settings) ⇒ <code>Promise</code>
Create a new Request Settings object

**Kind**: static method of <code>[phastly](#module_phastly)</code>  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| settings | <code>Object</code> | fastly request settings object: {hash_keys, action, ...} |

<a name="module_phastly.updateSettingsP"></a>

### phastly.updateSettingsP(serviceId, version, settings) ⇒ <code>Promise</code>
Update the settings for a particular service and version

**Kind**: static method of <code>[phastly](#module_phastly)</code>  
**Returns**: <code>Promise</code> - resolves to parsed api result object  

| Param | Type | Description |
| --- | --- | --- |
| serviceId | <code>string</code> |  |
| version | <code>number</code> |  |
| settings | <code>Object</code> | fastly settings object e.g. {general.default_host, general.default_ttl, ...} |

<a name="module_phastly.setApiKey"></a>

### phastly.setApiKey(key)
set or change the fastly api key

**Kind**: static method of <code>[phastly](#module_phastly)</code>  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | your fastly api key |


## Documentation

To update `README.md` make changes in `doc/README.md.hbs` and/or `src/index.js` and run `doc/generate`