vtx-sdk 0.1.2

Official SDK for developing VTX plugins using Rust and WebAssembly.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# vtx-sdk

[![Crates.io](https://img.shields.io/crates/v/vtx-sdk.svg)](https://crates.io/crates/vtx-sdk)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

**Official Rust SDK for developing VTX Project plugins.**

`vtx-sdk` provides safe, idiomatic Rust bindings for the VTX Host ABI. It abstracts away the complexity of the WebAssembly Component Model (`wit-bindgen`), allowing you to focus on building powerful video processing logic.

## ✨ Features

* **Type-Safe APIs**: Full Rust type support for database queries, HTTP handling, and file I/O.
* **Zero Boilerplate**: Use the `vtx_sdk::export!` macro to generate all necessary Wasm component exports.
* **Database Integration**: Built-in SQLite helpers with automatic JSON serialization/deserialization.
* **Helper Utilities**:
    * `ResponseBuilder` for fluent HTTP responses.
    * `UserBuilder` for easy auth context management.
    * `VtxError` for unified error handling.

## 📦 Installation

Add `vtx-sdk` to your plugin's `Cargo.toml`:

```toml
[dependencies]
vtx-sdk = "0.1.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
anyhow = "1.0"

[lib]
crate-type = ["cdylib"] # Essential for compiling to Wasm
````

## 🚀 Quick Start

Here is a minimal example of a VTX plugin:

```rust
use vtx_sdk::prelude::*;

// 1. Define your plugin structure
struct MyPlugin;

// 2. Export the component world
vtx_sdk::export!(MyPlugin);

// 3. Implement the Plugin trait
impl Plugin for MyPlugin {
    fn handle(req: HttpRequest) -> Result<HttpResponse, VtxError> {
        // Log to the host console
        println!("Received request: {} {}", req.method, req.path);

        // Return a JSON response
        ResponseBuilder::ok()
            .json(&serde_json::json!({
                "message": "Hello from VTX Plugin!",
                "path": req.path
            }))
            .build()
    }

    fn get_manifest() -> Result<Manifest, VtxError> {
        Ok(Manifest {
            id: "com.example.hello".to_string(),
            version: "0.1.0".to_string(),
            name: "Hello World Plugin".to_string(),
            description: "A simple example plugin".to_string(),
        })
    }

    // Optional: Declare database tables
    fn get_resources() -> Result<Vec<String>, VtxError> {
        Ok(vec![])
    }

    // Optional: SQL migrations
    fn get_migrations() -> Result<Vec<String>, VtxError> {
        Ok(vec![])
    }
}
```

## 🛠️ Build & Deploy

Plugins must be compiled to the `wasm32-wasip1` target.

### Prerequisites

```bash
rustup target add wasm32-wasip1
```

### Building with vtx-cli (Recommended)

The official CLI handles building, stripping, and packaging (`.vtx`) automatically.

```bash
vtx-cli build --package vtx-plugin-example
```

### Manual Build

If you are not using the CLI, you can build the raw Wasm file:

```bash
cargo build --release --target wasm32-wasip1
```

*Note: Raw Wasm files may need to be adapted using `wasm-tools` to work with the VTX runtime if not using `vtx-cli`.*

## 📚 Modules Overview

* **`db`**: Helpers for executing SQL queries and managing database transactions.

    * Example: `db::query("SELECT * FROM videos")`

* **`http`**: HTTP request/response types and builders.

* **`auth`**: Utilities for parsing headers and constructing `UserContext`.

* **`error`**: The `VtxError` enum maps internal errors to appropriate HTTP status codes (e.g., `VtxError::Unauthorized` -> 401).

## 📄 License

This project is licensed under the [Apache 2.0 License](https://www.google.com/search?q=LICENSE).