@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/AGENTS.ko.md ADDED
@@ -0,0 +1,82 @@
1
+ > English: 패키지의 `AGENTS.md`(이 파일 옆의 `agent-rules.md`) — 영어판이 정본입니다. 두 판이 다르면 영어판을 따르세요.
2
+
3
+ # Chatic 앱을 작성하는 AI 어시스턴트를 위한 규칙
4
+
5
+ 지금 `@lemoncloud/chatic-apps-sdk`를 사용해, DoU 앱 안에서 `https://<name>.apps.chatic.io`로 열리는 웹
6
+ 페이지를 작성한다. 다음 규칙을 따른다. 이 패키지의 `GUIDE.md`는 프로젝트를 구성하는 방법과 번들의 모양을
7
+ 설명하고, `README.md`는 모든 호출, 제한, 오류 코드의 레퍼런스다. 그 내용에 의존하는 코드를 쓰기 전에
8
+ 필요한 부분을 읽는다.
9
+
10
+ ## 프로젝트
11
+
12
+ 1. **정적 파일만 쓴다.** 결과물은 최상위에 `index.html`이 있고 그 옆에 `.well-known/chatic-app.json`이 있는
13
+ 폴더다. 서버 코드, 서버 사이드 렌더링, 서버 라우팅을 쓰지 않는다.
14
+ Vite에서는 매니페스트를 `public/.well-known/chatic-app.json`에 둔다.
15
+ 2. **페이지는 항상 `/`로 진입한다.** 경로로 라우팅하지 않고 `base`를 설정하지 않는다. 공유 링크는 데이터를
16
+ 쿼리에 담는다. 페이지가 시작할 때 `location.search`에서 읽는다.
17
+ 3. **mock은 개발 중에만, `connect()` 전에 설치한다**:
18
+ `if (import.meta.env.DEV) installChaticAppsMock({ permissions: [...] })`, 가져오는 곳은
19
+ `@lemoncloud/chatic-apps-sdk/mock`이다.
20
+
21
+ ## 호출
22
+
23
+ 4. `@lemoncloud/chatic-apps-sdk`를 사용한다. 시작할 때 `try/catch` 안에서 `await connect()`를 한 번 호출한다.
24
+ 5. 앱 기능을 제공하기 전에 `apps.inApp`과 `apps.supports(capability)`를 확인한다. 버전 번호를 비교하지
25
+ 않는다.
26
+ 6. 모든 호출은 `ChaticAppsError`를 던질 수 있다. `error.code`로만 분기하고, `error.message`로 분기하지 않는다.
27
+ 7. 테마와 언어는 OS가 아니라 `apps.context`와 `apps.onContextChange`에서 가져온다.
28
+ 8. 공유 링크는 `apps.link({ ... })`로 만든 것을 쓰고, 페이지 자체의 주소를 쓰지 않는다.
29
+ 9. 페이지의 상태는 바뀔 때마다, 늦어도 `visibilitychange`가 `hidden`이 될 때 `apps.storage`에 저장한다.
30
+ `localStorage`에는 절대 저장하지 않는다. 다른 휴대폰으로 사용자를 따라가야 하는 것은
31
+ 직접 운영하는 서버에 `apps.getUserKey()`로 받은 키로 구분해 둔다.
32
+ 10. 페이지 안의 화면과 대화상자는 스택으로 관리한다. 스택에 화면이 둘 이상인 동안은
33
+ `apps.onBack(back)`, 루트에서는 `apps.onBack(null)`로 두어 Android 뒤로 가기가 페이지를 닫게 한다. iOS에는
34
+ 뒤로 가기 키가 없으므로, 돌아갈 화면이 있을 때마다 같은 `back()`을 호출하는 뒤로 가기 버튼을 그린다.
35
+ 스택은 메모리에 둔다. 브라우저 히스토리를 push하는 라우터(해시 라우트, `pushState`)를 쓰면 루트에서
36
+ Android 뒤로 가기가 페이지를 닫는 대신 그 히스토리를 거슬러 간다.
37
+ 11. `apps.onCloseRequest`는 저장하지 않은 작업을 보호할 때만 쓴다. 닫으려면 `true`를 반환한다.
38
+ 12. 카메라나 마이크는 사용자가 그 기능을 쓰려 할 때 `apps.permissions.request(kind)`를 호출하고 — 시작할 때
39
+ 호출하지 않는다 — 그다음 `getUserMedia`를 호출한다. 매니페스트 권한은 필요 없다. 요청에 타임아웃을 두지
40
+ 않고, 응답이 `'blocked'`이면 `apps.openSettings()`를 호출해 사용자를 설정 화면으로 안내한다. `query`의 응답이 아니라 요청의 응답을 사실로
41
+ 취급한다. Android에서 `query`는 차단된 권한을 `'prompt'`로 읽을 수 있다.
42
+
43
+ 13. 앱의 데이터는 `apps.data`로만, 그리고 `apps.supports('data')` 확인 후에만 읽는다. 먼저
44
+ `apps.data.connect()`를 호출하고 `CONSENT_REFUSED`(페이지가 왜 데이터가 필요한지 보여준다)와
45
+ `CLOUD_CHANGED`(페이지를 끝내거나 안내를 보여준다. 재시도하지 않는다)를 처리한다. 메서드는
46
+ `DataCalls`와 `DataStreams`에 타입으로 정의된 이름으로 호출하고 인자는 타입이 검사하게 한다. 응답을
47
+ `any`로 캐스트하지 않고, 타입이 있는 메서드에 직접 만든 타입으로 `call<T>`를 넘기지 않으며, 메서드 이름을
48
+ 지어내지 않는다 — 앱이 열지 않는 메서드는 `RUNTIME_NOT_ALLOWED`로 실패한다. 타입이 있는 스트림에는 그
49
+ 인자만 넘기고, `LISTENER`를 넣지 않고 리스너 뒤에도 아무것도 넘기지 않으며, 화면에서 사라지면 `stop()`한다.
50
+ 모든 행 필드는 대체값과 함께 읽는다. 대부분 선택적이다. 메시지는 `chatSend`를 갖춘 상태에서
51
+ `apps.data.sendMessage(channelId, text)`로만, 사용자가 보내기로 고른 텍스트만 보낸다 — 사용자의 이름으로
52
+ 나간다. 메시지 반응은 `chatReact`를 갖춘 상태에서 `apps.data.react(messageId, emoji, on)`로만, 사용자가
53
+ 탭했을 때 단다 — 사용자의 반응을 달거나 떼며, 직접 단 것도 뗀다. 페이지가 있는 클라우드는 `cloud.cacheRead`가 아니라
54
+ `call('cloud.getCloud', { id }, { cache: false })`로 읽는다. `cloud.cacheRead`는 사용자가 소유한
55
+ 클라우드에 대해 자주 `null`이다. `id`는 세션의 `context.cloud.cloudId`(`session` 필요) 또는
56
+ `params.cloud.id`에서 가져온다. 행에는 연락처와 계정 정보(이메일, 전화번호, 로그인 id, 계정 번호)가
57
+ 담겨 있다. 페이지에 필요한 필드만 보여 주거나 저장하고, 기기 밖으로 절대 보내지 않는다.
58
+ mock에서는 지어낸 id와 이름으로 타입에 맞는 응답을 준다.
59
+
60
+ ## 페이지
61
+
62
+ 14. `window.opener`, 팝업 로그인, 파일 다운로드를 쓰지 않는다.
63
+ 15. 오류나 `reportError`에 사용자의 데이터를 절대 넣지 않는다.
64
+ 16. 페이지에 필요한 권한(`clipboard`, `share`, `openUrl`, `userKey`, 그리고 앱의 데이터를 위한 `session`,
65
+ `cloud`, `place`, `channel`, `chat`, `user`, 보내기를 위한 `chatSend`, 반응을 위한 `chatReact`)을
66
+ `/.well-known/chatic-app.json`에 나열한다 — 쓰지 않는 것은 나열하지 않는다. 권한이 필요한 호출은 그 권한
67
+ 없이는 `NOT_SUPPORTED`로 실패하고, 클라우드 데이터 권한이 여는 범위 밖의 클라우드 데이터 메서드는
68
+ `RUNTIME_NOT_ALLOWED`로 실패한다.
69
+ 17. 안전 영역을 위해 그리지 않는다. 페이지는 이미 모든 가장자리에서 안전 영역 안에 놓인다. 예외는 화면
70
+ 가장자리까지 장면이 닿아야 하는 페이지를 위한 `"display": "immersive"` 매니페스트다. 이때는 viewport
71
+ meta에 `viewport-fit=cover`를 추가하고, 모든 헤더, 컨트롤, 탭 가능한 요소에
72
+ `var(--chatic-safe-area-inset-<edge>, env(safe-area-inset-<edge>, 0px))`로 여백을 준다. 스크립트로 배치하는
73
+ 페이지는 `apps.context.safeArea`와 `onContextChange`로 오는 변경을 읽고, 오래된 앱이 그것을 보내지 않으면
74
+ CSS 속성으로 물러난다.
75
+ 18. 매니페스트가 `"display": "titled"`를 설정하지 않는 한 페이지에는 제목 바가 없다. 자기 헤더와 제목을
76
+ 그리고, 앱의 닫기 버튼이 떠 있는 오른쪽 위 모서리를 비워 둔다.
77
+
78
+ ## 다 됐다고 말하기 전에
79
+
80
+ 빌드를 실행하고, `dist/index.html`과 `dist/.well-known/chatic-app.json`이 있는지 확인한다. 확인하지 못한 것을
81
+ 말한다. mock을 쓴 브라우저는 페이지의 로직을 증명할 뿐 휴대폰에 대해서는 아무것도 증명하지 않는다 —
82
+ 레이아웃, 키보드, 실제 햅틱은 앱이 있어야 확인할 수 있다.
package/AGENTS.md ADDED
@@ -0,0 +1,83 @@
1
+ > Korean: `AGENTS.ko.md` in the package (`agent-rules.ko.md` beside this file). This English version is the canonical one.
2
+
3
+ # Rules for an AI assistant writing a Chatic app
4
+
5
+ You are writing a web page that opens inside the DoU app, at `https://<name>.apps.chatic.io`, using
6
+ `@lemoncloud/chatic-apps-sdk`. Follow these rules. `GUIDE.md` in this package says how to set the
7
+ project up and what the bundle looks like; `README.md` is the reference for every call, limit and error
8
+ code. Read the part you need before you write code that depends on it.
9
+
10
+ ## The project
11
+
12
+ 1. **Static files only.** The output is a folder with `index.html` at its top and
13
+ `.well-known/chatic-app.json` beside it. No server code, no server-side rendering, no server routing.
14
+ With Vite, put the manifest at `public/.well-known/chatic-app.json`.
15
+ 2. **The page is always entered at `/`.** Do not route on the path and do not set a `base`. A shared
16
+ link carries its data in the query: read it from `location.search` when the page starts.
17
+ 3. **Install the mock in development only**, before `connect()`:
18
+ `if (import.meta.env.DEV) installChaticAppsMock({ permissions: [...] })`, imported from
19
+ `@lemoncloud/chatic-apps-sdk/mock`.
20
+
21
+ ## The calls
22
+
23
+ 4. Use `@lemoncloud/chatic-apps-sdk`. Call `await connect()` once at start, inside `try/catch`.
24
+ 5. Check `apps.inApp` and `apps.supports(capability)` before offering an app feature; never compare
25
+ version numbers.
26
+ 6. Every call can throw `ChaticAppsError`; branch on `error.code` only, never on `error.message`.
27
+ 7. Take the theme and language from `apps.context` and `apps.onContextChange`, not from the OS.
28
+ 8. Share links built with `apps.link({ ... })`, never the page's own address.
29
+ 9. Keep the page's state in `apps.storage` as it changes, and at the latest on `visibilitychange` to
30
+ `hidden`; never in `localStorage`. What must follow the user to another phone goes on your own server
31
+ under `apps.getUserKey()`.
32
+ 10. For screens and dialogs inside the page, keep a stack: while it holds more than one screen,
33
+ `apps.onBack(back)`; at the root, `apps.onBack(null)`, so Android back closes the page. iOS has no
34
+ back key, so draw a back button that calls the same `back()` whenever there is a screen to go back to.
35
+ Keep the stack in memory: a router that pushes browser history (hash routes, `pushState`) makes
36
+ Android back at the root walk that history instead of closing the page.
37
+ 11. Use `apps.onCloseRequest` only to protect unsaved work; return `true` to close.
38
+ 12. For the camera or microphone, call `apps.permissions.request(kind)` when the user reaches for the
39
+ feature, never at start, then `getUserMedia`. No manifest permission is needed. Do not time the
40
+ request out, and send `'blocked'` to `apps.openSettings()`. Treat the request's answer, not
41
+ `query`'s, as the truth: on Android `query` can read `'prompt'` for a blocked permission.
42
+
43
+ 13. Read the app's data only through `apps.data`, and only after `apps.supports('data')`: call
44
+ `apps.data.connect()` first and handle `CONSENT_REFUSED` (show why the page needs it) and
45
+ `CLOUD_CHANGED` (finish or show a notice; do not retry). Call methods by the names typed in
46
+ `DataCalls` and `DataStreams` and let the types check the arguments: do not cast an answer to
47
+ `any` or pass `call<T>` a type of your own for a typed method, and do not invent a method name —
48
+ one the app does not open fails with `RUNTIME_NOT_ALLOWED`. For a typed stream pass only its
49
+ arguments, with no `LISTENER` and nothing after it, and `stop()` it when it leaves the screen.
50
+ Read every row field with a fallback: most are optional. Send a message only with
51
+ `apps.data.sendMessage(channelId, text)`, with `chatSend`, of text the user chose to send — it
52
+ goes out in their name; react to a message only with `apps.data.react(messageId, emoji, on)`, with
53
+ `chatReact`, on the user's tap — it adds or removes their reaction, a hand-made one included. Read the
54
+ cloud the page is in with
55
+ `call('cloud.getCloud', { id }, { cache: false })`, not `cloud.cacheRead`, which is often `null` for a
56
+ cloud the user owns; take `id` from the session's `context.cloud.cloudId` (needs `session`) or
57
+ `params.cloud.id`. Rows carry contact and account details (emails, phone numbers, sign-in ids,
58
+ account numbers): show or store only the fields the page needs, and never send them off the device.
59
+ In the mock, give typed answers with made-up ids and names.
60
+
61
+ ## The page
62
+
63
+ 14. No `window.opener`, no popup logins, no file downloads.
64
+ 15. Never put the user's data in errors or in `reportError`.
65
+ 16. List the permissions the page needs (`clipboard`, `share`, `openUrl`, `userKey`, and for the app's
66
+ data `session`, `cloud`, `place`, `channel`, `chat`, `user`, `chatSend` to send and `chatReact`
67
+ to react) in
68
+ `/.well-known/chatic-app.json` — and nothing it does not use. A call that needs one fails with `NOT_SUPPORTED` without it; a cloud data method
69
+ outside what the cloud data permissions open fails with `RUNTIME_NOT_ALLOWED`.
70
+ 17. Do not draw for the safe area: the page already lies inside it on every edge. The exception is a
71
+ manifest with `"display": "immersive"`, for a page whose scenery must reach the screen's edges: then
72
+ add `viewport-fit=cover` to the viewport meta and pad every header, control and tappable element with
73
+ `var(--chatic-safe-area-inset-<edge>, env(safe-area-inset-<edge>, 0px))`. A page that lays out in
74
+ script reads `apps.context.safeArea` and its changes through `onContextChange`, and falls back to the
75
+ CSS properties when an older app leaves it out.
76
+ 18. The page has no title bar unless the manifest sets `"display": "titled"`: draw your own header and
77
+ title, and keep the top-right corner clear, where the app's close button floats.
78
+
79
+ ## Before you say it is done
80
+
81
+ Run the build, and check that `dist/index.html` and `dist/.well-known/chatic-app.json` exist. Say what
82
+ you could not check: a browser with the mock proves a page's logic and nothing about a phone — layout,
83
+ the keyboard and real haptics need the app.
package/GUIDE.ko.md ADDED
@@ -0,0 +1,419 @@
1
+ > English: 패키지의 `GUIDE.md`(이 파일 옆의 `README.md`) — 영어판이 정본입니다. 두 판이 다르면 영어판을 따르세요.
2
+
3
+ # chatic-apps-sdk로 페이지 만들기
4
+
5
+ Chatic 앱은 DoU 앱 안에서 다른 모든 화면 위에 열리는 웹 페이지이며, 주소는
6
+ `https://<name>.apps.chatic.io`이다. 여느 웹 페이지처럼 만들면 되고, `@lemoncloud/chatic-apps-sdk`가
7
+ 페이지를 앱에 연결한다. 닫기, 제목, 햅틱, 공유, 기기에 데이터 저장 등을 이것으로 한다.
8
+ 이 가이드는 프로젝트를 구성하는 방법과 그 결과물을 다룬다. 라이브러리의 호출, 제한, 오류 코드는
9
+ 패키지 `README.md`에 있으며, 이 가이드는 그것을 반복하지 않는다.
10
+
11
+ ## 무엇을 만드는가
12
+
13
+ - **정적 파일.** 앱은 여느 브라우저처럼 웹 주소에서 페이지를 불러온다. 페이지 자체를 위해 직접
14
+ 운영할 서버는 없고, 서버 사이드 렌더링도 없다.
15
+ - **루트로 진입하는 한 페이지.** 앱은 항상 `/`를 연다. 링크는 데이터를 경로가 아니라 쿼리
16
+ (`/?level=3`)에 담으므로, 페이지는 경로로 라우팅하지 않는다.
17
+ - **휴대폰 자체의 웹 뷰 안에서.** 페이지는 iOS에서는 WKWebView, Android에서는 Android System WebView에서
18
+ 실행되므로, 그 엔진들이 지원하는 것을 쓸 수 있다. 지원하려는 가장 오래된 휴대폰을 확인한다.
19
+ - **개발 중에는 브라우저에서도.** 라이브러리는 브라우저가 할 수 있는 동작으로 대체하고, 앱을 대신하는
20
+ 대역을 함께 제공하므로, 휴대폰 없이 페이지를 작성하고 시험해 볼 수 있다.
21
+
22
+ ## 도구 고르기
23
+
24
+ 라이브러리는 런타임 의존성이 없고 나머지에 대해 아무 전제도 두지 않으므로, 익숙한 것을 쓰면 된다.
25
+ 도구가 적은 것부터 많은 것 순으로 세 가지 형태가 동작한다.
26
+
27
+ | 형태 | 이럴 때 쓴다 | 라이브러리를 가져오는 곳 |
28
+ | ------------------------------ | ----------------------------------------- | ------------------------------------------------- |
29
+ | `index.html` 하나, 빌드 없음 | 작은 페이지, 프로토타입 | `window.ChaticAppsSDK`를 정의하는 `<script>` 태그 |
30
+ | Vite와 일반 TypeScript 또는 JS | 화면 몇 개 분량의 로직을 가진 독립 페이지 | `npm install` |
31
+ | Vite와 React, Vue 또는 Svelte | 이미 이 중 하나로 인터페이스를 만든다 | `npm install` |
32
+
33
+ 결과가 정적 파일이면 무엇이든 괜찮지만, 다음 제한이 있다.
34
+
35
+ - **서버 렌더링도, 서버 라우팅도 없다.** 프레임워크의 서버 모드가 아니라 정적 모드나 싱글 페이지 모드를
36
+ 쓴다. Next.js는 `output: 'export'`, Nuxt는 `ssr: false` 또는 `nuxt generate`, SvelteKit은 싱글 페이지
37
+ 모드의 정적 어댑터가 필요하다.
38
+ - **경로에 의존하지 않는다.** 클라이언트 측 라우터는 페이지가 `/`로 진입한 상태에서 동작해야 하고,
39
+ 공유 링크에 도달하는 데 필요해서는 안 된다. 링크가 담는 것은 쿼리에 넣는다.
40
+ - **`window.opener`, 팝업, 파일 다운로드에 의존하지 않는다.** 팝업은 같은 뷰에서 열려 페이지를 대체하므로,
41
+ `window.opener`로 응답하는 로그인은 동작할 수 없고, 다운로드는 iOS에서 처리되지 않는다. 대신 무엇을 할지는
42
+ 패키지 `README.md`에 있다.
43
+
44
+ Vite가 가장 짧은 길이며, 이 가이드의 나머지는 Vite를 쓴다.
45
+
46
+ ## 프로젝트 구성하기
47
+
48
+ ```bash
49
+ npm create vite@latest quiz -- --template vanilla-ts
50
+ cd quiz
51
+ npm install @lemoncloud/chatic-apps-sdk
52
+ ```
53
+
54
+ 원한다면 템플릿으로 `react-ts`, `vue-ts`, `svelte-ts` 중 하나를 대신 고른다. 아래 내용은 템플릿에
55
+ 의존하지 않는다. `src/main.ts`를 앱에 연결하는 페이지로 바꾼다.
56
+
57
+ ```ts
58
+ import { connect, ChaticAppsError } from '@lemoncloud/chatic-apps-sdk';
59
+ import { installChaticAppsMock } from '@lemoncloud/chatic-apps-sdk/mock';
60
+
61
+ // A stand-in for the app in the browser, in development only. Vite removes a branch that is always
62
+ // false, so it is not in the production bundle. The controller lets you play the user's side.
63
+ if (import.meta.env.DEV) {
64
+ const app = installChaticAppsMock({ permissions: ['share', 'userKey'] });
65
+ Object.assign(window, { app }); // then `app.pressBack()` in the browser console
66
+ }
67
+
68
+ async function start() {
69
+ try {
70
+ const apps = await connect();
71
+ document.documentElement.dataset.theme = apps.context?.theme ?? 'light';
72
+ apps.onContextChange(context => (document.documentElement.dataset.theme = context.theme));
73
+ } catch (error) {
74
+ // `UNSUPPORTED_PROTOCOL` means the app is newer than this library: update the library.
75
+ const needsUpdate = error instanceof ChaticAppsError && error.code === 'UNSUPPORTED_PROTOCOL';
76
+ document.body.textContent = needsUpdate ? 'This page needs an update.' : 'This page could not start.';
77
+ }
78
+ }
79
+
80
+ void start();
81
+ ```
82
+
83
+ 그다음:
84
+
85
+ ```bash
86
+ npm run dev # the page in your browser, with the stand-in for the app
87
+ npm run build # the bundle, in dist/
88
+ ```
89
+
90
+ React, Vue, Svelte에서는 같은 줄을 애플리케이션이 시작하는 곳, 렌더링하기 전에 둔다.
91
+
92
+ ### 브라우저에서 개발하기
93
+
94
+ `installChaticAppsMock`은 탭을 가짜 앱으로 바꾼다. 앱처럼 응답하고, 모든 호출을 로그로 남기며, 반환하는
95
+ 컨트롤러로 사용자 쪽 동작을 흉내 낼 수 있게 한다. Android 뒤로 가기 버튼, 닫기 요청, 테마 변경 등이다
96
+ (위 예시는 컨트롤러를 `window`에 두므로 브라우저 콘솔에서 접근할 수 있다). 앱이 페이지의 매니페스트에
97
+ 있는 권한만 허용하듯, mock도 나열한 권한만 허용한다. mock은 페이지의 로직을 증명할 뿐 휴대폰에 대해서는
98
+ 아무것도 증명하지 않는다. 레이아웃, 키보드, 안전 영역, 실제 햅틱은 앱이 있어야 확인할 수 있다.
99
+
100
+ ## 번들
101
+
102
+ 넘겨주는 것은 정적 파일 폴더 하나다. Vite에서는 `dist/`이다.
103
+
104
+ ```text
105
+ dist/
106
+ ├── index.html
107
+ ├── assets/
108
+ │ ├── index-3fa1c9.js
109
+ │ └── index-81b2d0.css
110
+ └── .well-known/
111
+ └── chatic-app.json
112
+ ```
113
+
114
+ - **`index.html`은 폴더 최상위에 있다.** `/`가 제공하는 것이 이 파일이다.
115
+ - **에셋은 루트 기준 주소로 참조된다** (`/assets/…`). Vite는 기본으로 이렇게 한다. 페이지는 항상 자기
116
+ 주소의 루트에서 제공되므로 `base` 경로를 설정하지 않는다.
117
+ - **`.well-known/chatic-app.json`은 페이지의 매니페스트다.** 앱은 페이지를 보여 주기 전에 이 파일을 읽는다.
118
+ Vite에서는 파일을 `public/.well-known/chatic-app.json`에 두면 빌드가 그대로 복사한다.
119
+ - **그 밖에는 아무것도 필요 없다**: 서버 코드도, `package.json`도, 소스 파일도 없다. 빌드가 없어도 구성은
120
+ 같다. `index.html`과 그 옆의 `.well-known/chatic-app.json`이다.
121
+
122
+ 매니페스트는 페이지의 이름을 정하고 필요한 것을 요청한다.
123
+
124
+ ```json
125
+ {
126
+ "manifestVersion": 1,
127
+ "name": "Quiz",
128
+ "permissions": ["share", "userKey"],
129
+ "orientation": "portrait"
130
+ }
131
+ ```
132
+
133
+ 페이지에는 기본적으로 바가 없다. 작은 닫기 버튼이 항상 오른쪽 위 모서리에 떠 있고, 페이지가 자기 헤더를
134
+ 직접 그린다(`"display": "clean"`). 대신 페이지 제목과 닫기 버튼이 있는 앱의 바를 쓰려면
135
+ `"display": "titled"`를 추가한다. 게임처럼 자기 화면을 화면 가장자리까지 그리는 페이지는
136
+ `"display": "immersive"`를 설정한다. 그러면 페이지가 상태 표시줄과 홈 인디케이터 아래에서 실행되며,
137
+ README의 레이아웃·Immersive 항목이 설명하는 inset으로 자기 컨트롤에 여백을 직접 준다.
138
+
139
+ `manifestVersion`은 `1`이어야 한다. 앱은 읽을 수 없는 매니페스트를 무시한다. 페이지가 쓰는 권한만
140
+ 요청한다 — `clipboard`, `share`, `openUrl`, `userKey`, 그리고 앱의 데이터를 읽기 위한 `session`,
141
+ `cloud`, `place`, `channel`, `chat`, `user` — 각 권한이 무엇을 열어 주는지, 그리고 `display`와
142
+ `orientation`에 대해서는 패키지 `README.md`를 본다. 매니페스트가 없어도 페이지는 실행되며, 그 권한들이
143
+ 열어 주는 것을 제외한 모든 것을 얻는다.
144
+
145
+ ## 앱 안에서 페이지가 동작하는 방식
146
+
147
+ 브라우저용으로 먼저 작성된 페이지에서 가장 자주 예상을 벗어나는 점들이다. 각각의 자세한 내용은 패키지
148
+ `README.md`에 있다.
149
+
150
+ - **앱은 언제든 페이지를 닫을 수 있다.** 진행하면서 저장하고, `document`가 `hidden`이 될 때도 저장한다.
151
+ 페이지 자체의 데이터는 시스템이 웹사이트 데이터를 지울 때 사라지는 `localStorage`가 아니라
152
+ `apps.storage`에 둔다. 다른 휴대폰으로 사용자를 따라가야 하는 것은 직접 운영하는 서버에 `apps.getUserKey()`로
153
+ 받은 키로 구분해 둔다.
154
+ - **페이지는 모든 가장자리에서 안전 영역 안에 놓인다.** 단, 매니페스트가 `immersive`를 요청한 경우는
155
+ 예외다. 처리할 inset이 없으며, `immersive` 페이지는 직접 처리한다 — CSS에서는
156
+ `--chatic-safe-area-inset-*` 속성으로, 스크립트에서는 `apps.context.safeArea`로. 오래된 앱은 후자를 보내지
157
+ 않으므로 그때는 CSS 속성으로 물러난다.
158
+ - **다크 모드는 휴대폰이 아니라 앱의 테마를 따른다.** `apps.context.theme`에서 가져온다.
159
+ - **페이지 주소가 아니라 `apps.link({ … })`를 공유한다.** 링크가 담은 것은 페이지가 시작할 때
160
+ `location.search`에서 읽는다.
161
+ - **매니페스트가 요청하지 않는 한 제목 바가 없으므로**, 페이지가 자기 헤더와 제목을 그린다.
162
+ [화면과 뒤로 가기](#화면과-뒤로-가기)를 본다.
163
+ - **Android 뒤로 가기**는 `apps.onBack(handler)`를 설정해 둔 동안에만 페이지의 것이다. 그렇지 않으면 앱이
164
+ 결정한다.
165
+ - **오류**: 모든 호출은 `ChaticAppsError`를 던질 수 있다. `message`가 아니라 `code`로 분기한다.
166
+
167
+ ## 화면과 뒤로 가기
168
+
169
+ 메뉴, 게임, 설정 페이지처럼 화면이 둘 이상인 페이지는 자기만의 뒤로 가는 방법이 필요하다. 기댈 바도
170
+ 뒤로 가기 화살표도 없다. 앱이 주는 유일한 컨트롤은 오른쪽 위 모서리의 작은 닫기 버튼이며, 이것은 페이지를
171
+ 떠난다. Android에는 뒤로 가기 키가 있고 iOS에는 없다. 그래서 페이지는 자기 화면의 스택을 유지하고, 자기
172
+ 뒤로 가기 버튼을 그리며, 돌아갈 화면이 있는 동안에만 Android 뒤로 가기 키를 가져간다.
173
+
174
+ ```ts
175
+ const screens = ['home'];
176
+
177
+ // Take Android back while a screen is stacked; give it back at the root, where the app closes the page.
178
+ const sync = () => apps.onBack(screens.length > 1 ? back : null);
179
+
180
+ function open(name: string) {
181
+ screens.push(name);
182
+ sync();
183
+ render();
184
+ }
185
+
186
+ function back() {
187
+ if (screens.length > 1) screens.pop();
188
+ sync();
189
+ render();
190
+ }
191
+
192
+ sync();
193
+ ```
194
+
195
+ `screens.length > 1`일 때마다 헤더에 뒤로 가기 버튼을 그리고 `back()`을 호출하게 한다. 루트에서는 닫기
196
+ 버튼이 이미 있으므로 아무것도 그리지 않는다. React, Vue, Svelte에서는 `screens`를 상태로 두고, 그 길이가
197
+ 바뀔 때 실행되는 effect에서 `apps.onBack`을 호출한다. 같은 패턴으로 대화상자도 닫는다. 열린 대화상자를
198
+ 하나의 화면으로 취급한다.
199
+
200
+ 건드리지 말아야 할 세 가지가 있다. 루트에서는 핸들러를 설정하지 않아 Android 뒤로 가기가 여전히 페이지를
201
+ 닫게 한다. 탐색에 `onCloseRequest`를 쓰지 않는다 — 그것은 저장하지 않은 작업을 위한 것이다. 그리고 화면은
202
+ 브라우저의 히스토리가 아니라 메모리에 둔다. 항목을 push하는 라우터(해시 라우트, `pushState`)는 페이지에
203
+ 히스토리를 만들고, 히스토리가 있으면 루트에서 Android 뒤로 가기가 페이지를 닫는 대신 그 히스토리를
204
+ 거슬러 간다. iOS에서는 가장자리 스와이프가 그 히스토리만 거슬러 가므로, 메모리 내 스택에는 어느 경우든
205
+ 위의 뒤로 가기 버튼이 필요하다.
206
+
207
+ 모든 화면의 오른쪽 위 모서리에는 자기 컨트롤을 두지 않는다. 닫기 버튼이 그곳에 떠 있다.
208
+
209
+ ## 클라우드의 데이터를 쓰는 페이지
210
+
211
+ 클라우드에서 열린 페이지는 `apps.data`로 그 클라우드 — 플레이스, 채팅방, 메시지, 멤버 — 를 읽을 수 있고,
212
+ 텍스트 메시지를 보낼 수 있다. 모든 메서드와 그 인자, 응답하는 행은 패키지 `README.md`에 나열되어 있다.
213
+ 여기서는 그것들을 중심으로 페이지를 만드는 방법을 다룬다.
214
+
215
+ **페이지가 보여 주는 것에 따라 권한을 고른다.** `session`, `cloud`, `place`, `channel`, `chat`, `user`는
216
+ 각각 한 묶음의 읽기를 열고, `chatSend`는 보내기를, `chatReact`는 메시지에 반응 달기를 연다. 앱은 읽기가 응답하는 내용을 걸러내지 않는다.
217
+ `user`, `channel`, `chat`이 있는 페이지는 사용자의 로그인 id를 받고, `place`가 있는 페이지는 계정 서버가
218
+ 가진 그대로 각 플레이스의 소유자를 받으며, `cloud`가 있는 페이지는 클라우드의 계정 정보를 받는다. 일을
219
+ 해내는 데 필요한 최소한만 요청하고 — 읽은 것으로 페이지가 무엇을 하는지는 작성자의 책임이다 — 사용자에게
220
+ 알리지 않고는 그 어떤 것도 기기 밖으로 보내지 않는다.
221
+
222
+ ```json
223
+ { "manifestVersion": 1, "name": "Room stats", "permissions": ["session", "channel", "chat"] }
224
+ ```
225
+
226
+ **사용자를 기다린다.** `apps.data.connect()`에서 앱은 이 페이지가 이 클라우드를 읽어도 되는지 사용자에게
227
+ 묻고, 사용자가 걸리는 만큼 기다린다. 페이지 자체의 틀을 먼저 보여 주고, 그다음 연결한다.
228
+ 거부는 `CONSENT_REFUSED`다. 페이지가 왜 그 데이터가 필요한지 말하고 닫기를 제안한다.
229
+
230
+ ```ts
231
+ const apps = await connect();
232
+ if (!apps.supports('data')) return showNotAvailableHere(); // a browser, the desktop, an old Android WebView, an older app
233
+ try {
234
+ await apps.data.connect();
235
+ } catch (error) {
236
+ if (error instanceof ChaticAppsError && error.code === 'CONSENT_REFUSED') return showWhyWeAsk();
237
+ throw error;
238
+ }
239
+ const session = apps.data.session(); // CloudSession | null — null without `session`
240
+ const placeId = session?.committedSiteId ?? undefined; // undefined without `session`
241
+ ```
242
+
243
+ **타입과 함께 읽는다.** 앱이 여는 모든 메서드에는 타입이 있으므로, 에디터가 이름을 자동 완성하고 잘못된
244
+ 인자는 빌드를 실패시킨다. 행은 대부분 선택적 필드다. 각 필드를 대체값과 함께 읽는다.
245
+
246
+ ```ts
247
+ const rooms = await apps.data.call('channel.cacheReadList', { sid: placeId });
248
+ for (const room of rooms?.list ?? []) console.log(room.name ?? '(no name)', room.unreadCount ?? 0);
249
+ ```
250
+
251
+ **스트림에는 한도가 있다.** 한 페이지는 페이지 로드당 최대 16개를 가지며, 그다음 `subscribe`는 `INVALID`로
252
+ 실패한다. 화면에 있는 것을 구독하고, 화면에서 사라지면 `stop()`하며, 보여 주는 행만 보관한다 — 이벤트 하나가
253
+ 목록 전체를 담을 수 있다.
254
+
255
+ **페이지가 열려 있는 동안 클라우드가 바뀔 수 있다.** 사용자가 다른 클라우드로 옮기면 모든 스트림이
256
+ `CLOUD_CHANGED`로 끝나고, `onCloudChanged`가 한 번 발생하며, 그 뒤로는 아무것도 응답하지 않는다. 페이지를
257
+ 끝내거나 안내를 보여준다. 재시도하지 않는다.
258
+
259
+ ```ts
260
+ apps.data.onCloudChanged(() => apps.finish());
261
+ ```
262
+
263
+ **사용자가 보내기로 고른 것만 보낸다.** `apps.data.sendMessage(roomId, text)`는 사용자의 이름으로, 페이지가
264
+ 열린 플레이스의 채팅방에 메시지를 보낸다. 사용자가 직접 탭했을 때, 사용자가 본 텍스트를 보낸다. `chatReact`의
265
+ `apps.data.react(messageId, emoji, on)`도 같다: 사용자의 이름으로 반응을 달거나 뗀다 — 떼기는 그 이모지로 단
266
+ 사용자의 반응을, 사용자가 직접 단 것이라도 뗀다 — 그러니 사용자가 탭했을 때만 반응한다. 반응은 250 ms에 한 번,
267
+ 1분에 60번까지다.
268
+
269
+ **mock을 대상으로 개발한다.** mock은 주어진 데이터로 응답하며, 앱과 같은 맵으로 타입이 지정되어 있으므로
270
+ 모양이 잘못된 응답은 앱에서 실패하기 전에 빌드에서 실패한다.
271
+
272
+ ```ts
273
+ import { installChaticAppsMock } from '@lemoncloud/chatic-apps-sdk/mock';
274
+
275
+ const app = installChaticAppsMock({
276
+ permissions: ['session', 'channel', 'chatSend'],
277
+ data: {
278
+ session: {
279
+ context: {
280
+ cloud: { cloudId: 'cloud-1', siteId: 'place-1', isActive: true },
281
+ identity: { userId: 'user-1', isAuthenticated: true },
282
+ },
283
+ committedSiteId: 'place-1',
284
+ },
285
+ calls: {
286
+ 'channel.cacheReadList': () => ({
287
+ list: [{ id: 'room-1', cid: 'cloud-1', sid: 'place-1', isNotificationEnabled: true, name: 'Lobby' }],
288
+ meta: { total: 1 },
289
+ }),
290
+ },
291
+ },
292
+ });
293
+ // later: app.sentMessages, app.changeCloud()
294
+ ```
295
+
296
+ mock에는 실제 클라우드의 것이 아니라 지어낸 id와 이름을 쓴다. mock은 앱이 어떤 권한에 어떤 메서드를 여는지
297
+ 알지 못한다 — 주어진 것을 응답할 뿐이다 — 그러므로 앱에서 `connect()`의 `allowed`를 확인한다.
298
+
299
+ ## 직접 운영하는 서버
300
+
301
+ 페이지는 정적 파일이고 계속 그래야 한다. 서버 렌더링도, 서버 라우팅도 없다. 점수, 저장한 작업, 사용자끼리
302
+ 나누는 것처럼 자기 서버가 필요하면, 그 서버는 자기 origin에 있는 API이고 페이지는 `fetch`로 그것을 부른다.
303
+
304
+ **페이지의 origin을 허용한다.** 페이지에서 보내는 호출은 `https://<name>.apps.chatic.io`에서 오는 평범한
305
+ cross-origin 요청이다. 그래서 서버는 그 origin을 지정한 CORS 헤더로 응답하고, JSON `POST`가 먼저 보내는
306
+ preflight에도 응답한다:
307
+
308
+ ```http
309
+ Access-Control-Allow-Origin: https://<name>.apps.chatic.io
310
+ Access-Control-Allow-Methods: GET, POST, OPTIONS
311
+ Access-Control-Allow-Headers: Content-Type
312
+ Vary: Origin
313
+ ```
314
+
315
+ 시험하는 동안에는 개발용 주소도 허용하고(다음 절 참고), 페이지가 공개된 뒤에는 `*`를 쓰지 않는다.
316
+
317
+ **사용자는 사용자 키로 구분하되, 그 키에 다른 것을 기대하지 않는다.** `apps.getUserKey()`(`userKey` 권한)는
318
+ 한 기기와 이 사이트에 대해 늘 같은 64자리 16진수를 돌려준다. 요청마다 이것을 보내고, 서버에서는 사용자의
319
+ 데이터를 이 키로 구분해 둔다. 이것은 로그인이 아니다. 한 휴대폰을 쓰는 두 사람은 같은 키를 공유하고, 키를
320
+ 알게 된 사람은 누구나 그것을 보낼 수 있다. 게임 진행은 이 키로 보관해도 되지만 돈, 구매, 다른 사용자에게서
321
+ 빼앗을 수 있는 것은 두지 않는다. 그런 것이 필요하면 리다이렉트 방식의 자체 로그인을 붙인다. 앱에서는 팝업
322
+ 로그인이 동작하지 않는다(`window.open`은 같은 뷰에 로드되고, `window.opener`로는 아무것도 응답하지 않는다).
323
+
324
+ **페이지가 보내는 것은 아무것도 믿지 않는다.** 페이지는 사용자의 기기에서 돌고, 누구나 아무 본문, 아무 사용자
325
+ 키, 아무 `params`로 API를 직접 부를 수 있다. 서버에서 모든 값을 공개 웹의 폼을 다루듯 검사한다.
326
+ `MiniAppLaunchParams`는 누가 보고 있는지를 알려 줄 뿐 아무것도 증명하지 않는다.
327
+
328
+ **클라우드에서 읽은 것이 기기를 떠나면 그 책임은 작성자에게 있다.** 사용자는 페이지가 `apps.data`로 클라우드를
329
+ 읽도록 허락했을 뿐, 다른 곳으로 보내도록 허락하지 않았다. 페이지가 멤버의 이름이나 메시지를 자기 서버로
330
+ 보낸다면, 보내기 전에 페이지에서 그렇다고 알리고, 기능에 필요한 것만 보내며, 필요한 기간보다 오래 보관하지
331
+ 않는다.
332
+
333
+ ## 앱 안에서 시험하기
334
+
335
+ mock을 쓴 브라우저는 페이지의 로직을 증명할 뿐이고, 레이아웃, 키보드, 실제 햅틱은 앱에서만 볼 수 있다. 작업
336
+ 중인 페이지를 배포하기 전에 앱에서 열려면, 개발 서버에 https 주소를 주고 직접 소유한 클라우드에 미니앱으로
337
+ 추가한다.
338
+
339
+ 1. 개발 서버를 실행하고, 터널로 https 주소에 노출한다. `cloudflared`는 이 용도로 계정이 필요 없다:
340
+
341
+ ```bash
342
+ npm run dev # Vite, on http://localhost:5173
343
+ cloudflared tunnel --url http://localhost:5173 # prints https://<random words>.trycloudflare.com
344
+ ```
345
+
346
+ Vite는 모르는 호스트를 거부하므로 터널의 호스트를 허용한다:
347
+
348
+ ```ts
349
+ // vite.config.ts
350
+ export default defineConfig({ server: { allowedHosts: ['.trycloudflare.com'] } });
351
+ ```
352
+
353
+ 2. 휴대폰의 DoU 앱에서 직접 소유한 클라우드를 고른 상태로 **MY → 설정 → Lab → Mini apps**로 가서 **Add mini
354
+ app**을 누르고, 이름과 그 주소(`https://…`, 포트 없이)를 넣는다. 이 목록은 그 휴대폰에만 저장된다. 그다음
355
+ **Open mini apps**를 눌러 미니앱 홈에서 그것을 고른다. 처음 열 때 DoU는 내 이름, 클라우드 안에서의 내 id,
356
+ 클라우드, 열려 있는 플레이스를 페이지에 넘기기 전에 묻는다.
357
+ 3. 터널의 주소는 시작할 때마다 바뀐다. 같은 목록에서 그 미니앱을 눌러 주소를 고친다.
358
+
359
+ 터널의 주소는 터널이 떠 있는 동안만 유효하다. 고정된 주소가 필요하면 빌드를 https를 주는 아무 정적 호스팅(Vercel,
360
+ Netlify 같은 곳의 미리보기 배포)에 올리고 그 주소를 대신 추가한다. 똑같이 열리고 아래의 한계도 같지만, 고칠
361
+ 때마다 다시 배포해야 한다.
362
+
363
+ 이렇게 연 페이지는 심사를 거친 페이지가 아니라 외부 사이트로 열리고, `apps.chatic.io`에 배포된 뒤보다 받는
364
+ 것이 적다:
365
+
366
+ - **기본 요청만.** 닫기, 햅틱, Android 뒤로 가기, 닫기 가드, 오류 보고, 저장소, 카메라와 마이크 권한은
367
+ 동작한다. `setTitle`은 응답하지만 바에는 계속 호스트가 표시된다. `getUserKey`, `copy`, `share`, `openUrl`은 `NOT_SUPPORTED`로 실패한다. 데스크톱 앱은 이보다도
368
+ 적게, 닫기, 제목, 오류 보고에만 응답한다.
369
+ - **매니페스트 없음.** 앱은 페이지의 `/.well-known/chatic-app.json`을 읽지 않는다. 바는 늘 표시되고 터널의
370
+ 호스트가 제목이 되며, `display`와 `orientation`은 적용되지 않는다.
371
+ - **클라우드 데이터 없음.** `apps.supports('data')`가 `false`이므로 이 방법으로는 `apps.data`를 앱에서 시험할
372
+ 수 없다. mock으로 만들고, 페이지가 심사를 거친 뒤 앱에서 확인한다.
373
+ - **저장소가 따로다.** 저장소는 origin마다 따로 보관되므로, 여기서 저장한 것은 실제 주소에서 찾을 수 없다.
374
+
375
+ ## 프로젝트의 AI 어시스턴트를 위해
376
+
377
+ 패키지는 `AGENTS.md`를 함께 제공한다. Chatic 앱을 작성하는 AI 어시스턴트를 위한 규칙이다. AI 어시스턴트는
378
+ `node_modules` 안의 것이 아니라 프로젝트 최상위의 `AGENTS.md`를 읽으므로, 그곳으로 복사하거나 AI 어시스턴트가
379
+ `node_modules/@lemoncloud/chatic-apps-sdk/AGENTS.md`를 보게 한다.
380
+
381
+ 0.3.0부터는 스킬도 함께 제공한다. `skill/SKILL.md`(한국어판 `skill/SKILL.ko.md`)는 웹 페이지를 한 번도 만들어 보지 않은 사람을
382
+ 한 번에 하나씩 묻는 질문으로 아이디어에서 검증기를 통과한 zip까지 이끄는 절차다. 세 단계 — 아이디어, 초기 구축,
383
+ 배포 준비 — 로 나아가고, 계획과 진행 상황을 프로젝트 최상위의 `MINIAPP.md`에 남겨 다른 날의 대화가 멈춘 곳에서
384
+ 이어 간다. 프로젝트의 파일만 고치고, 시작 패키지를 묻고 나서 한 번 설치하고, 프로젝트의 스크립트만 돌린다.
385
+ 무엇도 업로드하거나 제출하지 않는다.
386
+
387
+ 쓰려면 `skill` 폴더를 AI 어시스턴트가 스킬을 읽는 곳에 두거나, `SKILL.md`를 주고 따르라고 한다. 이미 패키지를
388
+ 설치한 프로젝트라면 `node_modules`에서 복사하고, 빈 폴더라면 설치할 배포 버전의 파일을 받는다.
389
+
390
+ ```bash
391
+ cp -R node_modules/@lemoncloud/chatic-apps-sdk/skill ./chatic-app-skill
392
+ curl -fsSLO https://unpkg.com/@lemoncloud/chatic-apps-sdk@0.3.0/skill/SKILL.md
393
+ ```
394
+
395
+ 스킬의 첫 설치에는 npm에 SDK 0.3.0과 `@lemoncloud/chatic-apps-devtools`가 있어야 한다. 둘 다 배포되기 전에는 위
396
+ 명령도, 그 설치도 되지 않는다. 그다음 AI 어시스턴트에게 원하는 것을 말한다 — "퀴즈 미니앱 만들어줘"면 시작하기에
397
+ 충분하다. 사본은 패키지와 함께
398
+ 갱신되지 않는다. 스킬은 자기가 맞춰 쓴 SDK 버전을 적어 두고, 설치된 것과 다르면 알린다.
399
+
400
+ ## 넘겨주기 전에
401
+
402
+ - [ ] `npm run build`가 최상위에 `index.html`과 `.well-known/chatic-app.json`이 있는 `dist/`를 만든다.
403
+ - [ ] `@lemoncloud/chatic-apps-devtools`가 배포된 뒤: `npx @lemoncloud/chatic-apps-devtools verify`(또는 프로젝트의 `npm run verify`)가 "넘길 준비가 됐습니다"로
404
+ 끝난다.
405
+ - [ ] 일반 파일 서버에서 열었을 때, 빌드된 페이지가 주소에 경로 없이 루트에서 동작한다.
406
+ - [ ] 페이지가 앱 없는 브라우저(`apps.inApp`이 `false`)와 대역 양쪽에서 동작한다.
407
+ - [ ] 매니페스트의 모든 권한이 쓰이고, 권한이 필요한 모든 호출이 `apps.supports(…)`로 보호되거나
408
+ `NOT_SUPPORTED`를 처리한다.
409
+ - [ ] 상태가 버튼을 누를 때만이 아니라 사용자가 진행하는 동안 저장된다.
410
+ - [ ] `window.opener`, 팝업 로그인, 파일 다운로드, 서버 사이드 렌더링이 없다.
411
+ - [ ] 오류, `reportError`, 페이지 자체의 로그에 사용자 데이터가 없다.
412
+ - [ ] 자기 서버를 부르는 페이지: 서버가 페이지의 origin을 허용하고, 받는 모든 값을 검사하며, 사용자 키
413
+ 하나에만 기대어 가치 있는 것을 두지 않는다.
414
+ - [ ] 클라우드를 읽는 페이지: 쓰는 클라우드 데이터 권한만 요청하고, `CONSENT_REFUSED`와 `CLOUD_CHANGED`를
415
+ 처리하며, 더 이상 보여 주지 않는 모든 스트림을 멈춘다.
416
+
417
+ ## 배포하기
418
+
419
+ 페이지를 제출하고 심사받고 주소에 배포하는 방법은 아직 이 가이드에 포함되어 있지 않다.