From c955ee08d47663511112dbb787b6d070213f15f8 Mon Sep 17 00:00:00 2001 From: synt-xerror <169557594+synt-xerror@users.noreply.github.com> Date: Mon, 16 Feb 2026 20:34:40 -0300 Subject: [PATCH] New readme --- LICENSE | 2 +- README.md | 258 +++++++++++++++++++++++++++++++----------------- src/neocities.h | 9 +- src/neogities.c | 0 4 files changed, 170 insertions(+), 99 deletions(-) delete mode 100644 src/neogities.c diff --git a/LICENSE b/LICENSE index 9382207..af1e8ef 100755 --- a/LICENSE +++ b/LICENSE @@ -15,4 +15,4 @@ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNES FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 05d7c42..f53b9d1 100755 --- a/README.md +++ b/README.md @@ -1,121 +1,193 @@ -# Neocities C CLI +# Neocities C API -A simple command-line tool written in C that interacts with the [Neocities API](https://neocities.org/api). -Currently, only the `--info` command is implemented — it fetches and displays basic information about your Neocities site. +Minimal, secure C wrapper for the Neocities API using API key authentication. + +No login flow. +No credential storage. +Stateless by design. + +Users must generate their own API key via the Neocities dashboard. --- ## Features -- Fetch site information using Neocities API -- Authenticates via environment variables -- JSON parsing with [jansson](https://digip.org/jansson/) -- Works on Linux, Windows (MSYS2/MinGW), and Android (via Termux) -- Compilable with a Makefile for easy builds + +* Site info retrieval +* File listing +* Upload files +* Delete files +* TLS verification enabled by default + +Authentication is performed exclusively via: + +``` +Authorization: Bearer +``` --- ## Requirements -You’ll need: -- A C compiler (`gcc` or `clang`) -- [libcurl](https://curl.se/libcurl/) -- [jansson](https://digip.org/jansson/) -- `make` +* libcurl -### Linux (Debian/Ubuntu-based) -```bash -sudo apt update -sudo apt install build-essential libcurl4-openssl-dev libjansson-dev make -``` - -### Windows (MSYS2 / MinGW) -```bash -pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-curl mingw-w64-x86_64-jansson make -``` - -### Android (Termux) - -```bash -pkg install clang curl-dev jansson make -``` - -## Building - -Run in cloned repository: -```bash -make -``` - -This will generate the executable neocities (or neocities.exe on Windows). - -To clean build files: - -```bash -make clean -``` - -### Environment Variables - -Before running, export your Neocities credentials: - -#### Linux / macOS / Termux - -```bash -export NEOCITIES_USER="your_username" -export NEOCITIES_PASS="your_password" -``` - -#### Windows (PowerShell) - -```batch -setx NEOCITIES_USER "your_username" -setx NEOCITIES_PASS "your_password" -``` - -## Usage - -```bash -./neocities --info -``` - -Example output: +Linux (example): ``` -Neocities C CLI - -Sitename: example -Hits: 42 -Created at: 2024-01-10 -Last updated: 2025-11-01 -Domain: domain.com -Tags: art, blog, personal. +sudo apt install libcurl4-openssl-dev ``` -## Optional: Install Globally +--- -You can move the compiled executable to a directory in your PATH to run it from anywhere: +## Authentication -#### Linux / Termux +Generate your API key at: -```bash -sudo mv neocities /usr/local/bin/ +Neocities > Settings > Manage Site Settings > API +(or https://neocities.org/settings/YOUR-USERNAME#api_key) + +If you're coding a CLI or application, you must provide the key at runtime (env var, config file, etc). + +--- + +## API Overview + +Just an overview. For more detailed information, see: [[Function-Guide.md]] + +### Info (public) + +```c +int neocities_info(const char *sitename, neocities_info_t *out); ``` -#### Windows (PowerShell) -Move neocities.exe to a folder in your PATH, e.g., C:\Windows\System32\. +Fetch metadata about a site. -After that, you can run: +--- -```batch -neocities --info +### List files + +```c +int neocities_list(const char *api_key, + const char *path, + neocities_filelist_t *out); ``` -from any folder without specifying the path. +List files at a path. -## Notes +--- -Only the --info command is implemented for now. +### Upload -If you get curl_easy_perform errors, check your network and SSL setup. +```c +int neocities_upload(const char *api_key, + const char **local_files, + const char **remote_names, + size_t count, + char **response); +``` + +Uploads multiple files. + +* `local_files[i]` → local path +* `remote_names[i]` → remote filename + +--- + +### Delete + +```c +int neocities_delete(const char *api_key, + const char **filenames, + size_t count, + char **response); +``` + +Deletes files from the site. + +--- + +### API Key + +For security reasons, you should get the API key via Neocities settings. This function is not avaiable. + +--- + +## Memory Management + +Always free parsed outputs: + +```c +void neocities_free_info(neocities_info_t *info); +void neocities_free_filelist(neocities_filelist_t *list); +``` + +`response` returned by upload/delete must also be freed by caller. + +--- + +## Example Usage + +### List files + +```c +neocities_filelist_t list; + +if (neocities_list(api_key, "/", &list) == 0) { + for (size_t i = 0; i < list.count; i++) + printf("%s\n", list.paths[i]); + + neocities_free_filelist(&list); +} +``` + +--- + +### Upload + +```c +const char *local[] = {"index.html"}; +const char *remote[] = {"index.html"}; +char *resp; + +neocities_upload(api_key, local, remote, 1, &resp); +free(resp); +``` + +--- + +## Security Notes + +* TLS verification is enforced +* Redirects are disabled intentionally +* API key is never persisted internally + +Recommended: + +* Store key in env vars +* Avoid hardcoding + +--- + +## Design Philosophy + +* No login/password support +* API key only +* Explicit memory ownership +* Minimal abstraction + +--- + +## Future Extensions (Optional) + +Possible areas to explore: + +* Structured responses for upload/delete +* JSON passthrough mode +* Streaming uploads +* Error codes standardization + +--- + +## License + +[MIT](LICENSE) -On Termux, use clang for the best compatibility. \ No newline at end of file diff --git a/src/neocities.h b/src/neocities.h index af068cd..d254a83 100644 --- a/src/neocities.h +++ b/src/neocities.h @@ -25,10 +25,9 @@ typedef struct { // API functions // ------------------------- int neocities_info(const char *sitename, neocities_info_t *out); -int neocities_list(const char *user, const char *pass, const char *path, neocities_filelist_t *out); -int neocities_upload(const char *user, const char *pass, const char **local_files, const char **remote_names, size_t count, char **response); -int neocities_delete(const char *user, const char *pass, const char **filenames, size_t count, char **response); -int neocities_get_api_key(const char *user, const char *pass, char **api_key); +int neocities_list(const char *api_key, const char *path, neocities_filelist_t *out); +int neocities_delete(const char *api_key, const char **filenames, size_t count, char **response); +int neocities_upload(const char *api_key, const char **local_files, const char **remote_names, size_t count, char **response); // ------------------------- // Free functions @@ -36,4 +35,4 @@ int neocities_get_api_key(const char *user, const char *pass, char **api_key); void neocities_free_info(neocities_info_t *info); void neocities_free_filelist(neocities_filelist_t *list); -#endif // NEOCITIES_H \ No newline at end of file +#endif // NEOCITIES_H diff --git a/src/neogities.c b/src/neogities.c deleted file mode 100644 index e69de29..0000000