White-label PDF bez WordPress: inline branding przez jedno pole

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:00",
      "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 renderuje się z logo w nagłówku, customowym tytułem na okładce, odpowiednimi theme-color akcentami w czarcie-SVG, oraz blokiem kontaktów w stopce.

Wszystkie opcjonalne - pominięte pole bierze wartość z DB-konfiguracji (jeśli klucz API jest przypisany do użytkownika WP) lub z systemowych domyślnych (dla klientów SDK bez WP).

12 endpointów rodziny /v1/reports/* przyjmuje to pole w ten sam sposób: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Tryb booleanowy działa i się nie zmienił:

• whitelabel: true: czyta DB-konfigurację dla przypisanego użytkownika WP (jak wcześniej)
• whitelabel: false lub pole nieobecne: standardowy branding AstroWay
• whitelabel: {…}: inline-obiekt, nowe zachowanie

OpenAPI-schemat dla pola stał się boolean | BrandingObject (union type). Żaden istniejący request się nie zepsuje.

Gdy klucz API jest przypisany do użytkownika WP I klient wysyła inline-obiekt - inline ma pierwszeństwo nad DB. Konkretnie:

1. Systemowe domyślny (astroway-branding)
2. DB-konfiguracja z whitelabel_configs (jeśli użytkownik WP ma taką)
3. Inline-obiekt z body requestu

Merge - shallow, key-by-key. Czyli inline.themeColor = "#ff5500" nadpisze wartość z DB, ale inline.logoUrl pominięty zostawi logo z DB. To wygodne dla scenariuszy SaaS gdzie podstawowy branding siedzi w DB, a per-tenant fintuning przychodzi inline.

Wewnętrzne mapowanie: themeColor staje się primaryColor po wywołaniu applyBrandingPreferences, fontPairing mapuje się na CSS font-family stack w szablonie Handlebars (np. serif-sans = font-family: 'Playfair Display', serif dla nagłówków + 'Inter', sans-serif dla treści).

BrandingObject to teraz osobny komponent w /v1/openapi.json - to znaczy że następny release SDK (TS / Python / PHP) otrzyma typizowany klas:

// 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
  },
});

Roadmapy SDK-packów - w odpowiednich staging-repo (astroway-typescript-staging/ROADMAP.md, itd.). Cron publikuje minor release co 5-8 dni; typizowany BrandingObject będzie w najbliższym.

Wcześniej dla SaaS-konsumenta, który integruje AstroWay-generację PDF w swoim produkcie, ścieżka była:

1. Zająć się u siebie tabelą tenants z polem branding_json
2. Przed każdym report-requestem: pobrać konfig swojego użytkownika
3. Nie zrozumieć jak przekazać do API bez WP-pluginu (wcześniej: w ogóle, trzeba było prosić nas o zrobienie entry w whitelabel_configs pod SaaS-użytkownika)
4. Albo robić PDF-postprocessing swoim renderem: to dodatkowa infra

Teraz ścieżka:

1. Przechowywać branding_json u siebie
2. Przekazywać inline w whitelabel dla każdego requestu

Mniej HTTP-skoków, zero DB-synchronizacji między serwisami, pełna kontrola nad brandingiem per-request.

Inline-tryb dostępny na wszystkich taryfach gdzie są PDF-repory - od Indie ($19/mies) do Business. Free tier PDF nie daje (to celowe - w Free darmowy JSON, bez renderu). Koszt kredytu requestu się nie zmienia - inline-konfig nie dodaje credit-cost-u na renderze.

Dokumentacja dla wszystkich 12 endpointów zaktualizowana z przykładami inline-trybu. Patrz /docs/api/ → Reports.