SDK и свои коллекции

SDK работает с контентом сайтов на CMS платформы. Коллекции хранятся в истории версий сайта. Владелец редактирует записи в разделе «Свои разделы», а веб-мастер задаёт поля, связи и страницы.

Установка

Для Node.js 22.18 и новее:

npm install https://askia.ru/downloads/askia-sdk-0.1.0.tgz

Пакет содержит JavaScript, TypeScript-типы и примеры. Внешних зависимостей нет.

Читать опубликованные данные

import { AskiaClient } from "@askia/sdk";

const client = new AskiaClient();
const published = await client.getPublished("ВАШ_SITE_ID");
const branches = published.extensions.collections.find((c) => c.id === "branches");

Этот запрос доступен без ключа, в том числе из браузера. Он возвращает только опубликованную версию сайта: служебные поля и скрытые записи исключены. Фотографии доступны в published.assets по исходному src: url, srcset, width, height относятся к оптимизированному изображению на опубликованном сайте.

Сохранить и проверить черновик

Ключ создаётся в кабинете веб-мастера. Выберите проекты, операции и срок действия. Храните ключ на сервере или в окружении агента; код браузера не должен его получать.

const client = new AskiaClient({ token: process.env.ASKIA_TOKEN });
const draft = await client.getExtensions(siteId);
const next = structuredClone(draft.extensions);
// Измените next, сохраняя существующие коллекции и записи.
const saved = await client.saveExtensions(siteId, next, draft.version_id);
const queued = await client.preview(siteId, saved.version_id);
const finished = await client.waitJob(queued.job_id);
console.log(finished.result.preview_url);

При конфликте draft_changed перечитайте текущий черновик и согласуйте изменения. SDK не повторяет запись автоматически. Просмотр не публикует сайт. После проверки результата можно отдельно вызвать client.publish(siteId, saved.version_id) с ключом, которому разрешена публикация. Тариф, согласование и проверки сайта продолжают действовать.

Коллекции и страницы

Поле может содержать текст, длинный текст, число, «да/нет», дату, вариант из списка, фотографию или ссылку на запись другой коллекции. multiple: true позволяет хранить несколько значений, private: true исключает поле из публичной выдачи. Запись с hidden: true не публикуется.

При изменении состава полей увеличьте collection.version и приведите записи к новой схеме в том же сохранении. Предыдущая версия останется в истории.

Управляемая страница связывает коллекцию с адресом и способом отображения: cards или list. Выберите публичные поля для заголовка, описания и фотографии. CMS добавит раздел в меню и карту сайта.

defineCollection, defineComponent и defineProject позволяют использовать одни определения в нескольких проектах. Записи каждого сайта остаются отдельными. Пример examples/project.mjs внутри пакета добавляет коллекцию филиалов и страницу; без флага --save он только подготавливает изменения.

Произвольные загруженные HTML-проекты не превращаются в коллекции автоматически. Собственный Astro, React или другой интерфейс может читать опубликованные данные CMS-проекта через SDK. Хранить их в отдельном загруженном проекте этот API пока не позволяет.