@sayrio/public 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +271 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
|
|
2
|
+
# @sayrio/public
|
|
3
|
+
|
|
4
|
+
Public JavaScript & TypeScript SDK for **Sayr.io**.
|
|
5
|
+
Provides **read‑only access** to Sayr organizations, tasks, comments, and
|
|
6
|
+
real‑time updates via WebSockets.
|
|
7
|
+
|
|
8
|
+
- ✅ REST + WebSocket
|
|
9
|
+
- ✅ Browser‑safe
|
|
10
|
+
- ✅ TypeScript first
|
|
11
|
+
- ✅ React hooks included (`/react`)
|
|
12
|
+
- ✅ Zero runtime dependencies
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @sayrio/public
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
or
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pnpm add @sayrio/public
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Usage
|
|
31
|
+
|
|
32
|
+
### Basic (REST)
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import Sayr from "@sayrio/public";
|
|
36
|
+
|
|
37
|
+
const org = await Sayr.org.get("test");
|
|
38
|
+
|
|
39
|
+
console.log(org.name);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
### Tasks
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
const { data: tasks, pagination } =
|
|
48
|
+
await Sayr.org.tasks("test", {
|
|
49
|
+
order: "desc",
|
|
50
|
+
limit: 10
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
console.log(tasks);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
### Task Comments
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
const { data: comments } =
|
|
62
|
+
await Sayr.org.comments("test", 12);
|
|
63
|
+
|
|
64
|
+
console.log(comments);
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## WebSocket (Real‑Time Updates)
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
Sayr.ws(org.wsUrl, {
|
|
73
|
+
[Sayr.wsTypes.UPDATE_ORG]: (data) => {
|
|
74
|
+
console.log("Org updated", data);
|
|
75
|
+
},
|
|
76
|
+
|
|
77
|
+
[Sayr.wsTypes.UPDATE_TASK]: (task) => {
|
|
78
|
+
console.log("Task updated", task);
|
|
79
|
+
}
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Features
|
|
84
|
+
- Automatic reconnect
|
|
85
|
+
- Heartbeat (PING / PONG)
|
|
86
|
+
- Typed event names
|
|
87
|
+
- Public‑safe payloads
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## React Hooks
|
|
92
|
+
|
|
93
|
+
React hooks are available via a sub‑path export:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { useOrg, useTasks } from "@sayrio/public/react";
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
### `useOrg`
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
const { data: org, loading } = useOrg("test");
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
### `useTasks`
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
const { tasks } = useTasks("test", org?.wsUrl);
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
### `useComments`
|
|
118
|
+
|
|
119
|
+
```tsx
|
|
120
|
+
const { comments } = useComments(
|
|
121
|
+
"test",
|
|
122
|
+
task.shortId,
|
|
123
|
+
org?.wsUrl
|
|
124
|
+
);
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Hooks automatically refresh when relevant WebSocket events occur.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Browser Usage (No Bundler)
|
|
132
|
+
|
|
133
|
+
You can use the SDK directly in the browser via ESM:
|
|
134
|
+
|
|
135
|
+
```html
|
|
136
|
+
<script type="module">
|
|
137
|
+
import Sayr from "https://esm.sh/@sayrio/public";
|
|
138
|
+
|
|
139
|
+
const org = await Sayr.org.get("test");
|
|
140
|
+
console.log(org);
|
|
141
|
+
</script>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## API
|
|
147
|
+
|
|
148
|
+
### `Sayr.org`
|
|
149
|
+
|
|
150
|
+
| Method | Description |
|
|
151
|
+
|------|-------------|
|
|
152
|
+
| `get(slug)` | Get public organization |
|
|
153
|
+
| `labels(slug)` | List labels |
|
|
154
|
+
| `categories(slug, order?)` | List categories |
|
|
155
|
+
| `tasks(slug, opts?)` | List tasks (paginated) |
|
|
156
|
+
| `task(slug, shortId)` | Get single task |
|
|
157
|
+
| `comments(slug, shortId, opts?)` | List comments |
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
### `Sayr.ws(url, handlers)`
|
|
162
|
+
|
|
163
|
+
Create a WebSocket connection for public events.
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const conn = Sayr.ws(wsUrl, {
|
|
167
|
+
UPDATE_TASK: () => {}
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
// later
|
|
171
|
+
conn.close();
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
### `Sayr.wsTypes`
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
Sayr.wsTypes.UPDATE_TASK
|
|
180
|
+
Sayr.wsTypes.UPDATE_ORG
|
|
181
|
+
Sayr.wsTypes.ERROR
|
|
182
|
+
// ...
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## TypeScript
|
|
188
|
+
|
|
189
|
+
This package ships with full TypeScript definitions.
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
import type { Organization, Task } from "@sayrio/public";
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Basic HTML Example
|
|
198
|
+
|
|
199
|
+
This example shows how to use `@sayrio/public` in a **plain HTML file** with no
|
|
200
|
+
build tools.
|
|
201
|
+
|
|
202
|
+
> **Important:**
|
|
203
|
+
> This SDK is published as an **ES module**, so you must use
|
|
204
|
+
> `type="module"` and `import`.
|
|
205
|
+
> It does **not** create a global `Sayr` variable.
|
|
206
|
+
|
|
207
|
+
```html
|
|
208
|
+
<!DOCTYPE html>
|
|
209
|
+
<html lang="en">
|
|
210
|
+
<head>
|
|
211
|
+
<meta charset="utf-8" />
|
|
212
|
+
<title>Sayr Public SDK – HTML Example</title>
|
|
213
|
+
<style>
|
|
214
|
+
body {
|
|
215
|
+
background: #0b0b0b;
|
|
216
|
+
color: #e5e7eb;
|
|
217
|
+
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
|
218
|
+
padding: 24px;
|
|
219
|
+
}
|
|
220
|
+
</style>
|
|
221
|
+
</head>
|
|
222
|
+
|
|
223
|
+
<body>
|
|
224
|
+
<h1>Sayr Public SDK</h1>
|
|
225
|
+
<pre id="out">Loading…</pre>
|
|
226
|
+
|
|
227
|
+
<script type="module">
|
|
228
|
+
import Sayr from "https://esm.sh/@sayrio/public";
|
|
229
|
+
|
|
230
|
+
const out = document.getElementById("out");
|
|
231
|
+
|
|
232
|
+
function log(label, value) {
|
|
233
|
+
out.textContent +=
|
|
234
|
+
label + ": " + JSON.stringify(value, null, 2) + "\n\n";
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
const slug = "org";
|
|
238
|
+
|
|
239
|
+
// Fetch public organization
|
|
240
|
+
const org = await Sayr.org.get(slug);
|
|
241
|
+
log("Organization", org);
|
|
242
|
+
|
|
243
|
+
// Connect to public WebSocket
|
|
244
|
+
Sayr.ws(org.wsUrl, {
|
|
245
|
+
[Sayr.wsTypes.UPDATE_ORG]: (data) => {
|
|
246
|
+
log("Org updated", data);
|
|
247
|
+
},
|
|
248
|
+
|
|
249
|
+
[Sayr.wsTypes.UPDATE_TASK]: (task) => {
|
|
250
|
+
log("Task updated", task);
|
|
251
|
+
},
|
|
252
|
+
|
|
253
|
+
[Sayr.wsTypes.ERROR]: (err) => {
|
|
254
|
+
log("WebSocket error", err);
|
|
255
|
+
}
|
|
256
|
+
});
|
|
257
|
+
</script>
|
|
258
|
+
</body>
|
|
259
|
+
</html>
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## Notes on Browser Usage
|
|
265
|
+
|
|
266
|
+
- This package **does not expose a global `Sayr`**
|
|
267
|
+
- Always use `type="module"` and `import`
|
|
268
|
+
- For legacy `<script>` usage, a UMD build is not currently provided
|
|
269
|
+
- `esm.sh` is recommended for CDN usage
|
|
270
|
+
|
|
271
|
+
---
|