corteq-onepassword 0.1.5

# Developer Guide

This guide helps contributors get started with developing corteq-onepassword.

## Prerequisites

- **Rust 1.75+** - Install via [rustup](https://rustup.rs/)
- **Git** - For version control
- **1Password Service Account Token** (optional) - Only required for integration tests

## Getting Started

### Clone the Repository

```bash
git clone https://github.com/trendium-labs/corteq-onepassword.git
cd corteq-onepassword
```

### Build the Project

```bash
cargo build
```

The build script automatically downloads the 1Password SDK native library for your platform.

## Running Tests

### Unit Tests (no token required)

```bash
cargo test
```

### Integration Tests (requires token)

Set the environment variable and run:

```bash
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
export TEST_SECRET_REF="op://vault/item/field"  # A secret you have access to
cargo test
```

### Doc Tests

```bash
cargo test --doc
```

### All Tests with All Features

```bash
cargo test --all-features
```

## Code Style

### Formatting

Code is formatted with `rustfmt`. The pre-commit hook runs this automatically, but you can run it manually:

```bash
cargo fmt
```

Check formatting without modifying files:

```bash
cargo fmt -- --check
```

### Linting

Run clippy for lints:

```bash
cargo clippy --all-features
```

## Feature Flags

| Feature    | Description                                        |
| ---------- | -------------------------------------------------- |
| `blocking` | Enables `connect_blocking()` for synchronous usage |
| `tracing`  | Enables tracing spans for observability            |

Build with features:

```bash
cargo build --features blocking,tracing
```

## Security Guidelines

When contributing, follow these security practices:

1. **Never log secrets** - Use `expose_secret()` only when passing to consumers
2. **Don't print secret values** - Print length in examples/tests
3. **Use `SecretString`** - All sensitive data should use secure wrappers
4. **Validate inputs** - Check token/reference formats before use

## Documentation

Generate and view documentation:

```bash
cargo doc --open
```

## Troubleshooting

### Build Fails: Library Download

If the native library fails to download during build:

1. Check your internet connection
2. Verify the build script can access GitHub releases
3. Check `build.rs` for the expected SDK version

### Tests Fail: Missing Token

Integration tests are skipped without `OP_SERVICE_ACCOUNT_TOKEN`. This is expected behavior.

## Updating the 1Password SDK

When a new version of the 1Password SDK is released on PyPI, follow these steps to update the bundled native libraries.

### Files to Update

Three files contain version information that must stay in sync:

| File                       | Line | Variable      | Example     |
| -------------------------- | ---- | ------------- | ----------- |
| `build.rs`                 | 13   | `SDK_VERSION` | `"0.3.2"`   |
| `scripts/download-libs.sh` | 11   | `SDK_VERSION` | `"0.3.2"`   |
| `src/ffi/bindings.rs`      | 50   | `sdk_version` | `"0030201"` |

### SDK Version Format

The `sdk_version` in `bindings.rs` uses a packed numeric format: `"XXXYYBB"`

- `XXX` = major version (zero-padded to 3 digits)
- `YY` = minor version (zero-padded to 2 digits)
- `BB` = build number (always `01` for releases)

**Examples:**

| SDK Version | sdk_version String |
| ----------- | ------------------ |
| 0.3.2       | `"0030201"`        |
| 0.4.0       | `"0040001"`        |
| 1.0.0       | `"1000001"`        |
| 1.2.3       | `"1020301"`        |

### Update Process

1. **Check for new versions**

   Visit https://pypi.org/project/onepassword-sdk/ to see the latest release.

2. **Update version constants**

   Edit the three files listed above with the new version number.

   ```bash
   # Example: Updating from 0.3.2 to 0.4.0

   # build.rs
   const SDK_VERSION: &str = "0.4.0";

   # scripts/download-libs.sh
   SDK_VERSION="0.4.0"

   # src/ffi/bindings.rs (in InitClientParams)
   sdk_version: "0040001".to_string(),
   ```

3. **Download new libraries**

   Run the download script to fetch libraries for all platforms:

   ```bash
   ./scripts/download-libs.sh
   ```

   This downloads from PyPI, verifies SHA256 checksums, and extracts to `src/libs/`.

4. **Verify the update**

   ```bash
   cargo clean
   cargo build
   cargo test
   ```

5. **Commit all changes**

   Include both source changes and the updated binary libraries:

   ```bash
   git add build.rs scripts/download-libs.sh src/ffi/bindings.rs src/libs/
   git commit -m "chore: update 1Password SDK to X.Y.Z"
   ```

### Troubleshooting

**Download script fails:**

- Ensure `curl`, `jq`, `unzip`, and `sha256sum` are installed
- Check that PyPI is accessible from your network

**Build fails after update:**

- The SDK API may have changed; check 1Password release notes
- Verify the `sdk_version` format matches what the native library expects

**Tests fail:**

- New SDK versions may have different error messages or behavior
- Review test assertions against new SDK behavior

## Questions?

Open an issue on GitHub if you have questions or run into problems.