@lemoncloud/chatic-apps-sdk 0.2.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/GUIDE.md CHANGED
@@ -1,3 +1,5 @@
1
+ > Korean: `GUIDE.ko.md` in the package (`README.ko.md` beside this file). This English version is the canonical one.
2
+
1
3
  # Building a page with chatic-apps-sdk
2
4
 
3
5
  A Chatic app is a web page that opens inside the DoU app, over everything else, at
@@ -129,13 +131,16 @@ The manifest names the page and asks for what it needs:
129
131
  ```
130
132
 
131
133
  A page has no bar by default: a small close button floats in the top-right corner, always, and the page
132
- draws its own header. Add `"display": "standard"` to get the app's bar with the page's title and a
133
- close button instead.
134
+ draws its own header (`"display": "clean"`). Add `"display": "titled"` to get the app's bar with the page's title and a
135
+ close button instead. A page that draws its own scenery to the screen's edges — a game, say — sets
136
+ `"display": "immersive"`: it then runs under the status bar and the home indicator, and pads its own
137
+ controls with the insets the README's Layout notes describe.
134
138
 
135
139
  `manifestVersion` must be `1`; the app ignores a manifest it cannot read. Ask only for the permissions
136
- the page uses — `clipboard`, `share`, `openUrl`, `userKey` — and see the
137
- package `README.md` for what each one unlocks and for `display` and `orientation`. Without a manifest a
138
- page still runs; it gets everything but those four.
140
+ the page uses — `clipboard`, `share`, `openUrl`, `userKey`, and for reading the app's data `session`,
141
+ `cloud`, `place`, `channel`, `chat`, `user` — and see the package `README.md` for what each one unlocks
142
+ and for `display` and `orientation`. Without a manifest a page still runs; it gets everything but what
143
+ those permissions unlock.
139
144
 
140
145
  ## How the page behaves in the app
141
146
 
@@ -146,7 +151,10 @@ has the detail on each.
146
151
  Keep the page's own data in `apps.storage`, not `localStorage`, which goes when the system clears
147
152
  website data. What must follow the user to another phone goes on your own server, under
148
153
  `apps.getUserKey()`.
149
- - **The page lies inside the safe area on every edge.** There are no insets to handle.
154
+ - **The page lies inside the safe area on every edge**, unless its manifest asks for `immersive`.
155
+ There are no insets to handle; an `immersive` page handles them itself, from the
156
+ `--chatic-safe-area-inset-*` properties in CSS, or `apps.context.safeArea` in script, which an older
157
+ app does not send — then fall back to the CSS properties.
150
158
  - **Dark mode follows the app's theme**, from `apps.context.theme`, not the phone's.
151
159
  - **Share `apps.link({ … })`**, not the page's address, and read what a link carries from
152
160
  `location.search` when the page starts.
@@ -197,15 +205,215 @@ only walks that history, so an in-memory stack needs the back button above eithe
197
205
 
198
206
  Keep the top-right corner of every screen clear of your own controls: the close button floats there.
199
207
 
208
+ ## A page that uses the cloud's data
209
+
210
+ A page opened in a cloud can read that cloud — its places, rooms, messages and members — through
211
+ `apps.data`, and post a text message. The package `README.md` lists every method, its arguments and
212
+ the rows it answers; this is how to build a page around them.
213
+
214
+ **Choose permissions by what the page shows.** Each of `session`, `cloud`, `place`, `channel`, `chat`
215
+ and `user` opens a set of reads, `chatSend` opens the send, and `chatReact` opens reacting to a message. The app does not filter what a read
216
+ answers: a page with `user`, `channel` or `chat` gets users' sign-in ids, one with `place` gets each place's owner as the
217
+ account server has them, one with `cloud` the cloud's account details. Ask for the fewest that do the
218
+ job — what the page does with what it read is its author's responsibility — and do not send any of it
219
+ off the device without telling the user.
220
+
221
+ ```json
222
+ { "manifestVersion": 1, "name": "Room stats", "permissions": ["session", "channel", "chat"] }
223
+ ```
224
+
225
+ **Wait for the user.** `apps.data.connect()` is where the app asks the user whether this page may
226
+ read this cloud, and it waits as long as the user takes: show the page's own frame first, then connect.
227
+ A refusal is `CONSENT_REFUSED`: say why the page needs the data and offer to close.
228
+
229
+ ```ts
230
+ const apps = await connect();
231
+ if (!apps.supports('data')) return showNotAvailableHere(); // a browser, the desktop, an old Android WebView, an older app
232
+ try {
233
+ await apps.data.connect();
234
+ } catch (error) {
235
+ if (error instanceof ChaticAppsError && error.code === 'CONSENT_REFUSED') return showWhyWeAsk();
236
+ throw error;
237
+ }
238
+ const session = apps.data.session(); // CloudSession | null — null without `session`
239
+ const placeId = session?.committedSiteId ?? undefined; // undefined without `session`
240
+ ```
241
+
242
+ **Read with the types.** Every method the app opens is typed, so an editor completes the names and a
243
+ wrong argument fails the build. Rows are mostly optional fields: read each with a fallback.
244
+
245
+ ```ts
246
+ const rooms = await apps.data.call('channel.cacheReadList', { sid: placeId });
247
+ for (const room of rooms?.list ?? []) console.log(room.name ?? '(no name)', room.unreadCount ?? 0);
248
+ ```
249
+
250
+ **Streams are a budget.** A page holds at most 16 per page load; the next `subscribe` fails `INVALID`. Subscribe for what is on screen, `stop()`
251
+ when it leaves the screen, and hold only the rows you show — an event can carry a whole list.
252
+
253
+ **The cloud can change under the page.** If the user moves to another cloud, every stream ends with
254
+ `CLOUD_CHANGED`, `onCloudChanged` fires once, and nothing answers after. Finish the page or show a
255
+ notice; do not retry.
256
+
257
+ ```ts
258
+ apps.data.onCloudChanged(() => apps.finish());
259
+ ```
260
+
261
+ **Send only what the user chose to send.** `apps.data.sendMessage(roomId, text)` posts in the
262
+ user's name, to a room of the place the page was opened in. Send on a tap the user made, with text they
263
+ saw. The same goes for `apps.data.react(messageId, emoji, on)` with `chatReact`: it adds or removes a
264
+ reaction in the user's name — removing takes off the user's own reaction with that emoji, even one they
265
+ added by hand — so react only on the user's tap. Reactions are limited to one per 250 ms and 60 a
266
+ minute.
267
+
268
+ **Develop against the mock.** It answers from the data you give it, typed with the same map as the
269
+ app, so an answer of the wrong shape fails the build before it fails in the app:
270
+
271
+ ```ts
272
+ import { installChaticAppsMock } from '@lemoncloud/chatic-apps-sdk/mock';
273
+
274
+ const app = installChaticAppsMock({
275
+ permissions: ['session', 'channel', 'chatSend'],
276
+ data: {
277
+ session: {
278
+ context: {
279
+ cloud: { cloudId: 'cloud-1', siteId: 'place-1', isActive: true },
280
+ identity: { userId: 'user-1', isAuthenticated: true },
281
+ },
282
+ committedSiteId: 'place-1',
283
+ },
284
+ calls: {
285
+ 'channel.cacheReadList': () => ({
286
+ list: [{ id: 'room-1', cid: 'cloud-1', sid: 'place-1', isNotificationEnabled: true, name: 'Lobby' }],
287
+ meta: { total: 1 },
288
+ }),
289
+ },
290
+ },
291
+ });
292
+ // later: app.sentMessages, app.changeCloud()
293
+ ```
294
+
295
+ Use made-up ids and names in the mock, never a real cloud's. The mock does not know which methods the
296
+ app opens for which permission — it answers what you give it — so check `allowed` from `connect()` in
297
+ the app.
298
+
299
+ ## Your own server
300
+
301
+ A page is static files, and stays that way: no server rendering, no server routing. When it needs a
302
+ server of its own — scores, saved work, anything shared between users — that server is an API on its
303
+ own origin, and the page calls it with `fetch`.
304
+
305
+ **Allow the page's origin.** A call from the page is an ordinary cross-origin request from
306
+ `https://<name>.apps.chatic.io`, so the server answers it with CORS headers naming that origin, and
307
+ answers the preflight a JSON `POST` sends first:
308
+
309
+ ```http
310
+ Access-Control-Allow-Origin: https://<name>.apps.chatic.io
311
+ Access-Control-Allow-Methods: GET, POST, OPTIONS
312
+ Access-Control-Allow-Headers: Content-Type
313
+ Vary: Origin
314
+ ```
315
+
316
+ Allow your development address too while you test (see the next section), and not `*` once the page
317
+ is live.
318
+
319
+ **Tell users apart with the user key, and rely on nothing else from it.** `apps.getUserKey()` (the
320
+ `userKey` permission) answers 64 hex characters that stay the same for one device and your site. Send
321
+ it with each request and keep the user's data under it on the server. It is not a sign-in: two people
322
+ on one phone share it, and anyone who learns it can send it. Keep game progress under it, not money,
323
+ purchases or anything a user could take from another. If the page needs that, add a sign-in of your
324
+ own, with a redirect: a popup sign-in does not work in the app (`window.open` loads in the same view,
325
+ and nothing answers through `window.opener`).
326
+
327
+ **Trust nothing the page sends.** The page runs on the user's device, and anyone can call your API
328
+ directly with any body, any user key and any `params`. Check every value on the server as you would a
329
+ form on the open web. `MiniAppLaunchParams` names who is looking; it proves nothing.
330
+
331
+ **What the page read from the cloud is yours to answer for once it leaves the device.** The user
332
+ allowed the page to read the cloud with `apps.data`, not to send it elsewhere. If the page sends
333
+ members' names or messages to your server, say so in the page before it does, send only what the
334
+ feature needs, and keep it no longer than it needs.
335
+
336
+ ## Trying it in the app
337
+
338
+ A browser with the mock proves the page's logic; the app is the only place to see its layout, the
339
+ keyboard and real haptics. To open the page you are working on in the app before it is deployed, give
340
+ your development server an https address and add it to a cloud you own as a mini app.
341
+
342
+ 1. Run the development server, and expose it at an https address with a tunnel. `cloudflared` needs no
343
+ account for this:
344
+
345
+ ```bash
346
+ npm run dev # Vite, on http://localhost:5173
347
+ cloudflared tunnel --url http://localhost:5173 # prints https://<random words>.trycloudflare.com
348
+ ```
349
+
350
+ Vite refuses a host it does not know, so allow the tunnel's:
351
+
352
+ ```ts
353
+ // vite.config.ts
354
+ export default defineConfig({ server: { allowedHosts: ['.trycloudflare.com'] } });
355
+ ```
356
+
357
+ 2. In the DoU app on the phone, with a cloud you own selected, go to **My → Settings → Lab → Mini
358
+ apps** and tap **Add mini app**: a name, and that address (`https://…`, no port). The list is kept
359
+ on that phone only. Then tap **Open mini apps** and choose it on the mini app home. The first time,
360
+ DoU asks before it hands the page your name, your id in the cloud, the cloud and the place you have
361
+ open.
362
+ 3. The tunnel's address changes each time it starts: tap the mini app in the same list to edit its
363
+ address.
364
+
365
+ A tunnel's address lasts as long as the tunnel. For one that stays, put a build on any static host
366
+ with https (a preview deployment on Vercel, Netlify or the like) and add that address instead: it opens
367
+ the same way, with the same limits below, but each change needs a new deployment.
368
+
369
+ Such a page is opened as an outside site, not a reviewed page, and gets less than it will once
370
+ deployed to `apps.chatic.io`:
371
+
372
+ - **Only the base requests.** Closing, haptics, Android back, the close guard, error reports,
373
+ storage, and the camera and microphone permissions work. `setTitle` answers, but the bar keeps the
374
+ host. `getUserKey`, `copy`, `share` and
375
+ `openUrl` fail with `NOT_SUPPORTED`. The desktop app answers fewer still: closing, the title and
376
+ error reports.
377
+ - **No manifest.** The app does not read the page's `/.well-known/chatic-app.json`: the bar is always
378
+ shown, titled with the tunnel's host, and `display` and `orientation` do not apply.
379
+ - **No cloud data.** `apps.supports('data')` is `false`, so `apps.data` cannot be tried in the app this
380
+ way. Build it against the mock, and check it in the app once the page is reviewed.
381
+ - **Its own storage.** Storage is kept per origin, so what the page stores here is not what it will
382
+ find under its real address.
383
+
200
384
  ## For an AI assistant in your project
201
385
 
202
386
  The package ships `AGENTS.md`: rules for an assistant writing a Chatic app. Assistants read an
203
387
  `AGENTS.md` at the top of the project, not one inside `node_modules`, so copy it there, or point your
204
388
  assistant at `node_modules/@lemoncloud/chatic-apps-sdk/AGENTS.md`.
205
389
 
390
+ From 0.3.0 it also ships a skill, `skill/SKILL.md` (and `skill/SKILL.ko.md` in Korean): a procedure that takes
391
+ someone who has never built a web page from an idea to a zip that passes the verifier, by asking one
392
+ question at a time. It goes in three stages — the idea, the first build, the release prep — and keeps its
393
+ plan and progress in `MINIAPP.md` at the project's top, so a conversation on another day picks up where
394
+ the last one stopped. It only edits the project's files, installs the starting packages once after
395
+ asking, and runs the project's own scripts; it never uploads or submits anything.
396
+
397
+ To use it, put the `skill` folder where your assistant reads skills from, or give it `SKILL.md` and ask
398
+ it to follow it. In a project that already installed the package, copy it from `node_modules`; in an empty
399
+ folder, fetch the file of the published version you will install:
400
+
401
+ ```bash
402
+ cp -R node_modules/@lemoncloud/chatic-apps-sdk/skill ./chatic-app-skill
403
+ curl -fsSLO https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.3.0/skill/SKILL.md
404
+ ```
405
+
406
+ The skill's first install needs SDK 0.3.0 and `@lemoncloud/chatic-apps-devtools` on npm; until both are
407
+ published, neither the commands above nor that install work. Then tell the assistant what you want —
408
+ "make a quiz mini-app" is enough to start. A copy does not update
409
+ with the package; the skill names the SDK version it was written for and says so when the installed one
410
+ differs.
411
+
206
412
  ## Before you hand it over
207
413
 
208
414
  - [ ] `npm run build` produces `dist/` with `index.html` and `.well-known/chatic-app.json` at its top.
415
+ - [ ] Once `@lemoncloud/chatic-apps-devtools` is published: `npx @lemoncloud/chatic-apps-devtools verify`
416
+ (or the project's `npm run verify`) ends with "Ready to hand over".
209
417
  - [ ] Opened from a plain file server, the built page works at the root, with no path in the address.
210
418
  - [ ] The page works in a browser with no app (`apps.inApp` is `false`) and with the stand-in.
211
419
  - [ ] Every permission in the manifest is used, and every call that needs one is guarded with
@@ -213,6 +421,10 @@ assistant at `node_modules/@lemoncloud/chatic-apps-sdk/AGENTS.md`.
213
421
  - [ ] State is saved as the user goes, not only at a button.
214
422
  - [ ] No `window.opener`, popup login, file download or server-side rendering.
215
423
  - [ ] No user data in errors, in `reportError` or in the page's own logs.
424
+ - [ ] A page that calls its own server: the server allows the page's origin, checks every value it
425
+ receives, and puts nothing of value behind the user key alone.
426
+ - [ ] A page that reads the cloud: it asks for only the cloud data permissions it uses, handles
427
+ `CONSENT_REFUSED` and `CLOUD_CHANGED`, and stops every stream it no longer shows.
216
428
 
217
429
  ## Deploying
218
430