Metadata-Version: 2.4
Name: icakad
Version: 0.1.4
Summary: Utilities and tools for my apis and other life hacks.
Author: icakad
License: MIT License
        
        Copyright (c) 2024 icakad
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS 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.
        
Project-URL: Homepage, https://linkove.icu/
Project-URL: Repository, https://github.com/icakad97/icakad
Keywords: icakad
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# icakad

Lightweight Python client for managing short links hosted on the [linkove.icu](https://linkove.icu) worker.  
The package exports a small set of helpers that wrap the service API so automations and scripts can add, edit, delete, or list slugs without hand-crafting HTTP requests.

## Highlights

- Minimal footprint: only depends on `requests`
- Module-level configuration for base URL, bearer token, and debug logging
- Uniform response handling that normalises the `list` endpoint payload

## Installation

```bash
pip install icakad
```

Install `requests` separately if it is not already available in your environment.

## Quick Start

```python
from icakad import add_link, edit_link, delete_link, list_links
from icakad import shorturl

# Configure credentials and optional debugging up front
shorturl.HEADERS["Authorization"] = "Bearer <your-token>"
shorturl.DEBUG = False

# Create or overwrite a slug
add_link(slug="docs", url="https://example.com/docs")

# Update an existing slug
edit_link(slug="docs", new_url="https://example.com/documentation")

# Fetch the full catalogue
links = list_links()
print(links.get("docs"))

# Remove a slug
delete_link(slug="docs")
```

Each helper returns the JSON body produced by the worker. Inspect it for status codes, error messages, or additional metadata.

## API Reference

All helpers live in `icakad.shorturl` and are re-exported at the package root for convenience.

| Function | Description |
| --- | --- |
| `add_link(slug: str, url: str) -> dict` | Create or overwrite a slug with the target URL. |
| `edit_link(slug: str, new_url: str) -> dict` | Update an existing slug. Backed by `POST /api/<slug>`. |
| `delete_link(slug: str) -> dict` | Delete the slug via `DELETE /api/<slug>`. |
| `list_links() -> dict[str, str]` | Retrieve all slugs. Normalises both list-style and `{"items": [...]}` payloads. |

## Configuration

Tweak behaviour by adjusting attributes on `icakad.shorturl`:

- `BASE`: API root (default `https://linkove.icu`). Point this elsewhere for staging or local testing.
- `HEADERS`: Dictionary of headers supplied with every request. Set the bearer token here.
- `DEBUG`: When `True`, prints HTTP status codes and JSON responses to stdout.

Feel free to override the module-level `requests` usage with your own session or retry logic by wrapping these helpers.

## Error Handling Tips

- Wrap calls in `try/except requests.RequestException` for transport-level issues.
- Validate mandatory keys in the returned JSON before relying on them.
- Enable `DEBUG` when tuning your worker or troubleshooting authentication.

## Development

Clone the repository and install it in editable mode:

```bash
pip install -e .
```

Build packages:

```bash
python -m build
```

Run any tests or scripts you add:

```bash
python -m pytest
```

Contributions that improve ergonomics (e.g., async helpers, richer error handling) are welcome.
