White-label PDF без WordPress: inline branding через одне поле

До сьогодні whitelabel: true у наших report-ендпоінтах вимагало WordPress-акаунту з налаштованими ключами в whitelabel_configs. Це історично — раніше білий лейбл був Pro-фічею WP-плагіна, і API просто читав ту саму DB-таблицю.

Для SDK-користувачів без WP це означало: brand-config неможливий без додаткового HTTP-стрибка (тримати окремий конфіг-сервіс, синхронізувати з нашим, та потім посилати whitelabel: true).

Тепер поле приймає inline-об’єкт з усіма 15 полями брендингу. Один запит = повний контекст бренду = персоналізована PDF.

Приклад: PDF natal report з кастомним брендингом

curl -X POST https://api.astroway.info/v1/reports/natal \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chart": {
      "date": "1990-05-15",
      "time": "14:30",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52,
      "name": "Maria"
    },
    "whitelabel": {
      "companyName": "Acme Astrology",
      "companyUrl": "https://acme-astro.example.com",
      "companyEmail": "hello@acme-astro.example.com",
      "logoUrl": "https://cdn.example.com/logo.png",
      "themeColor": "#ff5500",
      "headingColor": "#1a1a2e",
      "reportName": "My Personal Cosmic Map",
      "footerText": "© 2026 Acme Astrology",
      "fontPairing": "serif-sans"
    }
  }'

PDF рендериться з лого в шапці, кастомним заголовком на cover, відповідною theme-color акцентами в чарт-SVG, та блоком контактів у футері.

Усі 15 полів об’єкта

Усі опціональні — пропущене поле бере значення з DB-конфігу (якщо API-ключ прив’язано до WP-користувача) або з системних дефолтів (для SDK-клієнтів без WP).

Поле	Тип	Призначення
companyName	string	Назва бренду в шапці PDF
companyUrl	URL	Клікабельне посилання на сайт у футері
companyEmail	email	Контакт-лінк у футері (mailto:)
companyMobile	string	Телефон у футері
companyBio	string	Один абзац опису компанії на cover-сторінці
logoUrl	URL (.png/.jpg/.svg/.webp)	Лого, https-only, 200×60 рекомендований ratio
frontImage	URL	Hero-зображення на cover-сторінці
textPrimaryColor	#RGB/#RRGGBB	Основний текст
textSecondaryColor	#RGB/#RRGGBB	Підписи, метадані
backgroundColor	#RGB/#RRGGBB	Фон сторінок
themeColor	#RGB/#RRGGBB	Акценти, заголовки, аспект-лінії в чартах
headingColor	#RGB/#RRGGBB	H1/H2 заголовки
footerText	string	Кастомний копірайт у футері
fontPairing	enum	serif-sans / sans-serif / serif-only / sans-only / system
reportName	string	Заміняє дефолтну назву звіту на cover

12 ендпоінтів сімейства /v1/reports/* приймають це поле однаково: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Зворотна сумісність

Boolean-режим живий і не змінився:

• whitelabel: true — читає DB-конфіг для прив’язаного WP-користувача (як раніше)
• whitelabel: false або поле відсутнє — стандартний AstroWay-брендинг
• whitelabel: {…} — inline-об’єкт, нова поведінка

OpenAPI-схема для поля стала boolean | BrandingObject (union type). Жоден існуючий запит не зламається.

Resolution priority

Коли API-ключ прив’язано до WP-користувача І клієнт надсилає inline-об’єкт — inline переважає DB. Конкретно:

1. Системні дефолти (астроуей-брендинг)
2. DB-конфіг з whitelabel_configs (якщо WP-користувач має один)
3. Inline-об’єкт з body запиту

Merge — shallow, key-by-key. Тобто inline.themeColor = "#ff5500" перепише DB-значення, але inline.logoUrl пропущене залишить DB-логотип. Це зручно для SaaS-сценаріїв де базовий брендинг сидить у DB, а per-tenant фінтюнинг приходить inline.

Внутрішнє мапування: themeColor стає primaryColor після виклику applyBrandingPreferences, fontPairing мапиться на CSS font-family стек в Handlebars-шаблоні (наприклад, serif-sans = font-family: 'Playfair Display', serif для заголовків + 'Inter', sans-serif для тіла).

OpenAPI 3.1 + SDK типізація

BrandingObject тепер окремий компонент у /v1/openapi.json — це значить наступний реліз SDK (TS / Python / PHP) отримає типізований клас:

// TS SDK — після наступного codegen-релізу
import { AstroWay } from "@astroway/sdk";

const client = new AstroWay({ apiKey: process.env.ASTROWAY_KEY });

const pdf = await client.reports.natal.create({
  chart: { date: "1990-05-15", time: "14:30", /* ... */ },
  whitelabel: {
    companyName: "Acme Astrology",
    themeColor: "#ff5500",
    reportName: "My Personal Cosmic Map",
    fontPairing: "serif-sans",  // typed enum, autocomplete у IDE
  },
});

Дорожні мапи SDK-пакетів — у відповідних staging-репо (astroway-typescript-staging/ROADMAP.md, тощо). Cron публікує мінорні релізи кожні 5-8 днів; типізований BrandingObject буде в найближчому.

Що це знімає

Раніше для SaaS-консумента, який інтегрує AstroWay-генерацію PDF у власний продукт, шлях був:

1. Стурбувати у себе таблицю tenants з полем branding_json
2. Перед кожним report-запитом — підтягнути конфіг свого юзера
3. Не зрозуміти як передати в API без WP-плагіна (раніше — ніяк, треба було просити нас зробити entry в whitelabel_configs під SaaS-користувача)
4. Або ж робити PDF-постпроцесинг своїм рендером — це додаткова інфра

Тепер шлях:

1. Зберігати branding_json у себе
2. Передавати inline у whitelabel для кожного запиту

Менше HTTP-стрибків, нуль DB-синхронізації між сервісами, повний контроль над брендингом per-request.

Доступність

Inline-режим доступний на всіх тарифах де є PDF-репорти — від Indie ($19/міс) до Business. Free tier PDF не дає (це навмисно — у Free безкоштовний JSON, без рендеру). Кредитна вартість запиту не змінюється — інлайн-конфіг не додає credit-cost-у поверх рендеру.

Документація для всіх 12 ендпоінтів оновлена з прикладами inline-режиму. Дивись /docs/api/ → Reports.