@lemoncloud/chatic-apps-sdk 0.1.0 → 0.3.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.
package/README.md CHANGED
@@ -1,14 +1,18 @@
1
+ > Korean: [README.ko.md](./README.ko.md). This English version is the canonical one.
2
+
1
3
  # chatic-apps-sdk
2
4
 
3
5
  Build pages that run inside the DoU app. A page on `https://<name>.apps.chatic.io` opens in the app
4
6
  over everything else, and talks to the app through this library: close itself and hand back a result,
5
- title the app's bar, play a haptic, share, copy, open a link outside, keep its own data on the device,
7
+ title the app's bar (when the page asks for one), play a haptic, share, copy, open a link outside, keep its own data on the device,
6
8
  get a key to keep the user's data under on a server, take Android's back button, and ask before the
7
9
  user closes it. Users reach it in the app only — a link to it never opens it in a browser — but the
8
10
  same page runs in a plain browser tab too while you build it, where the library falls back to what the
9
11
  browser can do.
10
12
 
11
- Published as `@lemoncloud/chatic-apps-sdk`. No runtime dependencies.
13
+ Published as `@lemoncloud/chatic-apps-sdk`. No runtime dependencies. `GUIDE.md` in the package says how
14
+ to set up a project and what the bundle looks like; `AGENTS.md` holds the rules for an AI assistant
15
+ writing a page.
12
16
 
13
17
  ## Install
14
18
 
@@ -20,7 +24,7 @@ Or, with no bundler, one script that defines `window.ChaticAppsSDK` (pin the ver
20
24
  is not in this file):
21
25
 
22
26
  ```html
23
- <script src="https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.1.0/chatic-apps-sdk.global.js"></script>
27
+ <script src="https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.3.0/chatic-apps-sdk.global.js"></script>
24
28
  ```
25
29
 
26
30
  ## Start
@@ -30,7 +34,6 @@ import { connect, ChaticAppsError } from '@lemoncloud/chatic-apps-sdk';
30
34
 
31
35
  try {
32
36
  const apps = await connect();
33
- if (apps.inApp) await apps.setTitle('Quiz');
34
37
  document.documentElement.dataset.theme = apps.context?.theme ?? 'light';
35
38
  } catch (error) {
36
39
  // `UNSUPPORTED_PROTOCOL`: the app is newer than this library — update the library, and tell the
@@ -54,7 +57,7 @@ stand-ins; deployed to your `apps.chatic.io` address, it runs in the app.
54
57
  <meta charset="utf-8" />
55
58
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
56
59
  <title>Quiz</title>
57
- <script src="https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.1.0/chatic-apps-sdk.global.js"></script>
60
+ <script src="https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.3.0/chatic-apps-sdk.global.js"></script>
58
61
  </head>
59
62
  <body>
60
63
  <h1 id="score">0</h1>
@@ -90,22 +93,25 @@ stand-ins; deployed to your `apps.chatic.io` address, it runs in the app.
90
93
 
91
94
  ## What a page can do
92
95
 
93
- | Call | In the app | In a browser | Needs permission |
94
- | ----------------------------------------- | ------------------------------------------------------------------ | ----------------------------------- | ---------------- |
95
- | `finish(result?)` | Closes the view; `result` (JSON, ≤ 16 KiB) goes back to the opener | `NOT_IN_APP` | — |
96
- | `setTitle(title)` | The app's bar shows it (1–100 characters) | `document.title` | — |
97
- | `haptic(kind)` | `selection`, `impact`, `success`, `warning`, `error` | a short vibration, if any | — |
98
- | `onBack(handler \| null)` | Android back calls `handler` and does nothing else | never called | — |
99
- | `onCloseRequest(handler \| null)` | Asks before the user closes; return `true` to close | never called | — |
100
- | `reportError(error)` | Into DoU's log, under your origin (20 per page load) | `console.error` | — |
101
- | `copy(text)` | The clipboard | the browser's clipboard | `clipboard` |
102
- | `share({ title, message, url })` | The share sheet; waits for the user (see below) | Web Share, else copies (`'copied'`) | `share` |
103
- | `openUrl(url)` | The browser, mail, phone, SMS or a store | a new tab | `openUrl` |
104
- | `getUserKey()` | 64 hex characters, the same for this device and site | `NOT_IN_APP` | `userKey` |
105
- | `link(params?)` | A link that opens this page in the app (see below) | the page's own root | — |
106
- | `storage.get(key)`, `.set(key, value)`, … | Your page's own storage on the device (see below) | `localStorage`, same limits | — |
107
-
108
- Plus `apps.context` (the app's language, theme, platform and the `params` you were opened with),
96
+ | Call | In the app | In a browser | Needs permission |
97
+ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
98
+ | `finish(result?)` | Closes the view; `result` (JSON, ≤ 16 KiB) goes back to the opener | `NOT_IN_APP` | — |
99
+ | `setTitle(title)` | The app's bar shows it, if the page asked for the bar (1–100 characters) | `document.title` | — |
100
+ | `haptic(kind)` | `selection`, `impact`, `success`, `warning`, `error` | a short vibration, if any | — |
101
+ | `onBack(handler \| null)` | Android back calls `handler` and does nothing else | never called | — |
102
+ | `onCloseRequest(handler \| null)` | Asks before the user closes; return `true` to close | never called | — |
103
+ | `reportError(error)` | Into DoU's log, under your origin (20 per page load) | `console.error` | — |
104
+ | `copy(text)` | The clipboard | the browser's clipboard | `clipboard` |
105
+ | `share({ title, message, url })` | The share sheet; waits for the user (see below) | Web Share, else copies (`'copied'`) | `share` |
106
+ | `openUrl(url)` | The browser, mail, phone, SMS or a store | a new tab | `openUrl` |
107
+ | `getUserKey()` | 64 hex characters, the same for this device and site | `NOT_IN_APP` | `userKey` |
108
+ | `link(params?)` | A link that opens this page in the app (see below) | the page's own root | — |
109
+ | `storage.get(key)`, `.set(key, value)`, … | Your page's own storage on the device (see below) | `localStorage`, same limits | — |
110
+ | `permissions.query(kind)`, `.request(kind)`, `openSettings()` | Where the app stands with the OS for `'camera'` or `'microphone'`, and asking it (see below) | the browser's own permission | — |
111
+ | `data.connect()`, `.call(…)`, `.subscribe(…)`, `.sendMessage(…)`, `.react(…)` | Reads the app's own data — the current cloud — as DoU's screens do; posts text with `chatSend`, reacts with `chatReact` | `NOT_IN_APP` | `session`, `cloud`, `place`, `channel`, `chat`, `user`; `chatSend` to send, `chatReact` to react |
112
+
113
+ Plus `apps.context` (the app's language, theme, platform — `ios`, `android` or `desktop` — and the
114
+ `params` you were opened with; DoU's own web opens a mini app with `MiniAppLaunchParams`, see below),
109
115
  `apps.onContextChange(listener)` for a theme or language change, `apps.supports(capability)`,
110
116
  `apps.inApp`, and `apps.disconnect()`.
111
117
 
@@ -126,13 +132,232 @@ Plus `apps.context` (the app's language, theme, platform and the `params` you we
126
132
  write fails with `QUOTA_EXCEEDED` and changes nothing — keys of 1–200 characters (not `__proto__`),
127
133
  and at most 64 KiB in one call (`TOO_LARGE`). A value is written in one call, so one value stays
128
134
  under 64 KiB; split anything bigger across keys.
135
+ - **`permissions`** is for the camera and the microphone, which a page uses with the browser's own
136
+ `getUserMedia` — the OS asks the user the first time, under DoU's name, so the user's answer is for
137
+ every page, not yours alone. `query(kind)` reports `'granted'`, `'prompt'` (not asked, or refused and
138
+ may be asked again) or `'blocked'` (the OS will not ask again) without showing anything — on Android
139
+ it can read `'prompt'` for one the OS will no longer ask for, so trust what `request` answers;
140
+ `request(kind)` shows the prompt and resolves with the answer; `openSettings()` opens DoU's page in
141
+ the OS settings, the way back for `'blocked'`. Ask when the user reaches for the feature, not at
142
+ start, and do not time `request` out: it waits for the user. A page can skip all this and call
143
+ `getUserMedia`; it then meets the prompt in the middle of the capture. In a browser the same calls
144
+ read and ask the browser's own permission, and `openSettings()` is `NOT_IN_APP`.
129
145
  - **Uncaught errors are reported for you.** `connect()` listens for `error` and `unhandledrejection` and
130
146
  sends them to DoU's log. An `Error` sends its message and stack, a string itself, anything else only
131
147
  its type. Pass `connect({ reportErrors: false })` to turn it off.
132
148
 
149
+ ## Reading the app's data: `apps.data`
150
+
151
+ A page can read the cloud it was opened in — its places, rooms, messages, members — with the same
152
+ reads DoU's own screens make, hear them change, and send a text message:
153
+
154
+ ```ts
155
+ const apps = await connect();
156
+ const placeId = (apps.context?.params as Partial<MiniAppLaunchParams> | undefined)?.place?.id;
157
+ if (apps.supports('data') && placeId) {
158
+ const { allowed } = await apps.data.connect(); // the app asks the user once, here
159
+ const rooms = await apps.data.call('channel.cacheReadList', { sid: placeId });
160
+ // rooms: CloudList<CloudChannel> | null
161
+ const stream = await apps.data.subscribe('channel.observeList', [{ sid: placeId }], result => {
162
+ render(result?.list ?? []);
163
+ });
164
+ apps.data.onCloudChanged(() => apps.finish());
165
+ }
166
+ ```
167
+
168
+ - **Typed by the app's own names.** Every method the app opens to a page is in `DataCalls` or
169
+ `DataStreams`, under the app's `<repository>.<method>` name, with its arguments and its answer:
170
+ a wrong argument or a misused answer fails the type check. A name the library does not know still
171
+ goes through and answers `unknown` — an app newer than this library may open more. `call<T>(name)`
172
+ with an explicit type still reaches any method untyped, as it did before the types.
173
+ - **What comes back is the app's own data**, as the app holds it — the rows below, field for field,
174
+ not reshaped or filtered for pages. `SDK_DATA_CONTRACTS` lists the cloud data contract versions this
175
+ library speaks.
176
+ - **Reads, and two writes, only as your manifest asks.** Each cloud data permission opens a fixed set of
177
+ methods (the table below); `connect()` answers the names this page may use (`allowed.calls`,
178
+ `allowed.streams`), and `can(name)` checks one — the types say what a method would be, `can` says
179
+ whether it is open now. Anything else is refused with `RUNTIME_NOT_ALLOWED`. Apart from the message
180
+ `chatSend` opens and the reaction `chatReact` opens, nothing a page can call changes anything, switches the cloud or the place,
181
+ or reads another cloud.
182
+ - **The user is asked once** whether your page may read this cloud. `connect()` waits for the answer
183
+ however long the user takes, with no timeout. A refusal is `CONSENT_REFUSED`; `connect()` asks again
184
+ the next time the page is opened.
185
+ - **Streams**: `subscribe(name, args, listener, onEnd)` hands `listener` each event. For a typed stream
186
+ pass only the arguments in the table: the library puts the listener right after them, where the
187
+ app's method takes its callback. For a name the library does not know, put `LISTENER` where that
188
+ method takes its callback (left out, it goes last). Pass nothing after the listener. `onEnd` hears a
189
+ stream the app ended: `CLOUD_CHANGED`, a too-large event, or `DISCONNECTED` after the page came back
190
+ from the back-forward cache (subscribe again). At most 16 per page load — the next `subscribe` fails
191
+ `INVALID` — so `stop()` each one you no longer need.
192
+ - **The cloud is fixed.** If the user's cloud changes under the view, every stream ends with
193
+ `CLOUD_CHANGED`, `onCloudChanged` fires once, and nothing answers after.
194
+ - **So is the place.** What belongs to a place — its rooms, their members and messages, its
195
+ profiles — is read only in the place your page was opened in, while the user is still there: a list
196
+ names that place (`sid`) or one of its rooms, and a room or a message is checked against it. Anything
197
+ else is `RUNTIME_NOT_ALLOWED`, and so is every read of a place once the user moved to another; open
198
+ a new view there. The places themselves and the cloud's own row are not a place's and stay open.
199
+ Read the place's id from `session().committedSiteId` or the launch parameters (`place.id`).
200
+ - **Server reads are budgeted**: one per 250 ms and 60 a minute per view, `RATE_LIMITED` past it, with
201
+ `error.details.retryAfterMs`. So are cache reads, apart: 600 a minute per view, each room the app
202
+ checks for a read or a message counting as one.
203
+ - **Only some launches answer it**: the app has to hold the session itself, the page has to be a
204
+ reviewed one on the phone, a cloud — Home included — has to be selected when it opens, and on
205
+ Android the WebView has to tell the page's own messages from a frame's inside it (an old Android
206
+ System WebView cannot, and the app then answers none of `apps.data` there).
207
+ `supports('data')` is `false` everywhere else, and every call is `NOT_IN_APP` in a browser.
208
+ - **The types cannot hold every argument the app checks.** An object passed from a variable may carry
209
+ fields its type does not list, and `call<T>` skips the argument types altogether; the app still
210
+ refuses what its checks refuse (an extra field on a send, `pageSize` on `user.listPlaceMembers`), with
211
+ `RUNTIME_NOT_ALLOWED`.
212
+ - **It reads what the app holds.** Nothing a page calls fetches into the app's cache, so it sees what
213
+ DoU has already synced, plus the methods marked "server" below.
214
+
215
+ ### Methods, by permission
216
+
217
+ | Permission | Method | Arguments | Answer |
218
+ | ----------- | ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------- |
219
+ | `session` | — (the hello's answer: `session()`, `onSessionChange`) | — | `CloudSession` |
220
+ | `cloud` | `cloud.cacheRead` | `id` — the current cloud's | `CloudInfo \| null` |
221
+ | `cloud` | `cloud.getCloud` (server) | `{ id }` — the current cloud's, `{ cache: false }` | `CloudInfo` |
222
+ | `cloud` | `cloud.observeItem` (stream) | `id` — the current cloud's | `CloudInfo \| null` |
223
+ | `place` | `place.cacheReadList` | `{}` (optional) | `CloudList<CloudPlace> \| null` |
224
+ | `place` | `place.observeList` (stream) | `{}` | `CloudList<CloudPlace> \| null` |
225
+ | `place` | `place.observeItem` (stream) | place `id` | `CloudPlace \| null` |
226
+ | `place` | `place.isPlaceDeleted` (server) | place `id` | `boolean` |
227
+ | `channel` | `channel.cacheRead` | room `id` — a room of the place | `CloudChannel \| null` |
228
+ | `channel` | `channel.cacheReadList` | `CloudChannelListQuery` — `sid` the place's, required | `CloudList<CloudChannel> \| null` |
229
+ | `channel` | `channel.fetchList` (server) | `CloudChannelListQuery` — `sid` the place's, required | `CloudList<CloudChannel>` |
230
+ | `channel` | `channel.observeList` (stream) | `CloudChannelListQuery` — `sid` the place's, required | `CloudList<CloudChannel> \| null` |
231
+ | `channel` | `channel.observeItem` (stream) | room `id` — a room of the place | `CloudChannel \| null` |
232
+ | `channel` | `join.cacheReadList` | `{ channelId, activeOnly? }` — a room of the place | `CloudList<CloudJoin> \| null` |
233
+ | `channel` | `join.observeList` (stream) | `{ channelId, activeOnly? }` — a room of the place | `CloudList<CloudJoin> \| null` |
234
+ | `chat` | `chat.cacheRead` | message `id` — answered if its room is the place's | `CloudChat \| null` |
235
+ | `chat` | `chat.cacheReadList` | `{ channelId, cursorNo?, limit? }` | `CloudList<CloudChat> \| null` |
236
+ | `chat` | `chat.listPendingImageChats` | room `id` | `CloudChat[]` |
237
+ | `chat` | `chat.observeList` (stream) | `{ channelId, cursorNo?, limit?, includeUnsent? }` | `CloudList<CloudChat> \| null` |
238
+ | `chat` | `chat.observeLastList` (stream) | room ids | `CloudLastChat[]` |
239
+ | `chat` | `chat.observeFeedCoverage` (stream) | room `id` | `[low, high][]` message-number ranges |
240
+ | `user` | `user.cacheReadList` | `{ channelId, limit?, page?, detail? }` | `CloudList<CloudUser> \| null` |
241
+ | `user` | `user.listPlaceMembers` (server) | `{ placeId, sessionPlaceId }` — both the current place's | `CloudPlaceMembers` |
242
+ | `user` | `user.observeList` (stream) | `{ channelId, limit?, page?, detail? }` | `CloudList<CloudUser> \| null` |
243
+ | `user` | `profile.cacheRead` | `<place id>@<user id>` — the place's | `CloudProfile \| null` |
244
+ | `user` | `profile.cacheReadList` | `{ sid, uid? }` — `sid` the place's, required | `CloudList<CloudProfile> \| null` |
245
+ | `user` | `profile.observeList` (stream) | `{ sid, uid? }` — `sid` the place's, required | `CloudList<CloudProfile> \| null` |
246
+ | `user` | `profile.observeItem` (stream) | `<place id>@<user id>` — the place's | `CloudProfile \| null` |
247
+ | `chatSend` | `chat.sendChat` — call it as `sendMessage` | `{ channelId, content }` | `CloudChat` |
248
+ | `chatReact` | `chat.setReaction` — call it as `react` | `{ chatId, emoji, action: 'on' \| 'off' }` | `CloudChat` |
249
+
250
+ ### The rows
251
+
252
+ All exported as types. Most fields are optional because the same row is filled from different answers
253
+ over time: a field is there only when the server or the app filled it, so read each with a fallback.
254
+
255
+ | Type | What it is | Fields worth knowing |
256
+ | -------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
257
+ | `CloudChannel` | A room | `id`, `sid` (its place), `name`, `stereo` (`dm`, `self`, …), `memberIds`, `chatNo`, `unreadCount`, `lastChat$` |
258
+ | `CloudJoin` | A member's place in a room | `channelId`, `userId`, `stereo` (`owner`, `member`), `readNo`, `nick`, `notify` |
259
+ | `CloudChat` | A message | `id`, `channelId`, `chatNo` (`0` while sending), `content`, `ownerId`, `createdAtMs` (always set), `upload$$`, `isPending`, `isFailed` |
260
+ | `CloudPlace` | A place of the cloud | `id`, `name`, `order`, `isOwner`, `owner$` |
261
+ | `CloudUser` | A user of the cloud | `id`, `name`, `nick`, `thumbnail` |
262
+ | `CloudProfile` | A user's name and picture in one place | `id` (`<place>@<user>`), `sid`, `userId`, `nick`, `thumbnail` |
263
+ | `CloudInfo` | The current cloud | `id`, `name`, `status`, `ownerId`, `cloudType` |
264
+ | `CloudSession` | The current cloud's part of the session | `context.cloud.cloudId`, `context.identity.userId`, `committedSiteId` |
265
+
266
+ `CloudList<Row>` is `{ list, meta: { total, limit?, page?, cursorNo?, readNo?, source? } }`.
267
+
268
+ ### What each permission hands over
269
+
270
+ The app does not filter a row for pages: what DoU's screens read, your page reads. That includes
271
+ contact and account details, marked in the types as such. Ask only for the permissions the page needs —
272
+ what it does with what it read is its author's responsibility — keep such details on the device, and
273
+ never send them to a third party without telling the user.
274
+
275
+ | Permission | Hands over |
276
+ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
277
+ | `session` | Which cloud and place the user is on, the user's id in this cloud, whether signed in. Nothing of the user's other clouds, no server address, no token |
278
+ | `cloud` | The current cloud's row; from the device cache, also its server addresses (`backend`, `wss`) and the device user ids that accepted an invite (`acceptedBy`). Through `cloud.getCloud`, for a cloud the user owns: its owner, the verified **email**, the linked **account** (`accountId`, `account$`), the subscription id, the cloud server's **account number** (`accountNo`) and service endpoints (`$envs`); for any other cloud, the relay's minimal `{ id, name, status }` |
279
+ | `place` | The cloud's places, with their server endpoints (`$envs`). A place's `owner$` is the account server's view of its owner, whose type includes **phone, email, address, birth date**, sign-in details and fields named after secrets (`loginPw`, `$account.otp$`, `$account.key$`) — filled as the server chooses. Never read, keep or send the secret-named ones |
280
+ | `channel` | Rooms of the place, their member ids, each member's join (role, nickname, read position), and the embedded owners (`owner$`, with **sign-in ids**) |
281
+ | `chat` | Messages in the place's rooms, with their files' addresses, any webhook cards, and the embedded senders (`owner$`, with **sign-in ids**) |
282
+ | `user` | Users of the place's rooms (names, nicknames, pictures, **sign-in ids**), the place's profiles, and its member list |
283
+ | `chatSend` | Nothing: it lets the page send |
284
+ | `chatReact` | Nothing: it lets the page add and remove the user's reactions; the reply is the message's row, which `chat` reads anyway |
285
+
286
+ ### Sending a message: `sendMessage`
287
+
288
+ ```ts
289
+ const sent = await apps.data.sendMessage(roomId, 'Round 3: 120 points'); // CloudChat
290
+ ```
291
+
292
+ With `chatSend`, `sendMessage(channelId, text)` posts `text` as plain text, in the user's name and
293
+ unmarked, to a room of the place the user was in when your page opened, and resolves with the sent
294
+ message. It is `call('chat.sendChat', { channelId, content: text })`, which still works. Text only — no
295
+ attachment, mention or reply — at most 1,000 characters with something besides white space in it; a
296
+ room in another place, one the user is not in, or any room once the user moved to another place, is
297
+ refused with `RUNTIME_NOT_ALLOWED`. The user is told, when asked, that the page sends messages, and is
298
+ asked per place. A send that fails leaves a failed message in the room on the user's device, as a
299
+ failed send from DoU's own composer does. Messages have their own budget, one per 500 ms and 30 a
300
+ minute, `RATE_LIMITED` past it. Get the room's id from a read (`channel`) or the launch parameters. In
301
+ a browser it is `NOT_IN_APP`.
302
+
303
+ ### Reacting to a message: `react`
304
+
305
+ ```ts
306
+ await apps.data.react(messageId, '👍', true); // CloudChat, the reaction on
307
+ await apps.data.react(messageId, '👍', false); // and off again
308
+ ```
309
+
310
+ With `chatReact`, `react(messageId, emoji, on)` adds (`true`) or removes (`false`) one emoji on a
311
+ message, in the user's name and unmarked, exactly as the user's own tap does, and resolves with the
312
+ message's row, the reaction applied. It is `call('chat.setReaction', { chatId, emoji, action })`, with
313
+ `action` `'on'` or `'off'`. `emoji` is one character as a person sees it — one emoji however many code
314
+ points build it, a skin tone or a flag included — and any emoji, not only DoU's picker's. **Removing
315
+ takes off the user's reaction with that emoji whoever set it**, one the user added by hand included:
316
+ nothing tells the two apart, and the user is told so when asked. The message must be one the device
317
+ holds, in a room of the place the user was in when your page opened, and one DoU's own screen offers a
318
+ reaction on — not deleted, sending or failed, nor a row that records an edit or a reaction; anything else, or any message once the user moved, is
319
+ `RUNTIME_NOT_ALLOWED`. Reactions have a budget of their own, one per 250 ms and 60 a minute, spent
320
+ before the message is read, so one refused for its message counts too (`RATE_LIMITED`). Read the message ids with `chat`. In a browser it is
321
+ `NOT_IN_APP`.
322
+
323
+ ### Place profiles: `placeProfile`, `placeProfiles`, `myProfile`
324
+
325
+ ```ts
326
+ const me = await apps.data.myProfile(); // CloudProfile | null
327
+ const sender = chat.ownerId ? await apps.data.placeProfile(chat.ownerId) : null; // a member of the place
328
+ const named = await apps.data.placeProfiles(); // CloudList<CloudProfile> | null: name the place's members
329
+ const stop = await apps.data.observePlaceProfile(userId, profile => renderName(profile?.nick));
330
+ ```
331
+
332
+ A place profile is what a member is called in one place of a cloud: the app keys it to the member's
333
+ id in that cloud, `<place id>@<user id>`, and it mostly holds the name shown there (`nick`) and a
334
+ picture — DoU names a member by it, and by the member's own name where there is none. As every read of
335
+ a place, it answers only for the place your page was opened in.
336
+
337
+ - `placeProfile(userId)` reads one member's profile as the device holds it, and
338
+ `observePlaceProfile(userId, listener, { onEnd? })` hears it and each change.
339
+ - `placeProfiles()` lists the place's profiles the device holds.
340
+ - `myProfile()` and `observeMyProfile(listener, { onEnd? })` do the same with the user's own id.
341
+
342
+ They need `user`, which reads profiles, and `session`, which names the place and the user's id:
343
+ without `session`, or before the session is on a place, they are `NOT_SUPPORTED`; without `user`, or
344
+ once the user moved to another place, `RUNTIME_NOT_ALLOWED`. `null` means the device holds no profile
345
+ for that member there: fall back to the member's own name. They are
346
+ `call('profile.cacheRead', '<place id>@<user id>')`, `call('profile.cacheReadList', { sid })` and
347
+ `subscribe('profile.observeItem', [id], …)`, which still work.
348
+
349
+ ### In the mock
350
+
351
+ The mock answers from `data: { calls, streams, session, consent }`, typed with the same map — an
352
+ answer of the wrong shape fails the type check — and plays the cloud change with `changeCloud()`. It
353
+ does not know the app's whitelist: it answers what you give it. With `chatSend` it opens
354
+ `chat.sendChat` itself, checks a send's shape as the app does (not the room's place, nor the send
355
+ budget), and records each send that went through in `sentMessages`. With `chatReact` it does the same
356
+ for `chat.setReaction`, recording each reaction in `reactions` (`{ messageId, emoji, on }`).
357
+
133
358
  ## Permissions
134
359
 
135
- The four calls marked above need a permission your page asks for in a file on its own site,
360
+ The calls marked above need a permission your page asks for in a file on its own site,
136
361
  `/.well-known/chatic-app.json`:
137
362
 
138
363
  ```json
@@ -140,15 +365,25 @@ The four calls marked above need a permission your page asks for in a file on it
140
365
  "manifestVersion": 1,
141
366
  "name": "Quiz",
142
367
  "permissions": ["share", "userKey"],
143
- "display": "standard",
368
+ "display": "titled",
144
369
  "orientation": "portrait"
145
370
  }
146
371
  ```
147
372
 
148
373
  You ask; an administrator grants them when your page is reviewed, and only what was granted is
149
- deployed. Without the file your page gets everything else but not these four, which then fail with
150
- `NOT_SUPPORTED`. `display: "fullscreen"` hides the app's bar (a small close button stays in the
151
- top-right corner — keep it clear); `orientation` is `any`, `portrait` or `landscape`. The app reads
374
+ deployed. Without the file your page gets everything else but not what these permissions unlock: a call
375
+ that needs one fails with `NOT_SUPPORTED`, and without a cloud data permission `supports('data')` is
376
+ `false`. `display` says how the page is shown:
377
+
378
+ | `display` | What the user sees |
379
+ | ----------------- | ------------------------------------------------------------------------------------------------------ |
380
+ | `clean` (default) | The page alone, with a small close button floating in the top-right corner (keep it clear) |
381
+ | `titled` | The app's bar above the page, with its title and a close button |
382
+ | `immersive` | `clean`, but the page fills the whole screen, under the status bar and the home indicator (see Layout) |
383
+
384
+ Apps from before bridge 2.29.0 called `titled` `standard` and `clean` `fullscreen`, and know only
385
+ those names: they show a new name as `clean`. Current apps read both. `orientation` is `any`,
386
+ `portrait` or `landscape`. The app reads
152
387
  the file before it shows your page, keeps it for the rest of its run, and fetches a fresh copy behind
153
388
  each later open: a change to the file takes effect one open later.
154
389
 
@@ -168,21 +403,27 @@ try {
168
403
  }
169
404
  ```
170
405
 
171
- | Code | Means |
172
- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
173
- | `NOT_SUPPORTED` | Not available: an older app, a permission the page does not hold, or no browser clipboard or storage |
174
- | `NOT_IN_APP` | The call needs the app, and the page is in a browser |
175
- | `TIMEOUT` | The app did not answer in 10 seconds (time in the background does not count) |
176
- | `INVALID` | A value is missing, of the wrong type, or too long |
177
- | `TOO_LARGE` | One call's data is over 65,536 characters |
178
- | `LINK_NOT_ALLOWED` | The link cannot be opened or shared from a page |
179
- | `NOT_OPEN` | `finish` after the view has already closed |
180
- | `UNAVAILABLE` | The device has no id to make a user key from, or the app could not open the page's storage |
181
- | `QUOTA_EXCEEDED` | A storage write would go past 1,048,576 characters; nothing was written |
182
- | `DISCONNECTED` | The call was waiting when `disconnect()` closed the connection |
183
- | `UNSUPPORTED_PROTOCOL` | `connect()` only: the app is newer than this library; update it |
184
-
185
- Treat a code not in this table as that call failing, and nothing more.
406
+ | Code | Means |
407
+ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
408
+ | `NOT_SUPPORTED` | Not available: an older app, a permission the page does not hold, or no browser clipboard or storage |
409
+ | `NOT_IN_APP` | The call needs the app, and the page is in a browser |
410
+ | `TIMEOUT` | The app did not answer in 10 seconds (time in the background does not count) |
411
+ | `INVALID` | A value is missing, of the wrong type, or too long |
412
+ | `TOO_LARGE` | One call's data is over 65,536 characters |
413
+ | `LINK_NOT_ALLOWED` | The link cannot be opened or shared from a page |
414
+ | `NOT_OPEN` | `finish` after the view has already closed |
415
+ | `UNAVAILABLE` | No device id to make a user key from, the page's storage could not be opened, or the device has no camera or microphone |
416
+ | `SETTINGS_ERROR` | `openSettings()`: the OS would not open the settings |
417
+ | `QUOTA_EXCEEDED` | A storage write would go past 1,048,576 characters; nothing was written |
418
+ | `DISCONNECTED` | The call was waiting when `disconnect()` closed the connection; or, for a cloud data stream, the page came back from the back-forward cache and the stream ended (subscribe again) |
419
+ | `RUNTIME_NOT_ALLOWED` | `data`: not a method this page may use, or an argument the app holds to the current cloud or place — for a message, its shape or its room |
420
+ | `CLOUD_CHANGED` | `data`: the user's cloud is no longer the one this view opened on; nothing answers after |
421
+ | `CONSENT_REFUSED` | `data.connect()`: the user did not allow this page to read this cloud |
422
+ | `RATE_LIMITED` | `data`: too many server reads, cache reads or messages sent; wait `error.details.retryAfterMs` |
423
+ | `UNSUPPORTED_PROTOCOL` | `connect()` only: the app is newer than this library; update it |
424
+
425
+ Treat a code not in this table as that call failing, and nothing more. The codes are the app's own,
426
+ so a few keep the app's older wording (`RUNTIME_NOT_ALLOWED` is about `apps.data`).
186
427
 
187
428
  ## Rules worth knowing
188
429
 
@@ -205,6 +446,22 @@ Treat a code not in this table as that call failing, and nothing more.
205
446
  - **You cannot see the error reports.** They go to DoU's log, read by the people who review pages.
206
447
  Send errors to your own server too if you want to see them.
207
448
 
449
+ ## Opened from DoU: `MiniAppLaunchParams`
450
+
451
+ When DoU itself opens your page — a cloud's owner registered it as the cloud's mini app — `params` has
452
+ this shape (exported as a type):
453
+
454
+ ```ts
455
+ import type { MiniAppLaunchParams } from '@lemoncloud/chatic-apps-sdk';
456
+
457
+ const params = apps.context?.params as Partial<MiniAppLaunchParams> | undefined;
458
+ // { cloud: { id, name }, place: { id, name } | null, user: { id, name } }
459
+ ```
460
+
461
+ `user.id` is the user's id in that cloud. These are names to show, not proof of who is looking: there
462
+ is no token, and your server must not treat them as a sign-in. `user.isOwner` and `miniApps` are sent
463
+ to DoU's own hub only; your page never receives them.
464
+
208
465
  ## What this WebView is like
209
466
 
210
467
  - **Use `apps.storage`, not the WebView's own**: `localStorage` and IndexedDB work, but go whenever the
@@ -212,13 +469,42 @@ Treat a code not in this table as that call failing, and nothing more.
212
469
  `getUserKey()`.
213
470
  - **No popups**: `window.open` and `target="_blank"` load in the same view, so a login that answers
214
471
  through `window.opener` does not work. Use a redirect login.
215
- - **Downloads**: a file download is not handled on iOS. Show the content instead.
472
+ - **Downloads**: a file download is not handled on iOS, nor on the desktop. Show the content instead.
473
+ - **On the desktop** (`platform: 'desktop'`) the page opens in a window over DoU with a bar: the
474
+ base requests only (`finish`, `setTitle`, error reports), no camera or microphone, and a site that is
475
+ not under `apps.chatic.io` always shows its own address in the bar.
216
476
  - **Camera and microphone** work through the browser APIs, under DoU's name: the OS asks the user
217
477
  "DoU would like to…". What your page uses is part of its review.
218
478
  - **Your own server**: calls to it are ordinary cross-origin requests from `https://<name>.apps.chatic.io`;
219
479
  allow that origin in its CORS settings.
220
- - **Layout**: the page sits inside the safe area on every edge; there are no insets to handle. Use the
480
+ - **Layout**: the page sits inside the safe area on every edge, unless its manifest sets `immersive`
481
+ (below); there are no insets to handle. Use the
221
482
  context's `theme`, not the OS's, for dark mode — the user can set DoU's theme apart from the phone's.
483
+ - **Immersive** (`display: "immersive"`, app bridge 2.29.0): the page fills the whole screen,
484
+ under the status bar, the home indicator and a landscape notch, and keeps its own controls clear of
485
+ them. The status bar stays visible. The app sets `--chatic-safe-area-inset-top`, `-right`, `-bottom` and `-left` on `<html>`; read
486
+ them first and fall back to `env()`, which not every Android WebView reports. The viewport meta must
487
+ say `viewport-fit=cover`: without it iOS keeps the page out of a landscape notch itself, and padding
488
+ by the properties as well pads that side twice:
489
+
490
+ ```css
491
+ .hud {
492
+ padding-top: var(--chatic-safe-area-inset-top, env(safe-area-inset-top, 0px));
493
+ }
494
+ .dock {
495
+ padding-bottom: var(--chatic-safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
496
+ }
497
+ ```
498
+
499
+ An older app shows the page padded, as `clean` (an older desktop app, with the bar), and the
500
+ insets read 0, so the same CSS is right on both.
501
+
502
+ A page that lays out in script — a canvas game — reads the same values from
503
+ `apps.context.safeArea` (`{ top, right, bottom, left }` in CSS px, 0 on every edge of a padded page)
504
+ and hears a rotation through `onContextChange`, once the insets have settled. `apps.context.display`
505
+ says which display the app actually used. Both are absent from apps before bridge 2.30.0 and from the
506
+ desktop: their absence is the signal to fall back to the CSS properties above. The close button still floats top-right, below the status bar. The status bar's icons follow
507
+ the app's theme.
222
508
 
223
509
  ## Try it without the app
224
510
 
@@ -236,44 +522,74 @@ const apps = await connect();
236
522
  app?.pressBack();
237
523
  app?.requestClose();
238
524
  app?.changeContext({ theme: 'dark' });
525
+ app?.rotate(); // an immersive page gets the other orientation's insets
239
526
  console.log(app?.closed); // { by: 'page', result } once the page finishes, { by: 'user' } on a close
240
527
  console.log(app?.storage); // what the page has stored
241
528
  ```
242
529
 
243
- Pass `storage: { … }` to start with data already stored; the mock keeps it in memory only.
530
+ Pass `storage: { … }` to start with data already stored; the mock keeps it in memory only. Pass
531
+ `context: { display: 'immersive' }` to try an immersive page: the mock sets a phone's insets in
532
+ `apps.context.safeArea` and the `--chatic-safe-area-inset-*` properties, and `rotate()` turns them.
533
+ `context: { display: undefined, safeArea: undefined }` stands in for an app before bridge 2.29.0, which
534
+ sends neither and shows the page padded.
244
535
 
245
536
  It answers as the app does — the base calls, plus the `permissions` you give it, and `NOT_SUPPORTED`
246
537
  for the rest — checks what the app checks, and logs every call. It is a stand-in: the share sheet is
247
538
  logged rather than shown, the user key is not the app's, and it proves nothing about a phone.
248
539
 
540
+ ## Versions
541
+
542
+ While the library is `0.x`, a release that adds anything — a call, a typed method, a field — raises the
543
+ minor version (`0.3.0`), and one that only fixes raises the patch (`0.3.1`). Pin the version you build
544
+ with, and read the changes before moving to a new minor.
545
+
546
+ Which app a page meets is the app's business, not the library's: a call the app cannot answer fails with
547
+ `NOT_SUPPORTED`, so decide with `apps.supports(...)`, never with a version number. The library's own
548
+ numbers, for reading a bug report:
549
+
550
+ | Library | Bridge it was built against (`SDK_BRIDGE_VERSION`) | Data contracts (`SDK_DATA_CONTRACTS`) | Added |
551
+ | ------- | -------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
552
+ | 0.1.0 | 2.19.0 | — | The base calls, storage, share, user key |
553
+ | 0.2.0 | 2.20.0 | — | Camera and microphone permissions; `GUIDE.md` and `AGENTS.md` in the package |
554
+ | 0.3.0 | 2.33.0 | `[1]` | `apps.data` with its typed methods, rows and session; `sendMessage`; place profiles (`placeProfile`, `placeProfiles`, `myProfile` and their `observe…`); the typed mock; `platform: 'desktop'`; the `MiniAppLaunchParams` type; the skill (`skill/SKILL.md`); `react` (`chatReact`); `context.display` and `context.safeArea`; the mock's `display`, `rotate()` and `reactions` |
555
+
556
+ What 0.3.0 needs from the app, for reading a bug report (bridge versions; the page still decides with
557
+ `apps.supports(...)`, and an older app answers `false` or `NOT_SUPPORTED` rather than breaking the page):
558
+
559
+ - `apps.data` reads: bridge 2.26.0; `sendMessage`: 2.27.0.
560
+ - `context.display` and `context.safeArea`: 2.30.0 (absent before it).
561
+ - The cache budget and merged events while hidden: 2.31.0.
562
+ - `react` (`chatReact`): 2.32.0.
563
+ - 2.33.0 is the bridge this build was made against; no further call needs it.
564
+
565
+ A page written for 0.2.0 needs no change: nothing it called was removed or renamed.
566
+
567
+ The data contract is the app's own version for what `apps.data` reads. The app answers a
568
+ page with the newest contract both speak; a library that speaks none the app does is answered
569
+ `NOT_SUPPORTED`.
570
+
249
571
  ## For an AI assistant writing a page
250
572
 
251
- Paste this list into the prompt along with what the page should do.
252
-
253
- 1. Use `@lemoncloud/chatic-apps-sdk`. Call `await connect()` once at start, inside `try/catch`.
254
- 2. Check `apps.inApp` and `apps.supports(capability)` before offering an app feature; never compare
255
- version numbers.
256
- 3. Every call can throw `ChaticAppsError`; branch on `error.code` only, never on `error.message`.
257
- 4. Take the theme and language from `apps.context` and `apps.onContextChange`, not from the OS.
258
- 5. Share links built with `apps.link({ ... })`, and read what one carries from `location.search` at
259
- start. The page is always entered at `/`; do not route on the path.
260
- 6. Keep the page's state in `apps.storage` as it changes, and at the latest on `visibilitychange` to
261
- `hidden`; never in `localStorage`. What must follow the user to another phone goes on your own server
262
- under `apps.getUserKey()`.
263
- 7. Use `apps.onBack(handler)` for in-page dialogs; clear it with `apps.onBack(null)` when they close.
264
- 8. Use `apps.onCloseRequest` only to protect unsaved work; return `true` to close.
265
- 9. No `window.opener`, no popup logins, no file downloads.
266
- 10. Never put the user's data in errors or in `reportError`.
267
- 11. List the permissions the page needs (`clipboard`, `share`, `openUrl`, `userKey`) in
268
- `/.well-known/chatic-app.json` — and nothing it does not use.
269
- 12. In development, `installChaticAppsMock({ permissions: [...] })` before `connect()`.
573
+ `AGENTS.md` in this package holds the rules for an assistant writing a page: the project, the calls
574
+ and the page. Copy it to the top of your project, where an assistant looks for it, or paste it into the
575
+ prompt along with what the page should do. `GUIDE.md` says how to set the project up.
576
+
577
+ `skill/SKILL.md` (Korean: `skill/SKILL.ko.md`) is a procedure for the assistant: it asks the author one
578
+ question at a time and goes from an idea to a zip that passes the verifier, in three stages. `GUIDE.md`,
579
+ "For an AI assistant in your project", says how to copy it into a project.
270
580
 
271
581
  ## For maintainers
272
582
 
273
583
  This library lives in the DoU app's repository so it cannot drift from the app: its public types are
274
584
  pinned to the app's message definitions by a type-level test, and a contract test in the app runs this
275
- client against the app's real page host. The protocol it speaks is specified in
276
- [sub-webview-protocol.md](https://github.com/lemoncloud-io/dou-app/blob/develop/apps/mobile/docs/webview/sub-webview-protocol.md).
585
+ client against the app's real page host. The cloud data rows, arguments and session are declared by hand
586
+ here (the app's types are private packages) and held to the app's by the app's contract test
587
+ (`chaticAppsSdkRuntime.contract.test.ts`):
588
+ the typed methods must be exactly what the whitelist opens, permission by permission, and every row
589
+ (and its embedded views, four levels deep)
590
+ field must match the app's in name, optionality and type. That test compiles itself, because neither
591
+ its transform nor CI type checks the app; dropping or retyping a field of an app row fails it. The protocol it speaks is specified in
592
+ [mini-app-protocol.md](https://github.com/lemoncloud-io/dou-app/blob/develop/apps/mobile/docs/webview/mini-app-protocol.md).
277
593
 
278
594
  ```bash
279
595
  npx jest --config libs/chatic-apps-sdk/jest.config.js