White-label PDF बिना WordPress: inline branding एक फ़ील्ड के माध्यम से

आज तक whitelabel: true हमारे report-एंडपॉइंट्स में WordPress अकाउंट की आवश्यकता रखता था जिसमें whitelabel_configs में सेट की गई कुंजियाँ हों। यह ऐतिहासिक है - पहले व्हाइटलेबल WP‑प्लगइन की Pro‑फ़ीचर थी, और API बस वही DB‑टेबल पढ़ता था।

SDK उपयोगकर्ताओं के लिए बिना WP यह मतलब था: brand‑config अतिरिक्त HTTP कूद के बिना संभव नहीं (एक अलग config सर्विस रखना, हमारे साथ सिंक्रोनाइज़ करना, और फिर 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 में उपयुक्त theme‑color एक्सेंट्स, और फुटर में संपर्क ब्लॉक के साथ रेंडर किया जाता है।

सभी वैकल्पिक हैं - यदि फ़ील्ड छोड़ी जाती है तो उसका मान DB‑config से लिया जाता है (यदि API‑की WP उपयोगकर्ता से जुड़ी है) या सिस्टम डिफ़ॉल्ट्स से (SDK क्लाइंट्स बिना WP के लिए)।

12 एंडपॉइंट्स परिवार /v1/reports/* इस फ़ील्ड को समान रूप से स्वीकार करते हैं: natal, transit-yearly, synastry, business, career, love, money, child, lal-kitab, human-design, tarot, vedic-kundli.

Boolean मोड अभी भी सक्रिय है और नहीं बदला:

• whitelabel: true: जुड़े WP उपयोगकर्ता के लिए DB‑config पढ़ता है (जैसा पहले था)
• whitelabel: false या फ़ील्ड अनुपस्थित: डिफ़ॉल्ट AstroWay‑ब्रांडिंग
• whitelabel: {…}: inline‑ऑब्जेक्ट, नई व्यवहार

फ़ील्ड के लिए OpenAPI स्कीमा अब boolean | BrandingObject (union type) है। कोई भी मौजूदा अनुरोध टूटेगा नहीं।

जब API‑की WP उपयोगकर्ता से जुड़ी हो और क्लाइंट inline‑ऑब्जेक्ट भेजता है - inline DB पर प्राथमिकता लेता है। विशेष रूप से:

1. सिस्टम डिफ़ॉल्ट (AstroWay‑ब्रांडिंग)
2. whitelabel_configs से DB‑config (यदि WP उपयोगकर्ता के पास एक है)
3. अनुरोध बॉडी से Inline‑ऑब्जेक्ट

Merge - उथला, कुंजी‑दर‑कुंजी। यानी inline.themeColor = "#ff5500" DB‑मान को ओवरराइट करेगा, लेकिन यदि inline.logoUrl छोड़ी गई है तो DB‑लोगो रहेगा। यह SaaS परिदृश्यों के लिए सुविधाजनक है जहाँ बेसिक ब्रांडिंग DB में रहती है, और per‑tenant फाइन‑ट्यूनिंग inline आती है।

आंतरिक मैपिंग: 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 पैकेजों की रोडमैप्स संबंधित staging रेपो में हैं (astroway-typescript-staging/ROADMAP.md, आदि)। Cron हर 5‑8 दिन में माइनर रिलीज़ प्रकाशित करता है; टाइप्ड BrandingObject जल्द ही उपलब्ध होगा।

पहले SaaS कंज्यूमर के लिए, जो AstroWay PDF जनरेशन को अपने प्रोडक्ट में इंटीग्रेट करता था, प्रक्रिया थी:

1. अपने पास tenants टेबल बनाना जिसमें branding_json फ़ील्ड हो
2. हर रिपोर्ट अनुरोध से पहले: अपने यूज़र की कॉन्फ़िग लाना
3. WP‑प्लगइन के बिना API को कैसे भेजें समझ न आना (पहले: कोई तरीका नहीं, हमें whitelabel_configs में SaaS यूज़र के लिए एंट्री बनाने को कहना पड़ता था)
4. या अपना रेंडरर से PDF पोस्ट‑प्रोसेसिंग करना: यह अतिरिक्त इन्फ्रा है

अब प्रक्रिया:

1. अपना branding_json संग्रहीत रखें
2. हर अनुरोध के लिए whitelabel में inline पास करें

कम HTTP कूद, सेवाओं के बीच DB‑सिंक्रोनाइज़ेशन शून्य, प्रति‑रिक्वेस्ट ब्रांडिंग पर पूर्ण नियंत्रण।

Inline‑मोड सभी टैरिफ़ पर उपलब्ध है जहाँ PDF‑रिपोर्ट्स हैं - Indie ($19/माह) से Business तक। Free टियर PDF नहीं देता (इसे जानबूझकर किया गया है - Free में मुफ्त JSON, रेंडर नहीं)। अनुरोध की क्रेडिट लागत नहीं बदलती - inline‑config रेंडर के ऊपर कोई अतिरिक्त credit‑cost नहीं जोड़ता।

सभी 12 एंडपॉइंट्स के लिए दस्तावेज़ inline‑मोड के उदाहरणों के साथ अपडेट किया गया है। देखें /docs/api/ → Reports.