Metadata-Version: 2.4
Name: cloud-task-utils
Version: 1.0.0
Summary: Reusable helper library for the Cloud Task Manager serverless application.
Author-email: Cloud Task Manager Project <project@example.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/cloud-task-manager
Project-URL: Repository, https://github.com/your-org/cloud-task-manager
Project-URL: Documentation, https://github.com/your-org/cloud-task-manager#readme
Keywords: aws,lambda,dynamodb,serverless,cloud
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.6; extra == "dev"

# cloud-task-utils

A lightweight, stdlib-only Python utility library for the Cloud Task Manager
serverless application.  Designed to run inside AWS Lambda without any
additional dependencies.

## Installation

```bash
pip install cloud-task-utils
```

## Quick Start

```python
from cloud_task_utils import TaskUtils, ResponseBuilder, ValidationError

utils = TaskUtils()
resp  = ResponseBuilder()

# Generate a unique task ID
task_id = utils.generate_task_id()
print(task_id)  # e.g. "550e8400-e29b-41d4-a716-446655440000"

# Validate user input — raises ValidationError on failure
try:
    name = utils.validate_task_name("  Write unit tests  ")
    print(name)  # "Write unit tests"
except ValidationError as exc:
    print(exc)

# Build an API Gateway v2 response
response = resp.created({"task_id": task_id, "message": "Task created."})
# {"statusCode": 201, "headers": {...}, "body": "{...}"}

# Calculate a DynamoDB TTL (7 days from now)
ttl = utils.ttl_from_days(7)
```

## API

### `TaskUtils`

| Method                       | Description                                        |
|------------------------------|----------------------------------------------------|
| `generate_task_id()`         | Returns a UUID v4 string                          |
| `validate_task_name(name)`   | Validates and strips a task name; raises on error |
| `parse_priority(raw)`        | Normalises priority to low/medium/high/critical   |
| `utc_now_iso()`              | Returns current UTC time as ISO 8601 string       |
| `ttl_from_days(days)`        | Returns Unix epoch TTL `days` from now            |
| `format_task_summary(task)`  | Returns a readable single-line task summary       |

### `ResponseBuilder`

| Method                  | Status | Description                    |
|-------------------------|--------|--------------------------------|
| `ok(body)`              | 200    | Standard success               |
| `created(body)`         | 201    | Resource created               |
| `bad_request(message)`  | 400    | Validation failure             |
| `not_found(message)`    | 404    | Resource not found             |
| `server_error(message)` | 500    | Internal error                 |

All responses include CORS headers compatible with S3-hosted frontends.

### `ValidationError`

Raised by `TaskUtils` when caller input fails validation.  The message is
safe to surface directly in API error responses.

## Licence

MIT
