From 407f49692c09f9c45098dc7c3f644bc5ec2eee4d Mon Sep 17 00:00:00 2001
From: ccurran <ccurran@onramp-solutions.com>
Date: Fri, 6 Mar 2026 17:02:58 -0500
Subject: [PATCH] Add README

---
 README | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..efd5dea
--- /dev/null
+++ b/README
@@ -0,0 +1,208 @@
+# OnRamp SDK
+
+The **OnRamp SDK** provides supported libraries for integrating external applications with the OnRamp platform.
+
+Current capabilities include:
+
+* Accessing the **OnRamp API**
+* Receiving **real-time Shop Monitor events** via WebSockets
+* Running **registered OnRamp API queries**
+
+The SDK is distributed via **NuGet** to allow deterministic versioning and updateable integrations.
+
+This approach enables applications to interact with OnRamp **without requiring direct database access**, which is particularly important for hosted or cloud environments.
+
+---
+
+# Installation
+
+Add the OnRamp SDK NuGet repository:
+
+```bash
+dotnet nuget add source https://git.onramp-solutions.com/api/packages/OnRampSDK/nuget/index.json --name onrampsdk
+```
+
+After adding the source, packages will be available under:
+
+```
+Package Source: onrampsdk
+```
+
+Packages can then be installed using standard NuGet workflows in Visual Studio or via the .NET CLI.
+
+---
+
+# Overview
+
+Applications integrating with OnRamp typically perform the following steps:
+
+1. Connect to the **OnRamp API**
+2. Connect to the **OnRamp WebSocket service**
+3. Register a **Socket ID**
+4. Receive **Shop Monitor events**
+5. Execute **API queries** to retrieve or process related data
+
+Incoming WebSocket messages function similarly to **interrupt events**. They are delivered with minimal latency when Shop Monitor activity occurs.
+
+Example event types include:
+
+* Work Order Login
+* Work Order Logout
+* Cycle Start
+* Cycle Complete
+* Device button events
+
+Applications can respond to these events by retrieving additional information through the OnRamp API.
+
+---
+
+# Example Architecture
+
+A typical implementation:
+
+* Launches an application (console app, service, or background process)
+* Connects to the OnRamp API
+* Establishes a WebSocket connection
+* Registers a **Socket ID**
+* Waits indefinitely for incoming Shop Monitor events
+
+The application remains active and processes events until it is terminated.
+
+Multiple deployment models are possible:
+
+* A **single application handling all devices**
+* Applications **per device**
+* Applications **per event type**
+
+---
+
+# Shop Monitor Integration
+
+Shop Monitor devices trigger events through a configured **Socket ID**.
+
+To configure a device:
+
+1. Open **S1280 – Device Shop Monitor**
+2. Set the **Process ID / Socket ID** to the value expected by the application
+3. The application registers with this same Socket ID
+
+Any application listening with that Socket ID will receive the event messages.
+
+---
+
+# API Queries
+
+API queries must be registered in:
+
+```
+S5011 – API Queries
+```
+
+Supported query types:
+
+* `SELECT`
+* `UPDATE`
+
+In most integrations, **SELECT queries are sufficient**. UPDATE queries should be used cautiously.
+
+---
+
+# Query Parameters
+
+Queries use **Handlebars-style parameters**.
+
+Example:
+
+```sql
+SELECT woo_oper, woo_qty_rep
+FROM wo_oper
+WHERE woo_nbr = '{{p:wonum}}'
+```
+
+`p:wonum` is a parameter passed by the client application.
+
+---
+
+# Example Query Execution
+
+Example code for executing a query through the API:
+
+```vb
+' Get all operations for a work order
+Dim allOpsArgs As New Dictionary(Of String, String)
+allOpsArgs.Add("wonum", woNum)
+
+' QL-10000006
+Dim rstDataAllOps = api.runQuery("QL-10000006", allOpsArgs)
+
+If rstDataAllOps.RecordCount > 0 Then
+    Do Until rstDataAllOps.EOF
+        Console.WriteLine(rstDataAllOps("woo_oper") + " - QtyRep:" & rstDataAllOps("woo_qty_rep"))
+        rstDataAllOps.MoveNext()
+    Loop
+End If
+```
+
+The returned result set exposes a familiar **recordset-style interface**, allowing iteration using:
+
+* `RecordCount`
+* `EOF`
+* `MoveNext()`
+* Column access via field name
+
+---
+
+# Query Performance Recommendations
+
+For optimal performance:
+
+* Avoid returning very large datasets
+* Do not use `SELECT *`
+* Specify explicit column names
+* Limit queries to only the data required by the application
+
+Example (recommended):
+
+```sql
+SELECT pt_part, pt_desc
+FROM pt_mstr
+```
+
+Example (not recommended):
+
+```sql
+SELECT *
+FROM pt_mstr
+```
+
+---
+
+# Use Cases
+
+Common uses for the SDK include:
+
+* Shop Monitor automation
+* Production event processing
+* Device integrations
+* External analytics services
+* Integration with external systems
+* Cloud-hosted integrations where database access is unavailable
+
+---
+
+# Future Expansion
+
+The SDK is designed to support additional OnRamp platform integration capabilities over time, including:
+
+* Additional event channels
+* Extended API functionality
+* Additional integration services
+
+---
+
+If you'd like, I can also help you add two sections that **good SDK repos almost always include but people forget**:
+
+* **Minimal working example (full program)**
+* **Event message structure / enum definitions**
+
+Those make the repo dramatically easier for developers to adopt.