@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
main
claude/smbcloud-github-app-k9641p development feature/apps feature/build-release feature/ci-docs feature/ci-ruby-gems feature/cicd feature/completion feature/dist-nuget feature/fix-ci-sdk-pypi-rubygem feature/fix-clippy-on-stable-channel feature/fix-deployment-script feature/github-email feature/gresiq-v1 feature/project-new-structure feature/rsync-deploy feature/ruby-runner feature/sdk-npm feature/sdk-workflows feature/smbcloud-cli-release-npm feature/smbcloud-deploy feature/wasm main release/v0.7.4
mdx 83 lines 2.99 KB
Raw
1 # GresIQ
2
3 GresIQ is the managed data layer for your app — a document store built on
4 PostgreSQL. You store and query JSON documents through a small REST gateway,
5 authenticated with an API key and secret, so there is no database to run
6 yourself.
7
8 ## What you can do
9
10 - Store JSON documents in named collections
11 - Upsert by a natural key, or append documents that get a generated id
12 - Query a collection with a containment filter, ordering, and a limit
13 - Run simple counts and group-by aggregates over a collection
14
15 ## How it fits together
16
17 Each GresIQ app gets an API key and secret — the data-plane credential — and
18 reaches its data through the document gateway. There is no raw database
19 connection to manage. Documents are grouped into **collections**, and each
20 document is addressed by a **key** within its collection. The platform never
21 interprets a document's shape; what the fields mean lives in your app.
22
23 ## The document gateway
24
25 Every request authenticates with the `X-Gresiq-Api-Key` and
26 `X-Gresiq-Api-Secret` headers and targets a collection:
27
28 - `POST /gresiq/v1/collections/<collection>` — store a document. Send
29 `{ "key": "<id>", "doc": { ... } }` to upsert on that key, or omit `key` to
30 append a document with a generated id.
31 - `GET /gresiq/v1/collections/<collection>` — list documents, optionally with a
32 `filter` (JSON containment), an `order` (`created_at` or `updated_at`), and a
33 `limit`.
34 - `GET /gresiq/v1/collections/<collection>/<key>` — fetch one document.
35 - `PATCH /gresiq/v1/collections/<collection>/<key>` — shallow-merge into a document.
36 - `DELETE /gresiq/v1/collections/<collection>/<key>` — remove one document.
37 - `POST /gresiq/v1/collections/<collection>/aggregate` — count, or group by a
38 single top-level field.
39
40 ## From Rust
41
42 The `smbcloud-gresiq-sdk` crate wraps the gateway. Build a client from your
43 environment and credentials, then upsert and query documents — the base URL is
44 resolved from the environment, so you never hardcode a host:
45
46 ```rust
47 use smbcloud_gresiq_sdk::{DocumentQuery, Environment, GresiqClient, GresiqCredentials};
48 use serde_json::json;
49
50 let client = GresiqClient::from_credentials(
51 Environment::Production,
52 GresiqCredentials { api_key: "your-key", api_secret: "your-secret" },
53 );
54
55 // Upsert a document keyed by "device-1".
56 client
57 .upsert_document(
58 "devices",
59 Some("device-1"),
60 &json!({ "label": "Edge 1", "status": "online" }),
61 )
62 .await?;
63
64 // Query the collection — only the documents matching the filter come back.
65 let online = client
66 .get_collection::<serde_json::Value>(
67 "devices",
68 &DocumentQuery {
69 filter: Some(json!({ "status": "online" })),
70 ..Default::default()
71 },
72 )
73 .await?;
74 ```
75
76 Each returned `GresiqDocument` carries the stored `doc` plus its `key` and
77 timestamps.
78
79 ## Getting started
80
81 1. Create a GresIQ app and copy its API key and secret.
82 2. Pick a collection name and POST your first document.
83 3. Read it back with a GET, or reach it from the SDK in your app.