From 85929ced9b2776728b4a53d0363209610c6886d7 Mon Sep 17 00:00:00 2001
From: robert <robert@ownwire>
Date: Sun, 4 Jan 2026 21:29:13 +0000
Subject: [PATCH] Add README (docs covering SDK and example cli app) and
 LICENSE files

---
 LICENSE   |  21 ++++++++
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..2d469a3
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ownwire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..62b256d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# 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.