Custom QuantumSync/ShadowClient API:

Error and retry convention

Clients own retry policy from stable error-code categories. Request and domain errors (441x and 443x–445x) require a corrected request rather than a blind replay. Backend errors (446x) may be retried with bounded exponential backoff; internal errors (447x) should be surfaced rather than automatically replayed. A sync response with an unconfirmed transactionOutcome must be reconciled before replaying the request.

QuantumSync QuantumSyncRequestTypes:

start: authenticates and specifies an initial context. note: the id for start and updateContext is used to key a Dictionary[String:AnyRootedQuantumGraph]

ex)

{
    "type": "start",
    "id": "site",
    "appType":"BuildingStudio"
    "payload": {
        "authToken": "REDACTED",
        "ID": "ACAF9E07-5031-4BC2-A8C5-D2C6598D83DE",
        "from": "Site",
        "include": [
            "Site",
            "Building",
            "Floor",
            "Zone"
    ]
    }
}

updateContext: change the current context / graph in memory.

note: the previous graph/context can be returned from memory by using updateContext id: <previous id used in start or updateContext>. Up to 5 contexts can be loaded before prevention (error) or deleteContext message needed to free up loaded count to load a new context.

ex)

{
    "type": "updateContext",
    "id": "building",
    "payload": {
        "ID": "ACAF9E07-5031-4BC2-A8C5-D2C6598D83DE",
        "from": "Building",
        "include": [
            "Site",
            "Floor",
            "Zone",
            "Image",
            "Surface",
            "Adjacency",
            "System",
            "Quanta",
            "Manufacturer",
            "Equipment",
            "Property",
            "Location"
        ]
    }
}

deleteContext: delete/clear the context out of memory.

ex)

{
    "type": "deleteContext",
    "id": "building",
    "payload": {}
}

sync: create/update/delete QuantumObjects via a FlatGraphDiff as the payload.

Executing concurrent sync's is not allowed. If there is a sync already processing and another sync is requested before the response of the first sync is sent, then the 2nd symc will return an error saying there is a sync currently processing, and to wait until its finished before requesting another sync.

ex)

{
    "type": "sync",
    "id": "F5B6BC51-B991-440C-8ACB-B55C65FD7C24",
    "payload": {
        "added": [],
        "updated": [
            {
                "description": null,
                "ID": "80187B0B-CEEB-488A-A9B7-06784CFB0464",
                "longitude": null,
                "locationPropertyID": null,
                "elevation": null,
                "latitude": null,
                "address": null,
                "timeZone": null,
                "siteIDs": [
                    "7E7E04B4-8F32-4585-839D-E0EFC7BB3544"
                ],
                "weatherSourceIDs": [],
                "locked": false,
                "authGroupID": "A1EBEC59-D887-473F-A5C5-7CBD4ADB2556",
                "__typename": "Location",
                "name": "foo"
            }
        ],
        "removed": []
    }
}

syncEphemeral: create/update/delete QuantumObjects via a FlatGraphDiff as the payload, do not write them to the database,

and discard them at the end of the websocket session. ex)

{
    "type": "syncEphemeral",
    "id": "F5B6BC51-B991-440C-8ACB-B55C65FD7C24",
    "payload": {
        "added": [],
        "updated": [
            {
                "description": null,
                "ID": "80187B0B-CEEB-488A-A9B7-06784CFB0464",
                "longitude": null,
                "locationPropertyID": null,
                "elevation": null,
                "latitude": null,
                "address": null,
                "timeZone": null,
                "siteIDs": [
                    "7E7E04B4-8F32-4585-839D-E0EFC7BB3544"
                ],
                "weatherSourceIDs": [],
                "locked": false,
                "authGroupID": "A1EBEC59-D887-473F-A5C5-7CBD4ADB2556",
                "__typename": "Location",
                "name": "foo"
            }
        ],
        "removed": []
    }
}

propertyHistory: Get history data for a property & listen for updates.

ex)

{
    "type": "propertyHistory",
    "id": "propertyHistory1",
    "payload": {
        "propertyIDs": ["E585C3B8-F1E5-40D0-83A7-658B248DF103"],
        "startAt": "2024-01-01T00:00:00Z",
        "endAt": "2024-01-01T01:00:00Z",
        "resample": {
            "interval": {
                "to": "minutely",
                "reduceUsing": "avg",
                "fillUsing": "interpolate"
        },
        "pollIntervalSec": 60
    }
}

### `propertyHistoryStop`: Stop listening for property history updates
ex)
```json
{
    "type": "propertyHistoryStop",
    "id": "propertyHistory1"
}

writeHistory: Write historical data to a property

ex)

{
    "type": "writeHistory",
    "id": "writeHistory",
    "payload": {
        "histories": [
            {
                "propertyID": "E585C3B8-F1E5-40D0-83A7-658B248DF103",
                "time": "2024-01-01T00:00:00Z",
                "value": 5.0
            }
        ]
    }
}