@weirdscience/based-client 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,187 @@
+# @weirdscience/based-client
+
+React SDK for [Based](https://based.weirdscience.dev) — a minimal self-hosted Backend-as-a-Service.
+
+Hooks for auth, queries, and mutations. Type-safe end-to-end when paired with `based typegen`.
+
+## Install
+
+```bash
+bun add @weirdscience/based-client
+# or: npm install @weirdscience/based-client
+# or: pnpm add @weirdscience/based-client
+```
+
+Peer dependency: `react >=18`.
+
+## Quick start
+
+```tsx
+import { createClient, BasedProvider } from "@weirdscience/based-client";
+
+const based = createClient({
+  url: process.env.NEXT_PUBLIC_BASED_URL!,
+  anonKey: process.env.NEXT_PUBLIC_BASED_ANON_KEY!,
+});
+
+export default function App({ children }: { children: React.ReactNode }) {
+  return <BasedProvider client={based}>{children}</BasedProvider>;
+}
+```
+
+## Hooks
+
+### `useUser()`
+
+Current authenticated user.
+
+```tsx
+import { useUser } from "@weirdscience/based-client";
+
+function Profile() {
+  const { user, isLoading } = useUser();
+  if (isLoading) return <p>...</p>;
+  if (!user) return <p>Not logged in</p>;
+  return <p>{user.email}</p>;
+}
+```
+
+### `useQuery(table, options?)`
+
+Read rows from a table. Returns `{ data, total, isLoading, error, refetch }`.
+
+```tsx
+import { useQuery } from "@weirdscience/based-client";
+
+const { data, total, isLoading } = useQuery("posts", {
+  filter: { status: "published" },
+  limit: 20,
+  offset: 0,
+});
+```
+
+### `useMutation(table, operation)`
+
+Write rows. `operation` is `"create" | "update" | "delete"`. Returns `{ mutate, isLoading, error }`.
+
+```tsx
+import { useMutation } from "@weirdscience/based-client";
+
+function NewPost() {
+  const { mutate, isLoading } = useMutation("posts", "create");
+  return (
+    <button
+      onClick={() => mutate({ title: "Hello", content: "World" })}
+      disabled={isLoading}
+    >
+      Create
+    </button>
+  );
+}
+```
+
+`update` and `delete` require an `id` field:
+
+```tsx
+const { mutate: update } = useMutation("posts", "update");
+await update({ id: "abc", title: "Renamed" });
+
+const { mutate: remove } = useMutation("posts", "delete");
+await remove({ id: "abc" });
+```
+
+## Auth
+
+```tsx
+import { useBasedClient } from "@weirdscience/based-client";
+
+function LoginForm() {
+  const client = useBasedClient();
+
+  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    const fd = new FormData(e.currentTarget);
+    await client.auth.signIn(
+      fd.get("email") as string,
+      fd.get("password") as string
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      <button type="submit">Sign in</button>
+    </form>
+  );
+}
+```
+
+Methods on `client.auth`:
+
+- `signUp(email, password)` → creates an account and signs in
+- `signIn(email, password)` → signs in
+- `signOut()` → invalidates the session
+- `refreshSession()` → manually refresh (happens automatically on 401)
+
+Access tokens auto-refresh on `401`. Sessions are stored in memory.
+
+## Type safety
+
+Generate types for your tables from the server:
+
+```bash
+based typegen
+# writes based.d.ts
+```
+
+Pass the generated `Tables` type as a generic:
+
+```tsx
+import type { Tables } from "./based.d.ts";
+import { useQuery, useMutation } from "@weirdscience/based-client";
+
+// data is typed as Tables["posts"][]
+const { data } = useQuery<Tables, "posts">("posts", {
+  filter: { status: "published" }, // typed keys
+});
+
+const { mutate } = useMutation<Tables, "posts">("posts", "create");
+await mutate({ title: "Hello", content: "World" }); // typed payload
+```
+
+Re-run `based typegen` after any schema change.
+
+## Row-level isolation
+
+If a table has a `user_id` (or `userId`) column, Based auto-scopes CRUD to the authenticated user. No configuration needed — just add the column:
+
+```bash
+based table create notes user_id:text:required title:text:required body:text
+```
+
+After that:
+
+- `useQuery("notes")` only returns the caller's notes
+- `useMutation("notes", "create")` auto-fills `user_id`
+- Other users' rows return 404
+
+## Upsert
+
+`PUT /api/:table/:id` creates if missing, updates if present. From the SDK:
+
+```tsx
+const { mutate: upsert } = useMutation("preferences", "update");
+
+// The URL id becomes the row id — perfect for deterministic keys like userId:key
+await upsert({ id: "alice:theme", value: "dark" });
+```
+
+## Links
+
+- [Based docs](https://based.weirdscience.dev/docs)
+- [GitHub](https://github.com/WeirdScience-dev/based)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weirdscience/based-client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React SDK for Based — a minimal self-hosted BaaS",
   "license": "MIT",
   "repository": {