@vedika-io/widgets

This package provides embeddable Vedika astrology widgets for the web:

• the <vedika-widget> custom element;
• the <vedika-theme-picker> custom element;
• the headless contracts both elements are built on.

A single small theme (seed + mode) recolors every widget. Every colour pick is clamped so the text stays readable (WCAG AA).

Install

npm install @vedika-io/widgets

<script type="module">
  import '@vedika-io/widgets';          // defines <vedika-widget>
  import '@vedika-io/widgets/picker';   // defines <vedika-theme-picker>
</script>

<!-- base-url: your own same-origin proxy (see "Calling the API from a web page") -->
<vedika-widget type="daily-horoscope" sign="leo" base-url="/vedika"></vedika-widget>
<vedika-widget type="panchang" base-url="/vedika"></vedika-widget>
<vedika-widget type="numerology" base-url="/vedika" input='{"birthDate":"1990-05-15"}'></vedika-widget>

Bare imports like the ones above need a bundler or an import map. Without either, load the module file directly:

<script type="module" src="https://cdn.jsdelivr.net/npm/@vedika-io/[email protected]/dist/web/vedikaWidget.mjs"></script>

The package is plain JavaScript and ships no TypeScript declarations.

Widgets

| type | Shows | API operation (production) | Required input | |---|---|---|---| | daily-horoscope | card | GET /v2/astrology/horoscope/{sign} | none; set the sign attribute | | panchang | list | GET /v2/astrology/panchang/today | none | | choghadiya | timing bands | GET /v2/astrology/choghadiya | none | | rahu-kaal | glance | GET /v2/astrology/rahu-kaal | none | | moon-phase | glance | GET /v2/daily/moon-phase | none | | numerology | grid | POST /v2/astrology/numerology/life-path | birthDate (or dateOfBirth, date, datetime) | | tarot-draw | cards | POST /v2/tarot/draw/three-card | none; question is optional | | birth-chart | chart | POST /v2/astrology/birth-chart | birth details (see below) | | compatibility | score | POST /v2/astrology/ashtakoot-match | male and female, each with birth details |

Birth details. Supply all four:

• datetime, or date with an optional time;
• latitude;
• longitude;
• timezone, such as "+05:30".

You can leave out timezone only when datetime carries its own offset, for example 1990-05-15T10:30:00+05:30. The API reads a datetime with no offset and no timezone as UTC, so the widget refuses to send one. The API's aliases also count: lat, lon/lng, tz, dob, dateOfBirth.

A birth chart sent with a date and no time is cast for 12:00 local time. The widget then shows the API's precision note under the title.

The input attribute. input is JSON. POST widgets send it as the request body; GET widgets send it as query parameters.

• panchang, choghadiya and rahu-kaal take a location, for example {"latitude":19.076,"longitude":72.8777,"timezone":"+05:30"}. Without one, the API uses New Delhi.
• When you give a location but no datetime, the widget sends the current time itself, so the reading is for now.
• daily-horoscope takes date and timezone. moon-phase takes date.

If required input is missing, the widget shows a "needs input" message and makes no request. You can also set input from script: el.input = { birthDate: '1990-05-15' }.

Rahu Kaal after dark. Late in the day the API can return an empty Rahu Kaal window. The widget shows — for it.

Attributes

| Attribute | Meaning | |---|---| | type | One of the widget types above. | | sign | Zodiac sign for daily-horoscope: one of the twelve English names (default aries). | | input | JSON request input (see above). | | env | sandbox (default) or prod. | | base-url | Send requests to this base instead of https://api.vedika.io, for example your own proxy. | | apikey | A Vedika API key for env="prod". Read the section below before using it. | | lang | Response language code for env="prod" (default en). | | seed, seed2, mode, skin | Theme: accent colour (#rrggbb), a second accent, light or dark, and a skin name. |

• Runtime theme. Set el.theme = { seed, mode } to recolor at runtime.
• Theme changes are free. Changing the theme attributes or el.theme restyles the widget without calling the API.
• Request changes are batched. Changes to the other attributes, or to el.input, made together (for example while the page loads) produce at most one request.
• Timing. A widget makes no request until it is in the document.

Sandbox and production

env="sandbox" calls https://api.vedika.io/sandbox/... with no key.

• The sandbox ignores the request input and returns one fixed demo reading. Only the horoscope sign in the path is used.
• Use it for layout and integration work, not for real readings.

env="prod" calls /v2/..., and every call is billed to the key's account.

Calling the API from a web page

Allowed origins. The API accepts cross-origin browser calls only from Vedika's own sites and a few localhost development ports.

• On localhost, both modes work directly while you develop.
• On your own domain, a direct call fails with a CORS error in either mode.

Use a same-origin proxy. Point base-url at a proxy on your own site. The proxy also keeps your key out of the page:

<vedika-widget type="panchang" env="prod" base-url="https://your-site.example/vedika"></vedika-widget>

With that setting, the widget requests https://your-site.example/vedika/v2/astrology/panchang/today and sends no key. Your proxy then does the following:

• It forwards the call to https://api.vedika.io with an Authorization: Bearer <key> header.
• It forwards only the operations the widgets use (the method and path pairs in the table above, plus their /sandbox/... twins if you proxy the sandbox). A proxy that forwards any path lets anyone use your key for any API operation.
• It caps the request body size and rate-limits each visitor.

About apikey. An apikey attribute is visible to every visitor. When you set it together with base-url, the key is sent to the base-url host.

• That host must use https://. The only exceptions are a relative path and http://localhost, for development.
• The widget refuses any other combination.

Theme picker

<vedika-theme-picker for="vedika-widget" persist="vedika-theme"></vedika-theme-picker>

• Attributes:
  • for is a CSS selector for the widgets to recolor.
  • persist is an optional localStorage key.
  • seed, mode and skin set the initial values.
  • presets takes a comma-separated list of #rrggbb colours.
• Event: the picker emits vedika-theme-change. Its detail holds { theme, roles, legible }.

Headless modules

These modules import without a DOM, so they work in Node, in SSR and in tests:

| Import | Provides | |---|---| | @vedika-io/widgets/contracts | WIDGETS, SCHEMAS, validate, missingInput, requestInput, BIRTH_KEYS | | @vedika-io/widgets/data-provider | createDataProvider({ mode, apiKey, baseUrl, lang, fetch }) | | @vedika-io/widgets/theme | derive(theme), which returns the 38 theme roles | | @vedika-io/widgets/primitives, @vedika-io/widgets/glyphs | the render primitives and sign/planet glyphs |

@vedika-io/widgets and /picker also import without a DOM. They register their custom elements only where customElements exists.

Requirements and license

• Runtime: a browser with ES modules and custom elements.
• License: proprietary. Use requires a Vedika API subscription or a written agreement with XALEN Technology Pvt Ltd; see LICENSE.
• Packing and publishing:
  • npm pack and npm publish run prepack, which builds dist/.
  • Do not pack with --ignore-scripts: the package would ship without dist/.