@archlast/client 0.1.0 → 0.1.1

package/README.md

@@ -60,7 +60,14 @@ import { ArchlastClient } from "@archlast/client";
 const client = new ArchlastClient(
   "ws://localhost:4000/ws",  // WebSocket URL
   "http://localhost:4000",   // HTTP URL
-  "web"                       // App ID
+  "web",                      // App ID
+  undefined,                  // Optional: auth URL (for same-origin proxy)
+  {
+    autoConnect: true,        // Auto-connect WebSocket (default: true)
+    isAdmin: false,           // Admin mode (default: false)
+    apiKey: "arch_key",       // Optional: Better-Auth API key
+    betterAuthCookies: {},    // Optional: Better-Auth session cookies
+  }
 );
 ```
 
@@ -262,15 +269,21 @@ import { usePagination } from "@archlast/client/react";
 
 function InfiniteTaskList() {
   const {
-    items,
-    isLoading,
-    hasMore,
-    loadMore,
-    error
-  } = usePagination(api.tasks.listPaginated, {
-    limit: 20,
-    filter: { completed: false }
-  });
+    items,           // Accumulated items across all pages
+    cursor,          // Current cursor for next page
+    isDone,          // Whether pagination is complete
+    hasMore,         // Convenience flag: !isDone && cursor exists
+    isLoading,       // Loading state
+    loadMore,        // Function to load next page
+    refresh,         // Function to reset and reload from first page
+    page,            // Optional: current page number (if server provides)
+    pageSize,        // Optional: page size (if server provides)
+    total,           // Optional: total count (if server provides)
+  } = usePagination(
+    api.tasks.listPaginated,
+    { completed: false }, // Base args (no cursor/limit)
+    { limit: 20 }         // Options
+  );
 
   return (
     <div>
@@ -288,6 +301,8 @@ function InfiniteTaskList() {
           {isLoading ? "Loading..." : "Load More"}
         </button>
       )}
+
+      <button onClick={refresh}>Refresh</button>
     </div>
   );
 }
@@ -296,10 +311,16 @@ function InfiniteTaskList() {
 **Server-side query must return:**
 
 ```ts
-interface PaginatedResult<T> {
+interface PaginatedResponse<T> {
   items: T[];
   continueCursor: string | null;
   isDone: boolean;
+  page?: number;        // Optional
+  pageSize?: number;    // Optional
+  total?: number;       // Optional
+}
+  continueCursor: string | null;
+  isDone: boolean;
 }
 ```
 
@@ -347,18 +368,18 @@ function FileUploader() {
 
 ### useAuth
 
-Authentication state and actions.
+Authentication state and actions via the `ArchlastAuthClient` wrapper.
 
 ```ts
 import { useAuth } from "@archlast/client/react";
 
 function AuthButton() {
   const {
-    signIn,
-    signOut,
     isAuthenticated,
     user,
-    isLoading
+    isLoading,
+    signIn,
+    signOut
   } = useAuth();
 
   if (isLoading) return <Spinner />;
@@ -367,14 +388,47 @@ function AuthButton() {
     return (
       <div>
         <span>Welcome, {user?.name}</span>
-        <button onClick={signOut}>Sign Out</button>
+        <button onClick={() => signOut()}>
+          Sign Out
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => signIn({ email: "user@example.com", password: "..." })}>
+      Sign In
+    </button>
+  );
+}
+```
+
+### Using Better-Auth React Hooks
+
+For full-featured auth in React, use Better-Auth's `useSession` hook:
+
+```tsx
+import { authClient } from "./lib/better-auth"; // Your Better-Auth client
+
+function AuthButton() {
+  const { data: session, isPending } = authClient.useSession();
+
+  if (isPending) return <Spinner />;
+
+  if (session?.user) {
+    return (
+      <div>
+        <span>Welcome, {session.user.name}</span>
+        <button onClick={() => authClient.signOut()}>
+          Sign Out
+        </button>
       </div>
     );
   }
 
   return (
-    <button onClick={() => signIn({ provider: "google" })}>
-      Sign in with Google
+    <button onClick={() => authClient.signIn.email({ email, password })}>
+      Sign In
     </button>
   );
 }
@@ -431,39 +485,97 @@ unsubscribe();
 
 ## Authentication
 
+Archlast uses [Better-Auth](https://www.better-auth.com/) for authentication. The server exposes Better-Auth endpoints at `/api/auth/*`.
+
 ### Using the Auth Client
 
+The `ArchlastAuthClient` provides a wrapper around Better-Auth endpoints:
+
 ```ts
 import { ArchlastAuthClient } from "@archlast/client/auth";
 
 const auth = new ArchlastAuthClient({
-  baseUrl: "http://localhost:4000"
+  baseUrl: "http://localhost:4000",
+  apiKey: "arch_your_api_key" // Optional: for programmatic access
 });
 
-// Email/password sign up
+// Sign up with email/password
+// POST /api/auth/sign-up/email
 await auth.signUp({
   email: "user@example.com",
   password: "secure_password",
   name: "John Doe"
 });
 
-// Email/password sign in
+// Sign in with email/password
+// POST /api/auth/sign-in/email
 await auth.signIn({
   email: "user@example.com",
   password: "secure_password"
 });
 
-// OAuth sign in
-await auth.signIn({ provider: "google" });
-await auth.signIn({ provider: "github" });
+// Sign in with username (if username plugin enabled)
+await auth.signIn({
+  username: "johndoe",
+  password: "secure_password"
+});
 
 // Get current session
-const session = await auth.getSession();
+// GET /api/auth/get-session
+const state = await auth.getState();
+console.log(state.isAuthenticated, state.user);
 
 // Sign out
 await auth.signOut();
 ```
 
+### Using Better-Auth Client Directly
+
+For full Better-Auth features (OAuth, organization, admin), use the Better-Auth client directly:
+
+```ts
+import { createAuthClient } from "better-auth/react";
+import {
+  adminClient,
+  usernameClient,
+  organizationClient,
+  // Optional plugins (add as needed):
+  // anonymousClient,  // For guest users
+  // apiKeyClient,     // For API key management
+} from "better-auth/client/plugins";
+
+const authClient = createAuthClient({
+  baseURL: "http://localhost:4000/api/auth",
+  fetchOptions: { credentials: "include" },
+  plugins: [
+    adminClient(),
+    usernameClient(),
+    organizationClient(),
+  ],
+});
+
+// Email sign in (typical for user-facing apps)
+await authClient.signIn.email({
+  email: "user@example.com",
+  password: "secure_password",
+});
+
+// Username sign in (used by dashboard)
+await authClient.signIn.username({
+  username: "admin",
+  password: "secure_password",
+});
+
+// Session management
+const { data: session } = authClient.useSession();
+
+// Organization management
+await authClient.organization.create({ name: "My Team" });
+
+// Admin operations (requires admin role)
+await authClient.admin.listUsers({ limit: 10 });
+```
+
 ### Auth State in Components
 
 ```tsx
@@ -504,24 +616,29 @@ const result = await client.storage.upload(file);
 console.log("Storage ID:", result.id);
 console.log("URL:", result.url);
 
-// Upload to specific bucket
-const imageResult = await client.storage.upload(imageFile, "images");
+// Upload with explicit content type
+const blob = new Blob(["data"], { type: "application/octet-stream" });
+const binaryResult = await client.storage.upload(blob, "application/octet-stream");
 ```
 
 ### List Files
 
-```ts
-// List all files
-const files = await client.storage.list();
-
-// List files in bucket
-const images = await client.storage.list("images");
+### List Files
 
-// With pagination
-const page1 = await client.storage.list("images", { limit: 20 });
-const page2 = await client.storage.list("images", {
-  limit: 20,
-  cursor: page1.nextCursor
+```ts
+// List files with pagination
+const { items } = await client.storage.list(20, 0); // limit, offset
+
+// Next page
+const page2 = await client.storage.list(20, 20);
+
+// Items structure
+items.forEach(file => {
+  console.log(file.id);          // Storage ID
+  console.log(file.fileName);    // Original filename
+  console.log(file.contentType); // MIME type
+  console.log(file.size);        // Size in bytes
+  console.log(file.url);         // Public URL
 });
 ```
 
@@ -551,22 +668,39 @@ console.log(metadata.createdAt);   // Date
 
 Access admin functionality (requires admin privileges).
 
+### Admin Auth Client
+
+The `AdminClient` currently provides authentication management:
+
 ```ts
-// Auth operations
-const profile = await client.admin.auth.getProfile();
-const users = await client.admin.auth.listUsers();
-await client.admin.auth.updateUser(userId, { role: "admin" });
+import { AdminClient } from "@archlast/client/admin";
+
+const admin = new AdminClient("http://localhost:4000", {
+  apiKey: "arch_your_api_key" // Optional: Better-Auth API key
+});
 
-// API key management
-const keys = await client.admin.apiKeys.list();
-const newKey = await client.admin.apiKeys.create({ name: "CI/CD" });
-await client.admin.apiKeys.revoke(keyId);
+// Admin authentication
+await admin.auth.signIn(email, password);
+const { user } = await admin.auth.getProfile();
+await admin.auth.signOut();
 
-// Data operations
-const collections = await client.admin.data.listCollections();
-const docs = await client.admin.data.query("tasks", { limit: 100 });
+// Session management
+const { sessions } = await admin.auth.getSessions();
+await admin.auth.revokeSession(sessionId);
+await admin.auth.signOutAll();
 ```
 
+**Available Methods:**
+
+- `admin.auth.signIn(email, password)` - Admin sign in
+- `admin.auth.signOut()` - Sign out current session
+- `admin.auth.getProfile()` - Get admin profile
+- `admin.auth.getSessions()` - List all sessions
+- `admin.auth.revokeSession(sessionId)` - Revoke specific session
+- `admin.auth.signOutAll()` - Sign out from all sessions
+
+**Note:** Additional admin clients (users, data, API keys) may be added in future releases.
+
 ---
 
 ## tRPC Integration
@@ -817,9 +951,9 @@ function App() {
 
 ---
 
-## Publishing (Maintainers)
+## Keywords
 
-See `docs/npm-publishing.md` for release and publish steps.
+archlast, client, sdk, react, hooks, real-time, websocket, typescript, api
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/client",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Archlast client SDK for React and API access",
     "license": "MIT",
     "repository": {