Metadata-Version: 2.4
Name: dilnaka
Version: 0.0.3
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
```

To create the workspace AI instruction file explicitly after install:

```bash
dilnaka-sync-instructions --print-path
```

The SDK also attempts a best-effort sync the first time `Dilnaka(...)` is constructed in an application workspace. That creates `.github/instructions/dilnaka.instructions.md` when the current project root can be detected.

## Configure

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

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)
```

## 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}
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
}
```

## 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.

## AI workspace instructions

Python packaging does not provide a reliable cross-environment post-install hook for wheel installs, so the SDK ships its own instruction-file generator instead of trying to mutate arbitrary projects during `pip install`.

Use `dilnaka-sync-instructions` in install scripts when you need deterministic creation, or rely on the SDK's best-effort first-use sync when `Dilnaka(...)` is instantiated.
