fastly-native-promises

DEPRECATION WARNING

THIS PACKAGE WILL LIKELY BE DEPRECATED IN THE NEAR FUTURE

As soon as the official fastly package on NPM leaves beta for version 3.0.0, this package will be deprecated in favor of the official package and this package will no longer receive feature updates and likely be archived after Adobe migrated its own usage of this package.

Native Promise based Fastly API client for Node.js

Problem

The callback-based fastly package is still the most used client on NPM. However, I needed a client which allows me to perform request sequentially and parallelly without ending up in an untamable callback hell. Philipp Schulte's fastly-native-promises client seemed almost perfect, except:

• it uses Axios, which is an additional dependency we'd like to avoid, especially when running inside Adobe I/O Runtime
• it has been missing features and pull requests were merged only slowly

This fork addresses the concerns above but breaks compatibility with Browsers, so that it can only be used in Node JS environments.

Solution

The fastly-native-promises package uses the promise-based HTTP client Request-Promise-Native to perform requests to the Fastly API. Request-Promise-Native supports the native JavaScript Promise API and automatically transforms the data into JSON. Each fastly-native-promises API method returns a Promise which represents either the completion or failure of the request.

Table of Contents

• Security
• Install
• Usage
• API
• Tests
• Contribute
• License

Security

You'll need a Fastly API Token to use the fastly-native-promises library. I recommend using a token with global scope to be able to use all fastly-native-promises API methods.

Install

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

$ npm install @adobe/fastly-native-promises

Changes

See the changelog.

Usage

import fastly from '@adobe/fastly-native-promises';

// create one or more instances
const service_1 = fastly('token', 'service_id_1');
const serivce_2 = fastly('token', 'service_id_2');

// make changes

service_1.transact(async () => {
  return this.writeS3('test-s3', {
    name: 'test-s3',
    bucket_name: 'my_corporate_bucket',
    access_key: 'AKIAIOSFODNN7EXAMPLE',
    secret_key: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  });
});


service_2.transact(async () => {
  return this.writeBigquery('test-bq', {
    name: 'test-bq',
    format: '{\n "timestamp":"%{begin:%Y-%m-%dT%H:%M:%S}t",\n  "time_elapsed":%{time.elapsed.usec}V,\n  "is_tls":%{if(req.is_ssl, "true", "false")}V,\n  "client_ip":"%{req.http.Fastly-Client-IP}V",\n  "geo_city":"%{client.geo.city}V",\n  "geo_country_code":"%{client.geo.country_code}V",\n  "request":"%{req.request}V",\n  "host":"%{req.http.Fastly-Orig-Host}V",\n  "url":"%{json.escape(req.url)}V",\n  "request_referer":"%{json.escape(req.http.Referer)}V",\n  "request_user_agent":"%{json.escape(req.http.User-Agent)}V",\n  "request_accept_language":"%{json.escape(req.http.Accept-Language)}V",\n  "request_accept_charset":"%{json.escape(req.http.Accept-Charset)}V",\n  "cache_status":"%{regsub(fastly_info.state, "^(HIT-(SYNTH)|(HITPASS|HIT|MISS|PASS|ERROR|PIPE)).*", "\\\\2\\\\3") }V"\n}',
    user: '[email protected]',
    project_id: 'example-fastly-log',
    dataset: 'fastly_log_test',
    table: 'fastly_logs',
    template_suffix: null,
    secret_key: '-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC7bPG9yaIYd5AL\nmvOaYvNozFJB/VWS53KWBll769kJvlmgMks6r6Xrv8w6rjxWKjZeDrnXVf7UDa0F\nckPPIFvXRxahftWFMGArw0lIvQzgT4/BlndXU5RNxfah/8m7q/GIF6oNYWzfJwvv\nzodxDUqIRH2e2JWidNRjElHuogYHLhV4O/od5pAkfDwak/ihuuh/2VA3Auwb3nph\ndX2F0JBs14oPKZUTYUUSzUQY5IMxSxYUA4Q7W4v21x1EnJt+biXOrERk1rm4ieEE\nU3WkjR5c5gvG8xcWyYod87RNFELmIhCCytI1+t5C3Em/jPsQFtLzwHpbNhdW4oEm\nn7d06n75AgMBAAECggEAWRh26lNZfOwJS5sDRlbXgu/uAnSdI1JmxC6Mhz4cVGdq\nT57Y6DLrWuA4A4UkJYm3gorZiSXWF5PQthAVb/bf8bxXY7nZYpEWhnc09SD5aAAq\nREp0vMx8aWQ709K2YUJg+zDUo7u2d3YmVH8HH5TD43c7iDFJIIsNE3N4A0p+NxZ+\nw06FFW+fz/etrWiNyhrlTsbkMbSgU+GpFFBq1pCd0ni5d1YM1rsaAaUpmkwdjgjL\noDs+M/L/HtqfEhyZNdw8JF7EJXVE1bIl7/NL0rBInhyO28FcB56t/AG5nzXKFI/c\nc+IO7d6MOOqiGRLRWZItEpnyzuV8DZo461wy1hSvqQKBgQDhSsg2cHkTrtBW8x0A\n3BwB/ygdkkxm1OIvfioT+JBneRufUPvVIM2aPZBBGKEedDAmIGn/8f9XAHhKjs8B\nEsPRgE206s4+hnrTcK7AeWWPvM9FDkrkQCoJFuJrNy9mJt8gs7AnnoBa9u/J4naW\ne1tfC8fUfsa7kdzblDhcRQ8FhwKBgQDU+N4kPzIdUuJDadd6TkBbjUNPEfZzU5+t\nIike2VSRhApxAxviUnTDsTROwJRzKik9w7gIMka8Ek+nmLNMEtds77ttcGQRdu16\n+vT1iualiCJe+/iMbl+PiJtFwhEHECLU9QfgBVS6r2lDAlZA+w6nwCRiidlrObzO\nCXqVOzN3fwKBgAsrOuu//bClHP0ChnCReO38aU+1/gWnDiOOnKVq0DXhAiaOzD1P\nqAG6hZlEkFBDMPWzq62doKv+gPgpRkfmV0DenHuYnGrrHdG3p2IxYoCSuq/QupPA\nPpU+xjDMhpQI30zuu4/rQq+/yDl4+aoSKYB3xAtb0Zxg6dMU8QpZ/hmnAoGBAIFu\nIesbcQR7O8FGkMrmxZweNNrYCtQ57R/WU/FImWm6OnJGNmsMO6Q2jJiT12RKKjg8\nOxrYGz7vTfOIDOddyAiPhXPUSyyF/3uvCrIzUUsmeeUJ8xq9dVwQ5HS3pYuKVfDg\nXYHbG4w9UJaF1A+3xEdUsYglSLouo7z/67zH9tZXAoGBAKpsdjSd3R+llaAv2HQ8\nGMlN92UTr5i9w++QMXq4qspH5NEYqz3NHbKuYthZqxEsRUZbRP50eDWU4jvxFVJl\nLBFINp6B+3AsIme0YCyOaleB/Cy0347miSinSv2I6QiH6dQxHdHzrG+x1evS/76f\nKT0KS+ySjCAEWgg4v+mjUDUV\n-----END PRIVATE KEY-----\n',
    response_condition: '',
  });

  // optional, but speeds up end of process
  await service_1.discard();
  await service_2.discard();
});

Promises

Purge all domains of the active version:

1. Get all the versions.
2. Filter out the active version.
3. Get all the domains for the active version.
4. Purge all the domains.
5. Log the status text for each purge request.

import fastly from '@adobe/fastly-native-promises';

const service = fastly('token', 'service_id');

function handler() {
  service.readVersions()
    .then(versions => {
      const active = versions.data.filter(version => version.active)[0];
      return service.readDomains(active.number);
    })
    .then(domains => {
      return Promise.all(domains.data.map(domain => service.purgeIndividual(domain.name)));
    })
    .then(purges => {
      purges.forEach(purge => console.log(purge.statusText));
    })
    .catch(e => {
      console.log('Shoot!');
    });
}

Async/Await

Update first_byte_timeout property for every backend and service if the value is less than 5000 milliseconds:

1. Get all the services associated with the Fastly API token.
2. Filter out the service IDs.
3. Iterate over all services synchronously.
4. Get all the versions.
5. Filter out the active version.
6. Get all the backends for the active version.
7. Filter out the affected backends.
8. Continue with the next service if there are no affected backends.
9. Clone the active version.
10. Update all the affected backends parallelly.
11. Activate the cloned version.

import fastly from '@adobe/fastly-native-promises';

const account = fastly('token');

async function handler() {
  try {
    const services = await account.readServices();
    const ids = services.data.map(service => service.id);

    for (const id of ids) {
      const service = fastly('token', id);
      const versions = await service.readVersions();
      const active = versions.data.filter(version => version.active)[0];
      const backends = await service.readBackends(active.number);
      const affected = backends.data.filter(backend => backend.first_byte_timeout < 5000);

      if (!affected.length) continue;

      const clone = await service.cloneVersion(active.number);
      await Promise.all(affected.map(backend => service.updateBackend(clone.data.number, backend.name, { first_byte_timeout: 5000 })));
      await service.activateVersion(clone.data.number);
    }
  } catch (e) {
    console.log('Shoot!');
  }
}

Response Schema

Each fastly-native-promises API method returns the following response object:

{
  // the HTTP status code from the server response
  status: 200,

  // the HTTP status message from the server response
  statusText: 'OK',

  // the headers that the server responded with
  headers: {},

  // the options that were provided to request for the request
  config: {},

  // the request that generated the response
  request: {},

  // the response that was provided by the server
  data: {}
}

Retrieving Request Statistics

The Fastly instance has a requestmonitor property that can be used to retrieve request statistics:

• requestmonitor.count for the total number of requests.
• requestmonitor.remaining for the number of requests remaining according to Fastly's API Rate limit for the hour or undefined (if no modifying requests have been made yet).
• requestmonitor.edgedurations for an array of API processing durations (in milliseconds, measured from the edge).
• requestmonitor.durations for an array of request durations (in milliseconds, measured from the client, i.e. including network latency).

With requestmonitor.stats you can get all of that in one object, including minimum, maximum and mean durations for all requests.

Guarding against Rate Limits

Using the requestmonitor.remaining property, you can make sure that you still have sufficient requests before you hit the rate limit.

When using the instance.transact method, you can furthermore provide a minimum for the necessary available request limit so that after the initial cloning of the version no additional requests will be made if the API rate limit will be exceeded. This allows you to fail fast in case of rate limit issues.

High-Level Helpers

While most functionality is a low-level wrapper of the Fastly, API, we provide a couple of higher-level helper functions in properties of the Fastly instance.

Conditions Helper in fastly.conditions

The conditions helper eases the creation and management of conditions.

const fastly = require('fastly-native-promises');

const instance = fastly('mykey', 'service-config');

const update = fastly.conditions.update(1, 'REQUEST', 'Created as an Example', 'example');

const conditions = await update('req.url.basename == "new.html"', 'req.url.basename == "index.html"');

console.log('Created a condition matching index.html with following name', conditions['req.url.basename == "index.html"'].name);

fastly.conditions.update can be called with the parameters version (service config version), type (condition type, either REQUEST, RESPONSE, or CACHE), comment (a comment that will be visible in the Fastly UI), nameprefix (a common prefix for the condition name) to get a new function update that performs the update.

When update is called with a list of statements in VCL condition language, it will synchronize the list of conditions passed in with the conditions that already exist in the Fastly service config. All conditions that share the same nameprefix, but are no longer used get deleted, new conditions that don't exist yet will get created (unchanged conditions aren't touched, reducing the number of requests made upon updates).

The return value of update is an object that maps condition statement to the condition object. This allows re-using the condition in other Fastly API calls.

Header Helper in fastly.headers

The headers helper eases the creation and management of conditional headers.

import fastly from '@adobe/fastly-native-promises';

const instance = fastly('mykey', 'service-config');

const update = fastly.headers.update(
  1,
  'REQUEST', // apply a request condition
  'Created as an Example', // use following comment for conditions
  'example', // name-prefix for all generated conditions and headers
  'set', // set the header
  'http.Location' // which header (Location)
  'request' // in the request handling
  );

await update(
    {
      condition: 'req.url.basename == "new.html"',
      expression: '"https://new.example.com"',
    },
    {
      condition: 'req.url.basename == "index.html"',
      expression: 'https://www.example.com',
    });

fastly.headers.update can be called with the parameters version (service config version), type (condition type, either REQUEST, RESPONSE, or CACHE), comment (a comment that will be visible in the Fastly UI), nameprefix (a common prefix for the condition name), action (what to do with the header, can be set, append, or delete), header (the name of the header – remember to include http. in the value), sub (the subroutine where the header is applied, can be request, fetch, cache, or response) to get a new function update that performs the update.

When update is called with a list of objects that looks like { condition: 'req.url ~ "foo/(.*)/bar"', expression: '"bar/" + re.group.1 + "/foo"'}, i.e. pairs of a condition (in VCL condition language) and an expression (also valid VCL), it will synchronize the list of headers (and resultant conditions) passed in with the headers and conditions that already exist in the Fastly service config. All conditions and headers that share the same nameprefix, but are no longer used get deleted, new conditions and headers that don't exist yet will get created (unchanged conditions and headers aren't touched, reducing the number of requests made upon updates).

API

Functions

Typedefs

readCurrentUser() ⇒ Promise

Get the currently logged in user.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_91db9d9178f3f4c7597899942bd3f941

readUsers() ⇒ Promise

Get a list of all users from the current customer.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#customer_12f4a69627ba3bbb1c8668aae03a60ad

readUser(id) ⇒ Promise

Get the the user with the specific id.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_15a6c72980b9434ebb8253c7e882c26c

| Param | Type | Description | | --- | --- | --- | | id | string | The User ID. |

createUser(name, login) ⇒ Promise

Create a user.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_00b606002596bac1c652614de98bd260

| Param | Type | Description | | --- | --- | --- | | name | string | The user name. | | login | string | The user login. |

readInvitations() ⇒ Promise

List all invitations.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_6d8623de97ed7e50b7b6498e374bb657

createInvitation(email, role) ⇒ Promise

Create an invitation.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_8c4da3ca11c75facd36cfaad024bd891

| Param | Type | Default | Description | | --- | --- | --- | --- | | email | string | | The email address for the invitation. | | role | string | "engineer" | The user role. Defaults to {@code engineer}. |

acceptInvitation(acceptCode, name, password) ⇒ Promise

Accept an invitation.

Kind: global function
Returns: Promise - The response object representing the completion or failure.

| Param | Type | Description | | --- | --- | --- | | acceptCode | string | The accept code retrieved in the email. | | name | string | Name for the new user. | | password | string | Password for the new user. |

deleteInvitation(id) ⇒ Promise

Delete an invitation.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_d70a7460c7e1bd8dd660c6f5b3558c2e

| Param | Type | Description | | --- | --- | --- | | id | string | The invitation id. |

readTokens([customerId]) ⇒ Promise

List all tokens of a customer.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_d59ff8612bae27a2317278abb048db0c

| Param | Type | Description | | --- | --- | --- | | [customerId] | string | The id of the customer. |

readToken([id]) ⇒ Promise

Get the token with the specified id. If the Id is missing, the self token is returned.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_bb00e7ed542cbcd7f32b5c908b8ce244

| Param | Type | Description | | --- | --- | --- | | [id] | string | The token id. |

deleteToken([id]) ⇒ Promise

Delete the token with the specified id.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_4a958ba69402500937f0d8570f7ce86f

| Param | Type | Description | | --- | --- | --- | | [id] | string | The token id. |

createToken(options) ⇒ Promise

Create an API token.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_db4655a45a0107448eb0676577446e40

| Param | Type | Description | | --- | --- | --- | | options | object | The token options. |

domainCheck(version, name) ⇒ Promise

Checks the status of all domains for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_30a3f14c9a0ce5730757d39983ab7dc6

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The name of the domain. |

domainCheckAll(version) ⇒ Promise

Checks the status of all domains for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_e33a599694c3316f00b6b8d53a2db7d9

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. |

Example

instance.domainCheckAll('182')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

readDomains(version) ⇒ Promise

List all the domains for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_6d340186666771f022ca20f81609d03d

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. |

Example

instance.readDomains('182')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

readDomain(version, name) ⇒ Promise

List all the domains for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_f1b5fab17a0729daeeaf7594b47759c5

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The domain name. |

readServiceDomains([serviceId]) ⇒ Promise

List the domains within a service.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#service_d5578a1e3bc75512711ddd0a58ce7a36

| Param | Type | Description | | --- | --- | --- | | [serviceId] | string | The service id. |

createDomain(version, name, comment) ⇒ Promise

Create a domain for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_90345101274774ff1b84f0a7dd010b01

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The domain name. | | comment | string | Optional comment. |

updateDomain(version, oldName, name, comment) ⇒ Promise

Update a domain for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_2ef42bd9b4c56c86b46dc0e36096ab10

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | oldName | string | The old name of the domain. | | name | string | The domain name. | | comment | string | Optional comment. |

deleteDomain(version, name) ⇒ Promise

Delete the domain for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_aab5a322f58df2b1db8dc276e8594a70

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The domain name. |

readHealthchecks(version) ⇒ Promise

List all healthchecks for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_126cb37382d68583269420ba772ded36

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. |

readHealthcheck(version, name) ⇒ Promise

Get details of a single named healthcheck.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_b54ea357a2377e62ae7649e609b94966

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The name of the healthcheck. |

createHealthcheck(version, data) ⇒ Promise

Create a healthcheck for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_8712be8923dd419c54393da3ac31f6d3

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | data | object | The healthcheck definition. |

updateHealthcheck(version, name, data) ⇒ Promise

Update the healthcheck for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_9a60b6005125c4afeaa80111e69d7586

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The name of the healthcheck to update. | | data | object | The healthcheck definition. |

deleteHealthcheck(version, name) ⇒ Promise

Delete the healthcheck for a particular service and version.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_a22900c40a2fd59db5028061dc5dfa36

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. | | name | string | The name of the healthcheck to delete. |

readPackage(version) ⇒ Promise

Get metadata about a package. The metadata is extracted from the package contents.

Kind: global function
Returns: Promise - The response object.

| Param | Type | Description | | --- | --- | --- | | version | string | The current version of a service. |

writePackage(version, buffer) ⇒ Promise

Upload a new package version. The package is a Buffer of a ZIP file containing the manifest as well as the main WASM file.

Kind: global function
Returns: Promise - The response object.

| Param | Type | Description | | --- | --- | --- | | version | string | The service version to update. | | buffer | Buffer | The package contents as a Buffer. |

purgeIndividual(url) ⇒ Promise

Instant Purge an individual URL.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_3aa1d66ee81dbfed0b03deed0fa16a9a

| Param | Type | Description | | --- | --- | --- | | url | string | The URL to purge. |

Example

instance.purgeIndividual('www.example.com')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

purgeAll() ⇒ Promise

Instant Purge everything from a service.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_bee5ed1a0cfd541e8b9f970a44718546
Example

instance.purgeAll()
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

purgeKey(key) ⇒ Promise

Instant Purge a particular service of items tagged with a Surrogate Key.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_d8b8e8be84c350dd92492453a3df3230

| Param | Type | Description | | --- | --- | --- | | key | string | The surrogate key to purge. |

Example

instance.purgeKey('key_1')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

purgeKeys(keys) ⇒ Promise

Instant Purge a particular service of items tagged with Surrogate Keys in a batch.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_db35b293f8a724717fcf25628d713583

| Param | Type | Description | | --- | --- | --- | | keys | Array | The array of surrogate keys to purge. |

Example

instance.purgeKeys(['key_2', 'key_3', 'key_4'])
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

softPurgeIndividual(url) ⇒ Promise

Soft Purge an individual URL.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#soft_purge_0c4f56f3d68e9bed44fb8b638b78ea36

| Param | Type | Description | | --- | --- | --- | | url | string | The URL to soft purge. |

Example

instance.softPurgeIndividual('www.example.com/images')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

softPurgeKey(key) ⇒ Promise

Soft Purge a particular service of items tagged with a Surrogate Key.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#soft_purge_2e4d29085640127739f8467f27a5b549

| Param | Type | Description | | --- | --- | --- | | key | string | The surrogate key to soft purge. |

Example

instance.softPurgeKey('key_5')
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

softPurgeKeys(keys) ⇒ Promise

Soft Purge a particular service of items tagged with Surrogate Keys in a batch.

Kind: global function
Returns: Promise - The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_db35b293f8a724717fcf25628d713583

| Param | Type | Description | | --- | --- | --- | | keys | Array | The array of surrogate keys to purge. |

Example

instance.softPurgeKeys(['key_2', 'key_3', 'key_4'])
   .then(res => {
     console.log(res.data);
   })
   .catch(err => {
     console.log(err.message);
   });

multistepupdate(version, type, commentprefix, nameprefix) ⇒ Array.<function()>

Creates functions for multi-step creation of missing and deletion of superflous conditions.

Kind: global function
Returns: Array.<function()> - A pair of a create and cleanup function.

| Param | Type | Description | | --- | --- | --- | | version | number | Service config version. | | type | string | Condition type, can be REQUEST, RESPONSE, or CACHE. | | commentprefix | string | The prefix to be used for comments. | | nameprefix | string | - The prefix to be used for names. |

update(version, type, commentprefix, nameprefix, action, header, sub) ⇒ Array.<function()>

Creates functions for multi-step creation of missing and deletion of superflous conditional headers.

Kind: global function
Returns: Array.<function()> - A pair of a create and cleanup function.

| Param | Type | Description | | --- | --- | --- | | version | number | Service config version. | | type | string | Condition type, can be REQUEST, RESPONSE, or CACHE. | | commentprefix | string | The prefix to be used for comments. | | nameprefix | string | - The prefix to be used for names. | | action | string | What do do with the header, can be set, append, delete. | | header | string | The name of the header to set. | | sub | string | Name of the subroutine where the header should be applied, can be request, fetch, cache, or response. |

repeat(responseOrError) ⇒ boolean

Determines if a response or error indicates that the response is repeatable.

Kind: global function
Returns: boolean - - True, if another attempt can be made.

| Param | Type | Description | | --- | --- | --- | | responseOrError | object | – the error response or error object. |

CreateFunction ⇒ Promise

A function that creates a resource of a specific type. If a resource of that name already exists, it will reject the returned promise with an error.

Kind: global typedef
Returns: Promise - The response object representing the completion or failure.
Throws:

• FastlyError

| Param | Type | Description | | --- | --- | --- | | version | string | The service config version to operate on. Needs to be checked out. | | data | object | The data object describing the resource to be created. | | data.name | string | The name of the resource to be created. |

UpdateFunction ⇒ Promise

A function that updates an already existing resource of a specific type. If no resource of that name exists, it will reject the returned promise with an error.

Kind: global typedef
Returns: Promise - The response object representing the completion or failure.
Throws:

• FastlyError

| Param | Type | Description | | --- | --- | --- | | version | string | The service config version to operate on. Needs to be checked out. | | name | string | The name of the resource to be updated. The old name in case of renaming something. | | data | object | The data object describing the resource to be updated. | | data.name | string | The new name of the resource to be updated. |

ReadFunction ⇒ Promise

A function that retrieves a representation of a resource of a specific type. If no resource of that name exists, it will reject the returned promise with an error.

Kind: global typedef
Returns: Promise - The response object representing the completion or failure.
Throws:

• FastlyError

| Param | Type | Description | | --- | --- | --- | | version | string | The service config version to operate on. Needs to be checked out. | | name | string | The name of the resource to be retrieved. |

ListFunction ⇒ Promise

A function that retrieves a list of resources of a specific type.

Kind: global typedef
Returns: Promise - The response object representing the completion or failure.
Throws:

• FastlyError

| Param | Type | Description | | --- | --- | --- | | version | string | The service config version to operate on. Needs to be checked out. |

FastlyError : object

The FastlyError class describes the most common errors that can occur when working with the Fastly API. Using error.status, the underlying HTTP status code can be retrieved. Known error status codes include:

• 400: attempting to activate invalid VCL
• 401: invalid credentials
• 404: resource not found
• 409: confict when trying to POST a resource that already exists
• 422: attempting to modify a service config that is not checked out
• 429: rate limit exceeded, try again later

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | status | number | The HTTP status code from the server response, e.g. 200. | | data | object | The parsed body of the HTTP response. | | code | string | A short error message. | | message | string | A more detailed error message. |

Response : object

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | status | number | The HTTP status code from the server response, e.g. 200. | | statusText | string | The HTTP status text, e.g. 'OK'. | | headers | object | The HTTP headers of the reponse. | | config | object | The original request configuration used for the HTTP client. | | request | object | The HTTP request. | | data | object | The parsed body of the HTTP response. |

Versions : object

Describes the most relevant versions of the service.

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | latest | number | The latest version of the service. | | active | number | The currently active version number. | | current | number | The latest editable version number. |

DictUpdate : object

Specifies a dictionary update operation. In most cases, upsert is the best way to update values, as it will work for existing and non-existing items.

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | op | string | The operation: create, update, delete, or upsert. | | item_key | string | The lookup key. | | item_value | string | The dictionary value. |

Snippet : object

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | name | string | The name of the snippet, as visible in the Fastly UI. | | content | string | The VCL body of the snippet. |

ResponseObject : object

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | name | string | The name of the synthetic response, as visible in the Fastly UI. | | content | string | The body of the response. | | content_type | string | The content type. | | status | number | Http status code. | | request_condition | string | Name of a request condition. |

VCL : object

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | name | string | The name of the VCL, as visible in the Fastly UI. Note: setting the name to 'main' here won't make it the main VCL, unless you also call setMainVCL. | | content | string | The VCL body of the custom VCL. |

Tests

To run the test suite, first install the dependencies, then run the npm test command:

$ npm install
$ npm test

Contribute

PRs accepted. I am open to suggestions in improving this library. Commit by:

$ npm run commit

License

Licensed under the MIT License © 2017 Philipp Schulte