Добавить источник

У вас есть сервис — календарь, приложение для встреч, хранилище файлов, — и вы хотите, чтобы его записи были в общем хранилище WireCat и ими пользовались поиск и все остальные инструменты. Эта страница показывает шаги: выбрать сущность, которую питают ваши записи, записать их как записи источников, дать cli-core их связать и не пустить внутрь секреты. Она предполагает, что вы знаете основы.

ШагиCopy Anchor Link

1. Выберите сущность. Решите, что владелец имеет в виду под вашими записями: человека, событие или документ. Ваши записи — записи источников этой сущности. Если ничего не подходит, это новая общая сущность, и она требует изменения в cli-core, а не своей таблицы.
2. Пишите через cli-core. Сохраняйте записи через области хранилища cli-core и никогда своим SQL (WC-STORE-5). Если в области нет нужного метода, добавьте его в cli-core вместе с тестом.
3. Ключ — id провайдера. У каждой записи есть account_id и id провайдера в external_id. Повторное сохранение той же записи обновляет её, а не добавляет копию.
4. Используйте стандартные имена. Поле, по которому фильтруют, сортируют, соединяют или которое показывают в списке, — колонка со стандартным именем: title, url, starts_at, ends_at, external_updated_at. Время — в миллисекундах UTC. Всё остальное — в metadata, по списку разрешённых полей (WC-DATA-4, WC-DATA-5).
5. Дайте сопоставлению их связать. cli-core связывает вашу запись с сущностью по правилу: тот же ключ, общий id вроде ical_uid календаря, ссылка для входа или точный хеш содержимого. Два равных кандидата не дают связи.
6. Мягко удаляйте то, что исчезло. Когда провайдер перестаёт возвращать запись, она получает deleted_at. Её сущность и связи владельца остаются (WC-DATA-7).

Пример: встречи ZoomCopy Anchor Link

Инструмент zm уже сейчас так переносит встречи Zoom в хранилище:

• каждая встреча — строка meetings, запись источника, сохранённая через хранилище встреч cli-core;
• account_id — аккаунт Zoom, external_id — id встречи в Zoom, вместе они уникальны;
• event_id указывает на событие — сущность — и выставляется при связывании событий;
• участники — учётные записи, поэтому участник Zoom и тот же человек в Telegram могут сойтись в одном человеке.

Запись разговора, пришедшая позже, находит ту же строку по ключу и обновляет её.

Никогда не хранитьCopy Anchor Link

• токены, пароли и ключи (правила безопасности);
• коды доступа к встречам, PIN-коды и параметры запроса в ссылке для входа;
• сырой ответ провайдера; храните только разрешённые поля.

Зарегистрируйте провайдераCopy Anchor Link

При каждом запуске ваш инструмент записывает своего провайдера в хранилище: имя, вид, псевдонимы и команду. Тогда все остальные инструменты узнают о новом источнике без выпуска cli-core. Строки провайдера, которого ни один инструмент не записал, пропускаются с пояснением и никогда не ищутся как сообщения.

import { openStore } from "@wirecat/cli-core/store"

const store = await openStore()
await store.accounts.registerProvider({ name: "acme", kind: "meetings", aliases: ["acme"], command: "acme" })

kind — как поиск читает ваши записи: messages, mail, notes, documents, meetings или events.

Что сломается, если это пропуститьCopy Anchor Link

Без external_id каждая синхронизация добавляет ту же запись снова. Без мягкого удаления неудачная синхронизация стирает то, что владелец связал или написал. Без общих областей хранилища следующая миграция cli-core ломает ваш инструмент.

Дальше: Хранить свои данные.