From bfa4b54b719aedcf8557aa0937760af837614c69 Mon Sep 17 00:00:00 2001
From: Doug <git@pixlwave.uk>
Date: Sat, 28 Jan 2023 09:51:56 +0000
Subject: [PATCH] Add a basic getting started guide.

---
 README.md               |  4 ++
 docs/Getting Started.md | 89 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 docs/Getting Started.md

diff --git a/README.md b/README.md
index 601340b..2ea8f80 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 This repository is a Swift Package for distributing releases of the [Matrix Rust SDK](https://github.com/matrix-org/matrix-rust-sdk). It provides the Swift source code packaged in a format understood by the Swift package manager, and depends on a pre-compiled binary release of the underlying Rust code published from [Matrix Rust SDK](https://github.com/matrix-org/matrix-rust-sdk).
 
+## Usage
+
+For more information about using the package, please read the [Getting Started](docs/Getting%20Started.md) guide.
+
 ## Releasing
 
 Whenever a new release of the underlying components is available, we need to tag a new release in this repo to make them available to Swift components. 
diff --git a/docs/Getting Started.md b/docs/Getting Started.md
new file mode 100644
index 0000000..252a4fd
--- /dev/null
+++ b/docs/Getting Started.md	
@@ -0,0 +1,89 @@
+# Getting Started
+
+The following instructions give a brief overview of using the Matrix Rust SDK from Swift. You can find more information about the API by browsing the [FFI crate](https://github.com/matrix-org/matrix-rust-sdk/tree/main/bindings/matrix-sdk-ffi/src) in the SDK's repository. In its current state, many of the calls to the SDK will block the thread that they're called on. You can determine this by looking for functions that use `RUNTIME.block_on` in their implementation. This is temporary and will be addressed in the future via [async support in Uniffi](https://github.com/mozilla/uniffi-rs/pull/1409).
+
+Please note: The Swift components for the Rust SDK are unstable meaning that the API could change at any point.
+
+
+### Project setup
+
+Add https://github.com/matrix-org/matrix-rust-components-swift to your project as a Swift package.
+
+### Usage
+
+First we need to authenticate the user.
+
+```swift
+import MatrixRustSDK
+
+// Create an authentication service to streamline the login process.
+let service = AuthenticationService(basePath: URL.applicationSupportDirectory.path(), passphrase: nil)
+
+// Configure the service for a particular homeserver.
+// Note that we can pass a server name (the second part of a Matrix user ID) instead of the direct URL.
+// This allows the SDK to discover the homeserver's well-known configuration for OIDC and Sliding Sync support.
+try service.configureHomeserver(serverName: "matrix.org")
+
+// Login through the service which creates a client.
+let client = try service.login(username: "alice", password: "secret", initialDeviceName: nil, deviceId: nil)
+
+let session = try client.session()
+// Store the session in the keychain.
+```
+
+Or, if the user has previously authenticated we can restore their session instead.
+
+```swift
+// Get the session from the keychain.
+let session = …
+
+// Build a client for the homeserver.
+let client = try ClientBuilder()
+    .basePath(path: URL.applicationSupportDirectory.path())
+    .homeserverUrl(url: session.homeserverUrl)
+    .build()
+
+// Restore the client using the session.
+try client.restoreSession(session: session)
+```
+
+Next we need to start the client and listen for updates. The following code does so using syncv2.
+
+```swift
+class ClientListener: ClientDelegate {
+    /// The user's list of rooms.
+    var rooms = [Room]()
+    
+    func didReceiveSyncUpdate() {
+        // Update the user's room list on each sync response.
+        self.rooms = client.rooms()
+    }
+    
+    func didReceiveAuthError(isSoftLogout: Bool) {
+        // Ask the user to reauthenticate.
+    }
+    
+    func didUpdateRestoreToken() {
+        let session = try? client.session()
+        // Update the session in the keychain.
+    }
+}
+
+// Listen to updates from the client.
+let listener = ClientListener()
+client.setDelegate(delegate: listener)
+
+// Start the client using syncv2.
+client.startSync(timelineLimit: 20)
+```
+
+Finally we can send messages into a room (with built in support for markdown).
+
+```swift
+// Create the message content from a markdown string.
+let message = messageEventContentFromMarkdown(md: "Hello, World!")
+
+// Send the message content to the first room in the list.
+try listener.rooms.first?.send(msg: message, txnId: UUID().uuidString)
+```
+