Metadata-Version: 2.4
Name: dilnaka
Version: 0.0.7
Summary: Python SDK for Dilnaka file uploads
Project-URL: Homepage, https://dilnaka.tsnc.tech
Author: Dilnaka
License: MIT
Keywords: dilnaka,presigned-url,s3,sdk,uploads
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# Dilnaka Python SDK

Python SDK for uploading files through the Dilnaka Upload API.

The SDK reads configuration from explicit arguments first, then environment variables. It requests a presigned S3 upload URL from your Dilnaka backend, uploads the file directly to S3, and calls the completion endpoint.

## Install

```bash
pip install dilnaka
```

## Configure

You can pass configuration directly to `Dilnaka(...)`, or set environment variables for your application.

Configuration precedence is:

1. Explicit constructor arguments such as `Dilnaka(base_url=...)`
2. Existing process environment variables such as `DILNAKA_BASE_URL`
3. Values loaded from `.env`
4. Built-in defaults

If you use a `.env` file, create it in your application project:

```env
DILNAKA_API_KEY=dlk_dev_your_api_key_here
DILNAKA_BASE_URL=https://dilnaka.tsnc.tech
DILNAKA_TIMEOUT=60
```

`DILNAKA_BASE_URL` defaults to `https://dilnaka.tsnc.tech` and `DILNAKA_TIMEOUT` defaults to `60`.

## Basic upload

```python
from dilnaka import Dilnaka

client = Dilnaka()

uploaded = client.upload("./test-upload.txt")

print(uploaded.id)
print(uploaded.key)
print(uploaded.status)
```

## Explicit configuration

```python
from dilnaka import Dilnaka

client = Dilnaka(
    api_key="dlk_dev_your_api_key_here",
    base_url="https://dilnaka.tsnc.tech",
)

uploaded = client.upload("./avatar.png", folder="avatars")
print(uploaded)
```

## Request a file access URL

Use `get_file_access_url(...)` when you need a URL for downloading or opening a file.

```python
from dilnaka import Dilnaka

client = Dilnaka()

access = client.get_file_access_url("file_123")

print(access.file_id)
print(access.url)
print(access.expires_in)
print(access.is_temporary)
```

Pass `expires_in` to request a temporary URL from the backend:

```python
from dilnaka import Dilnaka

client = Dilnaka()

temporary_access = client.get_file_access_url(
  "file_123",
  expires_in=600,
)

print(temporary_access.url)
print(temporary_access.expires_in)   # 600
print(temporary_access.is_temporary) # True
```

`expires_in` must be greater than `0`. If you omit it, the SDK requests the default access URL returned by your backend.

The method returns a `FileAccessUrl` object with:

- `file_id`: Dilnaka file ID
- `url`: Access URL returned by the API
- `expires_in`: Expiration time in seconds when the backend returns a temporary URL
- `is_temporary`: `True` when the backend marks the URL as temporary, or when an expiration is present

## Expected backend endpoints

The SDK expects your Caspian backend to expose:

```txt
POST /v1/uploads/presign
POST /v1/uploads/complete
GET  /v1/files
GET  /v1/files/{file_id}
GET  /v1/files/{file_id}/access-url
DELETE /v1/files/{file_id}
```

### Presign response shape

```json
{
  "fileId": "clx_file_id",
  "fileKey": "uploads/2026/05/clx_file_id-test.txt",
  "uploadUrl": "https://s3-presigned-url",
  "expiresIn": 300,
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  }
}
```

### Complete response shape

```json
{
  "fileId": "clx_file_id",
  "status": "uploaded",
  "key": "uploads/2026/05/clx_file_id-test.txt",
  "originalName": "test.txt",
  "contentType": "text/plain",
  "size": 94,
  "publicUrl": null
}
```

### Access URL response shape

```json
{
  "fileId": "clx_file_id",
  "url": "https://signed-download-url",
  "expiresIn": 600,
  "isTemporary": true
}
```

When a temporary URL is requested, the SDK sends:

```txt
GET /v1/files/{file_id}/access-url?expiresIn=600
```

## Security model

The SDK never receives AWS credentials. It only receives a temporary presigned upload URL from your Dilnaka backend.

Your backend remains responsible for API key validation, scope checking, file validation, S3 key generation, metadata persistence, and upload completion verification.
