WordPress不要のホワイトラベルPDF：1つのフィールドによるインラインブランディング

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

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

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

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 はヘッダーにロゴ、カバーにカスタムヘッダー、チャート SVG のテーマカラーアクセント、フッターに連絡先ブロックが描画されるんだ。

すべて オプション で、未指定のフィールドは DB コンフィグ（API キーが WP ユーザーに紐付いている場合）またはシステムデフォルト（WP なしの SDK クライアント向け）から値を取得するんだ。

/v1/reports/* ファミリーの 12 のエンドポイントはすべてこのフィールドを同様に受け取る: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli。

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

• whitelabel: true: 紐付けられた WP ユーザー用の DB コンフィグを読む（以前と同じ）
• whitelabel: false またはフィールドが無い場合: 標準の AstroWay ブランディング
• whitelabel: {…}: inline オブジェクト、新しい挙動

このフィールドの OpenAPI スキーマは boolean | BrandingObject（ユニオン型）になった。既存のリクエストが壊れることはない。

API キーが WP ユーザーに紐付いていて、かつクライアントが inline オブジェクトを送信した場合、inline が DB を上書きする。具体的には：

1. システムデフォルト（AstroWay ブランディング）
2. whitelabel_configs の DB コンフィグ（WP ユーザーが持っている場合）
3. リクエストボディの inline オブジェクト

マージは浅く、キーごとに上書きする。つまり inline.themeColor = "#ff5500" は DB の値を上書きするが、inline.logoUrl が未指定なら DB のロゴが残る。これは、基本のブランディングが DB にあり、テナントごとの微調整が inline で来る SaaS シナリオに便利だ。

内部マッピング: themeColor は applyBrandingPreferences 呼び出し後に primaryColor になる。fontPairing は Handlebars テンプレートの CSS font-family スタックにマップされる（例: serif-sans = ヘッダー用 font-family: 'Playfair Display', serif + 本文用 'Inter', sans-serif）。

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 パッケージのロードマップは各ステージングリポジトリにある（astroway-typescript-staging/ROADMAP.md など）。Cron が 5〜8 日ごとにマイナーレリースを公開するので、型付けされた BrandingObject はすぐに登場するだろう。

以前、AstroWay の PDF 生成を自社製品に統合する SaaS コンシューマーの流れは：

1. tenants テーブルに branding_json カラムを用意する
2. 各レポートリクエストの前に自分のユーザー設定を取得する
3. WP プラグインなしで API に渡す方法が分からなかった（以前は方法がなく、SaaS ユーザー用に whitelabel_configs にエントリを作るよう依頼する必要があった）
4. あるいは自前のレンダラで PDF 後処理を行う：追加のインフラが必要

今はこうなる：

1. 自分で branding_json を保存する
2. 各リクエストで whitelabel に inline で渡す

HTTP 呼び出しが減り、サービス間の DB 同期がゼロになり、リクエストごとにブランディングを完全にコントロールできるんだ。

Inline モードは PDF レポートが利用できるすべてのプランで利用可能だ - Indie（$19/月）から Business まで。Free tier では PDF が提供されない（意図的に、Free では無料の JSON のみでレンダリングはなし）。リクエストのクレジットコストは変わらず、inline 設定が追加でクレジットコストを増やすことはない。

すべての 12 エンドポイントのドキュメントは inline モードの例と共に更新された。/docs/api/ → Reports を参照してください。