Sayr Public API & SDK

Public JavaScript SDK for interacting with Sayr organizations, tasks, and real-time updates

Installation

npm install @sayrio/public

pnpm add @sayrio/public

Core Concepts

✅ `ApiResult<T>`

All SDK methods return a non‑throwing result object:

interface ApiResult<T> {
  success: boolean;
  data: T | null;
  error: string | null;
}

Always check success before accessing data.

Usage

Basic Usage (REST)

Fetch a public organization.

Sayr.org is an alias for the latest API version (v1).

import Sayr from "@sayrio/public";

const res = await Sayr.org.get("acme");

if (!res.success) {
  console.error(res.error);
  return;
}

console.log(res.data.name);

You can also use the versioned API explicitly:

const res = await Sayr.v1.org.get("acme");

Organizations

Fetch an Organization

const res = await Sayr.org.get("acme");

if (res.success) {
  console.log(res.data);
}

Tasks

List Tasks (Paginated)

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(res.data.pagination);

Returned shape:

ApiResult<{
  items: Task[];
  pagination: Pagination;
}>

Fetch a Single Task

const res = await Sayr.org.tasks.get("acme", 42);

if (res.success) {
  console.log(res.data.title);
}

Comments

List Task Comments (Paginated)

const res = await Sayr.org.comments.list("acme", 42);

if (!res.success) return;

res.data.items.forEach((comment) => {
  console.log(comment.contentMarkdown);
});

Returned shape:

ApiResult<{
  items: Comment[];
  pagination: Pagination;
}>

Labels & Categories

Labels

const res = await Sayr.org.labels.list("acme");

if (res.success) {
  console.log(res.data);
}

Authenticated User (`/me`)

The /me namespace provides read‑only access to the currently authenticated user.

Authentication is required
Set a token using Sayr.client.setToken(...).

Set Token

Sayr.client.setToken("********");

Fetch Current User

const res = await Sayr.me.get();

if (res.success) {
  console.log(res.data.email);
}

List Your Organizations

const res = await Sayr.me.organizations();

if (res.success) {
  console.log(res.data);
}

Real‑Time Updates (SSE)

Subscribe to public real‑time events using Server‑Sent Events:

Sayr.sse(org.eventsUrl, {
  [Sayr.EVENTS.UPDATE_TASK]: (data) => {
    console.log("Task updated", data);
  },
});

SSE Features

Automatic reconnection (native in browsers)
Lightweight, one‑way streaming
Typed event constants
Public‑safe payloads only

Browser Usage (No Bundler)

<script type="module">
  import Sayr from "https://esm.sh/@sayrio/public";

  const res = await Sayr.org.get("acme");

  if (res.success) {
    console.log(res.data);
  }
</script>

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

Method	Description
`categories.list(slug, order?)`	List categories

`Sayr.me`

Authenticated user endpoints.

Method	Description
`get()`	Fetch the authenticated user
`organizations()`	List organizations the user belongs to

Real‑Time API

Sayr.sse(url, handlers)

Create an SSE connection for public events:

const conn = Sayr.sse(eventsUrl, {
  UPDATE_TASK: () => {},
});

conn.close();

`EVENTS`

Typed SSE event constants:

Sayr.EVENTS.CREATE_TASK;
Sayr.EVENTS.UPDATE_TASK;
Sayr.EVENTS.UPDATE_TASK_COMMENTS;
Sayr.EVENTS.ERROR;

TypeScript

This package ships with full TypeScript definitions:

import type {
  Organization,
  Task,
  Comment,
  Label,
  Category,
} from "@sayrio/public";

React Hooks

React bindings are available via:

import {
  useOrg,
  useTasks,
  useTask,
  useComments,
} from "@sayrio/public/react";

See @sayrio/public/react README for full hook documentation.

Sayr Public API & SDK

On this page