@sayrio/public 1.0.0 → 1.0.1

package/README.md

@@ -6,9 +6,10 @@ real‑time updates via WebSockets.
 
 - ✅ REST + WebSocket
 - ✅ Browser‑safe
-- ✅ TypeScript first
+- ✅ TypeScript‑first
 - ✅ Zero runtime dependencies
 - ✅ Versioned API (`v1`)
+- ✅ Consistent `ApiResult<T>` responses
 
 > React hooks are available via the **`@sayrio/public/react`** sub‑path export.
 
@@ -28,73 +29,154 @@ 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.
+Fetch a public organization.
 
-`Sayr.org` is an alias for the current API version (`v1`):
+`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 org = await Sayr.v1.org.get("acme");
+const res = await Sayr.v1.org.get("acme");
+```
+
+---
+
+## Organizations
+
+### Fetch an Organization
+
+```ts
+const res = await Sayr.org.get("acme");
+
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
 
-### Listing Tasks
+## Tasks
 
-Retrieve tasks for an organization:
+### List Tasks (Paginated)
 
 ```ts
-const { data: tasks } = await Sayr.org.tasks.list("acme", {
+const res = await Sayr.org.tasks.list("acme", {
   order: "desc",
-  limit: 10
+  limit: 10,
+});
+
+if (!res.success) return;
+
+res.data.items.forEach((task) => {
+  console.log(task.title);
 });
 
-console.log(tasks);
+console.log(res.data.pagination);
+```
+
+Returned shape:
+
+```ts
+ApiResult<{
+  items: Task[];
+  pagination: Pagination;
+}>
 ```
 
 ---
 
-### Fetching a Single Task
+### Fetch a Single Task
 
 ```ts
-const task = await Sayr.org.tasks.get("acme", 42);
+const res = await Sayr.org.tasks.get("acme", 42);
 
-console.log(task.title);
+if (res.success) {
+  console.log(res.data.title);
+}
 ```
 
 ---
 
-### Task Comments
+## Comments
 
-Fetch comments for a specific task:
+### List Task Comments (Paginated)
 
 ```ts
-const { data: comments } =
-  await Sayr.org.comments.list("acme", 42);
+const res = await Sayr.org.comments.list("acme", 42);
+
+if (!res.success) return;
+
+res.data.items.forEach((comment) => {
+  console.log(comment.contentMarkdown);
+});
+```
+
+Returned shape:
 
-console.log(comments);
+```ts
+ApiResult<{
+  items: Comment[];
+  pagination: Pagination;
+}>
 ```
 
 ---
 
-### Labels & Categories
+## Labels & Categories
+
+### Labels
+
+```ts
+const res = await Sayr.org.labels.list("acme");
+
+if (res.success) {
+  console.log(res.data);
+}
+```
+
+### Categories
 
 ```ts
-const labels = await Sayr.org.labels.list("acme");
-const categories = await Sayr.org.categories.list("acme");
+const res = await Sayr.org.categories.list("acme", "desc");
+
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
@@ -104,19 +186,27 @@ const categories = await Sayr.org.categories.list("acme");
 The `/me` namespace provides **read‑only access** to the currently
 authenticated user.
 
-> Authentication is required.  
+> Authentication is required  
 > Set a token using `Sayr.client.setToken(...)`.
 
 ---
 
-### Fetch Current User
+### Set Token
 
 ```ts
-Sayr.client.setToken(token);
+Sayr.client.setToken("********");
+```
+
+---
 
-const me = await Sayr.me.get();
+### Fetch Current User
+
+```ts
+const res = await Sayr.me.get();
 
-console.log(me.email);
+if (res.success) {
+  console.log(res.data.email);
+}
 ```
 
 ---
@@ -124,9 +214,11 @@ console.log(me.email);
 ### List Your Organizations
 
 ```ts
-const orgs = await Sayr.me.organizations();
+const res = await Sayr.me.organizations();
 
-console.log(orgs);
+if (res.success) {
+  console.log(res.data);
+}
 ```
 
 ---
@@ -137,9 +229,9 @@ Subscribe to public real‑time events using WebSockets:
 
 ```ts
 Sayr.ws(org.wsUrl, {
-  [Sayr.WS_EVENTS.UPDATE_TASK]: (task) => {
-    console.log("Task updated", task);
-  }
+  [Sayr.WS_EVENTS.UPDATE_TASK]: (data) => {
+    console.log("Task updated", data);
+  },
 });
 ```
 
@@ -158,14 +250,17 @@ Sayr.ws(org.wsUrl, {
 <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)
 
@@ -181,18 +276,18 @@ Alias for `Sayr.v1.org`.
 
 #### Tasks
 
-| Method                      | Description            |
-| --------------------------- | ---------------------- |
-| `tasks.list(slug, opts?)`   | List tasks (paginated) |
-| `tasks.get(slug, shortId)`  | Fetch a single task    |
+| 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 |
+| Method                                | Description              |
+| ------------------------------------- | ------------------------ |
+| `comments.list(slug, shortId, opts?)` | List task comments       |
 
 ---
 
@@ -206,8 +301,8 @@ Alias for `Sayr.v1.org`.
 
 #### Categories
 
-| Method                         | Description     |
-| ------------------------------ | --------------- |
+| Method                          | Description     |
+| ------------------------------- | --------------- |
 | `categories.list(slug, order?)` | List categories |
 
 ---
@@ -216,10 +311,10 @@ Alias for `Sayr.v1.org`.
 
 Authenticated user endpoints.
 
-| Method              | Description                            |
-| ------------------- | -------------------------------------- |
-| `get()`             | Fetch the current authenticated user   |
-| `organizations()`   | List organizations the user belongs to |
+| Method            | Description                            |
+| ----------------- | -------------------------------------- |
+| `get()`           | Fetch the authenticated user           |
+| `organizations()` | List organizations the user belongs to |
 
 ---
 
@@ -229,7 +324,7 @@ Create a WebSocket connection for public events:
 
 ```ts
 const conn = Sayr.ws(wsUrl, {
-  UPDATE_TASK: () => {}
+  UPDATE_TASK: () => {},
 });
 
 conn.close();
@@ -242,8 +337,9 @@ conn.close();
 Typed WebSocket event constants:
 
 ```ts
+Sayr.WS_EVENTS.CREATE_TASK;
 Sayr.WS_EVENTS.UPDATE_TASK;
-Sayr.WS_EVENTS.UPDATE_ORG;
+Sayr.WS_EVENTS.UPDATE_TASK_COMMENTS;
 Sayr.WS_EVENTS.ERROR;
 ```
 
@@ -257,8 +353,27 @@ This package ships with full TypeScript definitions:
 import type {
   Organization,
   Task,
-  Comment
+  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.
+
 ---

package/dist/index.cjs

@@ -78,7 +78,7 @@ async function request(path, opts = {}) {
     if (method === "GET" && opts.body !== void 0) {
       throw new Error("GET request cannot have a body");
     }
-    res = await fetch(url, {
+    res = await config.fetch(url, {
       method,
       headers: {
         ...config.token ? { Authorization: `Bearer ${config.token}` } : {},
@@ -139,11 +139,23 @@ var org_default = {
    * @since v1.0.0
    */
   async get(slug, opts) {
-    const r = await request(
-      `/v1/organization/${slug}`,
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request(
+        `/v1/organization/${slug}`,
+        opts
+      );
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch organization"
+      };
+    }
   }
 };
 
@@ -164,15 +176,27 @@ var tasks_default = {
    * @since v1.0.0
    */
   async list(slug, params, opts) {
-    const q = buildPaginationParams(params);
-    const r = await request(
-      `/v1/organization/${slug}/tasks?${q}`,
-      opts
-    );
-    return {
-      data: r.data,
-      pagination: r.pagination
-    };
+    try {
+      const q = buildPaginationParams(params);
+      const r = await request(
+        `/v1/organization/${slug}/tasks?${q}`,
+        opts
+      );
+      return {
+        success: true,
+        data: {
+          items: r.data,
+          pagination: r.pagination
+        },
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch tasks"
+      };
+    }
   },
   /**
    * Fetches a single public task by short ID.
@@ -180,11 +204,23 @@ var tasks_default = {
    * @since v1.0.0
    */
   async get(slug, shortId, opts) {
-    const r = await request(
-      `/v1/organization/${slug}/tasks/${shortId}`,
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request(
+        `/v1/organization/${slug}/tasks/${shortId}`,
+        opts
+      );
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch task"
+      };
+    }
   }
 };
 
@@ -196,15 +232,27 @@ var comments_default = {
    * @since v1.0.0
    */
   async list(slug, shortId, params, opts) {
-    const q = buildPaginationParams(params);
-    const r = await request(
-      `/v1/organization/${slug}/tasks/${shortId}/comments?${q}`,
-      opts
-    );
-    return {
-      data: r.data,
-      pagination: r.pagination
-    };
+    try {
+      const q = buildPaginationParams(params);
+      const r = await request(
+        `/v1/organization/${slug}/tasks/${shortId}/comments?${q}`,
+        opts
+      );
+      return {
+        success: true,
+        data: {
+          items: r.data,
+          pagination: r.pagination
+        },
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch task comments"
+      };
+    }
   }
 };
 
@@ -216,11 +264,23 @@ var labels_default = {
    * @since v1.0.0
    */
   async list(slug, opts) {
-    const r = await request(
-      `/v1/organization/${slug}/labels`,
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request(
+        `/v1/organization/${slug}/labels`,
+        opts
+      );
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch labels"
+      };
+    }
   }
 };
 
@@ -232,11 +292,23 @@ var categories_default = {
    * @since v1.0.0
    */
   async list(slug, order = "desc", opts) {
-    const r = await request(
-      `/v1/organization/${slug}/categories?order=${order}`,
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request(
+        `/v1/organization/${slug}/categories?order=${order}`,
+        opts
+      );
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch categories"
+      };
+    }
   }
 };
 
@@ -252,29 +324,40 @@ var org_default2 = OrgAPI;
 
 // src/api/v1/me/index.ts
 var me_default = {
-  /**
-   * Fetches the currently authenticated user.
-   *
-   * @since v1.0.0
-   */
   async get(opts) {
-    const r = await request(
-      "/me",
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request("/v1/me", opts);
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch user"
+      };
+    }
   },
-  /**
-   * Lists organizations the current user belongs to.
-   *
-   * @since v1.0.0
-   */
   async organizations(opts) {
-    const r = await request(
-      "/organizations",
-      opts
-    );
-    return r.data;
+    try {
+      const r = await request(
+        "/v1/me/organizations",
+        opts
+      );
+      return {
+        success: true,
+        data: r.data,
+        error: null
+      };
+    } catch (err) {
+      return {
+        success: false,
+        data: null,
+        error: err?.message ?? "Failed to fetch organizations"
+      };
+    }
   }
 };