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

import path from 'node:path'
import { NeocitiesAPIClient } from 'async-neocities'

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

  const client = new NeocitiesAPIClient(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 })

Bin

async-neocities ships a bin that lets you deploy to neocities locally or in CI.

It's interactive and will help you set up your config and keys.

The site name is configured to a file in cwd called deploy-to-neocities.json that looks like:

{"siteName":"the-name-of-the-site"}

Usage: async-neocities [options]

    Example: async-neocities --src public

    --help, -h            print help text
    --src, -s             The directory to deploy to neocities (default: "public")
    --cleanup, -c         Destructively clean up orphaned files on neocities
    --protect, -p         String to minimatch files which will never be cleaned up
    --status              Print auth status of current working directory
    --print-key           Print api-key status of current working directory
    --clear-key           Remove the currently assoicated API key
    --force-auth          Force re-authorization of current working directory

async-neocities (v3.0.0)

You can set the flags with ENV vars

• ASYNC_NEOCITIES_API_KEY or NEOCITIES_API_TOKEN: the API token matching the site name, but you should set and commit the deploy-to-neocities.json file.
• ASYNC_NEOCITIES_SITE_NAME: the name of the site to deploy to.

API

import { NeocitiesAPIClient } from 'async-neocities'

Import the Neocities API client.

apiKey = await NeocitiesAPIClient.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 NeocitiesAPIClient(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, opts)

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. When a large nunber of files are passed, the request is batched into opts.batchSize requests.

Opts are passed through to client.batchPost.

A successful response is the array of request results:

[{
  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 Node's querystring 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 querystring 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])

Efficiently deploy a directory path to Neocities, 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) => {},
  batchSize: 50, // number of files to upload per request,
  protectedFileFilter: path => false // a function that is passed neocities file paths.  When it returns true, that path will never be cleaned up when cleanup is set to true.
}

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 querystringa 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-data 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.

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

Low level batched post request to a given endpoint. Same as client.post, except requests are batched into opts.batchSize requests.

See also

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

License

MIT