@underdogai/mesh-event-schemas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Underdog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @underdogai/mesh-event-schemas
+
+[`@underdogai/mesh-app-sdk`](https://www.npmjs.com/package/@underdogai/mesh-app-sdk) 가 주고받는 **Matrix 이벤트와 UI 데이터의 스키마**(zod). 카드·서피스가 와이어에서 어떤 모양이어야 하는지를 정의하는 단일 진실 공급원이다.
+
+```bash
+npm i @underdogai/mesh-event-schemas
+```
+
+보통은 직접 설치하지 않는다 — `@underdogai/mesh-app-sdk` 를 설치하면 함께 딸려온다. 이벤트 타입 상수나 스키마를 직접 다룰 때만 명시적으로 import 한다.
+
+## 구성
+
+| 파일 | 내용 |
+|---|---|
+| `namespace.ts` | `NS=org.corp`, `EventType.*` 상수, `UI_CONTENT_KEY` |
+| `blocks.ts` | UI Blocks 데이터 스키마 (text/heading/fields/input/select/button/actions …) — 닫힌 집합이라 앱이 새 블록을 만들 수 없다(안전 속성) |
+| `events.ts` | 이벤트 content 스키마 + 빌더 (`buildUiMessageContent`, `buildUiActionContent`, `extractUiCard` …) |
+| `surfaces.ts` | 방에 머무는 화면 — 패널·헤더·컴포저·커맨드 팔레트·도크·모달 스펙 |
+| `registry.ts` | 스키마 레지스트리 — `validateEvent(type, content)`, `canPublish(type, publisher)` |
+
+## 핵심 이벤트 타입
+
+| 타입 | 종류 | 방향 |
+|---|---|---|
+| `m.room.message` + `org.corp.ui` 키 | message | 앱 → 사용자 (타임라인 카드) |
+| `org.corp.ui.action` | message | 사용자·앱 → 앱 (버튼·폼 제출·앱 간 호출) |
+| `org.corp.app.surface` | state | 앱 → 방 (패널·컴포저·⌘K 등 머무는 화면) |
+| `org.corp.workflow.state` | state | 엔티티 진행 상태 |
+| `org.corp.agent.capability` | state | 에이전트 역량 |
+
+## 사용 예
+
+```ts
+import { EventType, buildUiMessageContent, validateEvent } from "@underdogai/mesh-event-schemas";
+
+const content = buildUiMessageContent({
+  card_id: "approve-inv-1023",
+  title: "Approval needed",
+  fallback: "Invoice INV-1023 needs approval",   // 미지원 클라이언트가 보는 평문 — 필수
+  blocks: [
+    { type: "fields", items: [{ label: "Invoice", value: "INV-1023" }, { label: "Amount", value: "$1,200" }] },
+    { type: "actions", elements: [
+      { type: "button", action_id: "finance.approve", text: "Approve", style: "primary" },
+      { type: "button", action_id: "finance.reject", text: "Reject", style: "danger" },
+    ]},
+  ],
+});
+// → client.sendEvent(roomId, "m.room.message", content)
+
+const v = validateEvent(EventType.UiAction, incoming);
+if (v.ok) { /* v.data 사용 */ }
+```
+
+보낼 때는 엄격하게 검증하고, 받을 때는 관대하다 — 모르는 블록은 버리고 나머지를 그린다(버전이 다른 클라이언트끼리도 카드가 통째로 깨지지 않는다).
+
+## 문서
+
+**https://chatops.theunderdog.ai/sdk-guide**
+
+## 라이선스
+
+MIT