neocities

README

NeoCities API Go Wrapper

A NeoCities Go API wrapper.

Provides:

• Upload, Delete, Info, and List APIs from NeoCities
• Directory push support

Usage

To use the API, you will have to create a Site struct that contains:

• a key (for uploading/deleting files)
• a site name (for getting site information)

Example (uploading files):

package main

import "github.com/vulppine/neocities-go"

s := neocities.Site{
  Key: [ API key ],
}

func main() {
    err := s.Upload("filepath", "", nil)
    // do something with err
}

Copyright

Flipp Syder, 2021, MIT License

Documentation

Overview

Package neocities is a wrapper around the NeoCities API to perform various functions related to managing a NeoCities site, as well as obtaining information about NeoCities sites.

Index

• Variables
• func MakeMIMEMultipartFile(f io.Reader, name string) (*bytes.Buffer, string, error)
• func ReadFile(filename string) (string, error)
• func SetLogger(l *log.Logger)
• type API
• type APIClient
  • func (a *APIClient) ChangeAPI(api API) *APIClient
  • func (a *APIClient) NewAPIRequest(r io.Reader) (*http.Request, error)
• type APIError
  • func NewAPIError(r io.Reader) APIError
• type NeoTime
  • func (t *NeoTime) UnmarshalJSON(b []byte) error
• type Site
  • func (s *Site) DeleteFiles(c *APIClient, files ...string) error
  • func (s *Site) GetInfo(c *APIClient) (*Site, error)
  • func (s *Site) List(path string, c *APIClient) ([]SiteFile, error)
  • func (s *Site) NewAPIClient(api API) (*APIClient, error)
  • func (s *Site) Push(dir string, c *APIClient) error
  • func (s *Site) UploadFile(file string, name string, c *APIClient) error
• type SiteFile

Variables

var (
	NoAPI      = errors.New("no API supplied to APIClient")
	NoKey      = errors.New("no key supplied, required for this operation")
	SiteError  = errors.New("an error occurred during API call")
	MissingReq = errors.New("a required variable is missing")
)

var Verbose bool

Verbose toggles the verbosity of the library when it is performing actions. Toggling it will automatically print any relevant information to a logger.

Functions

func MakeMIMEMultipartFile

func MakeMIMEMultipartFile(f io.Reader, name string) (*bytes.Buffer, string, error)

MakeMIMEMultipartFile makes a MIME multipart body based on the Reader given to it, and the name given to it for the file name.

func ReadFile

func ReadFile(filename string) (string, error)

ReadFile reads an entire file.

Its intended use is when creating a Site struct, and a key is stored in a file.

func SetLogger

func SetLogger(l *log.Logger)

SetLogger allows you to set a logger. If this isn't used, the default logger provided by log will be used instead.

Types

type API

type API string

API represents a NeoCities API endpoint

const (
	Upload API = "upload"
	Delete API = "delete"
	List   API = "list"
	Info   API = "info"
)

type APIClient

type APIClient struct {
	API API
	// contains filtered or unexported fields
}

APIClient represents an API client.

func (*APIClient) ChangeAPI

func (a *APIClient) ChangeAPI(api API) *APIClient

ChangeAPI changes the API being used by an APIClient.

func (*APIClient) NewAPIRequest

func (a *APIClient) NewAPIRequest(r io.Reader) (*http.Request, error)

NewAPIRequest takes the potential body of a request.

type APIError

type APIError struct {
	Result    string `json:"result"`
	ErrorType string `json:"error_type"`
	Message   string `json:"message"`
}

APIError represents an error message returned by the NeoCities API.

func NewAPIError

func NewAPIError(r io.Reader) APIError

NewAPIError takes a reader containing JSON related to an error, and returns a struct containing the error type and message.

type NeoTime

type NeoTime time.Time

NeoTime represents the time value used by NeoCities for unmarshalling via encoding/json.

func (*NeoTime) UnmarshalJSON

func (t *NeoTime) UnmarshalJSON(b []byte) error

type Site

type Site struct {
	SiteName string
	Key      string
	Info     struct {
		Hits    int      `json:"hits"`
		Updated NeoTime  `json:"last_updated"`
		Domain  string   `json:"domain"`
		Tags    []string `json:"tags"`
	} `json:"info"`
}

Site represents a NeoCities site - both in authentication, and in information grabbing. Info is only used to be filled in by the info API endpoint.

Some API calls require the Key field to be filled - others do not. If an API call requires an authentication key, and there is no key in the Key field, the NoKey error will be passed from NewAPIClient to the calling function.

func (*Site) DeleteFiles

func (s *Site) DeleteFiles(c *APIClient, files ...string) error

DeleteFiles deletes a set of files from a NeoCities website.

func (*Site) GetInfo

func (s *Site) GetInfo(c *APIClient) (*Site, error)

GetInfo encodes the site information into the recieving Site struct. If c is nil, an API client will be made with the given info.

func (*Site) List

func (s *Site) List(path string, c *APIClient) ([]SiteFile, error)

List grabs the files from path into an array of SiteFiles. Requires an API key. If c is nil, a new client is created.

func (*Site) NewAPIClient

func (s *Site) NewAPIClient(api API) (*APIClient, error)

NewAPIClient returns a struct containing everything you need to perform RESTful API actions with NeoCities.

If a key is not supplied, a NoKey error will be returned, but the API client will still be ready to be used. This is meant for API calls that require authentication.

func (*Site) Push

func (s *Site) Push(dir string, c *APIClient) error

Push pushes an entire directory and its subdirectories to the website in the given directory. If c is nil, a new client is created.

Be CAREFUL when using this - Push will automatically upload all directories recursively.

Attempts to upload all files to the NeoCities site, and only halts if the site key was not passed.

func (*Site) UploadFile

func (s *Site) UploadFile(file string, name string, c *APIClient) error

UploadFile uploads a file using the information provided by Site. If c is nil, a new client is created - otherwise, an existing API client is used. If name is nil, the base of the path provided by file (file can be a singular string) is used.

File cannot be an empty string.

type SiteFile

type SiteFile struct {
	Path    string  `json:"path"`
	IsDir   bool    `json:"is_directory"`
	Size    int     `json:"size"`
	Updated NeoTime `json:"updated_at"`
	SHA1    string  `json:"sha1_hash"`
}

SiteFile represents a file in a NeoCities website. This is typically the output you get from a list API call.