ownwire-go-sdk/README.md

# Ownwire Go SDK

A minimal Go SDK for connecting to an Ownwire backend over WebSockets, plus a small CLI example that demonstrates the SDK end-to-end.

The SDK handles:
- session creation and resumption
- cryptographic handshake
- encrypted message send/receive
- ordered delivery via sequence numbers

The CLI is intentionally simple and exists only as a working example.

---

## Installation

Add the module to your project:

```sh
go get ownwire.net/ownwire-sdk
```

Then import it in your code:

```go
import sdk "ownwire.net/ownwire-sdk"
```

---

## Using the SDK

### Creating a client and connecting

```go
client := sdk.NewClient(sdk.ClientOptions{
	Url: "ws://localhost:8080/ownwire",
})
```

To connect and create a **new session**:

```go
ctx := context.Background()
err := client.Connect(ctx, "")
if err != nil {
	log.Fatal(err)
}
```

To **resume an existing session**, pass the session ID:

```go
err := client.Connect(ctx, "cb653f53-6f7d-4aeb-ba0d-d2b17c290d8a")
```

---

### Receiving messages

The SDK uses channels in a Go-idiomatic way.

```go
for ev := range client.Events() {
	switch ev.Kind {
	case sdk.EventOpened:
		fmt.Println("connection opened")

	case sdk.EventMessage:
		fmt.Println("received:", ev.Message.Content)

	case sdk.EventError:
		log.Println("error:", ev.Err)

	case sdk.EventClosed:
		fmt.Println("connection closed")
	}
}
```

All messages delivered via `EventMessage` are already decrypted.

---

### Sending messages

```go
err := client.Send(ctx, "hello world", "")
if err != nil {
	log.Println("send failed:", err)
}
```

Messages are automatically encrypted once the session handshake is complete.

---

### Closing the connection

```go
client.Close()
```

---

## Example CLI

The repository includes a small CLI app that demonstrates the SDK working against a real Ownwire backend.

### Building the CLI

From the repository root:

```sh
go build -o ownwire-cli ./example/cli
```

### Running the CLI

```sh
./ownwire-cli -url ws://localhost:8080/ownwire
```

To resume an existing session:

```sh
./ownwire-cli -url ws://localhost:8080/ownwire -resume <session-id>
```

### What the CLI demonstrates

- dialing an Ownwire WebSocket endpoint
- creating or resuming a session
- printing incoming messages
- sending stdin lines as encrypted messages
- clean shutdown on Ctrl-C

The CLI is intentionally minimal and meant only as a reference implementation.

---

## Notes

- The SDK exposes only a small, stable API (`Client`, `Event`, `Message`).
- Internal protocol and crypto helpers are intentionally not documented as part of the public API.
- Unit tests cover handshake, crypto, and client behavior without requiring a server.