@nshiab/simple-data-analysis 5.19.8

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateAnnotationsDW.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Updates annotations on a Datawrapper chart. This function allows you to programmatically add, modify, or remove text and line annotations on your Datawrapper visualizations, providing precise control over highlighting specific data points or trends.
+ *
+ * This function supports various annotation properties, including position, text content, styling (bold, italic, color, size), alignment, and connector lines with customizable arrowheads.
+ *
+ * Authentication is handled via an API key, which can be provided through environment variables (`DATAWRAPPER_KEY`) or explicitly in the options. For detailed information on Datawrapper annotations and their properties, refer to the official Datawrapper API documentation.
+ *
+ * @param chartId - The ID of the Datawrapper chart to update. This ID can be found in the Datawrapper URL or dashboard.
+ * @param annotations - An array of annotation objects. Each object defines a single annotation with its properties. Required properties for each annotation are `x`, `y`, and `text`.
+ *   @param annotations.x - The x-coordinate of the annotation's position on the chart.
+ *   @param annotations.y - The y-coordinate of the annotation's position on the chart.
+ *   @param annotations.text - The text content of the annotation.
+ *   @param annotations.bg - If `true`, the annotation text will have a background. Defaults to `false`.
+ *   @param annotations.dx - The horizontal offset of the annotation text from its `x` coordinate, in pixels. Defaults to `0`.
+ *   @param annotations.dy - The vertical offset of the annotation text from its `y` coordinate, in pixels. Defaults to `0`.
+ *   @param annotations.bold - If `true`, the annotation text will be bold. Defaults to `false`.
+ *   @param annotations.size - The font size of the annotation text in pixels. Defaults to `12`.
+ *   @param annotations.align - The alignment of the annotation text relative to its `x` and `y` coordinates. Can be `"tl"` (top-left), `"tc"` (top-center), `"tr"` (top-right), `"ml"` (middle-left), `"mc"` (middle-center), `"mr"` (middle-right), `"bl"` (bottom-left), `"bc"` (bottom-center), or `"br"` (bottom-right). Defaults to `"mr"`.
+ *   @param annotations.color - The color of the annotation text (e.g., `"#FF0000"`, `"red"`). Defaults to `"#8C8C8C"`.
+ *   @param annotations.width - The maximum width of the annotation text box in pixels. Text will wrap if it exceeds this width. Defaults to `20`.
+ *   @param annotations.italic - If `true`, the annotation text will be italic. Defaults to `false`.
+ *   @param annotations.underline - If `true`, the annotation text will be underlined. Defaults to `false`.
+ *   @param annotations.showMobile - If `true`, the annotation will be visible on mobile devices. Defaults to `true`.
+ *   @param annotations.showDesktop - If `true`, the annotation will be visible on desktop devices. Defaults to `true`.
+ *   @param annotations.mobileFallback - If `true`, the annotation will be displayed as a simple text label on mobile if it's too complex. Defaults to `false`.
+ *   @param annotations.connectorLine - An object defining the properties of a connector line from the annotation to a data point.
+ *     @param annotations.connectorLine.type - The type of the connector line. Can be `"straight"`, `"curveRight"`, or `"curveLeft"`. Defaults to `"straight"`.
+ *     @param annotations.connectorLine.circle - If `true`, a circle will be drawn at the end of the connector line. Defaults to `false`.
+ *     @param annotations.connectorLine.stroke - The stroke width of the connector line. Can be `1`, `2`, or `3`. Defaults to `1`.
+ *     @param annotations.connectorLine.enabled - If `true`, the connector line will be drawn. Defaults to `false`.
+ *     @param annotations.connectorLine.arrowHead - The style of the arrowhead. Can be `"lines"`, `"triangle"`, or `false` (no arrowhead). Defaults to `"lines"`.
+ *     @param annotations.connectorLine.circleStyle - The style of the circle at the end of the connector line. Defaults to `"solid"`.
+ *     @param annotations.connectorLine.circleRadius - The radius of the circle at the end of the connector line. Defaults to `10`.
+ *     @param annotations.connectorLine.inheritColor - If `true`, the connector line will inherit the annotation's text color. Defaults to `false`.
+ *     @param annotations.connectorLine.targetPadding - The padding between the end of the connector line and the target data point. Defaults to `4`.
+ * @param options.apiKey - The name of the environment variable that stores your Datawrapper API key. If not provided, the function defaults to looking for `DATAWRAPPER_KEY`.
+ * @param options.returnResponse - If `true`, the function will return the full `Response` object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.
+ * @returns A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Update annotations on a Datawrapper chart with a simple text annotation and one with an arrow.
+ *
+ * const chartID = "myChartId";
+ * const myAnnotations = [
+ *    {
+ *        "x": "2024/08/30 01:52",
+ *        "y": "14496235",
+ *        "text": "This is an annotation!"
+ *    },
+ *    {
+ *        "x": "2024/06/29",
+ *        "y": "15035128",
+ *        "dy": 50,
+ *        "text": "This is also some text, but with an arrow!",
+ *        "connectorLine": {
+ *            "enabled": true,
+ *            "type": "straight",
+ *            "arrowHead": "lines"
+ *        },
+ *        "mobileFallback": false
+ *    }
+ * ];
+ *
+ * await updateAnnotationsDW(chartID, myAnnotations);
+ * console.log(`Annotations updated for chart ${chartID}.`);
+ * ```
+ * @example
+ * ```ts
+ * // If your Datawrapper API key is stored under a different environment variable name (e.g., `DW_API_KEY`).
+ * const customApiKeyChartID = "anotherChartId";
+ * const annotationsForCustomKey = [
+ *   { x: "2024/01/01", y: "100", text: "Custom API Key Test" }
+ * ];
+ * await updateAnnotationsDW(customApiKeyChartID, annotationsForCustomKey, { apiKey: "DW_API_KEY" });
+ * console.log(`Annotations updated for chart ${customApiKeyChartID} using custom API key.`);
+ * ```
+ * @category Dataviz
+ */
+export default function updateAnnotationsDW(chartId: string, annotations: {
+    x: string;
+    y: string;
+    text: string;
+    bg?: boolean;
+    dx?: number;
+    dy?: number;
+    bold?: boolean;
+    size?: number;
+    align?: "tl" | "tc" | "tr" | "ml" | "mc" | "mr" | "bl" | "bc" | "br";
+    color?: string;
+    width?: number;
+    italic?: boolean;
+    underline?: boolean;
+    showMobile?: boolean;
+    showDesktop?: boolean;
+    mobileFallback?: boolean;
+    connectorLine?: {
+        type?: "straight" | "curveRight" | "curveLeft";
+        circle?: boolean;
+        stroke?: 1 | 2 | 3;
+        enabled?: boolean;
+        arrowHead?: "lines" | "triangle" | false;
+        circleStyle?: string;
+        circleRadius?: number;
+        inheritColor?: boolean;
+        targetPadding?: number;
+    };
+}[], options?: {
+    apiKey?: string;
+    returnResponse?: boolean;
+}): Promise<void | Response>;
+//# sourceMappingURL=updateAnnotationsDW.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateAnnotationsDW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateAnnotationsDW.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateAnnotationsDW.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,wBAA8B,mBAAmB,CAC/C,OAAO,EAAE,MAAM,EACf,WAAW,EAAE;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE;QACd,IAAI,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,WAAW,CAAC;QAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC;QACzC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH,EAAE,EACH,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAoF1B"}

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateAnnotationsDW.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = updateAnnotationsDW;
+const node_process_1 = __importDefault(require("node:process"));
+/**
+ * Updates annotations on a Datawrapper chart. This function allows you to programmatically add, modify, or remove text and line annotations on your Datawrapper visualizations, providing precise control over highlighting specific data points or trends.
+ *
+ * This function supports various annotation properties, including position, text content, styling (bold, italic, color, size), alignment, and connector lines with customizable arrowheads.
+ *
+ * Authentication is handled via an API key, which can be provided through environment variables (`DATAWRAPPER_KEY`) or explicitly in the options. For detailed information on Datawrapper annotations and their properties, refer to the official Datawrapper API documentation.
+ *
+ * @param chartId - The ID of the Datawrapper chart to update. This ID can be found in the Datawrapper URL or dashboard.
+ * @param annotations - An array of annotation objects. Each object defines a single annotation with its properties. Required properties for each annotation are `x`, `y`, and `text`.
+ *   @param annotations.x - The x-coordinate of the annotation's position on the chart.
+ *   @param annotations.y - The y-coordinate of the annotation's position on the chart.
+ *   @param annotations.text - The text content of the annotation.
+ *   @param annotations.bg - If `true`, the annotation text will have a background. Defaults to `false`.
+ *   @param annotations.dx - The horizontal offset of the annotation text from its `x` coordinate, in pixels. Defaults to `0`.
+ *   @param annotations.dy - The vertical offset of the annotation text from its `y` coordinate, in pixels. Defaults to `0`.
+ *   @param annotations.bold - If `true`, the annotation text will be bold. Defaults to `false`.
+ *   @param annotations.size - The font size of the annotation text in pixels. Defaults to `12`.
+ *   @param annotations.align - The alignment of the annotation text relative to its `x` and `y` coordinates. Can be `"tl"` (top-left), `"tc"` (top-center), `"tr"` (top-right), `"ml"` (middle-left), `"mc"` (middle-center), `"mr"` (middle-right), `"bl"` (bottom-left), `"bc"` (bottom-center), or `"br"` (bottom-right). Defaults to `"mr"`.
+ *   @param annotations.color - The color of the annotation text (e.g., `"#FF0000"`, `"red"`). Defaults to `"#8C8C8C"`.
+ *   @param annotations.width - The maximum width of the annotation text box in pixels. Text will wrap if it exceeds this width. Defaults to `20`.
+ *   @param annotations.italic - If `true`, the annotation text will be italic. Defaults to `false`.
+ *   @param annotations.underline - If `true`, the annotation text will be underlined. Defaults to `false`.
+ *   @param annotations.showMobile - If `true`, the annotation will be visible on mobile devices. Defaults to `true`.
+ *   @param annotations.showDesktop - If `true`, the annotation will be visible on desktop devices. Defaults to `true`.
+ *   @param annotations.mobileFallback - If `true`, the annotation will be displayed as a simple text label on mobile if it's too complex. Defaults to `false`.
+ *   @param annotations.connectorLine - An object defining the properties of a connector line from the annotation to a data point.
+ *     @param annotations.connectorLine.type - The type of the connector line. Can be `"straight"`, `"curveRight"`, or `"curveLeft"`. Defaults to `"straight"`.
+ *     @param annotations.connectorLine.circle - If `true`, a circle will be drawn at the end of the connector line. Defaults to `false`.
+ *     @param annotations.connectorLine.stroke - The stroke width of the connector line. Can be `1`, `2`, or `3`. Defaults to `1`.
+ *     @param annotations.connectorLine.enabled - If `true`, the connector line will be drawn. Defaults to `false`.
+ *     @param annotations.connectorLine.arrowHead - The style of the arrowhead. Can be `"lines"`, `"triangle"`, or `false` (no arrowhead). Defaults to `"lines"`.
+ *     @param annotations.connectorLine.circleStyle - The style of the circle at the end of the connector line. Defaults to `"solid"`.
+ *     @param annotations.connectorLine.circleRadius - The radius of the circle at the end of the connector line. Defaults to `10`.
+ *     @param annotations.connectorLine.inheritColor - If `true`, the connector line will inherit the annotation's text color. Defaults to `false`.
+ *     @param annotations.connectorLine.targetPadding - The padding between the end of the connector line and the target data point. Defaults to `4`.
+ * @param options.apiKey - The name of the environment variable that stores your Datawrapper API key. If not provided, the function defaults to looking for `DATAWRAPPER_KEY`.
+ * @param options.returnResponse - If `true`, the function will return the full `Response` object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.
+ * @returns A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Update annotations on a Datawrapper chart with a simple text annotation and one with an arrow.
+ *
+ * const chartID = "myChartId";
+ * const myAnnotations = [
+ *    {
+ *        "x": "2024/08/30 01:52",
+ *        "y": "14496235",
+ *        "text": "This is an annotation!"
+ *    },
+ *    {
+ *        "x": "2024/06/29",
+ *        "y": "15035128",
+ *        "dy": 50,
+ *        "text": "This is also some text, but with an arrow!",
+ *        "connectorLine": {
+ *            "enabled": true,
+ *            "type": "straight",
+ *            "arrowHead": "lines"
+ *        },
+ *        "mobileFallback": false
+ *    }
+ * ];
+ *
+ * await updateAnnotationsDW(chartID, myAnnotations);
+ * console.log(`Annotations updated for chart ${chartID}.`);
+ * ```
+ * @example
+ * ```ts
+ * // If your Datawrapper API key is stored under a different environment variable name (e.g., `DW_API_KEY`).
+ * const customApiKeyChartID = "anotherChartId";
+ * const annotationsForCustomKey = [
+ *   { x: "2024/01/01", y: "100", text: "Custom API Key Test" }
+ * ];
+ * await updateAnnotationsDW(customApiKeyChartID, annotationsForCustomKey, { apiKey: "DW_API_KEY" });
+ * console.log(`Annotations updated for chart ${customApiKeyChartID} using custom API key.`);
+ * ```
+ * @category Dataviz
+ */
+async function updateAnnotationsDW(chartId, annotations, options = {}) {
+    const envVar = options.apiKey ?? "DATAWRAPPER_KEY";
+    const apiKey = node_process_1.default.env[envVar];
+    if (apiKey === undefined || apiKey === "") {
+        throw new Error(`process.env.${envVar} is undefined or ''.`);
+    }
+    // We set defaults as non-nested objects
+    const defaultsWithoutConnectorLine = {
+        bg: false,
+        dx: 0,
+        dy: 0,
+        bold: false,
+        size: 12,
+        align: "mr",
+        color: "#8C8C8C",
+        width: 20,
+        italic: false,
+        underline: false,
+        showMobile: true,
+        showDesktop: true,
+        mobileFallback: false,
+    };
+    const defaultConnectorLine = {
+        type: "straight",
+        circle: false,
+        stroke: 1,
+        enabled: false,
+        arrowHead: "lines",
+        circleStyle: "solid",
+        circleRadius: 10,
+        inheritColor: false,
+        targetPadding: 4,
+    };
+    // We map over annotations to add defaults.
+    const annotationsWithDefaults = annotations.map((annotation) => {
+        // We check for mandatory values.
+        if (!annotation.x || !annotation.y || !annotation.text) {
+            throw new Error("Missing x, y, or text for at least one annotation.");
+        }
+        // We extract the connectorLine from the rest
+        const { connectorLine, ...rest } = annotation;
+        // We create the nested object required for the DW API. We pass the defaults first, then we overwrite them with any value passed by the user.
+        return {
+            ...defaultsWithoutConnectorLine,
+            ...rest,
+            connectorLine: { ...defaultConnectorLine, ...connectorLine },
+        };
+    });
+    const response = await fetch(`https://api.datawrapper.de/v3/charts/${chartId}`, {
+        method: "PATCH",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            metadata: {
+                visualize: {
+                    "text-annotations": annotationsWithDefaults,
+                },
+            },
+        }),
+    });
+    await response.json();
+    // if returning a response, do it before the response.status checks
+    if (options.returnResponse === true) {
+        return response;
+    }
+    if (response.status !== 200) {
+        throw new Error(`updateAnnotationsDW ${chartId}: Upstream HTTP ${response.status} - ${response.statusText}`);
+    }
+}

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateDataDW.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Updates the data of a specified Datawrapper chart, table, or map. This function is essential for keeping your Datawrapper visualizations dynamic and up-to-date with the latest information. It supports both CSV data for standard charts and tables, and JSON data for more complex visualizations like locator maps.
+ *
+ * Datawrapper is a powerful tool for creating interactive data visualizations. This function allows for programmatic updates, which is ideal for automated data pipelines, dashboards, or applications that require fresh data to be reflected in visualizations without manual intervention.
+ *
+ * Authentication is handled via an API key, which can be provided through environment variables (`process.env.DATAWRAPPER_KEY`) or explicitly in the options. The `Content-Type` header for the API request is automatically set based on whether the data is CSV or JSON.
+ *
+ * @param chartId - The unique ID of the Datawrapper chart, table, or map to update. This ID can be found in the Datawrapper URL or dashboard.
+ * @param data - The data to update the chart, table, or map with. For standard charts and tables, this should be a CSV formatted string. For locator maps, this should be a JSON string representing the map's data (e.g., markers, areas).
+ * @param options - Optional parameters to configure the data update process.
+ *   @param options.apiKey - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for `process.env.DATAWRAPPER_KEY`.
+ *   @param options.returnResponse - If `true`, the function will return the full `Response` object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.
+ * @returns A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.
+ * @throws {Error} If the API key is not found, if the Datawrapper API returns an error status (e.g., invalid chart ID, authentication failure, malformed data), or if there's a network issue.
+ *
+ * @example
+ * ```ts
+ * // Update the data of a Datawrapper chart or table with CSV formatted data.
+ * import { updateDataDW, dataAsCsv } from "journalism";
+ *
+ * const chartID = "myChartId";
+ * const data = [
+ *  { salary: 75000, hireDate: new Date("2022-12-15") },
+ *  { salary: 80000, hireDate: new Date("2023-01-20") },
+ * ];
+ * const dataForChart = dataAsCsv(data);
+ *
+ * await updateDataDW(chartID, dataForChart);
+ * console.log(`Data updated for chart ${chartID}.`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Update the data of a Datawrapper locator map with GeoJSON data.
+ *
+ * const mapID = "myMapId";
+ * const geojson = {
+ *  "type": "FeatureCollection",
+ *   "features": [
+ *     {
+ *       "type": "Feature",
+ *       "properties": {},
+ *       "geometry": {
+ *         "coordinates": [
+ *           [
+ *             [
+ *               11.127454320325711,
+ *               20.34856592751224
+ *             ],
+ *             [
+ *               11.127454320325711,
+ *               -13.781306861158996
+ *             ],
+ *             [
+ *               55.68071875381875,
+ *               -13.781306861158996
+ *             ],
+ *             [
+ *               55.68071875381875,
+ *               20.34856592751224
+ *             ],
+ *             [
+ *               11.127454320325711,
+ *               20.34856592751224
+ *             ]
+ *           ]
+ *         ],
+ *         "type": "Polygon"
+ *       }
+ *     }
+ *   ]
+ * };
+ *
+ * const dataForMap = {
+ *   "markers": [
+ *     {
+ *       "id": "m1",
+ *       "type": "area",
+ *       "visible": true,
+ *       "exactShape": true,
+ *       "fill": true,
+ *       "stroke": true,
+ *       "properties": {
+ *         "fill": "#15607a",
+ *         "fill-opacity": 0.2,
+ *         "stroke": "#15607a",
+ *         "stroke-width": 1,
+ *         "stroke-opacity": 1,
+ *         "stroke-dasharray": "100000",
+ *         "pattern": "solid",
+ *         "pattern-line-width": 2,
+ *         "pattern-line-gap": 2
+ *       },
+ *       "feature": geojson
+ *     }
+ *   ]
+ * };
+ *
+ * await updateDataDW(mapID, JSON.stringify(dataForMap));
+ * console.log(`Data updated for map ${mapID}.`);
+ * ```
+ * @example
+ * ```ts
+ * // If your API key is stored under a different name in process.env, use the options.
+ * const chartIDCustomKey = "anotherChartId";
+ * const dataForCustomKey = "col1,col2\nval1,val2";
+ * await updateDataDW(chartIDCustomKey, dataForCustomKey, { apiKey: "DW_KEY" });
+ * console.log(`Data updated for chart ${chartIDCustomKey} using custom API key.`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Attempting to update data without a configured API key will throw an error.
+ * try {
+ *   await updateDataDW("someChartId", "data", { apiKey: "NON_EXISTENT_KEY" });
+ * } catch (error) {
+ *   console.error("Error:", error.message);
+ *   // Expected output: "Error: process.env.NON_EXISTENT_KEY is undefined or ''"
+ * }
+ * ```
+ *
+ * @category Dataviz
+ */
+export default function updateDataDW(chartId: string, data: string, options?: {
+    apiKey?: string;
+    returnResponse?: boolean;
+}): Promise<void | Response>;
+//# sourceMappingURL=updateDataDW.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateDataDW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateDataDW.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateDataDW.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AAEH,wBAA8B,YAAY,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CA6B1B"}

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateDataDW.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = updateDataDW;
+const node_process_1 = __importDefault(require("node:process"));
+/**
+ * Updates the data of a specified Datawrapper chart, table, or map. This function is essential for keeping your Datawrapper visualizations dynamic and up-to-date with the latest information. It supports both CSV data for standard charts and tables, and JSON data for more complex visualizations like locator maps.
+ *
+ * Datawrapper is a powerful tool for creating interactive data visualizations. This function allows for programmatic updates, which is ideal for automated data pipelines, dashboards, or applications that require fresh data to be reflected in visualizations without manual intervention.
+ *
+ * Authentication is handled via an API key, which can be provided through environment variables (`process.env.DATAWRAPPER_KEY`) or explicitly in the options. The `Content-Type` header for the API request is automatically set based on whether the data is CSV or JSON.
+ *
+ * @param chartId - The unique ID of the Datawrapper chart, table, or map to update. This ID can be found in the Datawrapper URL or dashboard.
+ * @param data - The data to update the chart, table, or map with. For standard charts and tables, this should be a CSV formatted string. For locator maps, this should be a JSON string representing the map's data (e.g., markers, areas).
+ * @param options - Optional parameters to configure the data update process.
+ *   @param options.apiKey - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for `process.env.DATAWRAPPER_KEY`.
+ *   @param options.returnResponse - If `true`, the function will return the full `Response` object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.
+ * @returns A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.
+ * @throws {Error} If the API key is not found, if the Datawrapper API returns an error status (e.g., invalid chart ID, authentication failure, malformed data), or if there's a network issue.
+ *
+ * @example
+ * ```ts
+ * // Update the data of a Datawrapper chart or table with CSV formatted data.
+ * import { updateDataDW, dataAsCsv } from "journalism";
+ *
+ * const chartID = "myChartId";
+ * const data = [
+ *  { salary: 75000, hireDate: new Date("2022-12-15") },
+ *  { salary: 80000, hireDate: new Date("2023-01-20") },
+ * ];
+ * const dataForChart = dataAsCsv(data);
+ *
+ * await updateDataDW(chartID, dataForChart);
+ * console.log(`Data updated for chart ${chartID}.`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Update the data of a Datawrapper locator map with GeoJSON data.
+ *
+ * const mapID = "myMapId";
+ * const geojson = {
+ *  "type": "FeatureCollection",
+ *   "features": [
+ *     {
+ *       "type": "Feature",
+ *       "properties": {},
+ *       "geometry": {
+ *         "coordinates": [
+ *           [
+ *             [
+ *               11.127454320325711,
+ *               20.34856592751224
+ *             ],
+ *             [
+ *               11.127454320325711,
+ *               -13.781306861158996
+ *             ],
+ *             [
+ *               55.68071875381875,
+ *               -13.781306861158996
+ *             ],
+ *             [
+ *               55.68071875381875,
+ *               20.34856592751224
+ *             ],
+ *             [
+ *               11.127454320325711,
+ *               20.34856592751224
+ *             ]
+ *           ]
+ *         ],
+ *         "type": "Polygon"
+ *       }
+ *     }
+ *   ]
+ * };
+ *
+ * const dataForMap = {
+ *   "markers": [
+ *     {
+ *       "id": "m1",
+ *       "type": "area",
+ *       "visible": true,
+ *       "exactShape": true,
+ *       "fill": true,
+ *       "stroke": true,
+ *       "properties": {
+ *         "fill": "#15607a",
+ *         "fill-opacity": 0.2,
+ *         "stroke": "#15607a",
+ *         "stroke-width": 1,
+ *         "stroke-opacity": 1,
+ *         "stroke-dasharray": "100000",
+ *         "pattern": "solid",
+ *         "pattern-line-width": 2,
+ *         "pattern-line-gap": 2
+ *       },
+ *       "feature": geojson
+ *     }
+ *   ]
+ * };
+ *
+ * await updateDataDW(mapID, JSON.stringify(dataForMap));
+ * console.log(`Data updated for map ${mapID}.`);
+ * ```
+ * @example
+ * ```ts
+ * // If your API key is stored under a different name in process.env, use the options.
+ * const chartIDCustomKey = "anotherChartId";
+ * const dataForCustomKey = "col1,col2\nval1,val2";
+ * await updateDataDW(chartIDCustomKey, dataForCustomKey, { apiKey: "DW_KEY" });
+ * console.log(`Data updated for chart ${chartIDCustomKey} using custom API key.`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Attempting to update data without a configured API key will throw an error.
+ * try {
+ *   await updateDataDW("someChartId", "data", { apiKey: "NON_EXISTENT_KEY" });
+ * } catch (error) {
+ *   console.error("Error:", error.message);
+ *   // Expected output: "Error: process.env.NON_EXISTENT_KEY is undefined or ''"
+ * }
+ * ```
+ *
+ * @category Dataviz
+ */
+async function updateDataDW(chartId, data, options = {}) {
+    const envVar = options.apiKey ?? "DATAWRAPPER_KEY";
+    const apiKey = node_process_1.default.env[envVar];
+    if (apiKey === undefined || apiKey === "") {
+        throw new Error(`process.env.${envVar} is undefined or ''.`);
+    }
+    const response = await fetch(`https://api.datawrapper.de/v3/charts/${chartId}/data`, {
+        method: "PUT",
+        body: data,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "text/csv",
+        },
+    });
+    // if returning a response, do it before the response.status checks
+    if (options.returnResponse === true) {
+        return response;
+    }
+    if (response.status !== 204) {
+        throw new Error(`updateDataDW ${chartId}: Upstream HTTP ${response.status} - ${response.statusText}`);
+    }
+}

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateNotesDW.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Updates the notes field for a specified Datawrapper chart, table, or map. This function provides a programmatic way to add or modify descriptive text associated with your Datawrapper visualizations, which can include data sources, methodologies, or any other relevant context.
+ *
+ * Authentication is handled via an API key, which can be provided through environment variables (`DATAWRAPPER_KEY`) or explicitly in the options.
+ *
+ * @param chartId - The unique ID of the Datawrapper chart, table, or map to update. This ID can be found in the Datawrapper URL or dashboard.
+ * @param note - The string content to update the chart's notes field with.
+ * @param options - Optional parameters to configure the notes update process.
+ *   @param options.apiKey - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for the `DATAWRAPPER_KEY` environment variable.
+ *   @param options.returnResponse - If `true`, the function will return the full `Response` object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.
+ * @returns A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Update the notes field of a Datawrapper chart with a simple text string.
+ * import { updateNotesDW, formatDate } from "journalism";
+ *
+ * const chartID = "myChartId";
+ * const dateString = formatDate(new Date(), "Month DD, YYYY, at HH:MM period", { abbreviations: true });
+ * const note = `This chart was last updated on ${dateString}`;
+ *
+ * await updateNotesDW(chartID, note);
+ * console.log(`Notes updated for chart ${chartID}.`);
+ * ```
+ * @example
+ * ```ts
+ * // If your API key is stored under a different name in process.env (e.g., `DW_KEY`).
+ * const customApiKeyChartID = "anotherChartId";
+ * const customNote = "This is a note using a custom API key.";
+ * await updateNotesDW(customApiKeyChartID, customNote, { apiKey: "DW_KEY" });
+ * console.log(`Notes updated for chart ${customApiKeyChartID} using custom API key.`);
+ * ```
+ * @category Dataviz
+ */
+export default function updateNotesDW(chartId: string, note: string, options?: {
+    apiKey?: string;
+    returnResponse?: boolean;
+}): Promise<void | Response>;
+//# sourceMappingURL=updateNotesDW.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateNotesDW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateNotesDW.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-dataviz/1.0.10/src/dataviz/updateNotesDW.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAA8B,aAAa,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAoC1B"}