Розробникам · Застосунки

Розробка застосунків

Застосунок — тека з маніфестом і кодом на TypeScript: доставка, оплата, події. Заготовка, перевірка на сервері, публікація, встановлення.

Застосунок розширює магазин: рахує доставку, приймає оплату, реагує на замовлення, синхронізує каталог із зовнішньою системою. Код виконується ізольовано й може ходити лише на дозволені зовнішні адреси.

Файли

Файл	Що в ньому
manifest.json	id (зворотний домен), назва, версія, entry, capabilities — що застосунок уміє.
declarations.json	Поля каталогу, egress.origins — дозволені зовнішні адреси, форма налаштувань і секрети.
extension.ts	Код на TypeScript: кожен хук отримує input і host.

Початок

Адмінка: Інтеграції → Розробка застосунків → «Заготовка застосунку (zip)», або в терміналі:

node storeforma-agent.mjs app init ./my-app --id ua.my-studio.delivery

Цикл розробки

Пишіть код в extension.ts і декларації.
— зберігає чернетку версії й перевіряє на сервері: TypeScript, декларації, дозволи. Помилки зрозумілі й людині, й агенту.
— пропонує публікацію; схваліть в асистенті адмінки.
Встановіть застосунок і видайте дозволи: Інтеграції → Застосунки.
Кожна нова публікація — нова версія в manifest.json: опублікована версія незмінна.

Характеристика й фільтр із застосунку

Застосунок може додати магазину власну характеристику й фільтр — наприклад, «Матеріал», який він визначає сам (з назви, із зовнішньої системи, з метаполя). Він не підміняє фільтри магазину: оголошена характеристика стає звичайною характеристикою довідника, а фільтр — звичайним фільтром із лічильниками, наборами за категорією й SEO-сторінками. Потрібні дозволи catalog.declarations і catalog.projection.

1. declarations.json — що застосунок додає. Ключ починається з id застосунку; scalar — одне значення (стає «Одне зі списку»), multi_select — кілька з переліку (стає «Кілька зі списку»); labels — назва мовами магазину; фільтр — оператор contains_any:

{
  "attributes": [
    {
      "key": "ua.my-studio.materials.material",
      "type": "multi_select",
      "values": ["Бавовна", "Льон", "Вовна"],
      "labels": { "uk": "Матеріал", "en": "Material" }
    }
  ],
  "filters": [
    { "attribute": "ua.my-studio.materials.material", "operator": "contains_any" }
  ]
}

2. extension.ts — значення для кожного товару. Хук projectProduct викликається, коли товар створюють, змінюють чи імпортують; він повертає значення своїх характеристик. Значення, якого хук не повернув, у товару прибирається:

import { defineApp, type ProductProjectionInput } from '@storeforma/extension-sdk';

const MATERIAL = 'ua.my-studio.materials.material';
const WORDS: Record<string, string> = { бавовн: 'Бавовна', cotton: 'Бавовна', льон: 'Льон', linen: 'Льон', вовн: 'Вовна', wool: 'Вовна' };

export default defineApp({
  async projectProduct(input: ProductProjectionInput) {
    const name = String(input.attributes['storeforma.product.name'] ?? '').toLowerCase();
    const found = Object.entries(WORDS).filter(([word]) => name.includes(word)).map(([, value]) => value);

    return { attributes: { [MATERIAL]: [...new Set(found)] } };
  },
});

3. Що бачить магазин після публікації й увімкнення застосунку:

«Каталог → Характеристики» — «Матеріал» із позначкою застосунку; назву, тип і значення задає застосунок, розділ, показ у таблиці, роль і фільтр — власник.
«Каталог → Фільтри» — фільтр «Матеріал» (адреса ); на вітрині він показує лише значення, які є в товарів категорії.
Таблиця характеристик на сторінці товару, фіди й експорт — зі значеннями застосунку.
Застосунок вимкнули або видалили — його характеристика, значення й фільтр зникають; знову увімкнули — зʼявляються після перерахунку товарів.

Нова версія застосунку з іншими оголошеннями оновлює назви й значення; характеристика, якої більше немає в оголошеннях, прибирається.