@sayrio/public 0.1.4 → 1.0.0

package/README.md

@@ -1,4 +1,3 @@
-
 # @sayrio/public
 
 Public JavaScript & TypeScript SDK for **Sayr.io**.  
@@ -8,28 +7,34 @@ real‑time updates via WebSockets.
 - ✅ REST + WebSocket
 - ✅ Browser‑safe
 - ✅ TypeScript first
-- ✅ React hooks included (`/react`)
 - ✅ Zero runtime dependencies
+- ✅ Versioned API (`v1`)
+
+> 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
 ```
 
+---
+
 ## Usage
 
 ### Basic Usage (REST)
 
-Fetch public organization data using the REST API:
+Fetch public organization data.
+
+`Sayr.org` is an alias for the current API version (`v1`):
 
 ```ts
 import Sayr from "@sayrio/public";
@@ -39,111 +44,116 @@ const org = await Sayr.org.get("acme");
 console.log(org.name);
 ```
 
+You can also use the versioned API explicitly:
+
+```ts
+const org = await Sayr.v1.org.get("acme");
+```
+
 ---
 
 ### Listing Tasks
 
-Retrieve tasks for an organization with pagination and ordering support:
+Retrieve tasks for an organization:
 
 ```ts
-const { data: tasks, pagination } =
-  await Sayr.org.tasks("acme", {
-    order: "desc",
-    limit: 10
-  });
+const { data: tasks } = await Sayr.org.tasks.list("acme", {
+  order: "desc",
+  limit: 10
+});
 
 console.log(tasks);
 ```
 
 ---
 
+### Fetching a Single Task
+
+```ts
+const task = await Sayr.org.tasks.get("acme", 42);
+
+console.log(task.title);
+```
+
+---
+
 ### Task Comments
 
 Fetch comments for a specific task:
 
 ```ts
 const { data: comments } =
-  await Sayr.org.comments("acme", 12);
+  await Sayr.org.comments.list("acme", 42);
 
 console.log(comments);
 ```
 
 ---
 
-### Real-Time Updates (WebSocket)
-
-Subscribe to public real-time events using WebSockets:
+### Labels & Categories
 
 ```ts
-Sayr.ws(org.wsUrl, {
-  [Sayr.wsTypes.UPDATE_ORG]: (data) => {
-    console.log("Organization updated", data);
-  },
-
-  [Sayr.wsTypes.UPDATE_TASK]: (task) => {
-    console.log("Task updated", task);
-  }
-});
+const labels = await Sayr.org.labels.list("acme");
+const categories = await Sayr.org.categories.list("acme");
 ```
 
-### WebSocket Features
-- Automatic reconnection
-- Heartbeat support (PING / PONG)
-- Typed event constants
-- Public-safe payloads only
-
 ---
 
-## React Hooks
+## Authenticated User (`/me`)
 
-React hooks are available via a dedicated sub-path export:
+The `/me` namespace provides **read‑only access** to the currently
+authenticated user.
 
-```ts
-import { useOrg, useTasks, useComments } from "@sayrio/public/react";
-```
+> Authentication is required.  
+> Set a token using `Sayr.client.setToken(...)`.
 
 ---
 
-### `useOrg`
+### Fetch Current User
+
+```ts
+Sayr.client.setToken(token);
 
-Fetch and subscribe to an organization:
+const me = await Sayr.me.get();
 
-```tsx
-const { data: org, loading } = useOrg("acme");
+console.log(me.email);
 ```
 
 ---
 
-### `useTasks`
+### List Your Organizations
 
-Fetch and subscribe to tasks for an organization:
+```ts
+const orgs = await Sayr.me.organizations();
 
-```tsx
-const { tasks } = useTasks("acme", org?.wsUrl);
+console.log(orgs);
 ```
 
 ---
 
-### `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]: (task) => {
+    console.log("Task updated", task);
+  }
+});
 ```
 
-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";
@@ -157,17 +167,59 @@ The SDK can be used directly in the browser via ESM:
 
 ## API
 
-### `Sayr.org`
+### `Sayr.org` (latest)
+
+Alias for `Sayr.v1.org`.
 
-| 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          |
+#### 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
+
+| Method                         | Description     |
+| ------------------------------ | --------------- |
+| `categories.list(slug, order?)` | List categories |
+
+---
+
+### `Sayr.me`
+
+Authenticated user endpoints.
+
+| Method              | Description                            |
+| ------------------- | -------------------------------------- |
+| `get()`             | Fetch the current authenticated user   |
+| `organizations()`   | List organizations the user belongs to |
 
 ---
 
@@ -180,19 +232,19 @@ const conn = Sayr.ws(wsUrl, {
   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.UPDATE_TASK;
+Sayr.WS_EVENTS.UPDATE_ORG;
+Sayr.WS_EVENTS.ERROR;
 ```
 
 ---
@@ -202,5 +254,11 @@ Sayr.wsTypes.ERROR
 This package ships with full TypeScript definitions:
 
 ```ts
-import type { Organization, Task } from "@sayrio/public";
+import type {
+  Organization,
+  Task,
+  Comment
+} from "@sayrio/public";
 ```
+
+---

package/dist/index.cjs

@@ -20,82 +20,273 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  default: () => index_default,
-  org: () => org,
-  ws: () => ws,
-  wsTypes: () => wsTypes
+  SayrClient: () => SayrClient,
+  SayrV1: () => SayrV1,
+  SayrWS: () => SayrWS,
+  SayrWSEvents: () => SayrWSEvents,
+  WS_EVENTS: () => WS_EVENTS,
+  buildPaginationParams: () => buildPaginationParams,
+  default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/org.ts
-var API = "https://sayr.io/api/public";
-async function get(url) {
-  const res = await fetch(url);
-  const json = await res.json();
-  if (!json.success) throw json;
+// src/client/index.ts
+var DEFAULT_API = "https://api.sayr.io";
+var config = {
+  fetch: globalThis.fetch,
+  baseUrl: DEFAULT_API
+};
+var hooks = {};
+function setToken(token) {
+  config.token = token;
+}
+function setHeaders(headers) {
+  config.headers = {
+    ...config.headers,
+    ...headers
+  };
+}
+function setFetch(fn) {
+  config.fetch = fn;
+}
+function setBaseUrl(url) {
+  config.baseUrl = url.replace(/\/$/, "");
+}
+function setHooks(h) {
+  Object.assign(hooks, h);
+}
+function resetClient() {
+  config.token = void 0;
+  config.headers = void 0;
+  config.baseUrl = DEFAULT_API;
+}
+async function request(path, opts = {}) {
+  let url;
+  try {
+    url = path.startsWith("http") ? path : `${config.baseUrl}${path}`;
+  } catch (err) {
+    throw err;
+  }
+  try {
+    hooks.onRequest?.(url, opts);
+  } catch (err) {
+    throw err;
+  }
+  let res;
+  try {
+    const method = opts.method ?? "GET";
+    if (method === "GET" && opts.body !== void 0) {
+      throw new Error("GET request cannot have a body");
+    }
+    res = await fetch(url, {
+      method,
+      headers: {
+        ...config.token ? { Authorization: `Bearer ${config.token}` } : {},
+        ...opts.body && method !== "GET" ? { "Content-Type": "application/json" } : {},
+        ...config.headers,
+        ...opts.headers
+      },
+      body: opts.body && method !== "GET" ? JSON.stringify(opts.body) : void 0,
+      signal: opts.signal
+    });
+  } catch (err) {
+    const error = {
+      success: false,
+      error: "NETWORK_ERROR",
+      message: "Failed to reach Sayr API",
+      // 👇 keep raw error so we can see it
+      // @ts-ignore
+      raw: err
+    };
+    hooks.onError?.(error);
+    throw error;
+  }
+  try {
+    hooks.onResponse?.(res);
+  } catch (err) {
+    throw err;
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch (err) {
+    const error = {
+      success: false,
+      error: "INVALID_RESPONSE",
+      message: "Server returned invalid JSON",
+      status: res.status
+    };
+    hooks.onError?.(error);
+    throw error;
+  }
+  if (!res.ok || !json.success) {
+    const error = {
+      ...json,
+      success: false,
+      status: res.status
+    };
+    hooks.onError?.(error);
+    throw error;
+  }
   return json;
 }
-var org = {
-  async get(slug) {
-    const r = await get(
-      `${API}/organization/${slug}`
+
+// src/api/v1/org/org.ts
+var org_default = {
+  /**
+   * Fetches a public organization by slug.
+   *
+   * @since v1.0.0
+   */
+  async get(slug, opts) {
+    const r = await request(
+      `/v1/organization/${slug}`,
+      opts
     );
     return r.data;
-  },
-  async labels(slug) {
-    const r = await get(
-      `${API}/organization/${slug}/labels`
+  }
+};
+
+// src/shared/index.ts
+function buildPaginationParams(params) {
+  return new URLSearchParams({
+    order: params?.order ?? "desc",
+    limit: String(params?.limit ?? 5),
+    page: String(params?.page ?? 1)
+  });
+}
+
+// src/api/v1/org/tasks.ts
+var tasks_default = {
+  /**
+   * Lists public tasks for an organization.
+   *
+   * @since v1.0.0
+   */
+  async list(slug, params, opts) {
+    const q = buildPaginationParams(params);
+    const r = await request(
+      `/v1/organization/${slug}/tasks?${q}`,
+      opts
     );
-    return r.data;
+    return {
+      data: r.data,
+      pagination: r.pagination
+    };
   },
-  async categories(slug, order = "desc") {
-    const r = await get(
-      `${API}/organization/${slug}/categories?order=${order}`
+  /**
+   * Fetches a single public task by short ID.
+   *
+   * @since v1.0.0
+   */
+  async get(slug, shortId, opts) {
+    const r = await request(
+      `/v1/organization/${slug}/tasks/${shortId}`,
+      opts
     );
     return r.data;
-  },
-  async tasks(slug, opts) {
-    const q = new URLSearchParams({
-      order: opts?.order ?? "desc",
-      limit: String(opts?.limit ?? 5),
-      page: String(opts?.page ?? 1)
-    });
-    const res = await fetch(
-      `${API}/organization/${slug}/tasks?${q}`
+  }
+};
+
+// src/api/v1/org/comments.ts
+var comments_default = {
+  /**
+   * Lists public comments for a task.
+   *
+   * @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
     );
-    const json = await res.json();
-    if (!json.success) throw json;
     return {
-      data: json.data,
-      pagination: json.pagination
+      data: r.data,
+      pagination: r.pagination
     };
-  },
-  async task(slug, shortId) {
-    const r = await get(
-      `${API}/organization/${slug}/tasks/${shortId}`
+  }
+};
+
+// src/api/v1/org/labels.ts
+var labels_default = {
+  /**
+   * Lists public labels for an organization.
+   *
+   * @since v1.0.0
+   */
+  async list(slug, opts) {
+    const r = await request(
+      `/v1/organization/${slug}/labels`,
+      opts
+    );
+    return r.data;
+  }
+};
+
+// src/api/v1/org/categories.ts
+var categories_default = {
+  /**
+   * Lists public categories for an organization.
+   *
+   * @since v1.0.0
+   */
+  async list(slug, order = "desc", opts) {
+    const r = await request(
+      `/v1/organization/${slug}/categories?order=${order}`,
+      opts
+    );
+    return r.data;
+  }
+};
+
+// src/api/v1/org/index.ts
+var OrgAPI = {
+  ...org_default,
+  tasks: tasks_default,
+  comments: comments_default,
+  labels: labels_default,
+  categories: categories_default
+};
+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;
   },
-  async comments(slug, shortId, opts) {
-    const q = new URLSearchParams({
-      order: opts?.order ?? "desc",
-      limit: String(opts?.limit ?? 5),
-      page: String(opts?.page ?? 1)
-    });
-    const res = await fetch(
-      `${API}/organization/${slug}/tasks/${shortId}/comments?${q}`
+  /**
+   * Lists organizations the current user belongs to.
+   *
+   * @since v1.0.0
+   */
+  async organizations(opts) {
+    const r = await request(
+      "/organizations",
+      opts
     );
-    const json = await res.json();
-    if (!json.success) throw json;
-    return {
-      data: json.data,
-      pagination: json.pagination
-    };
+    return r.data;
   }
 };
 
-// src/ws.ts
-var wsTypes = {
+// src/api/v1/index.ts
+var v1 = {
+  org: org_default2,
+  me: me_default
+};
+var v1_default = v1;
+
+// src/ws/types.ts
+var WS_EVENTS = {
   CONNECTION_STATUS: "CONNECTION_STATUS",
   SUBSCRIBED: "SUBSCRIBED",
   ERROR: "ERROR",
@@ -112,6 +303,8 @@ var wsTypes = {
   UPDATE_ISSUE_TEMPLATES: "UPDATE_ISSUE_TEMPLATES",
   DISCONNECTED: "DISCONNECTED"
 };
+
+// src/ws/index.ts
 function ws(url, handlers = {}) {
   if (!url) {
     throw new Error(
@@ -126,8 +319,8 @@ function ws(url, handlers = {}) {
     socket = new WebSocket(url);
     socket.onmessage = (e) => {
       const msg = JSON.parse(e.data);
-      if (msg.type === wsTypes.PING) {
-        socket.send(JSON.stringify({ type: wsTypes.PONG }));
+      if (msg.type === WS_EVENTS.PING) {
+        socket.send(JSON.stringify({ type: WS_EVENTS.PONG }));
         return;
       }
       handlers[msg.type]?.(msg.data, msg);
@@ -148,12 +341,36 @@ function ws(url, handlers = {}) {
 }
 
 // src/index.ts
-var Sayr = { org, ws, wsTypes };
+var SayrV1 = v1_default;
+var SayrWS = ws;
+var SayrWSEvents = WS_EVENTS;
+var SayrClient = {
+  setToken,
+  setHeaders,
+  setBaseUrl,
+  resetClient,
+  setHooks,
+  setFetch
+};
+var Sayr = {
+  // client configuration
+  client: SayrClient,
+  // APIs
+  v1: v1_default,
+  org: v1_default.org,
+  me: v1_default.me,
+  // realtime
+  ws,
+  WS_EVENTS
+};
 var index_default = Sayr;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  org,
-  ws,
-  wsTypes
+  SayrClient,
+  SayrV1,
+  SayrWS,
+  SayrWSEvents,
+  WS_EVENTS,
+  buildPaginationParams
 });
 //# sourceMappingURL=index.cjs.map