Metadata-Version: 2.4
Name: lyng-sdk
Version: 1.0.0
Summary: Official Python SDK for the lyng URL shortener API
Project-URL: Homepage, https://lyng.my.id
Project-URL: Documentation, https://lyng.my.id/docs
Project-URL: Repository, https://github.com/hellolyng/LyngSDK-Python
Project-URL: Issues, https://github.com/hellolyng/LyngSDK-Python/issues
License: MIT
Keywords: lyng,sdk,url-shortener
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# lyng-sdk

Official Python SDK for the [lyng](https://lyng.my.id) URL shortener API.

[![PyPI version](https://img.shields.io/pypi/v/lyng-sdk)](https://pypi.org/project/lyng-sdk)
[![license](https://img.shields.io/pypi/l/lyng-sdk)](LICENSE)
[![python](https://img.shields.io/pypi/pyversions/lyng-sdk)](https://pypi.org/project/lyng-sdk)

## Installation

```bash
pip install lyng-sdk
```

Requires Python 3.10 or later.

## Quick start

```python
from lyng import Lyng

lyng = Lyng(api_key="lk_your_key")

link = lyng.links.create(url="https://example.com")
print(link.short_url)  # https://lyng.my.id/abc123
```

## Getting an API key

1. Sign up at [lyng.my.id](https://lyng.my.id)
2. Go to **Dashboard → Developer**
3. Create a project and click **Create key**

Store your key in an environment variable rather than hardcoding it:

```python
import os
from lyng import Lyng

lyng = Lyng(api_key=os.environ["LYNG_API_KEY"])
```

## Reference

### `lyng.links.create(url, slug=None)`

Shortens a URL and returns the new short link.

```python
link = lyng.links.create(url="https://example.com")
print(link.short_url)  # https://lyng.my.id/abc123
print(link.slug)       # abc123

# Custom slug — Premium accounts only
link = lyng.links.create(url="https://example.com", slug="my-link")
```

**Returns** `CreatedLink`

| Field       | Type  | Description                          |
|-------------|-------|--------------------------------------|
| `short_url` | `str` | The complete short URL, ready to share. |
| `slug`      | `str` | The short code at the end of the URL. |

---

### `lyng.links.list()`

Returns your 100 most recently created links, newest first.

```python
links = lyng.links.list()

for link in links:
    print(link.short_url, link.clicks)
```

**Returns** `list[Link]`

| Field          | Type  | Description                              |
|----------------|-------|------------------------------------------|
| `slug`         | `str` | The unique short code.                   |
| `short_url`    | `str` | The full short URL.                      |
| `original_url` | `str` | The original long URL.                   |
| `clicks`       | `int` | Number of times the link was visited.    |
| `created_at`   | `str` | ISO 8601 creation timestamp.             |

---

## Async support

Use `AsyncLyng` for async/await code (FastAPI, asyncio, etc.):

```python
import asyncio
from lyng import AsyncLyng

async def main():
    async with AsyncLyng(api_key="lk_your_key") as lyng:
        link = await lyng.links.create(url="https://example.com")
        print(link.short_url)

asyncio.run(main())
```

---

## Context managers

Both clients support context managers to ensure the HTTP connection is closed properly:

```python
# Sync
with Lyng(api_key="lk_your_key") as lyng:
    link = lyng.links.create(url="https://example.com")

# Async
async with AsyncLyng(api_key="lk_your_key") as lyng:
    link = await lyng.links.create(url="https://example.com")
```

---

## Error handling

All API errors raise `LyngError` with a `status` code and a message.

```python
from lyng import Lyng, LyngError

lyng = Lyng(api_key="lk_your_key")

try:
    link = lyng.links.create(url="https://example.com")
except LyngError as e:
    print(e.status)  # 429
    print(str(e))    # "Link limit reached."
```

**Common status codes**

| Status | Meaning |
|--------|---------|
| `400`  | Bad request — missing or invalid fields. |
| `401`  | Invalid or missing API key. |
| `403`  | Feature not available on your plan. |
| `409`  | Slug already taken. |
| `429`  | Free account link limit (60) reached. |
| `500`  | Server error — try again later. |

---

## Links

- [API documentation](https://lyng.my.id/docs)
- [PyPI package](https://pypi.org/project/lyng-sdk)
- [GitHub](https://github.com/hellolyng/LyngSDK-Python)
- [Report an issue](https://github.com/hellolyng/LyngSDK-Python/issues)

## License

MIT
