port-sdk 0.1.0

# Port SDK (Rust)

Rust crate for interacting with the [Port](https://www.port.io/) REST APIs. The SDK aims to wrap the Swagger definition at `https://api.port.io/swagger/json` with type-safe request/response models, predictable error handling, and ergonomics that match the Rust ecosystem.

## Status

Actively under construction. See `TODO.md` for the current implementation plan.

## Getting Started

1. **Install Rust toolchain**  
   Use [`rustup`](https://www.rust-lang.org/tools/install) to install the latest stable toolchain.
2. **Clone the repo**  
   ```bash
   git clone https://github.com/port-experimental/port-sdk-rs.git
   cd port-sdk-rs
   ```
3. **Verify the code compiles**  
   ```bash
   cargo check
   ```

## Usage Guide

```rust,no_run
use port_sdk::{PortClient, PortConfig, auth::AuthStrategy};

# #[tokio::main]
# async fn main() -> Result<(), port_sdk::error::PortError> {
// Load from environment variables (`PORT_CLIENT_ID`, `PORT_CLIENT_SECRET`, etc.).
let client = PortClient::from_env()?;

// Or configure explicitly.
/*
let config = PortConfig::builder()
    .auth(AuthStrategy::StaticToken("my-api-token".into()))
    .build()?;
let client = PortClient::from_config(config)?;
*/

// Call resource helpers. Responses deserialize into typed structs or serde_json::Value.
let blueprints: serde_json::Value = client.get("/blueprints").await?;
println!("known blueprints: {blueprints}");
# Ok(())
# }
```

- Authentication helpers live under `port_sdk::auth`.
- High-level flows are available in `port_sdk::apis` (e.g., `apis::blueprints::list`).
- See `docs/usage.md` for end-to-end walkthroughs and troubleshooting tips.

## Crate Layout

- `src/lib.rs` – crate root re-exporting the public API surface.
- `src/client.rs` – HTTP client that wraps `reqwest` and applies authentication.
- `src/error.rs` – error types surfaced to SDK consumers.
- `src/types.rs` – placeholder for structs generated from the Swagger schema (to be implemented).
- `src/apis.rs` – placeholder for higher-level endpoint wrappers (to be implemented).
- `docs/` – developer-facing documentation (architecture, build, testing, release).
- `TODO.md` – detailed roadmap for completing the SDK.

## Development Workflow

1. Follow the tasks in `TODO.md` sequentially. Each task explains *why* it exists so newcomers can learn the rationale.
2. Keep the documentation under `docs/` updated when adding new functionality.
3. Run the standard cargo commands:
   ```bash
   cargo fmt
   cargo clippy --all-targets --all-features
   cargo test --all-features
   ```
4. When adding network calls, prefer dependency injection or test doubles for unit tests to avoid flaky integration runs.

## Configuration & Authentication

- Load configuration from a `.env` file or shell environment variables. Call `PortClient::from_env()` or `PortConfig::from_env()` to bootstrap defaults.
- Provide OAuth client credentials via `PORT_CLIENT_ID` and `PORT_CLIENT_SECRET` (optionally `PORT_TOKEN_URL`). The SDK automatically exchanges them for access tokens.
- Supply a pre-issued access token with `PORT_ACCESS_TOKEN` (or legacy `PORT_API_TOKEN`) if you manage tokens externally.
- Control the target region using `PORT_REGION` (`eu` default, `us` supported) or override with `PORT_BASE_URL`. Base URL defaults to the EU endpoint when not specified.
- Configure outbound proxies with `PORT_PROXY_URL` (falls back to `HTTP_PROXY` / `HTTPS_PROXY`) and optional `PROXY_AUTH_USERNAME` / `PROXY_AUTH_PASSWORD`.
- Tune request behaviour with `PORT_TIMEOUT` (milliseconds) and `PORT_MAX_RETRIES`. Disable retries by setting `PORT_RETRY_DISABLED=1`.
- Enable request tracing by setting `PORT_TRACING_ENABLED=1` when the crate is built with the `telemetry` feature.

### Testing with `.env`

1. Copy the skeleton file and fill in credentials:
   ```bash
   cp .env.example .env
   $EDITOR .env
   ```
2. Provide either `PORT_CLIENT_ID`/`PORT_CLIENT_SECRET` (plus overrides such as `PORT_TOKEN_URL`) or a pre-issued token via `PORT_ACCESS_TOKEN`.
3. Run `cargo test` to ensure the SDK can authenticate using the supplied values—end-to-end tests read from the environment at runtime.
4. For manual experiments, run snippets from the `examples/` directory (`cargo run --example ...`) or the code in [`docs/usage.md`](docs/usage.md); the runtime automatically loads `.env` via `dotenvy`.

## Documentation

Additional context lives in:

- `docs/architecture.md` – module responsibilities, data flow, and security guidelines.
- `docs/build_and_release.md` – end-to-end instructions for building, testing, and publishing the crate.
- `docs/testing_strategy.md` – recommended testing layers, including unit, integration, and contract testing.
- `CHANGELOG.md` – history of notable changes and release notes.
- `docs/feature_flags.md` – overview of optional crate features and how to enable them.
- `docs/logging.md` – tracing integration and safe logging practices.
- `docs/examples.md` – guide to the walkthroughs in the `examples/` directory.

## Releasing

High-level release checklist:

1. Ensure `cargo fmt`, `cargo clippy`, and `cargo test` pass on the main branch.
2. Update `CHANGELOG.md` (to be added) with notable changes.
3. Bump the crate version in `Cargo.toml`.
4. Follow `docs/build_and_release.md` for `cargo publish` preparation steps (audit, dry run, tagging).

## Contributing

Issues and pull requests are welcome. Please include tests and documentation updates for any new feature to keep the SDK reliable and easy to understand.

## Quick Links

- [Architecture](docs/architecture.md)
- [Usage Guide](docs/usage.md)
- [Testing Strategy](docs/testing_strategy.md)
- [Examples](examples/README.md)
- [Publishing Checklist](docs/publishing.md)
- [Parity with `port-js`](docs/parity_with_js.md)