astromansion 0.1.0-alpha.3 → 0.1.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- ![Astro Mansion, Official JavaScript SDK](https://raw.githubusercontent.com/mustafayavuzak/astromansion-js/main/banner.webp)
1
+ ![Astro Mansion, Official JavaScript SDK](https://api.astromansion.com/v1/sky/banner.svg?sdk=javascript)
2
2
 
3
3
  # AstroMansion
4
4
 
@@ -430,6 +430,68 @@ There is no ceiling on how many you may read this way. `options.all_bodies`
430
430
  walks every category at once and needs the full-catalog scope that comes with
431
431
  Pro and Enterprise. Naming the categories yourself does not.
432
432
 
433
+ ## A planet's moons
434
+
435
+ `planetarySystem` reads one planet's satellites at the birth moment. It
436
+ covers Mars, Jupiter, Saturn, Uranus, Neptune and Pluto, and it needs the
437
+ `extended` scope that comes with Basic, Pro and Enterprise. With the `birth`
438
+ object from the examples above:
439
+
440
+ ```js
441
+ const system = await client.planetarySystem({ birth, parent: "jupiter" });
442
+
443
+ system.parent.natal_sign; // "Aries"
444
+ system.time.utc; // "2000-01-01T12:00:00Z"
445
+
446
+ for (const moon of system.satellites) {
447
+ console.log(
448
+ moon.name,
449
+ moon.geocentric?.longitude?.toFixed(2),
450
+ moon.parentcentric.longitude?.toFixed(2),
451
+ moon.natal_parent_projected.sign,
452
+ );
453
+ }
454
+ // Io 25.24 18.11 Libra
455
+ // Europa 25.25 212.49 Taurus
456
+ // Ganymede 25.23 219.91 Taurus
457
+ // Callisto 25.38 80.07 Sagittarius
458
+ ```
459
+
460
+ Every satellite carries three answers, and they are not versions of one
461
+ another:
462
+
463
+ - `geocentric` is where the moon is seen from Earth, on the ecliptic of
464
+ date, with the light time solved. From Earth the Galilean moons sit within
465
+ a fraction of a degree of Jupiter, so this longitude nearly repeats the
466
+ planet's own.
467
+ - `parentcentric` is where the moon is in its orbit, measured on the
468
+ planet's equator. A planet-centred frame has no horizon, so it has no
469
+ houses.
470
+ - `natal_parent_projected` carries that orbital phase onto the natal circle
471
+ from the planet's own natal degree. It is an AstroMansion derivation rather
472
+ than a received rule, and its `tradition` field says so.
473
+
474
+ `system.frames` names each frame. The planet-centred one also publishes the
475
+ pole its equator is built on, so the plane can be checked:
476
+
477
+ ```js
478
+ const frame = system.frames.parentcentric;
479
+ frame.frame_id; // "jupiter_equator_iau2015_j2000_fixed"
480
+ [frame.pole.ra_deg, frame.pole.dec_deg]; // [268.057204, 64.49581]
481
+ ```
482
+
483
+ `options` narrows the answer. `satellites` names the moons and their order,
484
+ and `include_geocentric: false` leaves the view from Earth out, so
485
+ `geocentric` comes back as `null`:
486
+
487
+ ```js
488
+ await client.planetarySystem({
489
+ birth,
490
+ parent: "saturn",
491
+ options: { satellites: ["titan", "enceladus"], include_geocentric: false },
492
+ });
493
+ ```
494
+
433
495
  ## MansionSQL
434
496
 
435
497
  A chart is a table of bodies, a table of houses and a table of aspects, and
@@ -458,7 +520,8 @@ for (const row of rows.data) {
458
520
 
459
521
  `query` takes the request body rather than flat birth fields, because a
460
522
  statement may name two charts and a moment, and each of them needs its own
461
- birth block. It needs the `advanced` scope.
523
+ birth block. It needs the `query` scope that comes with Basic, Pro and
524
+ Enterprise.
462
525
 
463
526
  ### Tables
464
527
 
@@ -802,7 +865,7 @@ list of one:
802
865
 
803
866
  ## Every endpoint
804
867
 
805
- Every published operation, 68 of them, has a method on the client and a
868
+ Every published operation, 69 of them, has a method on the client and a
806
869
  module-level shortcut, all generated from the schema. They are the Python
807
870
  SDK's methods under the same names, written in camelCase: `natal`,
808
871
  `transits`, `synastry`, `composite`, `solarReturn`, `progression`,
@@ -898,7 +961,7 @@ await client.exportPdf({
898
961
 
899
962
  Every endpoint that answers with a document takes `output` the same way:
900
963
  `exportPdf`, `exportCsv`, `exportReport`, `renderSvg`, `renderPng`,
901
- `renderBiwheel`, `renderAstrocartography` and `renderSharecard`, and their
964
+ `renderBiwheel`, `renderChart`, `renderAstrocartography` and `renderSharecard`, and their
902
965
  module-level shortcuts.
903
966
 
904
967
  ```js
@@ -919,6 +982,74 @@ before the request is sent, so no quota is spent. The refusal is a
919
982
  `ValidationError` that says "output needs a file system, and this runtime has
920
983
  none. Leave output out to get the bytes."
921
984
 
985
+ ### Styled chart wheels
986
+
987
+ `renderChart` draws a chart as SVG or PNG. Its body is typed as
988
+ `ChartRenderRequest`, exported by the package, and includes the chart kind,
989
+ the birth and the drawing's options.
990
+
991
+ ```ts
992
+ const birth = {
993
+ date: "1990-07-15",
994
+ time: "14:30",
995
+ lat: 51.5074,
996
+ lon: -0.1278,
997
+ timezone: "Europe/London",
998
+ };
999
+
1000
+ await client.renderChart({
1001
+ type: "natal",
1002
+ format: "svg",
1003
+ birth,
1004
+ options: {
1005
+ theme: "light",
1006
+ style: {
1007
+ preset: "ink",
1008
+ colors: { house_lines: "#123456" },
1009
+ show: { ticks: false, watermark: false, canvas_background: false },
1010
+ },
1011
+ },
1012
+ output: "styled-chart.svg",
1013
+ });
1014
+
1015
+ await client.renderChart({
1016
+ type: "natal",
1017
+ format: "png",
1018
+ birth,
1019
+ options: { width: 800, style: { preset: "premium" } },
1020
+ output: "styled-chart.png",
1021
+ });
1022
+ ```
1023
+
1024
+ The kinds are `natal`, `rising`, `transits`, `synastry`, `composite`,
1025
+ `solar_return`, `lunar_return`, `saturn_return`, `progressions` and `solar_arc`. Synastry and
1026
+ composite need a second birth as `partner`. Moment options belong under
1027
+ `options`: `date` and `time` for transits, `year` for solar returns, `date`
1028
+ for lunar returns, and either `date` or `age` for progressions and solar arcs.
1029
+ Saturn returns use `cycle: 1`, `2` or `3`, defaulting to the first return.
1030
+ `custom_bodies` accepts up to eight Keplerian bodies on the first ring,
1031
+ using the custom-body endpoint's orbital fields. Their positions follow
1032
+ the chart's actual moment; a composite uses the midpoint of both placements.
1033
+ Rising-sign charts accept no bodies.
1034
+
1035
+ Presets are `classic`, `minimal`, `ink`, `editorial` and `premium`. With no
1036
+ style the server uses `minimal`. Colours use six hexadecimal digits, such
1037
+ as `#123456`. The server validates style sections, ring order and the
1038
+ options each kind reads. `renderSvg` and `renderPng` also take `style`
1039
+ inside their `options`.
1040
+
1041
+ `style.show.watermark` controls the faint centre logo. Set
1042
+ `style.show.canvas_background` to `false` for a painted wheel with
1043
+ transparent surroundings. Both default to `true` in the API. The designer
1044
+ starts with transparent surroundings and writes that choice into its JSON.
1045
+ For other outputs, use `options.watermark` in `natal` and `exportPdf`,
1046
+ and `watermark` in `renderBiwheel` and `exportReport`. White-label
1047
+ reports always omit the centre logo.
1048
+
1049
+ Use the [chart designer](https://astromansion.com/en/chart-designer) to edit
1050
+ every setting and copy its JSON. A timeline, firdaria and zodiacal releasing
1051
+ are not wheel kinds in this version.
1052
+
922
1053
  ## Security
923
1054
 
924
1055
  The key travels in the `X-API-Key` header, never in a URL. It is masked in
package/dist/index.cjs CHANGED
@@ -84,6 +84,7 @@ __export(index_exports, {
84
84
  rectification: () => rectification,
85
85
  renderAstrocartography: () => renderAstrocartography,
86
86
  renderBiwheel: () => renderBiwheel,
87
+ renderChart: () => renderChart,
87
88
  renderPng: () => renderPng,
88
89
  renderSharecard: () => renderSharecard,
89
90
  renderSvg: () => renderSvg,
@@ -393,7 +394,7 @@ var KEY_MASK = Object.freeze({
393
394
 
394
395
  // package.json
395
396
  var name = "astromansion";
396
- var version = "0.1.0-alpha.3";
397
+ var version = "0.1.0-alpha.5";
397
398
 
398
399
  // src/models/constants/package.ts
399
400
  var PACKAGE_IDENTITY = Object.freeze({
@@ -983,6 +984,9 @@ function isEclipseEvent(value) {
983
984
  function isEclipsesResponse(value) {
984
985
  return isJsonObject(value) && Number.isInteger(value["year"]) && (value["timezone"] === void 0 || typeof value["timezone"] === "string") && isJsonArrayOf(value["events"], (item0) => isEclipseEvent(item0));
985
986
  }
987
+ function isFramePole(value) {
988
+ return isJsonObject(value) && typeof value["ra_deg"] === "number" && typeof value["dec_deg"] === "number" && typeof value["model"] === "string" && typeof value["epoch"] === "string" && typeof value["fixed"] === "boolean";
989
+ }
986
990
  function isGeocentricFrame(value) {
987
991
  return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && typeof value["has_houses"] === "boolean";
988
992
  }
@@ -1026,7 +1030,7 @@ function isNatalResponse(value) {
1026
1030
  return isJsonObject(value) && isJsonRecordOf(value["summary"], (member0) => isSummaryRow(member0)) && isJsonArrayOf(value["planets"], (item0) => isBodyRow(item0)) && isJsonArrayOf(value["aspects"], (item0) => isAspectRow(item0)) && (value["wheel"] === void 0 || typeof value["wheel"] === "string" || value["wheel"] === null);
1027
1031
  }
1028
1032
  function isParentcentricFrame(value) {
1029
- return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && Number.isInteger(value["center"]) && typeof value["has_houses"] === "boolean";
1033
+ return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && Number.isInteger(value["center"]) && isFramePole(value["pole"]) && typeof value["has_houses"] === "boolean";
1030
1034
  }
1031
1035
  function isPlaceRow(value) {
1032
1036
  return isJsonObject(value) && typeof value["name"] === "string" && typeof value["label"] === "string" && typeof value["lat"] === "number" && typeof value["lon"] === "number" && typeof value["timezone"] === "string";
@@ -1047,7 +1051,10 @@ function isRetrogradesResponse(value) {
1047
1051
  return isJsonObject(value) && Number.isInteger(value["year"]) && (value["timezone"] === void 0 || typeof value["timezone"] === "string") && isJsonArrayOf(value["bodies"], (item0) => isRetrogradeBody(item0));
1048
1052
  }
1049
1053
  function isSatelliteGeocentric(value) {
1050
- return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && typeof value["correction_label"] === "string" && Number.isInteger(value["observer"]) && Number.isInteger(value["origin"]) && typeof value["distance_km"] === "number" && typeof value["light_time_seconds"] === "number" && typeof value["target_epoch_et"] === "number" && Number.isInteger(value["iterations"]) && typeof value["has_houses"] === "boolean";
1054
+ return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && typeof value["correction_label"] === "string" && Number.isInteger(value["observer"]) && Number.isInteger(value["origin"]) && (value["longitude"] === void 0 || typeof value["longitude"] === "number" || value["longitude"] === null) && (value["latitude"] === void 0 || typeof value["latitude"] === "number" || value["latitude"] === null) && (value["position_icrf_km"] === void 0 || isJsonArrayOf(
1055
+ value["position_icrf_km"],
1056
+ (item0) => typeof item0 === "number"
1057
+ ) || value["position_icrf_km"] === null) && typeof value["distance_km"] === "number" && typeof value["light_time_seconds"] === "number" && typeof value["target_epoch_et"] === "number" && Number.isInteger(value["iterations"]) && typeof value["has_houses"] === "boolean";
1051
1058
  }
1052
1059
  function isSatelliteParentcentric(value) {
1053
1060
  return isJsonObject(value) && typeof value["frame_id"] === "string" && typeof value["correction"] === "string" && (value["longitude"] === void 0 || typeof value["longitude"] === "number" || value["longitude"] === null) && (value["latitude"] === void 0 || typeof value["latitude"] === "number" || value["latitude"] === null) && typeof value["distance_km"] === "number" && Number.isInteger(value["sector"]) && (value["degree_in_sector"] === void 0 || typeof value["degree_in_sector"] === "number" || value["degree_in_sector"] === null) && typeof value["has_houses"] === "boolean";
@@ -1083,7 +1090,7 @@ function isSystemParent(value) {
1083
1090
  return isJsonObject(value) && typeof value["name"] === "string" && Number.isInteger(value["naif_id"]) && typeof value["natal_longitude"] === "number" && typeof value["natal_sign"] === "string" && (value["parentcentric_longitude"] === void 0 || value["parentcentric_longitude"] === null);
1084
1091
  }
1085
1092
  function isSystemTime(value) {
1086
- return isJsonObject(value) && typeof value["scale"] === "string" && typeof value["model"] === "string" && typeof value["et_seconds"] === "number" && typeof value["jd"] === "number";
1093
+ return isJsonObject(value) && typeof value["scale"] === "string" && typeof value["model"] === "string" && typeof value["et_seconds"] === "number" && typeof value["jd"] === "number" && Number.isInteger(value["offset_seconds"]) && typeof value["utc"] === "string" && typeof value["local"] === "string";
1087
1094
  }
1088
1095
  function isTechniqueEnvelope(value) {
1089
1096
  return isJsonObject(value) && typeof value["technique"] === "string" && value["result"] !== void 0;
@@ -1840,6 +1847,9 @@ var EndpointMethods = class {
1840
1847
  *
1841
1848
  * Export a chart as a PDF report.
1842
1849
  *
1850
+ * `options.watermark` defaults to true. Set it to false to omit the
1851
+ * centre logo. The document's paper remains painted.
1852
+ *
1843
1853
  * @param fields - The birth fields, flat: date, time, lat, lon, timezone, and houses. options and signal may stand beside them. output, the path to write the document to, is allowed among them.
1844
1854
  * @param keywords - The method's other arguments, when they come apart from the birth fields.
1845
1855
  * @returns The document's bytes, sent as application/pdf, or the path it was written to when output is given.
@@ -1871,13 +1881,16 @@ var EndpointMethods = class {
1871
1881
  * is charged only once the document exists, and a chart already paid for is
1872
1882
  * drawn again for free. Developer keys never spend credits.
1873
1883
  *
1874
- * Hiding the AstroMansion brand or embedding a custom logo additionally
1884
+ * Removing the document's AstroMansion branding or embedding a custom logo additionally
1875
1885
  * requires `Scope.WHITE_LABEL`. The plan that grants it is read from
1876
1886
  * `TierConstants`, so the error, the schema, and the pricing page name the same
1877
1887
  * plan. A request without that scope is rejected with 403 rather than
1878
1888
  * silently ignored: a machine caller cannot see a dropped field, and would
1879
- * ship a branded document it never got. The engine output is already
1880
- * unbranded. White-label access means applying the caller's brand.
1889
+ * ship a branded document it never got. White-label access means applying
1890
+ * the caller's brand and also removes the centre watermark.
1891
+ *
1892
+ * `watermark` defaults to true. Set it to false to omit only the faint
1893
+ * centre logo. This switch requires no additional branding scope.
1881
1894
  *
1882
1895
  * @param fields - The request body, as {@link ReportExportRequest} describes it, sent as given. signal may stand beside its fields. output, the path to write the document to, is allowed among them.
1883
1896
  * @param keywords - signal, and output for a document, when they come apart from the body.
@@ -2547,6 +2560,9 @@ var EndpointMethods = class {
2547
2560
  *
2548
2561
  * Render a bi-wheel SVG with natal and outer charts.
2549
2562
  *
2563
+ * `watermark` defaults to true. Set it to false to omit the centre logo.
2564
+ * Use render/chart for the full style and transparent surroundings options.
2565
+ *
2550
2566
  * @param birth - The first person's birth fields, as natal takes them.
2551
2567
  * @param partner - The second person's birth fields.
2552
2568
  * @param keywords - The options, signal, and the body's further fields. output, the path to write the document to, is allowed among them.
@@ -2575,6 +2591,57 @@ var EndpointMethods = class {
2575
2591
  writer
2576
2592
  );
2577
2593
  }
2594
+ /**
2595
+ * Any kind of chart as a styled wheel: natal, rising sign, transits, synastry, and more.
2596
+ *
2597
+ * @remarks
2598
+ * Sends `POST /v1/render/chart`. The Python SDK names it render_chart.
2599
+ *
2600
+ * Draw a chart of any kind as one wheel, in a style, as SVG or PNG.
2601
+ *
2602
+ * `type` names the kind. Each is cast by the technique of its own
2603
+ * endpoint, so the wheel shows what that endpoint answers. A wheel of two
2604
+ * charts draws the second on a ring of its own around the first one's
2605
+ * houses, with the chords between them. `options` takes the drawing's
2606
+ * settings of render/svg and render/png, `style` among them, and the
2607
+ * moment the kind is drawn for. An option the kind or the image does not
2608
+ * read is refused.
2609
+ *
2610
+ * Every heading names the drawn frame's Ascendant sign and degree.
2611
+ * `options.lang` selects `en` (the default) or `tr` for the heading
2612
+ * and rising centre caption. Body labels retain their published names.
2613
+ *
2614
+ * `options.style.show.watermark` controls faint branding: the centre
2615
+ * logo, or a wordmark below the zodiac on a rising-sign chart.
2616
+ * `options.style.show.canvas_background` defaults to true. Set it to false
2617
+ * to keep the wheel painted and its surroundings transparent in SVG or PNG.
2618
+ *
2619
+ * `saturn_return` reads `options.cycle` from 1 through 3, defaulting to
2620
+ * the first return. `options.custom_bodies` accepts up to eight Keplerian
2621
+ * bodies with the custom-body endpoint's orbital fields. They join the first
2622
+ * ring at its actual chart moment. A composite uses the midpoint of both
2623
+ * placements. Rising-sign charts accept no body selection or custom bodies.
2624
+ *
2625
+ * @param fields - The request body, as {@link ChartRenderRequest} describes it, sent as given. signal may stand beside its fields. output, the path to write the document to, is allowed among them.
2626
+ * @param keywords - signal, and output for a document, when they come apart from the body.
2627
+ * @returns The document's bytes, sent as image/svg+xml or image/png, or the path it was written to when output is given.
2628
+ * @throws {@link AstroMansionError} or the subclass that names the cause, as {@link AstroMansion.request} describes. The code unexpected_answer means the answer did not have its published shape.
2629
+ */
2630
+ async renderChart(fields, keywords) {
2631
+ const call = RequestBodies.body("renderChart", fields, keywords, true);
2632
+ const writer = documentWriter(call.output);
2633
+ const answer = await this.request("POST", "/v1/render/chart", {
2634
+ json: call.json,
2635
+ binary: true,
2636
+ technique: "render_chart",
2637
+ signal: call.signal
2638
+ });
2639
+ return saveDocument(
2640
+ readDocument(answer, "renderChart"),
2641
+ call.output,
2642
+ writer
2643
+ );
2644
+ }
2578
2645
  /**
2579
2646
  * Chart wheel PNG image.
2580
2647
  *
@@ -2583,6 +2650,15 @@ var EndpointMethods = class {
2583
2650
  *
2584
2651
  * Render a chart wheel as PNG.
2585
2652
  *
2653
+ * Every heading names the drawn frame's Ascendant sign and degree.
2654
+ * `options.lang` selects `en` (the default) or `tr` for the heading
2655
+ * and rising centre caption. Body labels retain their published names.
2656
+ *
2657
+ * `options.style.show.watermark` controls faint branding: the centre
2658
+ * logo, or a wordmark below the zodiac on a rising-sign chart.
2659
+ * `options.style.show.canvas_background` defaults to true. Set it to false
2660
+ * for transparent pixels outside the painted wheel.
2661
+ *
2586
2662
  * @param fields - The birth fields, flat: date, time, lat, lon, timezone, and houses. options and signal may stand beside them. output, the path to write the document to, is allowed among them.
2587
2663
  * @param keywords - The method's other arguments, when they come apart from the birth fields.
2588
2664
  * @returns The document's bytes, sent as image/png, or the path it was written to when output is given.
@@ -2608,6 +2684,11 @@ var EndpointMethods = class {
2608
2684
  *
2609
2685
  * Render a chart wheel as SVG or interactive HTML.
2610
2686
  *
2687
+ * `options.style.show.watermark` controls the faint centre logo.
2688
+ * `options.style.show.canvas_background` controls the rectangular ground
2689
+ * outside the wheel. Both default to true. Set the latter to false to keep
2690
+ * the wheel painted and its surroundings transparent.
2691
+ *
2611
2692
  * @param fields - The birth fields, flat: date, time, lat, lon, timezone, and houses. options and signal may stand beside them. output, the path to write the document to, is allowed among them.
2612
2693
  * @param keywords - The method's other arguments, when they come apart from the birth fields.
2613
2694
  * @returns The document's bytes, sent as image/svg+xml or text/html, or the path it was written to when output is given.
@@ -3986,6 +4067,9 @@ async function renderAstrocartography(...args) {
3986
4067
  async function renderBiwheel(...args) {
3987
4068
  return defaultClient().renderBiwheel(...args);
3988
4069
  }
4070
+ async function renderChart(...args) {
4071
+ return defaultClient().renderChart(...args);
4072
+ }
3989
4073
  async function renderPng(...args) {
3990
4074
  return defaultClient().renderPng(...args);
3991
4075
  }