@centia-io/sdk 0.0.27 → 0.0.29

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

@@ -1,30 +1,36 @@
-# @centia-io/sdk
+# SDK
 
-TypeScript/JavaScript client SDK for Centia GC2. It provides:
+TypeScript/JavaScript client SDK for Centia-io. It provides:
 
 - Authentication helpers:
-  - CodeFlow (OAuth 2.0 Authorization Code + PKCE) for browser apps
-  - PasswordFlow for trusted/CLI/server environments
+    - 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).
+    - Sql: Execute parameterized SQL
+    - Rpc: Call JSON-RPC methods
+    - createApi: A tiny type-safe helper that maps TypeScript interfaces to JSON‑RPC calls
 
 ## Installation
 
-- npm: `npm install @centia-io/sdk`
-- pnpm: `pnpm add @centia-io/sdk`
-- yarn: `yarn add @centia-io/sdk`
+```bash
+npm install @centia-io/sdk
+yarn add @centia-io/sdk
+pnpm add @centia-io/sdk
+```  
+
+Or from CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@centia-io/sdk@latest/dist/centia-io-sdk.umd.js"></script>
+```
 
 Requirements:
 - Browser or Node.js 18+ (for global `fetch`).
-- An accessible GC2 host URL and client credentials.
+- An accessible Centia.io host URL and client credentials.
 
 ESM import:
 ```ts
-import { CodeFlow, PasswordFlow, Sql, Rpc, createApi } from "@centia-io/sdk";
+import { CodeFlow, PasswordFlow, Sql, Rpc, createApi, SignUp } from "@centia-io/sdk";
 import type { RpcRequest, RpcResponse, PgTypes } from "@centia-io/sdk";
 ```
 
@@ -38,23 +44,22 @@ The SDK handles token storage and refresh for you.
 
 ### 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.
+Use this flow in browser applications where you can redirect the user to the Centia-io 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"`
+- `host`: Base URL of your Centia-io instance, e.g. `https://api.centia.io`
+- `clientId`: OAuth client id configured in Centia.io
+- `redirectUri`: The URL in your app that handles the redirect back from Centia.io (must be whitelisted)
+- `scope` (optional): Not in use yet, but will be used to request additional permissions from the user.
 
 Example (vanilla JS/TS + SPA):
 ```ts
 import { CodeFlow } from "@centia-io/sdk";
 
 const codeFlow = new CodeFlow({
-  host: "https://your.gc2.host",
+  host: "https://api.centia.io",
   clientId: "your-client-id",
-  redirectUri: window.location.origin + "/auth/callback",
-  scope: "openid"
+  redirectUri: window.location.origin + "/auth/callback"
 });
 
 // On app startup, call redirectHandle() once to complete a login redirect (if any)
@@ -76,7 +81,7 @@ function onLogoutClick() {
 ```
 
 Notes:
-- `redirectHandle()` detects errors from the auth server, validates `state` (CSRF protection), exchanges the `code` for tokens, stores tokens and cleans up the URL.
+- `redirectHandle()` detects errors from the auth server, validates `state` (CSRF protection), exchanges the `code` for tokens, performs `PKCE` (Proof Key for Code Exchange), 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)
@@ -95,11 +100,11 @@ Example (Node.js):
 import { PasswordFlow } from "@centia-io/sdk";
 
 const flow = new PasswordFlow({
-  host: "http://localhost:8080",
-  clientId: "gc2-cli",
-  username: "mydb",
-  password: "secret",
-  database: "mydb"
+  host: "https://api.centia.io",
+  clientId: "your-client-id",
+  username: "your-username",
+  password: "your-password",
+  database: "parent-database" // The database to connect to. If superuser, this is the sam as username.
 });
 
 await flow.signIn();
@@ -110,7 +115,37 @@ await flow.signIn();
 flow.signOut(); // Clears tokens/options in local storage (no redirect)
 ```
 
----
+### SignUp (Browser – Create a new user)
+
+Use this helper in browser applications to redirect the user to the Centia‑io sign‑up page. 
+The user will create an account under a specified parent database/tenant and then be redirected back to your application.
+
+Required options:
+- host: Base URL of your Centia‑io instance, e.g. https://api.centia.io
+- clientId: OAuth client id configured in Centia.io
+- parentDb: The parent/tenant database under which the new user should be created
+- redirectUri: URL in your app to return to after sign‑up
+
+Example (vanilla JS/TS):
+```ts
+import { SignUp } from "@centia-io/sdk";
+
+const signUp = new SignUp({
+  host: "https://api.centia.io",
+  clientId: "your-client-id",
+  parentDb: "your-parent-database",
+  redirectUri: window.location.origin + "/auth/callback"
+});
+
+// Start sign-up when the user clicks "Create account"
+function onSignUpClick() {
+  signUp.signUp(); // Redirects to GC2 sign-up page
+}
+```
+
+Notes:
+- Default endpoint is {host}/signup/. You can override with authUri if needed.
+- After the user completes sign‑up and is redirected back to your app, start your normal sign‑in flow (e.g., CodeFlow. A session is started when the user signed up, so the user will be signed in automatically in the flow.)
 
 ## SQL
 
@@ -118,17 +153,17 @@ Execute parameterized SQL against GC2.
 
 - Class: `new Sql()`
 - Method: `exec(request: SqlRequest): Promise<SQLResponse>`
-- Endpoint: `POST {host}/api/v4/sql`
+- Endpoint: `POST https://api.centia.io/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
+    - `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)
+    - `schema`: a map of column name -> `{ type: string, array: boolean }`
+    - `data`: an array of rows (records)
 
 Example:
 ```ts
@@ -146,7 +181,8 @@ const payload = {
 
 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
+  params: payload,
+  type_hints: { d: "varchar[]" } // Arrays are not inferred by default, and must be specified explicitly
 });
 
 console.log(res.schema); // { a: {type: 'int4', array: false}, ... }
@@ -159,9 +195,9 @@ import type { PgTypes } from "@centia-io/sdk";
 
 interface Row extends PgTypes.DataRow {
   a: number;
-  b: string;
+  b: Pgtypes.Varchar;
   c: PgTypes.NumericString;
-  d: PgTypes.PgArray<string>;
+  d: PgTypes.PgArray<Pgtypes.Varchar>;
   e: PgTypes.JsonValue;
 }
 
@@ -169,8 +205,6 @@ interface Row extends PgTypes.DataRow {
 const res = await sql.exec({ q: "...", params: payload }) as PgTypes.SQLResponse<Row>;
 ```
 
----
-
 ## RPC
 
 Call JSON‑RPC methods exposed by GC2.
@@ -214,9 +248,7 @@ interface Row extends PgTypes.DataRow {
 const res = await rpc.call({ jsonrpc: "2.0", method: "typeTest", params: payload }) as PgTypes.RpcResponse<Row>;
 ```
 
----
-
-## createApi (Api.ts)
+## createApi
 
 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.
 
@@ -231,15 +263,15 @@ import type { PgTypes } from "@centia-io/sdk";
 interface MyApi {
   typeTest(params: {
     a: number;
-    b: string;
+    b: Pgtypes.Varchar;
     c: PgTypes.NumericString;
-    d: PgTypes.PgArray<string>;
+    d: PgTypes.PgArray<Pgtypes.Varchar>;
     e: PgTypes.JsonValue;
   }): Promise<Array<{
     a: number;
-    b: string;
+    b: Pgtypes.Varchar;
     c: PgTypes.NumericString;
-    d: PgTypes.PgArray<string>;
+    d: PgTypes.PgArray<Pgtypes.Varchar>;
     e: PgTypes.JsonValue;
   }>>;
 }
@@ -248,10 +280,10 @@ const api = createApi<MyApi>();
 
 const rows = await api.typeTest({
   a: 1,
-  b: "hej",
+  b: "Hello world",
   c: "3.4",
-  d: ["ds", "sdsd"],
-  e: { zdsd: [2,3,4,5,6,7,8,9,10] }
+  d: ["Hello", "world"],
+  e: { "x": [1,2,3,4,5,6,7,8,9,10] }
 });
 
 console.log(rows); // typed row array
@@ -261,28 +293,17 @@ 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
+The SDK is licensed under [The MIT License](https://opensource.org/license/mit)