@sayrio/public 0.1.4 → 1.0.1

package/README.md

@@ -1,4 +1,3 @@
-
 # @sayrio/public
 
 Public JavaScript & TypeScript SDK for **Sayr.io**.  
@@ -7,167 +6,315 @@ real‑time updates via WebSockets.
 
 - ✅ REST + WebSocket
 - ✅ Browser‑safe
-- ✅ TypeScript first
-- ✅ React hooks included (`/react`)
+- ✅ TypeScript‑first
 - ✅ Zero runtime dependencies
+- ✅ Versioned API (`v1`)
+- ✅ Consistent `ApiResult<T>` responses
+
+> React hooks are available via the **`@sayrio/public/react`** sub‑path export.
 
 ---
 
 ## Installation
 
-Install the public Sayr SDK using your preferred package manager:
-
 ```bash
 npm install @sayrio/public
 ```
+
 or
+
 ```bash
 pnpm add @sayrio/public
 ```
 
+---
+
+## Core Concepts
+
+### ✅ `ApiResult<T>`
+
+All SDK methods return a **non‑throwing** result object:
+
+```ts
+interface ApiResult<T> {
+  success: boolean;
+  data: T | null;
+  error: string | null;
+}
+```
+
+Always check `success` before accessing `data`.
+
+---
+
 ## Usage
 
 ### Basic Usage (REST)
 
-Fetch public organization data using the REST API:
+Fetch a public organization.
+
+`Sayr.org` is an alias for the latest API version (`v1`).
 
 ```ts
 import Sayr from "@sayrio/public";
 
-const org = await Sayr.org.get("acme");
+const res = await Sayr.org.get("acme");
 
-console.log(org.name);
+if (!res.success) {
+  console.error(res.error);
+  return;
+}
+
+console.log(res.data.name);
+```
+
+You can also use the versioned API explicitly:
+
+```ts
+const res = await Sayr.v1.org.get("acme");
 ```
 
 ---
 
-### Listing Tasks
+## Organizations
 
-Retrieve tasks for an organization with pagination and ordering support:
+### Fetch an Organization
 
 ```ts
-const { data: tasks, pagination } =
-  await Sayr.org.tasks("acme", {
-    order: "desc",
-    limit: 10
-  });
+const res = await Sayr.org.get("acme");
 
-console.log(tasks);
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
 
-### Task Comments
+## Tasks
 
-Fetch comments for a specific task:
+### List Tasks (Paginated)
 
 ```ts
-const { data: comments } =
-  await Sayr.org.comments("acme", 12);
+const res = await Sayr.org.tasks.list("acme", {
+  order: "desc",
+  limit: 10,
+});
+
+if (!res.success) return;
+
+res.data.items.forEach((task) => {
+  console.log(task.title);
+});
 
-console.log(comments);
+console.log(res.data.pagination);
+```
+
+Returned shape:
+
+```ts
+ApiResult<{
+  items: Task[];
+  pagination: Pagination;
+}>
+```
+
+---
+
+### Fetch a Single Task
+
+```ts
+const res = await Sayr.org.tasks.get("acme", 42);
+
+if (res.success) {
+  console.log(res.data.title);
+}
 ```
 
 ---
 
-### Real-Time Updates (WebSocket)
+## Comments
 
-Subscribe to public real-time events using WebSockets:
+### List Task Comments (Paginated)
 
 ```ts
-Sayr.ws(org.wsUrl, {
-  [Sayr.wsTypes.UPDATE_ORG]: (data) => {
-    console.log("Organization updated", data);
-  },
+const res = await Sayr.org.comments.list("acme", 42);
 
-  [Sayr.wsTypes.UPDATE_TASK]: (task) => {
-    console.log("Task updated", task);
-  }
+if (!res.success) return;
+
+res.data.items.forEach((comment) => {
+  console.log(comment.contentMarkdown);
 });
 ```
 
-### WebSocket Features
-- Automatic reconnection
-- Heartbeat support (PING / PONG)
-- Typed event constants
-- Public-safe payloads only
+Returned shape:
+
+```ts
+ApiResult<{
+  items: Comment[];
+  pagination: Pagination;
+}>
+```
 
 ---
 
-## React Hooks
+## Labels & Categories
+
+### Labels
 
-React hooks are available via a dedicated sub-path export:
+```ts
+const res = await Sayr.org.labels.list("acme");
+
+if (res.success) {
+  console.log(res.data);
+}
+```
+
+### Categories
 
 ```ts
-import { useOrg, useTasks, useComments } from "@sayrio/public/react";
+const res = await Sayr.org.categories.list("acme", "desc");
+
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
 
-### `useOrg`
+## Authenticated User (`/me`)
+
+The `/me` namespace provides **read‑only access** to the currently
+authenticated user.
 
-Fetch and subscribe to an organization:
+> Authentication is required  
+> Set a token using `Sayr.client.setToken(...)`.
 
-```tsx
-const { data: org, loading } = useOrg("acme");
+---
+
+### Set Token
+
+```ts
+Sayr.client.setToken("********");
+```
+
+---
+
+### Fetch Current User
+
+```ts
+const res = await Sayr.me.get();
+
+if (res.success) {
+  console.log(res.data.email);
+}
 ```
 
 ---
 
-### `useTasks`
+### List Your Organizations
 
-Fetch and subscribe to tasks for an organization:
+```ts
+const res = await Sayr.me.organizations();
 
-```tsx
-const { tasks } = useTasks("acme", org?.wsUrl);
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
 
-### `useComments`
+## Real‑Time Updates (WebSocket)
 
-Fetch and subscribe to comments for a task:
+Subscribe to public real‑time events using WebSockets:
 
-```tsx
-const { comments } = useComments(
-  "acme",
-  task.shortId,
-  org?.wsUrl
-);
+```ts
+Sayr.ws(org.wsUrl, {
+  [Sayr.WS_EVENTS.UPDATE_TASK]: (data) => {
+    console.log("Task updated", data);
+  },
+});
 ```
 
-Hooks automatically refresh when relevant WebSocket events occur.
+### WebSocket Features
+
+- Automatic reconnection
+- Heartbeat support (PING / PONG)
+- Typed event constants
+- Public‑safe payloads only
 
 ---
 
 ## Browser Usage (No Bundler)
 
-The SDK can be used directly in the browser via ESM:
-
 ```html
 <script type="module">
   import Sayr from "https://esm.sh/@sayrio/public";
 
-  const org = await Sayr.org.get("acme");
-  console.log(org);
+  const res = await Sayr.org.get("acme");
+
+  if (res.success) {
+    console.log(res.data);
+  }
 </script>
 ```
 
 ---
 
-## API
+## API Overview
+
+### `Sayr.org` (latest)
+
+Alias for `Sayr.v1.org`.
+
+#### Organization
+
+| Method      | Description                 |
+| ----------- | --------------------------- |
+| `get(slug)` | Fetch a public organization |
+
+---
+
+#### Tasks
+
+| Method                     | Description            |
+| -------------------------- | ---------------------- |
+| `tasks.list(slug, opts?)`  | List tasks (paginated) |
+| `tasks.get(slug, shortId)` | Fetch a single task    |
+
+---
+
+#### Comments
+
+| Method                                | Description              |
+| ------------------------------------- | ------------------------ |
+| `comments.list(slug, shortId, opts?)` | List task comments       |
+
+---
+
+#### Labels
+
+| Method              | Description              |
+| ------------------- | ------------------------ |
+| `labels.list(slug)` | List organization labels |
+
+---
+
+#### Categories
 
-### `Sayr.org`
+| Method                          | Description     |
+| ------------------------------- | --------------- |
+| `categories.list(slug, order?)` | List categories |
 
-| Method                           | Description                 |
-| -------------------------------- | --------------------------- |
-| `get(slug)`                      | Fetch a public organization |
-| `labels(slug)`                   | List organization labels    |
-| `categories(slug, order?)`       | List categories             |
-| `tasks(slug, opts?)`             | List tasks (paginated)      |
-| `task(slug, shortId)`            | Fetch a single task         |
-| `comments(slug, shortId, opts?)` | List task comments          |
+---
+
+### `Sayr.me`
 
+Authenticated user endpoints.
+
+| Method            | Description                            |
+| ----------------- | -------------------------------------- |
+| `get()`           | Fetch the authenticated user           |
+| `organizations()` | List organizations the user belongs to |
 
 ---
 
@@ -177,22 +324,23 @@ Create a WebSocket connection for public events:
 
 ```ts
 const conn = Sayr.ws(wsUrl, {
-  UPDATE_TASK: () => {}
+  UPDATE_TASK: () => {},
 });
 
-// Close the connection when no longer needed
 conn.close();
 ```
 
 ---
 
-### `Sayr.wsTypes`
+### `WS_EVENTS`
+
+Typed WebSocket event constants:
 
 ```ts
-Sayr.wsTypes.UPDATE_TASK
-Sayr.wsTypes.UPDATE_ORG
-Sayr.wsTypes.ERROR
-// ...
+Sayr.WS_EVENTS.CREATE_TASK;
+Sayr.WS_EVENTS.UPDATE_TASK;
+Sayr.WS_EVENTS.UPDATE_TASK_COMMENTS;
+Sayr.WS_EVENTS.ERROR;
 ```
 
 ---
@@ -202,5 +350,30 @@ Sayr.wsTypes.ERROR
 This package ships with full TypeScript definitions:
 
 ```ts
-import type { Organization, Task } from "@sayrio/public";
+import type {
+  Organization,
+  Task,
+  Comment,
+  Label,
+  Category,
+} from "@sayrio/public";
+```
+
+---
+
+## React Hooks
+
+React bindings are available via:
+
+```ts
+import {
+  useOrg,
+  useTasks,
+  useTask,
+  useComments,
+} from "@sayrio/public/react";
 ```
+
+See **`@sayrio/public/react` README** for full hook documentation.
+
+---