async-neocities

An api client for neocities with an async/promise API and an efficient deploy algorithm.

Now available as a Github Action: deploy-to-neocities

npm install async-neocities

Usage

const path = require('path')
const Neocities = require('async-neocities')

async function deploySite () {
  const token = await Neocities.getKey('sitename', 'password')

  const client = new Neocities(token)

  console.log(await client.list()) // site files
  console.log(await client.info()) // site info

  return client.deploy(path.join(__dirname, './site-contents'))
}

deploySite.then(info => { console.log('done deploying site!') })
  .catch(e => { throw e })

API

Neocities = require('async-neocities')

Import the Neocities API client.

apiKey = await Neocities.getKey(sitename, password, [opts])

Static class method that will get an API Key from a sitename and password.

opts include:

{
  url: 'https://neocities.org' // Base URL to use for requests
}

client = new Neocities(apiKey, [opts])

Create a new API client for a given API key.

opts include:

{
  url: 'https://neocities.org' // Base URL to use for requests
}

response = await client.upload(files)

Pass an array of objects with the { name, path } pair to upload these files to neocities, where name is desired remote unix path on neocities and path is the local path on disk in whichever format the local operating system desires.

A successful response:

{
  result: 'success',
  message: 'your file(s) have been successfully uploaded'
}

response = await client.delete(filenames)

Pass an array of path strings to delete on neocities. The path strings should be the unix style path of the file you want to delete.

A successful response:

{ result: 'success', message: 'file(s) have been deleted' }

response = await client.list([queries])

Get a list of files for your site. The optional queries object is passed through qs and added to the request.

Available queries:

{
  path // list the contents of a subdirectory on neocities
}

Example responses:

{
  "result": "success",
  "files": [
    {
      "path": "index.html",
      "is_directory": false,
      "size": 1023,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "c8aac06f343c962a24a7eb111aad739ff48b7fb1"
    },
    {
      "path": "not_found.html",
      "is_directory": false,
      "size": 271,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "cfdf0bda2557c322be78302da23c32fec72ffc0b"
    },
    {
      "path": "images",
      "is_directory": true,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000"
    },
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}

With the path query:

{
  "result": "success",
  "files": [
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}

response = await client.info([queries])

Get info about your or other sites. The optional queries object is passed through qs and added to the request.

Available queries:

{
  sitename // get info on a given sitename
}

Example responses:

{
  "result": "success",
  "info": {
    "sitename": "youpi",
    "hits": 5072,
    "created_at": "Sat, 29 Jun 2013 10:11:38 +0000",
    "last_updated": "Tue, 23 Jul 2013 20:04:03 +0000",
    "domain": null,
    "tags": []
  }
}

stats = await client.deploy(directory, [opts])

Deploy a path to a directory, efficiently only uploading missing and changed files. Files are determined to be different by size, and sha1 hash, if the size is the same.

opts include:

{
  cleanup: false // delete orphaned files on neocities that are not in the `directory`
  statsCb: (stats) => {}
}

For an example of a stats handler, see lib/stats-handler.js.

client.get(endpoint, [quieries], [opts])

Low level GET request to a given endpoint.

NOTE: The /api/ prefix is automatically added: /api/${endpoint} so that must be omitted from endpoint.

The optional queries object is stringified to a querystring using qsa and added to the request.

opts includes:

{
  method: 'GET',
  headers: { ...client.defaultHeaders, ...opts.headers },
}

Note, that opts is passed internally to node-fetch and you can include any options that work for that client here.

client.post(endpoint, formEntries, [opts])

Low level POST request to a given endpoint.

NOTE: The /api/ prefix is automatically adeded: /api/${endpoint} so that must be omitted from `endpoint.

Pass a formEntries array or iterator containing objects with {name, value} pairs to be sent with the POST request as FormData. The form-datat module is used internally.

opts include:

{
  method: 'POST',
  body: new FormData(), // Don't override this.
  headers: { ...client.defafultHeaders, ...formHeaders, opts.headers }
}

Note, that opts is passed internally to node-fetch and you can include any options that work for that client here.

See also

• Neocities API docs
• Official Node.js API client
• bcomnes/deploy-to-neocities This module as an action.

License

MIT