@kividb/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Kivi
+
+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,136 @@
+# @kividb/client
+
+The JavaScript/TypeScript client SDK for kividb — a thin, typed wrapper over the
+`data-api`, `auth`, and `realtime` services. Works in browsers, React Native,
+and Node 22+ (uses global `fetch` and `WebSocket`, no runtime dependencies).
+
+> Status: initial scaffold. Covers the full data, auth, and realtime surface the
+> services expose today. Storage and edge-function helpers are not built yet.
+
+## Install
+
+```sh
+pnpm add @kividb/client
+```
+
+## Quick start
+
+```ts
+import { createClient } from "@kividb/client";
+
+// One gateway URL + the project's anon key. The project slug is read from the
+// key's `ref` claim, and /auth, /rest, /realtime are derived from the URL.
+const kdb = createClient("https://database.akivi.se", ANON_KEY);
+```
+
+The single URL points at the gateway (see the repo's `Caddyfile` /
+`docker-compose.prod.yml`) that fronts all services. For local dev without a
+gateway, override the per-service base URLs to hit the ports directly:
+
+```ts
+const kdb = createClient("http://localhost", ANON_KEY, {
+  auth: "http://localhost:4000",
+  rest: "http://localhost:4001",
+  realtime: "ws://localhost:4002",
+});
+```
+
+## Data
+
+Every call resolves to `{ data, error }` — nothing throws for an HTTP failure.
+
+```ts
+// select with PostgREST-style filters
+const { data, error } = await kdb
+  .from("posts")
+  .select("id,title,created_at")
+  .eq("published", true)
+  .ilike("title", "%launch%")
+  .order("created_at", { ascending: false })
+  .limit(20);
+
+// insert (returns the inserted rows)
+await kdb.from("posts").insert({ title: "Hello", body: "..." });
+
+// update with a filter
+await kdb.from("posts").update({ published: true }).eq("id", 42);
+
+// delete
+await kdb.from("posts").delete().eq("id", 42);
+```
+
+Filter methods: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `is`
+(`is` accepts only `null`, `true`, `false`). Pagination: `limit`, `offset`, or
+`range(from, to)`.
+
+Requests use the anon key until a user signs in, then automatically switch to
+that user's access token. Row-level security is enforced server-side per role.
+
+## Auth
+
+```ts
+await kdb.auth.signUp({ email, password });
+await kdb.auth.signInWithPassword({ email, password });
+await kdb.auth.signInWithOtp({ email });          // magic link
+await kdb.auth.verifyOtp({ type: "magiclink", token });
+await kdb.auth.refreshSession();
+await kdb.auth.getUser();
+await kdb.auth.updateUser({ data: { displayName: "Ada" } });
+await kdb.auth.resetPasswordForEmail(email);
+await kdb.auth.signOut();
+
+const unsubscribe = kdb.auth.onAuthStateChange((event, session) => {
+  // "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED"
+});
+```
+
+### OAuth (GitHub / Google)
+
+OAuth is a browser redirect. Get the URL, navigate to it, then exchange the
+`?code=` the provider bounces back:
+
+```ts
+window.location.href = kdb.auth.getOAuthUrl({
+  provider: "github",
+  redirectTo: "https://app.example.com/callback",
+});
+
+// on the callback page:
+const code = new URLSearchParams(location.search).get("code")!;
+await kdb.auth.exchangeCodeForSession(code);
+```
+
+### Persisting the session
+
+By default the session lives in memory. Provide a `store` to survive reloads:
+
+```ts
+const kdb = createClient("blog", ANON_KEY, {
+  store: {
+    get: () => JSON.parse(localStorage.getItem("kdb.session") ?? "null"),
+    set: (s) => localStorage.setItem("kdb.session", JSON.stringify(s)),
+  },
+});
+```
+
+## Realtime
+
+```ts
+const channel = kdb
+  .channel("room:1")
+  .on("broadcast", { event: "message" }, ({ payload }) => console.log(payload))
+  .on("presence", { event: "sync" }, (state) => console.log(state))
+  .on("postgres_changes", { table: "messages", event: "INSERT" }, (change) =>
+    console.log(change.new),
+  )
+  .subscribe();
+
+channel.send({ event: "message", payload: { text: "hi" } });
+channel.track({ user: "ada" });
+channel.untrack();
+channel.unsubscribe();
+```
+
+One WebSocket is shared per project across all channels. It reconnects with
+backoff and re-subscribes automatically; `DELETE` postgres events are delivered
+only to `service_role` tokens (a documented v1 server limitation).