WordPress plugin

The Kaal Jyoti plugin puts all 22 widgets on a WordPress site, each as a block and a shortcode, in four groups:

• Daily — Panchang, Muhurta and choghadiya, Panchang month, Hindu calendar, Planets now, Ephemeris.
• Calculators — Moon sign, Lagna, Manglik, Sade sati, Dasha, Divisional charts, KP, Shadbala and ashtakavarga, and a drawn Chart.
• Reports — Horoscope, Reading, Life areas, Varshphal, Dasha reading.
• Kundli & Match — the Kundli form with its tabbed report, and the Ashtakoot Match.

By default every widget is drawn in the visitor's browser with a publishable key. With a secret key the plugin also offers PDF downloads, a cache for the two month widgets, and server rendering of the daily panchang, the muhurta, charts, and preset horoscopes and readings.

It needs WordPress 6.5 or later and PHP 8.2 or later.

Install#

The plugin is not in the WordPress.org directory yet: the listing is in review there. Once it is there: Plugins → Add New Plugin, search for "Kaal Jyoti", install and activate.

Until then, install it from a zip: download kaal-jyoti-0.1.0.zip, then Plugins → Add New Plugin → Upload Plugin, choose it, install and activate.

The plugin is self-contained. The widgets and the PHP SDK are inside it, and the widgets are served from your own site rather than a CDN; each file's URL carries a hash of its contents, so a browser never mixes an old loader with new widget code after an update.

Then get a publishable key from the dashboard and open Settings → Kaal Jyoti.

Settings → Kaal Jyoti#

Six tabs. Each opens with a line saying what it holds, and saving a tab saves only that tab. A Search settings box narrows the tab to the settings that match and links to matches on the other tabs.

Connection#

Above the keys the page prints this site's origin — scheme, host and port, exactly as the browser will send it. Copy it into the key's origin list in the dashboard: a publishable key only works from the origins listed on it.

The fields check what you paste: a secret key in the publishable field is refused with a message saying where it belongs, and a key with the wrong prefix is refused and the stored one kept. To change the secret key, type a new one; leaving the field blank keeps the stored key, and a checkbox removes it. The secret key is stored in the options table like any plugin's API key, and is never printed in a page, a script or an error message.

Test connection asks the API for its version from your server and reports the engine and the ephemeris it runs. With a secret key stored it also asks for the default city's panchang, names the key's plan, and says what that plan means for PDF downloads. It saves nothing. A publishable key's origin list can only be tested from a browser, so open a page with a widget as well.

Appearance#

Auto takes the text colour from your site and leaves the background transparent, so the widgets sit in a light or a dark theme without looking pasted in. Light and Dark use the style's own palettes. An empty colour field keeps the theme's own; the colours are the widgets' --kj-* properties (see theming), and server-rendered markup follows the same settings.

Defaults and forms#

The place search works as in the widgets' place search: Automatic is Google Places with a Google Maps key, otherwise Photon; Photon is free, finds villages and costs no Kaal Jyoti credits; Google Places needs your key with Places API (New) and Maps JavaScript API enabled, and Google bills its searches to your Google account; Kaal Jyoti only asks no third party and costs 1 credit a search. If Photon or Google fails, the form goes on with the Kaal Jyoti search.

Reports and PDFs#

Advanced#

Blocks and shortcodes#

Every widget is a block and a shortcode. The shortcode is kj_ and the widget's name with underscores; the block is Kaal Jyoti and its name, in the Widgets category of the block inserter:

Blocks and shortcodes go through the same code, so an attribute means the same in both, and it means what the widget's attribute of the same name means — see widgets for each. An attribute that is not on a shortcode's list, or a value that does not fit it, is dropped rather than passed on for the API to refuse. Underscores in attribute names are read as hyphens, so show_degrees and show-degrees are the same.

[kj_panchang city="varanasi" lang="hi"]
[kj_muhurta city="mumbai"]
[kj_panchang_month city="delhi" masa="amanta"]
[kj_chart datetime="1990-05-14T10:30:00" city="delhi" style="south" varga="d9"]
[kj_kundli_form tabs="overview charts planets dasha" readings="lagna,nakshatra" pdf="off"]
[kj_match_form city="mumbai" lang="hi"]
[kj_horoscope sign="aries" period="weekly" show_basis="yes"]
[kj_reading type="nakshatra" nakshatra="revati"]
[kj_reading type="vimshottari" datetime="1990-05-14T10:30:00" city="delhi"]
[kj_dasha datetime="1990-05-14T10:30:00" city="delhi" name="Asha"]
[kj_moon_sign]

Attributes every shortcode takes#

And where they apply:

• sign_icons — element, glyph, devanagari or custom — on the thirteen widgets that show a sign: the kundli form, the match, the horoscope, the reading, planets now, the ephemeris, moon sign, lagna, sade sati, divisional charts, KP, shadbala and varshphal.
• disclaimer (default or off), or disclaimer_name and disclaimer_url, on every widget that ends with a reading: the horoscope, the reading, the kundli form, moon sign, lagna, life areas, varshphal and the dasha reading. They override the Disclaimer setting.
• time_format="24" and remember="off" on the two forms and the eleven calculators.
• A birth — datetime, and city or lat / lon, timezone, place, name — on the calculators, which then show that birth with no form. Without one, they show the form, pre-filled with the default city.
• pdf="off", or a narrower list of editions, on the two forms.

The kundli form's readings takes lagna, nakshatra, house_lords, grahas, yogas, vimshottari, varshphal, life_areas, or all; a bare readings is the lagna and nakshatra. Each reading is 5 credits per submit, so they are off unless you set them. Its tabs takes overview, charts, planets, dasha and life; the first release's show="summary chart" still works.

Blocks#

Each block's inspector has a Place or Birth panel, the widget's own choices, and a Display panel — language, theme, style, font, heading, powered by, the sign icons where a sign is shown, the forms' time format and memory, and the disclaimer where there is a reading. Every select starts at "Site default", which means the value from Settings → Kaal Jyoti.

The editor preview is live. A block in the editor calls the API exactly as the published page will, so each widget you place spends its credits when the editor draws it. The forms and calculators call nothing until you submit them in the preview.

Sign icons#

Settings → Kaal Jyoti → Appearance → Zodiac sign icons chooses how every sign is drawn: Element tiles (the default), Glyph, Hindi name, or Your own images — one image per sign, chosen from your media library with twelve pickers. A sign without an image keeps the default icon, and images must be served over HTTPS or from your own site. Each block can choose its own in its Display panel, including "the site's own images" while the rest of the page keeps the site's theme; a shortcode takes sign_icons="glyph". See zodiac sign icons.

The server connection#

The widgets call the API from the visitor's browser with the publishable key. One thing the API never gives a browser, on any plan, is a PDF. With a secret key stored, this site makes PDFs for its visitors, and also serves the two month widgets from its own cache. The widgets send those requests to this site's proxy, /wp-json/kaaljyoti/v1/proxy, which checks them and calls the API with the secret key. The key stays on the server.

The proxy is not an open relay:

• An allowlist. It answers only /panchang/month and /ephemeris/month, and, with PDF downloads on, /pdf/kundli and /pdf/match. Anything else is 403 proxy_path_not_allowed.
• Rebuilt bodies. Each request is rebuilt from the fields its route takes, with their types checked; anything else in it is dropped. A PDF's edition must be one you offer, and its disclaimer is your setting, not the page's.
• A size cap. A body over 16 KB is refused before it is read.
• This site's pages only. A nonce in the URL the plugin writes into the page, and a check of the browser's origin.
• Rate limits per visitor: 10 month requests and 3 PDFs a minute by default, kept against a salted hash of the IP address, never the address itself.
• A month cache. A month's answer is the same for a place and a month, so it is kept for 12 hours and served without a call — a busy page costs one call per place and month rather than one per visitor.

The API's answer is relayed as it is, so a site out of credits gets the widgets' "Monthly limit reached" card. Your balance is not relayed to the page.

Without a secret key there is no PDF button, and the month widgets call the API directly with the publishable key.

PDF downloads#

Switch them on under Reports and PDFs, and choose the kundli editions: Basic, Professional, or both. The kundli report and the match result then show a "Download PDF" button with the edition and the language; the PDF uses the widget's style and your Kaal Jyoti branding from the dashboard.

A kundli PDF costs 1,000 credits and a match PDF 500, and each uses one PDF of your plan's monthly allowance: Starter 50, Growth 200, Scale 500, Enterprise 2,500. PDFs are on every paid plan and not on Free; on Free the button shows a polite "needs a plan" note. See PDFs.

Server rendering#

In Browser mode, the default, the plugin writes a widget element into the page and every visitor's browser asks the API for itself. In Server mode the plugin asks instead, from your server with the secret key, and caches the finished HTML.

To turn it on: add a secret key, set Render mode to Server under Advanced, choose the Cache minutes, and save.

What is drawn on the server:

• the panchang, and the muhurta as the day's five windows (the choghadiya table is drawn in the browser);
• the chart, as an inline SVG;
• a horoscope with its sign set;
• a reading with its sign or nakshatra set.

They are plain HTML, in the page before any JavaScript runs. Everything else stays in the browser: the forms and calculators have nothing to draw until a visitor types a birth, and a horoscope or a reading that lets the visitor pick, or reads a birth, needs the page to ask.

On the server the plugin calls POST /v1/panchang (for both the panchang and the muhurta), POST /v1/kundli/chart, POST /v1/horoscope, POST /v1/reports/lagna and POST /v1/reports/nakshatra, nothing else.

Caching — each rendered widget is stored in a WordPress transient for the cache minutes you set, keyed on its request. Two shortcodes for the same place and day share one entry, and so do a panchang and a muhurta for the same place and day. The theme is not part of the entry. A failed call is not cached.

Fallbacks — if a server call fails and a publishable key is stored, the page gets the ordinary browser widget, so a visitor still sees a panchang. With no publishable key, visitors see nothing, and an administrator sees a line naming the error code.

Language — Hindi works in both modes: every name, label and reading comes through in Hindi.

What a page costs#

The plugin is a client for the API, and each call it makes costs that route's credits — see Credits per API. Every plan can use every widget.

The block editor says what each calculator costs. Identical requests on one page are made once. A busy page is where server mode pays for itself: at the default fifteen minutes, a panchang seen by any number of visitors is at most 96 calls a day.

FAQ#

The widget says the key does not allow this origin#

That is forbidden_origin: this site's origin is not on the publishable key. Settings → Kaal Jyoti → Connection prints the exact origin to paste into the key in the dashboard — scheme, host and port, nothing else. https://example.com and https://www.example.com are different origins, and so are http://localhost:3000 and http://localhost. A staging copy of your site is another origin and needs its own entry.

A widget says "Monthly limit reached"#

Your account has used its credits for the month, or has fewer left than the request costs. The widget says so politely, with a link for you to the pricing page: buy a credit pack or move to a larger plan, or wait for your billing day, when the credits reset.

Do I need a secret key?#

Not for the widgets: the publishable key is enough for all 22. A secret key adds PDF downloads, the month cache and server rendering.

The PDF button or a month stopped loading on a cached page#

With a secret key, these go through this site's proxy with a check that the page is no more than a day old. If your page cache keeps pages longer, clear it, or turn off Page check (nonce) under Advanced.

The widget looks wrong on my dark theme#

With the theme at Auto the widget reads your site's text colour and has no background of its own, so it should already read on a dark page. If not, choose Dark under Appearance, or theme="dark" on one shortcode. If one colour is still off, set just that one under Appearance.

Can it show Hindi?#

Yes. Set Language to Hindi, or write lang="hi" on one shortcode or block. Every name, label and reading comes through in Hindi, in both render modes.

Why does it need PHP 8.2?#

The plugin bundles the Kaal Jyoti PHP SDK for server rendering, and the SDK's answers are readonly classes, which older PHP cannot load. WordPress will not activate the plugin on an older version; ask your host to move the site to 8.2 or later.

Does it work without JavaScript?#

In server mode, the panchang, the muhurta, the chart, a horoscope with its sign set and a reading with its sign or nakshatra set are plain HTML. The forms, the calculators and the month widgets need JavaScript in either mode.

Where is my data?#

The plugin stores one option row (your settings), and in transients: the server-rendered HTML, the proxy's cached months, and its per-visitor rate limits. Deleting the plugin removes all of them. A birth a visitor types goes to the API to answer that one request and is not stored there. What a visitor types in the place search goes to Photon or Google when one of them searches.

Can I point it at staging?#

Yes: Connection → Advanced: API address. Leave it at https://api.kaaljyoti.com unless you have been given a staging host.

MIT licensed. Source, issues and pull requests: kaaljyoti-integrations.