Preparing Ring content
Preparing Ring content
Preparing Ring content
Використовуйте вкладки Founder / Developer у бічній панелі документації, щоб фільтрувати цю сторінку. Ця стаття є SSOT для Conversation.type (канал) проти metadata.kind (підтип) і гігієни скриньки для чатів інструментів.
Повідомлення Ring поєднують REST-розмови з розсилкою через Tunnel Protocol, тож учасники спілкуються в контексті можливостей, організацій і угод магазину без оновлення сторінки.
| Рівень | Де |
|---|---|
| REST | app/api/conversations/** |
| Реальний час | Канали Tunnel conversation:{id}, див. Tunnel Protocol |
| UI | features/chat, features/messages; глибокі посилання /messages?c=<conversationId> (аліас ?conversation=) і /messages?user=<userId> (messages-shell.tsx) |
| Типи | features/chat/types/index.ts |
| Довідник API | Messaging API |
Ring не вигадує новий тип розмови верхнього рівня для кожної функції. Два рівні лишаються окремими:
| Поле | Значення | Приклад |
|---|---|---|
Conversation.type | Канал / маршрутизація домену: де гілка живе в системі повідомлень | direct, entity, opportunity, product, group |
metadata.kind | Необов'язковий підтип у цьому каналі | generative_gallery |
metadata.hiddenFromInbox | Контракт скриньки: приховати зі списку Messages | true для редакторів-інструментів |
Перевірений enum каналів (TypeScript + zod створення в app/api/conversations/route.ts):
direct | entity | opportunity | product | group
Не додавайте type: 'generative'. Generative Gallery повторно використовує type: 'product' плюс kind: 'generative_gallery' і hiddenFromInbox: true. Розширення enum каналів заради однієї функції ламає помічники пошуку товарів і створює паралельну інфраструктуру.
Той самий канал product, різна видимість:
| Використання | type | Ключові метадані | Скринька Messages |
|---|---|---|---|
| Агент товару магазину (DAGI) | product | справжній productId, без kind інструмента | Видимий |
| Чат інструмента Generative Gallery | product | kind: 'generative_gallery', hiddenFromInbox: true, productId/subject = genmedia:… | Прихований |
metadata.kind розмови це не той самий простір імен, що metadata.kind повідомлення (напр. payment_request, env_request, task, poll, rsvp, dao_jar, share_card, gallery_upload, ghost_write_result, game_request).
Інтерактивні типи мають спільний набір життєвого циклу (features/chat/lib/interactive-kind.ts + реєстр бульбашок + помічник сповіщень): створення через server action → віджет із подвійною перевіркою (type АБО metadata.kind) → updateMessage / тунель message:update → типізоване сповіщення. Домен відповідає за гроші для dao_jar через public-pools: внесок нативним токеном скарбниці (contributeToPool) і карткою/PayPal (public_pool_contribution → курс desk-oracle). Чат відповідає за знімок: завжди викликайте refreshOpenDaoJarMessages після зміни сум. share_card повторно використовує MESSAGE_RECEIVED + data.kind. Інтерактивний UX рівня A виправлено (2026-07-21); див. Public Pools & DAO Jars.
Peer games додають game_request (у allowlist в interactive-kind.ts): SSOT сесії в PeerGameService.createInvite, Tunnel game:invite / games:incoming (включно з фінальним очищенням) і IncomingGameBanner у Messages + /games. Ігри: хрестики-нулики · шахи · шашки. Лише прямі розмови. Див. Peer Games.
Структурована робота всередині гілки: Ring Tasks (type: 'task' + дерево /tasks).
Миттєва розмова скорочує шлях від збігу → довіри → угоди. Учасники лишаються у вашому Ring, а не йдуть в email чи сторонні чати. Редактори-інструменти (історія генерації зображень) не потрапляють у головну скриньку, тож операторів не засипає системними гілками.
Той самий процес: Contact відкриває /messages?user=<createdBy>; From chat власника використовує /messages?c=.
Залежить від: живі оновлення повідомлень і банок публікуються в тунельних каналах розмов.
Той самий процес: гроші dao_jar, внески у двох валютах і оновлення банки після внеску.
Дивіться також: чати інструментів у каналі product приховані зі скриньки Messages.
Використовуйте вкладки Founder / Developer у бічній панелі документації, щоб фільтрувати цю сторінку. Ця стаття є SSOT для Conversation.type (канал) проти metadata.kind (підтип) і гігієни скриньки для чатів інструментів.
Повідомлення Ring поєднують REST-розмови з розсилкою через Tunnel Protocol, тож учасники спілкуються в контексті можливостей, організацій і угод магазину без оновлення сторінки.
| Рівень | Де |
|---|---|
| REST | app/api/conversations/** |
| Реальний час | Канали Tunnel conversation:{id}, див. Tunnel Protocol |
| UI | features/chat, features/messages; глибокі посилання /messages?c=<conversationId> (аліас ?conversation=) і /messages?user=<userId> (messages-shell.tsx) |
| Типи | features/chat/types/index.ts |
| Довідник API | Messaging API |
Ring не вигадує новий тип розмови верхнього рівня для кожної функції. Два рівні лишаються окремими:
| Поле | Значення | Приклад |
|---|---|---|
Conversation.type | Канал / маршрутизація домену: де гілка живе в системі повідомлень | direct, entity, opportunity, product, group |
metadata.kind | Необов'язковий підтип у цьому каналі | generative_gallery |
metadata.hiddenFromInbox | Контракт скриньки: приховати зі списку Messages | true для редакторів-інструментів |
Перевірений enum каналів (TypeScript + zod створення в app/api/conversations/route.ts):
direct | entity | opportunity | product | group
Не додавайте type: 'generative'. Generative Gallery повторно використовує type: 'product' плюс kind: 'generative_gallery' і hiddenFromInbox: true. Розширення enum каналів заради однієї функції ламає помічники пошуку товарів і створює паралельну інфраструктуру.
Той самий канал product, різна видимість:
| Використання | type | Ключові метадані | Скринька Messages |
|---|---|---|---|
| Агент товару магазину (DAGI) | product | справжній productId, без kind інструмента | Видимий |
| Чат інструмента Generative Gallery | product | kind: 'generative_gallery', hiddenFromInbox: true, productId/subject = genmedia:… | Прихований |
metadata.kind розмови це не той самий простір імен, що metadata.kind повідомлення (напр. payment_request, env_request, task, poll, rsvp, dao_jar, share_card, gallery_upload, ghost_write_result, game_request).
Інтерактивні типи мають спільний набір життєвого циклу (features/chat/lib/interactive-kind.ts + реєстр бульбашок + помічник сповіщень): створення через server action → віджет із подвійною перевіркою (type АБО metadata.kind) → updateMessage / тунель message:update → типізоване сповіщення. Домен відповідає за гроші для dao_jar через public-pools: внесок нативним токеном скарбниці (contributeToPool) і карткою/PayPal (public_pool_contribution → курс desk-oracle). Чат відповідає за знімок: завжди викликайте refreshOpenDaoJarMessages після зміни сум. share_card повторно використовує MESSAGE_RECEIVED + data.kind. Інтерактивний UX рівня A виправлено (2026-07-21); див. Public Pools & DAO Jars.
Peer games додають game_request (у allowlist в interactive-kind.ts): SSOT сесії в PeerGameService.createInvite, Tunnel game:invite / games:incoming (включно з фінальним очищенням) і IncomingGameBanner у Messages + /games. Ігри: хрестики-нулики · шахи · шашки. Лише прямі розмови. Див. Peer Games.
Структурована робота всередині гілки: Ring Tasks (type: 'task' + дерево /tasks).
Миттєва розмова скорочує шлях від збігу → довіри → угоди. Учасники лишаються у вашому Ring, а не йдуть в email чи сторонні чати. Редактори-інструменти (історія генерації зображень) не потрапляють у головну скриньку, тож операторів не засипає системними гілками.
Той самий процес: Contact відкриває /messages?user=<createdBy>; From chat власника використовує /messages?c=.
Залежить від: живі оновлення повідомлень і банок публікуються в тунельних каналах розмов.
Той самий процес: гроші dao_jar, внески у двох валютах і оновлення банки після внеску.
Дивіться також: чати інструментів у каналі product приховані зі скриньки Messages.
Використовуйте вкладки Founder / Developer у бічній панелі документації, щоб фільтрувати цю сторінку. Ця стаття є SSOT для Conversation.type (канал) проти metadata.kind (підтип) і гігієни скриньки для чатів інструментів.
Повідомлення Ring поєднують REST-розмови з розсилкою через Tunnel Protocol, тож учасники спілкуються в контексті можливостей, організацій і угод магазину без оновлення сторінки.
| Рівень | Де |
|---|---|
| REST | app/api/conversations/** |
| Реальний час | Канали Tunnel conversation:{id}, див. Tunnel Protocol |
| UI | features/chat, features/messages; глибокі посилання /messages?c=<conversationId> (аліас ?conversation=) і /messages?user=<userId> (messages-shell.tsx) |
| Типи | features/chat/types/index.ts |
| Довідник API | Messaging API |
Ring не вигадує новий тип розмови верхнього рівня для кожної функції. Два рівні лишаються окремими:
| Поле | Значення | Приклад |
|---|---|---|
Conversation.type | Канал / маршрутизація домену: де гілка живе в системі повідомлень | direct, entity, opportunity, product, group |
metadata.kind | Необов'язковий підтип у цьому каналі | generative_gallery |
metadata.hiddenFromInbox | Контракт скриньки: приховати зі списку Messages | true для редакторів-інструментів |
Перевірений enum каналів (TypeScript + zod створення в app/api/conversations/route.ts):
direct | entity | opportunity | product | group
Не додавайте type: 'generative'. Generative Gallery повторно використовує type: 'product' плюс kind: 'generative_gallery' і hiddenFromInbox: true. Розширення enum каналів заради однієї функції ламає помічники пошуку товарів і створює паралельну інфраструктуру.
Той самий канал product, різна видимість:
| Використання | type | Ключові метадані | Скринька Messages |
|---|---|---|---|
| Агент товару магазину (DAGI) | product | справжній productId, без kind інструмента | Видимий |
| Чат інструмента Generative Gallery | product | kind: 'generative_gallery', hiddenFromInbox: true, productId/subject = genmedia:… | Прихований |
metadata.kind розмови це не той самий простір імен, що metadata.kind повідомлення (напр. payment_request, env_request, task, poll, rsvp, dao_jar, share_card, gallery_upload, ghost_write_result, game_request).
Інтерактивні типи мають спільний набір життєвого циклу (features/chat/lib/interactive-kind.ts + реєстр бульбашок + помічник сповіщень): створення через server action → віджет із подвійною перевіркою (type АБО metadata.kind) → updateMessage / тунель message:update → типізоване сповіщення. Домен відповідає за гроші для dao_jar через public-pools: внесок нативним токеном скарбниці (contributeToPool) і карткою/PayPal (public_pool_contribution → курс desk-oracle). Чат відповідає за знімок: завжди викликайте refreshOpenDaoJarMessages після зміни сум. share_card повторно використовує MESSAGE_RECEIVED + data.kind. Інтерактивний UX рівня A виправлено (2026-07-21); див. Public Pools & DAO Jars.
Peer games додають game_request (у allowlist в interactive-kind.ts): SSOT сесії в PeerGameService.createInvite, Tunnel game:invite / games:incoming (включно з фінальним очищенням) і IncomingGameBanner у Messages + /games. Ігри: хрестики-нулики · шахи · шашки. Лише прямі розмови. Див. Peer Games.
Структурована робота всередині гілки: Ring Tasks (type: 'task' + дерево /tasks).
Миттєва розмова скорочує шлях від збігу → довіри → угоди. Учасники лишаються у вашому Ring, а не йдуть в email чи сторонні чати. Редактори-інструменти (історія генерації зображень) не потрапляють у головну скриньку, тож операторів не засипає системними гілками.
Той самий процес: Contact відкриває /messages?user=<createdBy>; From chat власника використовує /messages?c=.
Залежить від: живі оновлення повідомлень і банок публікуються в тунельних каналах розмов.
Той самий процес: гроші dao_jar, внески у двох валютах і оновлення банки після внеску.
Дивіться також: чати інструментів у каналі product приховані зі скриньки Messages.
Контракти для інтеграторів щодо розмов і індикатора набору.
/api/mcp/v1/messaging/conversations| Інструменти агентів |
Після записів публікуйте в канал Tunnel conversation:{id} через publishToChannel; клієнти підписуються через useTunnelChannel (а не сирий useTunnel().subscribe() в ефектах).
type у тілі створення має бути одним із: direct | entity | opportunity | product | group (z.enum в app/api/conversations/route.ts). Необов'язкові метадані включають productId, groupName, kind, hiddenFromInbox і id доменів (entityId, opportunityId, …).
ConversationService.getConversations пропускає рядки, де isHiddenToolConversation дорівнює true (features/chat/services/conversation-service.ts):
metadata.hiddenFromInbox === true (бажане довгострокове обмеження)metadata.kind === 'generative_gallery'productId або subject починається з genmedia: чи imggen:Окремо гілки product пропускаються, якщо не виконано metadata.buyerEngaged === true і глядач не надіслав у них жодного повідомлення. Сторінки товарів створюють гілку лише коли покупець пише (див. Store).
| Шлях | Відповідальність |
|---|---|
features/chat/types/index.ts | Conversation, CreateConversationRequest, фільтри |
features/chat/services/conversation-service.ts | CRUD + isHiddenToolConversation |
features/chat/, features/messages/ | UI чату |
features/generative-media/service.ts | Створює приховані чати product + generative_gallery |
features/store/services/product-agent-service.ts | Створює агентські чати product при першому повідомленні покупця; findExistingConversation лише шукає |
lib/tunnel/ | Хаб, публікатор, транспорти |
hooks/use-tunnel-channel.ts | Стабільна підписка на канал |
/api/tunnel/ws/api/tunnel/poll)Повні приклади ендпоінтів: Messaging API. Архітектура: Real-time.
Дивіться також: агентські чати товарів мають тип product, але видимі в скриньці.
Наступний крок: досягайте учасників, коли вкладку закрито.
Контракти для інтеграторів щодо розмов і індикатора набору.
/api/mcp/v1/messaging/conversations| Інструменти агентів |
Після записів публікуйте в канал Tunnel conversation:{id} через publishToChannel; клієнти підписуються через useTunnelChannel (а не сирий useTunnel().subscribe() в ефектах).
type у тілі створення має бути одним із: direct | entity | opportunity | product | group (z.enum в app/api/conversations/route.ts). Необов'язкові метадані включають productId, groupName, kind, hiddenFromInbox і id доменів (entityId, opportunityId, …).
ConversationService.getConversations пропускає рядки, де isHiddenToolConversation дорівнює true (features/chat/services/conversation-service.ts):
metadata.hiddenFromInbox === true (бажане довгострокове обмеження)metadata.kind === 'generative_gallery'productId або subject починається з genmedia: чи imggen:Окремо гілки product пропускаються, якщо не виконано metadata.buyerEngaged === true і глядач не надіслав у них жодного повідомлення. Сторінки товарів створюють гілку лише коли покупець пише (див. Store).
| Шлях | Відповідальність |
|---|---|
features/chat/types/index.ts | Conversation, CreateConversationRequest, фільтри |
features/chat/services/conversation-service.ts | CRUD + isHiddenToolConversation |
features/chat/, features/messages/ | UI чату |
features/generative-media/service.ts | Створює приховані чати product + generative_gallery |
features/store/services/product-agent-service.ts | Створює агентські чати product при першому повідомленні покупця; findExistingConversation лише шукає |
lib/tunnel/ | Хаб, публікатор, транспорти |
hooks/use-tunnel-channel.ts | Стабільна підписка на канал |
/api/tunnel/ws/api/tunnel/poll)Повні приклади ендпоінтів: Messaging API. Архітектура: Real-time.
Дивіться також: агентські чати товарів мають тип product, але видимі в скриньці.
Наступний крок: досягайте учасників, коли вкладку закрито.
Контракти для інтеграторів щодо розмов і індикатора набору.
/api/mcp/v1/messaging/conversations| Інструменти агентів |
Після записів публікуйте в канал Tunnel conversation:{id} через publishToChannel; клієнти підписуються через useTunnelChannel (а не сирий useTunnel().subscribe() в ефектах).
type у тілі створення має бути одним із: direct | entity | opportunity | product | group (z.enum в app/api/conversations/route.ts). Необов'язкові метадані включають productId, groupName, kind, hiddenFromInbox і id доменів (entityId, opportunityId, …).
ConversationService.getConversations пропускає рядки, де isHiddenToolConversation дорівнює true (features/chat/services/conversation-service.ts):
metadata.hiddenFromInbox === true (бажане довгострокове обмеження)metadata.kind === 'generative_gallery'productId або subject починається з genmedia: чи imggen:Окремо гілки product пропускаються, якщо не виконано metadata.buyerEngaged === true і глядач не надіслав у них жодного повідомлення. Сторінки товарів створюють гілку лише коли покупець пише (див. Store).
| Шлях | Відповідальність |
|---|---|
features/chat/types/index.ts | Conversation, CreateConversationRequest, фільтри |
features/chat/services/conversation-service.ts | CRUD + isHiddenToolConversation |
features/chat/, features/messages/ | UI чату |
features/generative-media/service.ts | Створює приховані чати product + generative_gallery |
features/store/services/product-agent-service.ts | Створює агентські чати product при першому повідомленні покупця; findExistingConversation лише шукає |
lib/tunnel/ | Хаб, публікатор, транспорти |
hooks/use-tunnel-channel.ts | Стабільна підписка на канал |
/api/tunnel/ws/api/tunnel/poll)Повні приклади ендпоінтів: Messaging API. Архітектура: Real-time.
Дивіться також: агентські чати товарів мають тип product, але видимі в скриньці.