@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/AGENTS.ko.md +82 -0
- package/AGENTS.md +34 -7
- package/GUIDE.ko.md +419 -0
- package/GUIDE.md +218 -6
- package/README.ko.md +582 -0
- package/README.md +364 -46
- package/chatic-apps-sdk.global.js +1 -1
- package/index.cjs +1 -1
- package/index.d.cts +1295 -6
- package/index.d.ts +1295 -6
- package/index.js +282 -196
- package/mock.cjs +1 -1
- package/mock.d.cts +1203 -3
- package/mock.d.ts +1203 -3
- package/mock.js +306 -118
- package/package.json +15 -2
- package/skill/SKILL.ko.md +263 -0
- package/skill/SKILL.md +275 -0
- package/storage-BXB76dd8.js +175 -0
- package/storage-C42PwRjA.cjs +1 -0
- package/storage-BuvWwLx2.js +0 -104
- package/storage-yeS4HWKZ.cjs +0 -1
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": "
|
|
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
|
|
137
|
-
|
|
138
|
-
page still runs; it gets everything but
|
|
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
|
|
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
|
|