@pingroom/sdk 0.7.1 → 0.9.0

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.
Files changed (191) hide show
  1. package/README.md +288 -44
  2. package/dist/client.d.ts +27 -312
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +33 -1154
  5. package/dist/client.js.map +1 -1
  6. package/dist/errors.d.ts +40 -6
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +56 -4
  9. package/dist/errors.js.map +1 -1
  10. package/dist/http.d.ts +12 -1
  11. package/dist/http.d.ts.map +1 -1
  12. package/dist/http.js +47 -18
  13. package/dist/http.js.map +1 -1
  14. package/dist/index.d.ts +3 -5
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +1 -2
  17. package/dist/index.js.map +1 -1
  18. package/dist/internal/async.d.ts +2 -0
  19. package/dist/internal/async.d.ts.map +1 -1
  20. package/dist/internal/async.js +6 -0
  21. package/dist/internal/async.js.map +1 -1
  22. package/dist/internal/guards.d.ts +16 -0
  23. package/dist/internal/guards.d.ts.map +1 -1
  24. package/dist/internal/guards.js +22 -1
  25. package/dist/internal/guards.js.map +1 -1
  26. package/dist/internal/request.d.ts +41 -0
  27. package/dist/internal/request.d.ts.map +1 -0
  28. package/dist/internal/request.js +78 -0
  29. package/dist/internal/request.js.map +1 -0
  30. package/dist/internal/retry.d.ts +65 -0
  31. package/dist/internal/retry.d.ts.map +1 -0
  32. package/dist/internal/retry.js +126 -0
  33. package/dist/internal/retry.js.map +1 -0
  34. package/dist/internal/url.d.ts +9 -0
  35. package/dist/internal/url.d.ts.map +1 -1
  36. package/dist/internal/url.js +25 -0
  37. package/dist/internal/url.js.map +1 -1
  38. package/dist/internal/validate.d.ts +13 -0
  39. package/dist/internal/validate.d.ts.map +1 -0
  40. package/dist/internal/validate.js +36 -0
  41. package/dist/internal/validate.js.map +1 -0
  42. package/dist/linkPing.d.ts.map +1 -1
  43. package/dist/linkPing.js +6 -2
  44. package/dist/linkPing.js.map +1 -1
  45. package/dist/liveStatus.d.ts +106 -11
  46. package/dist/liveStatus.d.ts.map +1 -1
  47. package/dist/liveStatus.js +20 -3
  48. package/dist/liveStatus.js.map +1 -1
  49. package/dist/mcp.d.ts.map +1 -1
  50. package/dist/mcp.js +40 -10
  51. package/dist/mcp.js.map +1 -1
  52. package/dist/namespaces/actions.d.ts +50 -0
  53. package/dist/namespaces/actions.d.ts.map +1 -0
  54. package/dist/namespaces/actions.js +219 -0
  55. package/dist/namespaces/actions.js.map +1 -0
  56. package/dist/namespaces/approvals.d.ts +23 -0
  57. package/dist/namespaces/approvals.d.ts.map +1 -0
  58. package/dist/namespaces/approvals.js +78 -0
  59. package/dist/namespaces/approvals.js.map +1 -0
  60. package/dist/namespaces/attachments.d.ts +37 -0
  61. package/dist/namespaces/attachments.d.ts.map +1 -0
  62. package/dist/namespaces/attachments.js +91 -0
  63. package/dist/namespaces/attachments.js.map +1 -0
  64. package/dist/namespaces/auth.d.ts +58 -0
  65. package/dist/namespaces/auth.d.ts.map +1 -0
  66. package/dist/namespaces/auth.js +242 -0
  67. package/dist/namespaces/auth.js.map +1 -0
  68. package/dist/namespaces/directory.d.ts +10 -0
  69. package/dist/namespaces/directory.d.ts.map +1 -0
  70. package/dist/namespaces/directory.js +19 -0
  71. package/dist/namespaces/directory.js.map +1 -0
  72. package/dist/namespaces/handoffs.d.ts +47 -0
  73. package/dist/namespaces/handoffs.d.ts.map +1 -0
  74. package/dist/namespaces/handoffs.js +126 -0
  75. package/dist/namespaces/handoffs.js.map +1 -0
  76. package/dist/namespaces/inbox.d.ts +17 -0
  77. package/dist/namespaces/inbox.d.ts.map +1 -0
  78. package/dist/namespaces/inbox.js +192 -0
  79. package/dist/namespaces/inbox.js.map +1 -0
  80. package/dist/namespaces/live.d.ts +57 -0
  81. package/dist/namespaces/live.d.ts.map +1 -0
  82. package/dist/namespaces/live.js +116 -0
  83. package/dist/namespaces/live.js.map +1 -0
  84. package/dist/namespaces/notifications.d.ts +25 -0
  85. package/dist/namespaces/notifications.d.ts.map +1 -0
  86. package/dist/namespaces/notifications.js +128 -0
  87. package/dist/namespaces/notifications.js.map +1 -0
  88. package/dist/namespaces/profile.d.ts +19 -0
  89. package/dist/namespaces/profile.d.ts.map +1 -0
  90. package/dist/namespaces/profile.js +22 -0
  91. package/dist/namespaces/profile.js.map +1 -0
  92. package/dist/namespaces/questions.d.ts +41 -0
  93. package/dist/namespaces/questions.d.ts.map +1 -0
  94. package/dist/namespaces/questions.js +107 -0
  95. package/dist/namespaces/questions.js.map +1 -0
  96. package/dist/namespaces/rooms.d.ts +13 -0
  97. package/dist/namespaces/rooms.d.ts.map +1 -0
  98. package/dist/namespaces/rooms.js +41 -0
  99. package/dist/namespaces/rooms.js.map +1 -0
  100. package/dist/namespaces/webhooks.d.ts +11 -0
  101. package/dist/namespaces/webhooks.d.ts.map +1 -0
  102. package/dist/namespaces/webhooks.js +32 -0
  103. package/dist/namespaces/webhooks.js.map +1 -0
  104. package/dist/types/approvals.d.ts +62 -0
  105. package/dist/types/approvals.d.ts.map +1 -0
  106. package/dist/types/approvals.js +2 -0
  107. package/dist/types/approvals.js.map +1 -0
  108. package/dist/types/auth.d.ts +185 -0
  109. package/dist/types/auth.d.ts.map +1 -0
  110. package/dist/types/auth.js +2 -0
  111. package/dist/types/auth.js.map +1 -0
  112. package/dist/types/common.d.ts +43 -0
  113. package/dist/types/common.d.ts.map +1 -0
  114. package/dist/types/common.js +2 -0
  115. package/dist/types/common.js.map +1 -0
  116. package/dist/types/handoffs.d.ts +121 -0
  117. package/dist/types/handoffs.d.ts.map +1 -0
  118. package/dist/types/handoffs.js +2 -0
  119. package/dist/types/handoffs.js.map +1 -0
  120. package/dist/types/inbox.d.ts +51 -0
  121. package/dist/types/inbox.d.ts.map +1 -0
  122. package/dist/types/inbox.js +2 -0
  123. package/dist/types/inbox.js.map +1 -0
  124. package/dist/types/notifications.d.ts +376 -0
  125. package/dist/types/notifications.d.ts.map +1 -0
  126. package/dist/types/notifications.js +2 -0
  127. package/dist/types/notifications.js.map +1 -0
  128. package/dist/types/profile.d.ts +30 -0
  129. package/dist/types/profile.d.ts.map +1 -0
  130. package/dist/types/profile.js +3 -0
  131. package/dist/types/profile.js.map +1 -0
  132. package/dist/types/questions.d.ts +210 -0
  133. package/dist/types/questions.d.ts.map +1 -0
  134. package/dist/types/questions.js +2 -0
  135. package/dist/types/questions.js.map +1 -0
  136. package/dist/types/rooms.d.ts +163 -0
  137. package/dist/types/rooms.d.ts.map +1 -0
  138. package/dist/types/rooms.js +3 -0
  139. package/dist/types/rooms.js.map +1 -0
  140. package/dist/types.d.ts +9 -1035
  141. package/dist/types.d.ts.map +1 -1
  142. package/dist/version.d.ts +1 -1
  143. package/dist/version.js +1 -1
  144. package/dist/webhooks.d.ts +32 -5
  145. package/dist/webhooks.d.ts.map +1 -1
  146. package/dist/webhooks.js +44 -14
  147. package/dist/webhooks.js.map +1 -1
  148. package/package.json +4 -2
  149. package/src/client.ts +115 -0
  150. package/src/errors.ts +291 -0
  151. package/src/http.ts +225 -0
  152. package/src/index.ts +97 -0
  153. package/src/internal/async.ts +54 -0
  154. package/src/internal/guards.ts +129 -0
  155. package/src/internal/request.ts +97 -0
  156. package/src/internal/retry.ts +157 -0
  157. package/src/internal/url.ts +78 -0
  158. package/src/internal/validate.ts +42 -0
  159. package/src/linkPing.ts +56 -0
  160. package/src/liveStatus.ts +337 -0
  161. package/src/locationPing.ts +101 -0
  162. package/src/mcp.ts +161 -0
  163. package/src/namespaces/actions.ts +234 -0
  164. package/src/namespaces/approvals.ts +104 -0
  165. package/src/namespaces/attachments.ts +106 -0
  166. package/src/namespaces/auth.ts +284 -0
  167. package/src/namespaces/directory.ts +21 -0
  168. package/src/namespaces/handoffs.ts +160 -0
  169. package/src/namespaces/inbox.ts +253 -0
  170. package/src/namespaces/live.ts +134 -0
  171. package/src/namespaces/notifications.ts +152 -0
  172. package/src/namespaces/profile.ts +24 -0
  173. package/src/namespaces/questions.ts +133 -0
  174. package/src/namespaces/rooms.ts +53 -0
  175. package/src/namespaces/webhooks.ts +38 -0
  176. package/src/types/approvals.ts +67 -0
  177. package/src/types/auth.ts +202 -0
  178. package/src/types/common.ts +74 -0
  179. package/src/types/handoffs.ts +148 -0
  180. package/src/types/inbox.ts +64 -0
  181. package/src/types/notifications.ts +393 -0
  182. package/src/types/profile.ts +37 -0
  183. package/src/types/questions.ts +226 -0
  184. package/src/types/rooms.ts +169 -0
  185. package/src/types.ts +17 -0
  186. package/src/version.ts +2 -0
  187. package/src/webhooks.ts +373 -0
  188. package/dist/liveActivity.d.ts +0 -101
  189. package/dist/liveActivity.d.ts.map +0 -1
  190. package/dist/liveActivity.js +0 -83
  191. package/dist/liveActivity.js.map +0 -1
@@ -0,0 +1,376 @@
1
+ import type { JsonObject } from './common.js';
2
+ import type { Room } from './rooms.js';
3
+ import type { Question } from './questions.js';
4
+ /** A visible Ping — used for broadcasts and the retired direct-ping compatibility method. */
5
+ export interface PingInput {
6
+ /** Visible body (≤ 120 characters in private rooms; ≤ 160 in public rooms). */
7
+ message: string;
8
+ /** Optional visible title (≤ 40 characters). */
9
+ title?: string;
10
+ action_number?: number;
11
+ action_icon?: string;
12
+ /**
13
+ * Structured data echoed on every read surface (<= 25 keys / 8KB).
14
+ * Reserved keys `url` + `button_label` make the ping a tappable link —
15
+ * see the `linkPing()` helper. Reserved `location` carries finite numeric
16
+ * latitude/longitude plus an optional label/address — see `locationPing()`.
17
+ */
18
+ data?: JsonObject;
19
+ correlation_id?: string;
20
+ reply_to?: string;
21
+ /**
22
+ * Ordered ids from `attachments.upload()` (max 4). Ids are single-use: the
23
+ * send claims them, and an already-claimed or expired id fails the whole
24
+ * ping. File bytes never ride this JSON body.
25
+ */
26
+ attachment_ids?: string[];
27
+ /**
28
+ * Open the acknowledgement lifecycle for this ping. The ack_mode rule
29
+ * determines when it resolves, and recipients see a lock-screen card with an Acknowledge button.
30
+ *
31
+ * Does NOT raise the delivery priority — that is {@link PingInput.is_urgent},
32
+ * and the two are independent. They were one flag, which meant asking for a
33
+ * ping that cuts through Focus also demanded that somebody acknowledge it.
34
+ */
35
+ requires_ack?: boolean;
36
+ /** Confirmation rule; defaults to any. all waits for every original eligible recipient. */
37
+ ack_mode?: AckMode;
38
+ /**
39
+ * Deliver time-sensitive so the ping breaks through Focus / Do Not Disturb
40
+ * and reaches members who muted the room or you (a block still wins).
41
+ * Delivery priority only: no acknowledgement, no Live Activity, nothing asked
42
+ * of the recipient. Set alongside `requires_ack` for an acknowledgement that
43
+ * also cuts through Focus.
44
+ */
45
+ is_urgent?: boolean;
46
+ /**
47
+ * Optional acknowledgement deadline in seconds (60–86400). Omit/null for no
48
+ * deadline. Validated on every send, so an out-of-range value is a 422 even
49
+ * without `requires_ack`; it takes effect only when the ping requires
50
+ * acknowledgement.
51
+ */
52
+ ack_timeout_seconds?: number | null;
53
+ /**
54
+ * Sent as the `Idempotency-Key` header (1–255 printable ASCII characters,
55
+ * spaces allowed), never in the body.
56
+ * Reuse the same key when retrying after a timeout or network error: the
57
+ * server replays the first result instead of sending the ping again.
58
+ */
59
+ idempotencyKey?: string;
60
+ }
61
+ /**
62
+ * Safe attachment metadata. Storage keys, checksums, owner ids, and permanent
63
+ * URLs are deliberately not part of this contract — read the bytes through
64
+ * `attachments.content()` with the credential that can see the ping.
65
+ */
66
+ export interface Attachment {
67
+ id: string;
68
+ filename: string;
69
+ mime_type: string;
70
+ size_bytes: number;
71
+ created_at: string;
72
+ }
73
+ /** The file types the attachment endpoint accepts. */
74
+ /** One row of a `.zip` attachment's listing. */
75
+ export interface ZipManifestEntry {
76
+ name: string;
77
+ /** Null when the archive declared no size, or declared a ZIP64 sentinel. */
78
+ size_bytes: number | null;
79
+ is_directory: boolean;
80
+ }
81
+ /**
82
+ * A `.zip` attachment's contents as recorded at upload. Bounded server-side, so
83
+ * `entries` may be shorter than `total_entries`.
84
+ */
85
+ export interface ZipManifest {
86
+ entries: ZipManifestEntry[];
87
+ total_entries: number;
88
+ truncated: boolean;
89
+ /** Sum of the sizes the archive DECLARES. Nothing verifies or expands them. */
90
+ total_uncompressed_bytes: number;
91
+ }
92
+ export type AttachmentExtension = 'md' | 'pdf' | 'html' | 'txt' | 'jpg' | 'jpeg' | 'png' | 'zip';
93
+ export interface UploadAttachmentInput {
94
+ /** File bytes (1 byte–5 MiB). A Blob/File, a Uint8Array, or a UTF-8 string. */
95
+ content: Blob | Uint8Array | string;
96
+ /** Display filename. Its extension must be one of AttachmentExtension. */
97
+ filename: string;
98
+ /** Overrides the type sent in the multipart part. Usually inferred is fine. */
99
+ contentType?: string;
100
+ signal?: AbortSignal;
101
+ }
102
+ export interface TriggerInput {
103
+ /**
104
+ * Only the sources a device legitimately originates; `webhook`/`system` are
105
+ * stamped server-side and are rejected here. `manual` (the default) presses
106
+ * the slot.
107
+ *
108
+ * `location` is the device-geofence source, not a press modifier. It is for
109
+ * the ROOM OWNER only and sends the owner's Location Ping (an "Arrived at
110
+ * {place}" or "Left {place}" Ping to every member, with no action number)
111
+ * INSTEAD of the quick action in the slot. A caller who is not the room owner
112
+ * gets `403 location_trigger_owner_only`; a room with no enabled location
113
+ * trigger (or none that listens for the reported crossing) gets
114
+ * `409 location_trigger_inactive`; the operator's Location Pings switch being
115
+ * off gets `403 feature_disabled`. `is_urgent` and `requires_ack` still apply
116
+ * to it. To press a Quick Ping leave this unset.
117
+ */
118
+ trigger_source?: 'manual' | 'location';
119
+ /**
120
+ * Deliver this one press time-sensitive so it breaks through Focus / Do Not
121
+ * Disturb and reaches members who muted the room or you (a block still
122
+ * wins). Send-time only — the action's saved configuration is untouched,
123
+ * and quick actions have no stored urgency policy to override. Never implies
124
+ * `requires_ack`, which is the action's own saved acknowledgement policy.
125
+ */
126
+ is_urgent?: boolean;
127
+ /**
128
+ * One-shot acknowledgement modifier for this press only. It is OR-ed with the
129
+ * action's stored policy, so it can only ADD an ack requirement — passing
130
+ * `false` never removes one from an action already configured to require it.
131
+ * The action's saved configuration is untouched either way.
132
+ */
133
+ requires_ack?: boolean;
134
+ /** Applies to this press only, when its effective acknowledgement policy is enabled. */
135
+ ack_mode?: AckMode;
136
+ /**
137
+ * The detail this press carries when the action has an `input_type`. Only
138
+ * `location` and `url` are accepted on a trigger — no `button_label`; build
139
+ * the fragments with `locationPing()` / `linkPing()` or pass them directly.
140
+ */
141
+ data?: TriggerData;
142
+ /**
143
+ * Ids from `attachments.upload()`, at most 4. Required when `input_type` is
144
+ * `file`, `photo` (jpg/png only) or `pdf` (pdf only); a mismatched type is
145
+ * `422 quick_action_input_type`.
146
+ */
147
+ attachment_ids?: string[];
148
+ /**
149
+ * The action's `id` as read from `actions.list()`. When that slot has since
150
+ * moved pages the press is refused with `409 quick_action_layout_changed`
151
+ * rather than firing the wrong Ping.
152
+ */
153
+ quick_action_id?: string;
154
+ /**
155
+ * Sent as the `Idempotency-Key` header (1–255 printable ASCII characters,
156
+ * spaces allowed), never in the body.
157
+ * Reuse the same key when retrying after a timeout or network error: the
158
+ * server replays the first result instead of firing the press again.
159
+ */
160
+ idempotencyKey?: string;
161
+ }
162
+ /** The closed `data` object a quick-action press may carry. */
163
+ export interface TriggerData {
164
+ location?: TriggerLocation;
165
+ /** Absolute http(s) URL, at most 2048 characters. */
166
+ url?: string;
167
+ }
168
+ /** Same shape as `LocationPingLocation`; declared here to keep types.ts import-free. */
169
+ export interface TriggerLocation {
170
+ latitude: number;
171
+ longitude: number;
172
+ label?: string;
173
+ address?: string;
174
+ }
175
+ export type AckMode = 'any' | 'all';
176
+ /** The server-authoritative acknowledgement lifecycle attached to a ping. */
177
+ export interface ActionState {
178
+ /** Omitted by older servers and by the default any mode. */
179
+ mode?: AckMode;
180
+ confirmed_count?: number;
181
+ required_count?: number;
182
+ /** REST only; public rooms redact identities and MCP omits them. */
183
+ confirmed_user_ids?: string[];
184
+ status: 'open' | 'acked' | 'expired' | null;
185
+ requires_ack: boolean;
186
+ acked_by: {
187
+ id: string | null;
188
+ name: string | null;
189
+ profile_image: string | null;
190
+ } | null;
191
+ acked_at: string | null;
192
+ expires_at: string | null;
193
+ /** Set when the confirmation window was closed early. */
194
+ ended_at?: string | null;
195
+ /** Viewer-specific human mutation eligibility; agent read paths return false. */
196
+ can_ack?: boolean;
197
+ /** Recipients who dismissed the card without confirming. Never counts as a confirmation. */
198
+ dismissed_count?: number;
199
+ /** REST only; public rooms redact identities and MCP omits them. */
200
+ dismissed_user_ids?: string[];
201
+ /** Viewer-scoped: when the reading viewer dismissed it. */
202
+ dismissed_at?: string | null;
203
+ }
204
+ /**
205
+ * Who cannot show Confirm for this ping. A recipient with no capable device
206
+ * gets a plain alert, so their confirmation may never come. `checked: false`
207
+ * means nothing was checked (public rooms, rooms over 100 recipients, a failed
208
+ * lookup), not that everyone is reachable. Absent unless `requires_ack`.
209
+ */
210
+ export type ConfirmationReach = {
211
+ checked: true;
212
+ unavailable_user_ids: string[];
213
+ unavailable_count: number;
214
+ } | {
215
+ checked: false;
216
+ };
217
+ export interface PingResult {
218
+ id: string;
219
+ message: string;
220
+ action_number: number | null;
221
+ action_icon: string | null;
222
+ trigger_source: string | null;
223
+ data?: JsonObject | null;
224
+ correlation_id?: string | null;
225
+ reply_to?: string | null;
226
+ attachments?: Attachment[];
227
+ action_state?: ActionState | null;
228
+ created_at: string;
229
+ recipient_count?: number;
230
+ muted_count?: number;
231
+ confirmation_reach?: ConfirmationReach;
232
+ [key: string]: unknown;
233
+ }
234
+ /**
235
+ * The named fields of a listened/listed notification, without the index
236
+ * signature. `Omit` collapses a type carrying a string index signature down to
237
+ * that signature alone, so `NotificationDetail` derives from this rather than
238
+ * from `AgentNotification` — otherwise every named field would widen to
239
+ * `unknown`.
240
+ */
241
+ interface AgentNotificationFields {
242
+ id: string;
243
+ message: string;
244
+ action_number: number | null;
245
+ action_icon: string | null;
246
+ trigger_source: string | null;
247
+ /**
248
+ * True when this ping is an agent handoff (a request to take over a
249
+ * conversation) rather than an ordinary ping.
250
+ */
251
+ is_handoff?: boolean;
252
+ data?: JsonObject | null;
253
+ correlation_id?: string | null;
254
+ reply_to?: string | null;
255
+ attachments?: Attachment[];
256
+ action_state?: ActionState | null;
257
+ /** Confirmation rule the ping was sent with; absent on older rows. */
258
+ ack_mode?: AckMode;
259
+ /**
260
+ * Delivered without sound/haptics (the sender's silent mode at send time).
261
+ * `null` on rows written before 2026-09-16; not surfaced through MCP.
262
+ */
263
+ is_silent?: boolean | null;
264
+ /**
265
+ * The embedded Question when this ping carries one, else null. Same wire
266
+ * shape as the dedicated Question read paths.
267
+ */
268
+ question?: Question | null;
269
+ created_at: string;
270
+ room?: {
271
+ code: string;
272
+ name: string;
273
+ icon: string | null;
274
+ color: string | null;
275
+ };
276
+ sender?: {
277
+ id: string;
278
+ name: string | null;
279
+ };
280
+ /**
281
+ * Present when a connected agent (MCP / CLI credential) originated the
282
+ * ping: the agent registration's display identity. Null/absent on human,
283
+ * webhook, and trigger rows.
284
+ */
285
+ origin_agent?: {
286
+ id?: string;
287
+ handle: string | null;
288
+ display_name: string | null;
289
+ avatar_url?: string | null;
290
+ } | null;
291
+ }
292
+ export interface AgentNotification extends AgentNotificationFields {
293
+ [key: string]: unknown;
294
+ }
295
+ /** Full notification record returned by the single-notification read path. */
296
+ export type NotificationDetail = Omit<AgentNotificationFields, 'room'> & {
297
+ room_id?: string;
298
+ sender_id?: string;
299
+ type?: string;
300
+ requires_ack?: boolean;
301
+ /** Whether this ping was delivered time-sensitive. Independent of `requires_ack`. */
302
+ is_urgent?: boolean;
303
+ action_state: ActionState | null;
304
+ room?: Room;
305
+ [key: string]: unknown;
306
+ };
307
+ /** History keeps the full room and adds the listener-compatible `room.code`. */
308
+ export interface NotificationHistoryEntry extends AgentNotification {
309
+ room?: Room & {
310
+ code: string;
311
+ };
312
+ }
313
+ export interface ListNotificationsInput {
314
+ /** `received` or `sent`; the server refuses any other value. */
315
+ type?: 'received' | 'sent';
316
+ room_id?: string;
317
+ date?: string;
318
+ /** Page size (1–25). Omit to retain the server's legacy default. */
319
+ limit?: number;
320
+ /** Page number, starting at 1. */
321
+ page?: number;
322
+ /** @deprecated Use limit. Sent as limit when limit is absent. */
323
+ notifications_per_page?: number;
324
+ }
325
+ export interface WaitInput {
326
+ /** Cursor (a notification id). Omit to start from the current head. */
327
+ after?: string;
328
+ /** Seconds to hold the connection (0–30, default 20). */
329
+ timeout?: number;
330
+ /** Max notifications to return (1–100, default 50). */
331
+ limit?: number;
332
+ signal?: AbortSignal;
333
+ }
334
+ export interface WaitResult {
335
+ notifications: AgentNotification[];
336
+ cursor: string;
337
+ }
338
+ export interface WaitForAcknowledgementInput {
339
+ /** Seconds to hold the connection (0–30, default 20). */
340
+ timeout?: number;
341
+ signal?: AbortSignal;
342
+ }
343
+ export interface AcknowledgementWaitResult {
344
+ id: string;
345
+ action_state: ActionState;
346
+ }
347
+ export interface ListenInput {
348
+ /** Cursor (a notification id). Omit to start from the current head. */
349
+ after?: string;
350
+ /**
351
+ * Seconds each poll holds the connection (0–30, default 20). Polls start at
352
+ * least 2.1 s apart after an empty answer, so `0` (or a proxy that answers
353
+ * early) cannot use up the wait route's 30-per-minute limit, which is shared
354
+ * with the human's other listeners.
355
+ */
356
+ timeout?: number;
357
+ /** Max notifications per poll (1–100, default 50). */
358
+ limit?: number;
359
+ signal?: AbortSignal;
360
+ /**
361
+ * Called with each transient error (network failure, request timeout, 429,
362
+ * 5xx) before the loop backs off and retries; transient errors are retried
363
+ * whether or not this is set. Any other error (401, 403, 422, …) ends the
364
+ * iterator by throwing, so a revoked credential never retries forever.
365
+ */
366
+ onError?: (err: unknown) => void;
367
+ /**
368
+ * First backoff after a transient error, in ms (default 1000, minimum 250:
369
+ * a smaller value is raised to 250, so a persistent failure never retries in
370
+ * a tight loop against the shared wait limit). It doubles on each consecutive
371
+ * failure up to 30 s; a server `retryAfter` replaces it.
372
+ */
373
+ backoffMs?: number;
374
+ }
375
+ export {};
376
+ //# sourceMappingURL=notifications.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/types/notifications.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=notifications.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/types/notifications.ts"],"names":[],"mappings":""}
@@ -0,0 +1,30 @@
1
+ export interface RotateHandleResult {
2
+ handle: string;
3
+ [key: string]: unknown;
4
+ }
5
+ export type PingPolicy = 'open' | 'members' | 'closed' | (string & {});
6
+ export type ActivityBucket = 'active_now' | 'today' | 'this_week' | 'quiet' | (string & {});
7
+ export interface DirectoryEntry {
8
+ handle: string;
9
+ display_name: string;
10
+ tagline: string;
11
+ tags: string[];
12
+ icon: string | null;
13
+ color: string | null;
14
+ ping_policy: PingPolicy;
15
+ is_featured: boolean;
16
+ operated_by: string | null;
17
+ last_active: ActivityBucket;
18
+ }
19
+ export interface DirectoryProfile extends DirectoryEntry {
20
+ description: string | null;
21
+ listed_at: string | null;
22
+ card_url: string | null;
23
+ }
24
+ export interface DirectoryListInput {
25
+ search?: string;
26
+ tag?: string;
27
+ per_page?: number;
28
+ page?: number;
29
+ }
30
+ //# sourceMappingURL=profile.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/types/profile.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AACvE,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE5F,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
@@ -0,0 +1,3 @@
1
+ // --- profile --------------------------------------------------------------
2
+ export {};
3
+ //# sourceMappingURL=profile.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/types/profile.ts"],"names":[],"mappings":"AAAA,6EAA6E"}
@@ -0,0 +1,210 @@
1
+ import type { JsonObject } from './common.js';
2
+ /**
3
+ * The authenticated human who answered a Question or handoff (never
4
+ * caller-supplied).
5
+ *
6
+ * Every field is redacted to `null` together when the caller is not entitled to
7
+ * see who answered, which is why `id` is nullable even on a decided question.
8
+ * The server sends all five fields from both `QuestionPresenter::responder` and
9
+ * the handoff presenter; the type previously declared only `id` and
10
+ * `display_name`, and being a closed object type that made the avatar fields
11
+ * unreachable without a cast.
12
+ */
13
+ export interface QuestionResponder {
14
+ id: string | null;
15
+ display_name: string | null;
16
+ profile_image_url: string | null;
17
+ emoji: string | null;
18
+ color: string | null;
19
+ }
20
+ /** The lifecycle states of a Question. Terminal states are immutable. */
21
+ export type QuestionState = 'pending' | 'answered' | 'expired' | 'cancelled';
22
+ /** Who may answer: `direct` (one named person) or `room` (any eligible member). */
23
+ export type ResponderScope = 'direct' | 'room';
24
+ /**
25
+ * How a room Question resolves: `first` (the default — the first valid answer
26
+ * wins) or `all` (a poll — everyone asked votes once; it closes when they all
27
+ * have, or at its deadline).
28
+ */
29
+ export type QuestionResolutionPolicy = 'first' | 'all';
30
+ /** One option offered on a Question. A bare string is shorthand for `{ value, label: value }`. */
31
+ export interface QuestionOptionInput {
32
+ /** Stable machine token returned as the answer (1–40 chars, unique per question). */
33
+ value: string;
34
+ /** Human text on the button (defaults to `value`; 1–40 chars). */
35
+ label?: string;
36
+ /** Presentation hint: `primary` = brand-strike affirmative, `danger` = cancel. */
37
+ style?: 'primary' | 'danger' | 'default';
38
+ /** Legacy boolean form of `style: 'primary'`. */
39
+ primary?: boolean;
40
+ /** Legacy boolean form of `style: 'danger'`. */
41
+ destructive?: boolean;
42
+ }
43
+ export type QuestionOptionSpec = string | QuestionOptionInput;
44
+ /** Invite a short typed answer, on its own (text-only) or alongside options. */
45
+ export interface QuestionTextInput {
46
+ placeholder?: string;
47
+ /** 1–60 (default 60). A value outside that range is refused with a 422. */
48
+ max_length?: number;
49
+ }
50
+ export interface QuestionInput {
51
+ /** The question the human reads (required, ≤ 500 chars). */
52
+ prompt: string;
53
+ /** Optional secondary line, e.g. a build number (≤ 40 chars). */
54
+ context?: string;
55
+ /** 2–4 options. Omit for the binary Approve/Deny default (the lock-screen fast path). */
56
+ options?: QuestionOptionSpec[];
57
+ /** Offer a typed answer instead of / alongside options. */
58
+ text_input?: QuestionTextInput;
59
+ /** `direct` (defaults to your bound user) or `room` (any eligible member). Default `direct`. */
60
+ responder_scope?: ResponderScope;
61
+ /**
62
+ * `first` (default) or `all` to poll the room: every member except your bound
63
+ * human gets one final vote. A poll implies `room` scope when
64
+ * `responder_scope` is omitted, and cannot be combined with
65
+ * `responder_scope: 'direct'`, `target_user_id`, or `text_input`. If your
66
+ * bound human is the room's only member the server falls back to a `direct`
67
+ * `first` Question — check `resolution_policy` on the returned Question.
68
+ */
69
+ resolution_policy?: QuestionResolutionPolicy;
70
+ /** For `direct` scope: a specific room member (UUID). Defaults to the bound user. */
71
+ target_user_id?: string;
72
+ /** Seconds until expiry. Omit for the server default (1h); clamped to 30–86400. A poll with at least one vote closes `answered` at this deadline. */
73
+ ttl?: number;
74
+ data?: JsonObject;
75
+ correlation_id?: string;
76
+ reply_to?: string;
77
+ /** Ordered ids from `attachments.upload()` (max 4). Same single-use rules as PingInput. */
78
+ attachment_ids?: string[];
79
+ /**
80
+ * Sent as the `Idempotency-Key` header (1–255 printable ASCII characters,
81
+ * spaces allowed). Reuse this key when retrying the same question creation.
82
+ */
83
+ idempotencyKey?: string;
84
+ }
85
+ /** A resolved option on the Question wire shape. */
86
+ export interface QuestionOption {
87
+ value: string;
88
+ label: string;
89
+ primary?: boolean;
90
+ destructive?: boolean;
91
+ [key: string]: unknown;
92
+ }
93
+ /**
94
+ * The resolution, present once `state === 'answered'` — except on a tied poll,
95
+ * which is `answered` with a null `answer` (read `results` instead).
96
+ */
97
+ export interface QuestionAnswer {
98
+ /** The chosen option's `value` (a poll's leading option), or null for a text-only answer. */
99
+ value: string | null;
100
+ /** The chosen option's `label`. */
101
+ label: string | null;
102
+ /** The typed answer, when the question invited one. Always null on a poll. */
103
+ text: string | null;
104
+ /**
105
+ * The authenticated human who answered (never caller-supplied). Present once
106
+ * the question is decided — but every field is redacted to `null` when the
107
+ * caller is not entitled to see who answered, so `id` is nullable even here.
108
+ * Null on a poll: the room chose the answer, and the voters are in
109
+ * `results.responses`. Matches `HandoffAnswer.responder`.
110
+ */
111
+ responder: QuestionResponder | null;
112
+ answered_at: string | null;
113
+ }
114
+ /** One option's tally in a poll's {@link QuestionPollResults}. */
115
+ export interface QuestionPollOptionResult {
116
+ value: string;
117
+ label: string;
118
+ /** Votes cast for this option (0 when nobody chose it). */
119
+ count: number;
120
+ }
121
+ /** One cast vote in a poll's {@link QuestionPollResults.responses}. */
122
+ export interface QuestionPollResponse {
123
+ value: string;
124
+ label: string;
125
+ /** Who voted. Every field is `null` when the caller may not see who answered. */
126
+ responder: QuestionResponder;
127
+ answered_at: string | null;
128
+ }
129
+ /** The reading person's own seat in a poll. */
130
+ export interface QuestionPollViewer {
131
+ /** Whether the poll asked this person. */
132
+ asked: boolean;
133
+ /** The value they voted, or null until they vote. */
134
+ response: string | null;
135
+ }
136
+ /**
137
+ * A poll's tally (`resolution_policy: 'all'`). Present on every read of a poll
138
+ * — including while it is still `pending` — and `null` on a `first` Question.
139
+ */
140
+ export interface QuestionPollResults {
141
+ /** People the poll asked, fixed when it was created. */
142
+ audience_count: number;
143
+ /** Votes cast so far (exact). */
144
+ response_count: number;
145
+ /** Every option, in display order, with its count. */
146
+ options: QuestionPollOptionResult[];
147
+ /** Up to the 100 most recent votes, oldest first. */
148
+ responses: QuestionPollResponse[];
149
+ /** Only on a signed-in person's own surfaces; always `null` on agent reads and webhook events. */
150
+ viewer: QuestionPollViewer | null;
151
+ }
152
+ /** The public Question wire shape — identical across ask / get / wait / list. */
153
+ export interface Question {
154
+ id: string;
155
+ /** Canonical delivery notification when supplied by the server. */
156
+ notification_id?: string | null;
157
+ kind: 'question';
158
+ prompt: string;
159
+ context: string | null;
160
+ options: QuestionOption[];
161
+ text_input: {
162
+ placeholder: string | null;
163
+ max_length: number;
164
+ } | null;
165
+ responder_scope: ResponderScope;
166
+ target_user_id: string | null;
167
+ /** `first` or `all` (a poll). Open-ended so a future policy does not break callers. */
168
+ resolution_policy: QuestionResolutionPolicy | (string & {});
169
+ state: QuestionState;
170
+ /** Null until answered, and on a tied poll even once `answered`. */
171
+ answer: QuestionAnswer | null;
172
+ /** A poll's tally; `null` on a `first` Question (absent on servers before Question Protocol 1.3). */
173
+ results?: QuestionPollResults | null;
174
+ expires_at: string | null;
175
+ resolved_at: string | null;
176
+ correlation_id: string | null;
177
+ reply_to: string | null;
178
+ data: JsonObject | null;
179
+ created_at: string | null;
180
+ room?: {
181
+ code: string;
182
+ name: string;
183
+ icon: string | null;
184
+ color: string | null;
185
+ };
186
+ room_code?: string;
187
+ asker?: {
188
+ /**
189
+ * `'user'` for a human-asked Question (composer "Add Options"), `'agent'`
190
+ * when an agent asked it. Both reach an agent's listen/list feed, so this
191
+ * cannot be narrowed to `'agent'`.
192
+ */
193
+ type: 'agent' | 'user';
194
+ id: string | null;
195
+ handle: string | null;
196
+ display_name: string | null;
197
+ avatar_url: string | null;
198
+ };
199
+ [key: string]: unknown;
200
+ }
201
+ export interface WaitQuestionInput {
202
+ /** Seconds the server holds the connection (0–30, default 20). */
203
+ timeout?: number;
204
+ signal?: AbortSignal;
205
+ }
206
+ export interface ListQuestionsInput {
207
+ /** Filter by state; `all` returns every state. Omit for the recent window across states. */
208
+ state?: QuestionState | 'all';
209
+ }
210
+ //# sourceMappingURL=questions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../../src/types/questions.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=questions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"questions.js","sourceRoot":"","sources":["../../src/types/questions.ts"],"names":[],"mappings":""}