@centia-io/sdk 0.0.26 → 0.0.28

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MapCentia ApS
+
+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.

package/README.md

@@ -0,0 +1,288 @@
+# @centia-io/sdk
+
+TypeScript/JavaScript client SDK for Centia GC2. It provides:
+
+- Authentication helpers:
+  - CodeFlow (OAuth 2.0 Authorization Code + PKCE) for browser apps
+  - PasswordFlow for trusted/CLI/server environments
+- Data access:
+  - Sql: Execute parameterized SQL
+  - Rpc: Call JSON-RPC methods
+  - createApi: A tiny type-safe helper that maps TypeScript interfaces to JSON‑RPC calls
+
+This README focuses on CodeFlow, PasswordFlow, Sql, Rpc and Api.ts (createApi).
+
+## Installation
+
+- npm: `npm install @centia-io/sdk`
+- pnpm: `pnpm add @centia-io/sdk`
+- yarn: `yarn add @centia-io/sdk`
+
+Requirements:
+- Browser or Node.js 18+ (for global `fetch`).
+- An accessible GC2 host URL and client credentials.
+
+ESM import:
+```ts
+import { CodeFlow, PasswordFlow, Sql, Rpc, createApi } from "@centia-io/sdk";
+import type { RpcRequest, RpcResponse, PgTypes } from "@centia-io/sdk";
+```
+
+---
+
+## Authentication
+
+The SDK handles token storage and refresh for you.
+- Tokens and minimal options are saved to `localStorage` in browsers. In non‑browser environments, an in‑memory store is used for the lifetime of the process.
+- Authorization headers are added automatically for Sql/Rpc requests.
+
+### CodeFlow (Browser, OAuth 2.0 Authorization Code + PKCE)
+
+Use this flow in browser applications where you can redirect the user to the GC2 login page.
+
+Required options:
+- `host`: Base URL of your GC2 instance, e.g. `https://your.gc2.host`
+- `clientId`: OAuth client id configured in GC2
+- `redirectUri`: The URL in your app that handles the redirect back from GC2 (must be whitelisted)
+- `scope` (optional): space‑separated scopes, e.g. `"openid profile"`
+
+Example (vanilla JS/TS + SPA):
+```ts
+import { CodeFlow } from "@centia-io/sdk";
+
+const codeFlow = new CodeFlow({
+  host: "https://your.gc2.host",
+  clientId: "your-client-id",
+  redirectUri: window.location.origin + "/auth/callback",
+  scope: "openid"
+});
+
+// On app startup, call redirectHandle() once to complete a login redirect (if any)
+codeFlow.redirectHandle().then((signedIn) => {
+  if (signedIn) {
+    console.log("User signed in");
+  }
+});
+
+// Start sign-in when user clicks Login
+function onLoginClick() {
+  codeFlow.signIn(); // Redirects to GC2 auth page
+}
+
+// Sign out (clears tokens/options and redirects to signout endpoint)
+function onLogoutClick() {
+  codeFlow.signOut();
+}
+```
+
+Notes:
+- `redirectHandle()` detects errors from the auth server, validates `state` (CSRF protection), exchanges the `code` for tokens, stores tokens and cleans up the URL.
+- `signOut()` clears local tokens/options and redirects to the sign-out URL. If you only need to clear local state without redirect, call `codeFlow.clear()`.
+
+### PasswordFlow (Trusted environments, CLI/Server)
+
+Use only in trusted environments. The user’s database credentials are exchanged directly for tokens.
+
+Required options:
+- `host`
+- `clientId`
+- `username`
+- `password`
+- `database`
+
+Example (Node.js):
+```ts
+import { PasswordFlow } from "@centia-io/sdk";
+
+const flow = new PasswordFlow({
+  host: "http://localhost:8080",
+  clientId: "gc2-cli",
+  username: "mydb",
+  password: "secret",
+  database: "mydb"
+});
+
+await flow.signIn();
+// Tokens are now stored; subsequent Sql/Rpc calls will include Authorization header.
+
+// ... your code ...
+
+flow.signOut(); // Clears tokens/options in local storage (no redirect)
+```
+
+---
+
+## SQL
+
+Execute parameterized SQL against GC2.
+
+- Class: `new Sql()`
+- Method: `exec(request: SqlRequest): Promise<SQLResponse>`
+- Endpoint: `POST {host}/api/v4/sql`
+
+Types (simplified):
+- `SqlRequest` has:
+  - `q`: SQL string, you can use named placeholders like `:a` (server-side feature)
+  - `params?`: object with values for placeholders
+  - `type_hints?`: optional explicit type hints
+  - `type_formats?`: optional per-column format strings
+- `SQLResponse` has:
+  - `schema`: a map of column name -> `{ type: string, array: boolean }`
+  - `data`: an array of rows (records)
+
+Example:
+```ts
+import { Sql } from "@centia-io/sdk";
+
+const sql = new Sql();
+
+const payload = {
+  a: 1,
+  b: "hello",
+  c: "3.14",          // numeric/decimal values are strings
+  d: ["x", "y"],      // arrays are supported
+  e: { nested: [1,2] } // JSON
+};
+
+const res = await sql.exec({
+  q: "select :a::int as a, :b::varchar as b, :c::numeric as c, :d::varchar[] as d, :e::jsonb as e",
+  params: payload
+});
+
+console.log(res.schema); // { a: {type: 'int4', array: false}, ... }
+console.log(res.data);   // [{ a: 1, b: 'hello', c: '3.14', d: ['x','y'], e: {nested:[1,2]} }]
+```
+
+Typing the rows:
+```ts
+import type { PgTypes } from "@centia-io/sdk";
+
+interface Row extends PgTypes.DataRow {
+  a: number;
+  b: string;
+  c: PgTypes.NumericString;
+  d: PgTypes.PgArray<string>;
+  e: PgTypes.JsonValue;
+}
+
+// res: PgTypes.SQLResponse<Row>
+const res = await sql.exec({ q: "...", params: payload }) as PgTypes.SQLResponse<Row>;
+```
+
+---
+
+## RPC
+
+Call JSON‑RPC methods exposed by GC2.
+
+- Class: `new Rpc()`
+- Method: `call(request: RpcRequest): Promise<RpcResponse>`
+- Endpoint: `POST {host}/api/v4/call`
+
+Types (simplified):
+- `RpcRequest` has `jsonrpc: "2.0"`, `method`, optional `params`, optional `id`
+- `RpcResponse` has `jsonrpc: "2.0"`, `id`, and `result` with `{ schema, data }`
+
+Example:
+```ts
+import { Rpc } from "@centia-io/sdk";
+
+const rpc = new Rpc();
+
+const payload = { a: 1, b: "hello" };
+
+const res = await rpc.call({
+  jsonrpc: "2.0",
+  method: "typeTest",
+  params: payload,
+  id: 1
+});
+
+console.log(res.result.schema);
+console.log(res.result.data); // array of rows
+```
+
+Typing the rows:
+```ts
+import type { PgTypes } from "@centia-io/sdk";
+
+interface Row extends PgTypes.DataRow {
+  a: number;
+  b: string;
+}
+
+const res = await rpc.call({ jsonrpc: "2.0", method: "typeTest", params: payload }) as PgTypes.RpcResponse<Row>;
+```
+
+---
+
+## createApi (Api.ts)
+
+A tiny helper that builds a Proxy around `Rpc` so you can call `api.someMethod(params)` directly, with TypeScript autocompletion and type‑checking based on your own interface.
+
+Under the hood, each property access becomes a JSON‑RPC call with the property name as the method. The helper returns `result.data` (array of rows) from the RPC response.
+
+Example with typing:
+```ts
+import { createApi } from "@centia-io/sdk";
+import type { PgTypes } from "@centia-io/sdk";
+
+// Define the shape of your RPC methods and return types
+interface MyApi {
+  typeTest(params: {
+    a: number;
+    b: string;
+    c: PgTypes.NumericString;
+    d: PgTypes.PgArray<string>;
+    e: PgTypes.JsonValue;
+  }): Promise<Array<{
+    a: number;
+    b: string;
+    c: PgTypes.NumericString;
+    d: PgTypes.PgArray<string>;
+    e: PgTypes.JsonValue;
+  }>>;
+}
+
+const api = createApi<MyApi>();
+
+const rows = await api.typeTest({
+  a: 1,
+  b: "hej",
+  c: "3.4",
+  d: ["ds", "sdsd"],
+  e: { zdsd: [2,3,4,5,6,7,8,9,10] }
+});
+
+console.log(rows); // typed row array
+```
+
+Notes:
+- `createApi<T>()` relies on naming conventions: the property name is the JSON‑RPC `method` name.
+- Each call returns `result.data` from the RPC response (array of rows).
+
+---
+
+## Error handling
+
+- Network/HTTP errors: thrown as `Error` with the status/body text when available.
+- Auth errors: the SDK auto‑refreshes access tokens when possible. If the refresh token is expired or missing, you’ll get an error and should re‑authenticate.
+
+---
+
+## Environment details
+
+- Storage: tokens/options stored in `localStorage` when available; otherwise a global in‑memory store is used (`globalThis.__gc2_memory_storage`).
+- Fetch: Node.js 18+ recommended (includes native `fetch`). For older Node versions, add a Fetch polyfill.
+
+---
+
+## Examples
+
+See the `examples/` folder for runnable snippets showing PasswordFlow + Sql/Rpc and browser CodeFlow usage.
+
+---
+
+## License
+
+AGPL-3.0