@nshiab/simple-data-analysis 5.19.8

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/deleteFromBucket.js

@@ -0,0 +1,61 @@
+import { Storage } from "@google-cloud/storage";
+import process from "node:process";
+/**
+ * Deletes a specified file from a Google Cloud Storage (GCS) bucket.
+ *
+ * The function requires the Google Cloud project ID and the target bucket name. These can be provided either through environment variables (`BUCKET_PROJECT` and `BUCKET_NAME`) or directly as parameters in the `options` object. Parameters passed in `options` will take precedence over environment variables.
+ *
+ * By default, if the specified file does not exist in the bucket, the function will throw an error. However, you can suppress this behavior by setting the `try` option to `true`, which will cause the function to complete silently if the file is not found.
+ *
+ * @param destination The full path to the file within the bucket (e.g., 'my-folder/my-file.txt').
+ * @param options Optional configuration for the deletion operation.
+ * @param options.project The Google Cloud project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ * @param options.bucket The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @param options.try If `true`, the function will not throw an error if the file to be deleted does not exist. Defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * // Basic usage: Delete a file from the bucket.
+ * await deleteFromBucket("path/to/your/file.txt");
+ * ```
+ * @example
+ * ```ts
+ * // Delete a file, suppressing errors if it doesn't exist.
+ * await deleteFromBucket("path/to/non-existent-file.txt", { try: true });
+ * ```
+ * @example
+ * ```ts
+ * // Explicitly specify project ID and bucket name.
+ * await deleteFromBucket("reports/2023-summary.pdf", {
+ *   project: "my-gcp-project-id",
+ *   bucket: "my-data-bucket"
+ * });
+ * ```
+ * @category Google
+ */
+export default async function deleteFromBucket(destination, options = {}) {
+    const projectId = options.project ?? process.env.BUCKET_PROJECT;
+    const bucketName = options.bucket ?? process.env.BUCKET_NAME;
+    if (!projectId || !bucketName) {
+        throw new Error("Project ID and bucket name must be provided. Make sure to set BUCKET_PROJECT and BUCKET_NAME environment variables or pass them in options.");
+    }
+    const s = new Storage({ projectId });
+    const b = s.bucket(bucketName);
+    const file = b.file(destination);
+    if (options.try) {
+        try {
+            await file.delete();
+        }
+        catch (error) {
+            // Ignore 404 errors (file doesn't exist)
+            if (error instanceof Error && (error.message.includes("404") ||
+                error.message.includes("No such object"))) {
+                return;
+            }
+            throw error;
+        }
+    }
+    else {
+        await file.delete();
+    }
+}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/downloadFromBucket.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Downloads a file from a Google Cloud Storage (GCS) bucket to a specified local path. This function provides robust handling for existing local files, allowing you to skip downloads or overwrite files as needed.
+ *
+ * The function requires the Google Cloud project ID and the target bucket name. These can be provided either through environment variables (`BUCKET_PROJECT` and `BUCKET_NAME`) or directly as parameters in the `options` object. Parameters passed in `options` will take precedence over environment variables.
+ *
+ * By default, if a local file with the same name already exists at the `destination` path, the function will throw an error to prevent accidental overwrites. You can modify this behavior using the `skip` or `overwrite` options.
+ *
+ * @param source The path to the file within the GCS bucket (e.g., 'my-folder/document.pdf').
+ * @param destination The local file path where the downloaded file will be saved (e.g., './downloads/document.pdf').
+ * @param options Optional configuration for the download operation.
+ * @param options.project The Google Cloud project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ * @param options.bucket The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @param options.overwrite If `true`, an existing local file at the `destination` path will be overwritten. Cannot be used with `skip`. Defaults to `false`.
+ * @param options.skip If `true`, the download will be skipped if a local file already exists at the `destination` path. Cannot be used with `overwrite`. Defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * // Basic usage: Download a file.
+ * await downloadFromBucket("reports/annual-report.pdf", "./local-reports/annual-report.pdf");
+ * console.log("File downloaded successfully!");
+ * ```
+ * @example
+ * ```ts
+ * // Skip download if the file already exists locally.
+ * await downloadFromBucket("images/profile.jpg", "./local-images/profile.jpg", { skip: true });
+ * console.log("Download skipped if file exists, or downloaded otherwise.");
+ * ```
+ * @example
+ * ```ts
+ * // Overwrite an existing local file.
+ * await downloadFromBucket("data/latest-data.csv", "./local-data/latest-data.csv", { overwrite: true });
+ * console.log("File downloaded and overwritten if it existed.");
+ * ```
+ * @example
+ * ```ts
+ * // Specify project and bucket explicitly.
+ * await downloadFromBucket("configs/app-settings.json", "./local-configs/settings.json", {
+ *   project: "my-gcp-project",
+ *   bucket: "my-config-bucket"
+ * });
+ * ```
+ * @category Google
+ */
+export default function downloadFromBucket(source: string, destination: string, options?: {
+    project?: string;
+    bucket?: string;
+    overwrite?: boolean;
+    skip?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=downloadFromBucket.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/downloadFromBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloadFromBucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/downloadFromBucket.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAA8B,kBAAkB,CAC9C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/downloadFromBucket.js

@@ -0,0 +1,69 @@
+import { Storage } from "@google-cloud/storage";
+import process from "node:process";
+import { existsSync } from "node:fs";
+/**
+ * Downloads a file from a Google Cloud Storage (GCS) bucket to a specified local path. This function provides robust handling for existing local files, allowing you to skip downloads or overwrite files as needed.
+ *
+ * The function requires the Google Cloud project ID and the target bucket name. These can be provided either through environment variables (`BUCKET_PROJECT` and `BUCKET_NAME`) or directly as parameters in the `options` object. Parameters passed in `options` will take precedence over environment variables.
+ *
+ * By default, if a local file with the same name already exists at the `destination` path, the function will throw an error to prevent accidental overwrites. You can modify this behavior using the `skip` or `overwrite` options.
+ *
+ * @param source The path to the file within the GCS bucket (e.g., 'my-folder/document.pdf').
+ * @param destination The local file path where the downloaded file will be saved (e.g., './downloads/document.pdf').
+ * @param options Optional configuration for the download operation.
+ * @param options.project The Google Cloud project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ * @param options.bucket The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @param options.overwrite If `true`, an existing local file at the `destination` path will be overwritten. Cannot be used with `skip`. Defaults to `false`.
+ * @param options.skip If `true`, the download will be skipped if a local file already exists at the `destination` path. Cannot be used with `overwrite`. Defaults to `false`.
+ *
+ * @example
+ * ```ts
+ * // Basic usage: Download a file.
+ * await downloadFromBucket("reports/annual-report.pdf", "./local-reports/annual-report.pdf");
+ * console.log("File downloaded successfully!");
+ * ```
+ * @example
+ * ```ts
+ * // Skip download if the file already exists locally.
+ * await downloadFromBucket("images/profile.jpg", "./local-images/profile.jpg", { skip: true });
+ * console.log("Download skipped if file exists, or downloaded otherwise.");
+ * ```
+ * @example
+ * ```ts
+ * // Overwrite an existing local file.
+ * await downloadFromBucket("data/latest-data.csv", "./local-data/latest-data.csv", { overwrite: true });
+ * console.log("File downloaded and overwritten if it existed.");
+ * ```
+ * @example
+ * ```ts
+ * // Specify project and bucket explicitly.
+ * await downloadFromBucket("configs/app-settings.json", "./local-configs/settings.json", {
+ *   project: "my-gcp-project",
+ *   bucket: "my-config-bucket"
+ * });
+ * ```
+ * @category Google
+ */
+export default async function downloadFromBucket(source, destination, options = {}) {
+    const projectId = options.project ?? process.env.BUCKET_PROJECT;
+    const bucketName = options.bucket ?? process.env.BUCKET_NAME;
+    if (options.skip && options.overwrite) {
+        throw new Error("Cannot use both 'skip' and 'overwrite' options at the same time. Choose one: set 'skip: true' to skip existing files or 'overwrite: true' to replace them.");
+    }
+    if (!projectId || !bucketName) {
+        throw new Error("Project ID and bucket name must be provided. Make sure to set BUCKET_PROJECT and BUCKET_NAME environment variables or pass them in options.");
+    }
+    const localFileExists = existsSync(destination);
+    if (localFileExists) {
+        if (options.skip) {
+            return; // Skip download if file exists and skip is true
+        }
+        if (!options.overwrite) {
+            throw new Error(`Local file '${destination}' already exists. Set overwrite: true to replace it or skip: true to skip download.`);
+        }
+    }
+    const s = new Storage({ projectId });
+    const b = s.bucket(bucketName);
+    const file = b.file(source);
+    await file.download({ destination });
+}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/filesInBucket.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lists files within a Google Cloud Storage (GCS) bucket. You can list all files in the bucket or narrow down the results to a specific folder. The function can also return the full Google Storage URIs for each file.
+ *
+ * This function requires the Google Cloud project ID and the target bucket name. These can be provided either through environment variables (`BUCKET_PROJECT` and `BUCKET_NAME`) or directly as parameters in the `options` object. Parameters passed in `options` will take precedence over environment variables.
+ *
+ * @param options Optional configuration for listing files.
+ * @param options.folder The path to a specific folder within the bucket (e.g., 'my-data/'). Only files within this folder will be listed.
+ * @param options.project The Google Cloud project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ * @param options.bucket The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @param options.URI If `true`, the function will return the full Google Storage URI (e.g., 'gs://your-bucket/path/to/file.txt') for each file. Defaults to `false`, returning just the file path within the bucket.
+ *
+ * @returns An array of strings, where each string is either the file path within the bucket or its full Google Storage URI, depending on the `URI` option.
+ *
+ * @example
+ * ```ts
+ * // List all files in the default bucket.
+ * const allFiles = await filesInBucket();
+ * console.log("All files:", allFiles);
+ * ```
+ * @example
+ * ```ts
+ * // List files within a specific folder.
+ * const folderFiles = await filesInBucket({ folder: "images/thumbnails/" });
+ * console.log("Files in folder:", folderFiles);
+ * ```
+ * @example
+ * ```ts
+ * // Get Google Storage URIs for files in a folder.
+ * const fileURIs = await filesInBucket({ folder: "documents/", URI: true });
+ * console.log("File URIs:", fileURIs);
+ * ```
+ * @example
+ * ```ts
+ * // Explicitly specify project and bucket.
+ * const specificBucketFiles = await filesInBucket({
+ *   project: "my-gcp-project",
+ *   bucket: "my-archive-bucket",
+ *   folder: "old-data/"
+ * });
+ * console.log("Files from specific bucket:", specificBucketFiles);
+ * ```
+ * @category Google
+ */
+export default function filesInBucket(options?: {
+    folder?: string;
+    project?: string;
+    bucket?: string;
+    URI?: boolean;
+}): Promise<string[]>;
+//# sourceMappingURL=filesInBucket.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/filesInBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesInBucket.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/filesInBucket.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAA8B,aAAa,CACzC,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACV,GACL,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBnB"}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/filesInBucket.js

@@ -0,0 +1,62 @@
+import { Storage } from "@google-cloud/storage";
+import process from "node:process";
+/**
+ * Lists files within a Google Cloud Storage (GCS) bucket. You can list all files in the bucket or narrow down the results to a specific folder. The function can also return the full Google Storage URIs for each file.
+ *
+ * This function requires the Google Cloud project ID and the target bucket name. These can be provided either through environment variables (`BUCKET_PROJECT` and `BUCKET_NAME`) or directly as parameters in the `options` object. Parameters passed in `options` will take precedence over environment variables.
+ *
+ * @param options Optional configuration for listing files.
+ * @param options.folder The path to a specific folder within the bucket (e.g., 'my-data/'). Only files within this folder will be listed.
+ * @param options.project The Google Cloud project ID. If not provided, it defaults to the `BUCKET_PROJECT` environment variable.
+ * @param options.bucket The name of the Google Cloud Storage bucket. If not provided, it defaults to the `BUCKET_NAME` environment variable.
+ * @param options.URI If `true`, the function will return the full Google Storage URI (e.g., 'gs://your-bucket/path/to/file.txt') for each file. Defaults to `false`, returning just the file path within the bucket.
+ *
+ * @returns An array of strings, where each string is either the file path within the bucket or its full Google Storage URI, depending on the `URI` option.
+ *
+ * @example
+ * ```ts
+ * // List all files in the default bucket.
+ * const allFiles = await filesInBucket();
+ * console.log("All files:", allFiles);
+ * ```
+ * @example
+ * ```ts
+ * // List files within a specific folder.
+ * const folderFiles = await filesInBucket({ folder: "images/thumbnails/" });
+ * console.log("Files in folder:", folderFiles);
+ * ```
+ * @example
+ * ```ts
+ * // Get Google Storage URIs for files in a folder.
+ * const fileURIs = await filesInBucket({ folder: "documents/", URI: true });
+ * console.log("File URIs:", fileURIs);
+ * ```
+ * @example
+ * ```ts
+ * // Explicitly specify project and bucket.
+ * const specificBucketFiles = await filesInBucket({
+ *   project: "my-gcp-project",
+ *   bucket: "my-archive-bucket",
+ *   folder: "old-data/"
+ * });
+ * console.log("Files from specific bucket:", specificBucketFiles);
+ * ```
+ * @category Google
+ */
+export default async function filesInBucket(options = {}) {
+    const projectId = options.project ?? process.env.BUCKET_PROJECT;
+    const bucketName = options.bucket ?? process.env.BUCKET_NAME;
+    const folder = options.folder;
+    const URI = options.URI ?? false;
+    if (!projectId || !bucketName) {
+        throw new Error("Project ID and bucket name must be provided. Make sure to set BUCKET_PROJECT and BUCKET_NAME environment variables or pass them in options.");
+    }
+    const s = new Storage({ projectId });
+    const b = s.bucket(bucketName);
+    const [files] = await b.getFiles({ prefix: folder, autoPaginate: true });
+    if (URI) {
+        return files.map((file) => `gs://${bucketName}/${file.name}`);
+    }
+    // Default: return file paths
+    return files.map((file) => file.name);
+}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/getSheetData.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Retrieves data from a Google Sheet.
+ *
+ * By default, this function attempts to authenticate using environment variables (`GOOGLE_PRIVATE_KEY` for the API key and `GOOGLE_SERVICE_ACCOUNT_EMAIL` for the service account email). Alternatively, you can use `GOOGLE_APPLICATION_CREDENTIALS` pointing to a service account JSON file. For detailed instructions on setting up credentials, refer to the `node-google-spreadsheet` authentication guide: [https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication).
+ *
+ * @param sheetUrl - The URL of the Google Sheet from which to retrieve data. This URL should point to a specific sheet (e.g., ending with `#gid=0`).
+ * @param options - An optional object with configuration options:
+ *   @param options.skip - The number of rows to skip from the beginning of the sheet before parsing the data. This is useful for sheets that have metadata at the top. Defaults to `0`.
+ *   @param options.csv - If `true`, the function will return the raw data as a CSV string. If `false` or omitted, it will return an array of objects, where each object represents a row and keys correspond to column headers. Defaults to `false`.
+ *   @param options.apiEmail - Optional. Your Google Service Account email. If provided, this will override the `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable.
+ *   @param options.apiKey - Optional. Your Google Service Account private key. If provided, this will override the `GOOGLE_PRIVATE_KEY` environment variable.
+ * @returns A Promise that resolves to either an array of objects (`Record<string, string>[]`) if `options.csv` is `false`, or a CSV string (`string`) if `options.csv` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Fake URL used as an example.
+ * const sheetUrl = "https://docs.google.com/spreadsheets/d/nrqo3oP4KMWYbELScQa8W1nHZPfIrA7LIz9UmcRE4GyJN/edit#gid=0";
+ *
+ * // Returning the data as an array of objects.
+ * const data = await getSheetData(sheetUrl);
+ * console.log(data);
+ * // Expected output (example):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Retrieve data, skipping the first row (e.g., if it contains metadata).
+ * const dataSkippingFirstRow = await getSheetData(sheetUrl, { skip: 1 });
+ * console.log(dataSkippingFirstRow);
+ * // Expected output (example, assuming first row was metadata):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Return the data as a raw CSV string, useful for direct writing to files or other systems.
+ * const csvString = await getSheetData(sheetUrl, { csv: true });
+ * console.log(csvString);
+ * // Expected output (example):
+ * // "Header1,Header2\nValue1,Value2\nValue3,Value4"
+ * ```
+ * @example
+ * ```ts
+ * // Use custom environment variable names for API email and key.
+ * const dataWithCustomCredentials = await getSheetData(sheetUrl, {
+ *   apiEmail: "GG_EMAIL",
+ *   apiKey: "GG_KEY"
+ * });
+ * console.log(dataWithCustomCredentials);
+ * ```
+ * @category Google
+ */
+export default function getSheetData(sheetUrl: string, options: {
+    csv: true;
+    skip?: number;
+    apiEmail?: string;
+    apiKey?: string;
+}): Promise<string>;
+/**
+ * Retrieves data from a Google Sheet.
+ *
+ * By default, this function attempts to authenticate using environment variables (`GOOGLE_PRIVATE_KEY` for the API key and `GOOGLE_SERVICE_ACCOUNT_EMAIL` for the service account email). Alternatively, you can use `GOOGLE_APPLICATION_CREDENTIALS` pointing to a service account JSON file. For detailed instructions on setting up credentials, refer to the `node-google-spreadsheet` authentication guide: [https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication).
+ *
+ * @param sheetUrl - The URL of the Google Sheet from which to retrieve data. This URL should point to a specific sheet (e.g., ending with `#gid=0`).
+ * @param options - An optional object with configuration options:
+ *   @param options.skip - The number of rows to skip from the beginning of the sheet before parsing the data. This is useful for sheets that have metadata at the top. Defaults to `0`.
+ *   @param options.csv - If `true`, the function will return the raw data as a CSV string. If `false` or omitted, it will return an array of objects, where each object represents a row and keys correspond to column headers. Defaults to `false`.
+ *   @param options.apiEmail - Optional. Your Google Service Account email. If provided, this will override the `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable.
+ *   @param options.apiKey - Optional. Your Google Service Account private key. If provided, this will override the `GOOGLE_PRIVATE_KEY` environment variable.
+ * @returns A Promise that resolves to either an array of objects (`Record<string, string>[]`) if `options.csv` is `false`, or a CSV string (`string`) if `options.csv` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Fake URL used as an example.
+ * const sheetUrl = "https://docs.google.com/spreadsheets/d/nrqo3oP4KMWYbELScQa8W1nHZPfIrA7LIz9UmcRE4GyJN/edit#gid=0";
+ *
+ * // Returning the data as an array of objects.
+ * const data = await getSheetData(sheetUrl);
+ * console.log(data);
+ * // Expected output (example):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Retrieve data, skipping the first row (e.g., if it contains metadata).
+ * const dataSkippingFirstRow = await getSheetData(sheetUrl, { skip: 1 });
+ * console.log(dataSkippingFirstRow);
+ * // Expected output (example, assuming first row was metadata):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Return the data as a raw CSV string, useful for direct writing to files or other systems.
+ * const csvString = await getSheetData(sheetUrl, { csv: true });
+ * console.log(csvString);
+ * // Expected output (example):
+ * // "Header1,Header2\nValue1,Value2\nValue3,Value4"
+ * ```
+ * @example
+ * ```ts
+ * // Use custom environment variable names for API email and key.
+ * const dataWithCustomCredentials = await getSheetData(sheetUrl, {
+ *   apiEmail: "GG_EMAIL",
+ *   apiKey: "GG_KEY"
+ * });
+ * console.log(dataWithCustomCredentials);
+ * ```
+ * @category Google
+ */
+export default function getSheetData(sheetUrl: string, options?: {
+    csv?: false;
+    skip?: number;
+    apiEmail?: string;
+    apiKey?: string;
+}): Promise<Record<string, string>[]>;
+//# sourceMappingURL=getSheetData.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/getSheetData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSheetData.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/getSheetData.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/getSheetData.js

@@ -0,0 +1,76 @@
+import { csvParse } from "d3-dsv";
+import logToSheet from "./helpers/logToSheet.js";
+/**
+ * Retrieves data from a Google Sheet.
+ *
+ * By default, this function attempts to authenticate using environment variables (`GOOGLE_PRIVATE_KEY` for the API key and `GOOGLE_SERVICE_ACCOUNT_EMAIL` for the service account email). Alternatively, you can use `GOOGLE_APPLICATION_CREDENTIALS` pointing to a service account JSON file. For detailed instructions on setting up credentials, refer to the `node-google-spreadsheet` authentication guide: [https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication).
+ *
+ * @param sheetUrl - The URL of the Google Sheet from which to retrieve data. This URL should point to a specific sheet (e.g., ending with `#gid=0`).
+ * @param options - An optional object with configuration options:
+ *   @param options.skip - The number of rows to skip from the beginning of the sheet before parsing the data. This is useful for sheets that have metadata at the top. Defaults to `0`.
+ *   @param options.csv - If `true`, the function will return the raw data as a CSV string. If `false` or omitted, it will return an array of objects, where each object represents a row and keys correspond to column headers. Defaults to `false`.
+ *   @param options.apiEmail - Optional. Your Google Service Account email. If provided, this will override the `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable.
+ *   @param options.apiKey - Optional. Your Google Service Account private key. If provided, this will override the `GOOGLE_PRIVATE_KEY` environment variable.
+ * @returns A Promise that resolves to either an array of objects (`Record<string, string>[]`) if `options.csv` is `false`, or a CSV string (`string`) if `options.csv` is `true`.
+ *
+ * @example
+ * ```ts
+ * // Fake URL used as an example.
+ * const sheetUrl = "https://docs.google.com/spreadsheets/d/nrqo3oP4KMWYbELScQa8W1nHZPfIrA7LIz9UmcRE4GyJN/edit#gid=0";
+ *
+ * // Returning the data as an array of objects.
+ * const data = await getSheetData(sheetUrl);
+ * console.log(data);
+ * // Expected output (example):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Retrieve data, skipping the first row (e.g., if it contains metadata).
+ * const dataSkippingFirstRow = await getSheetData(sheetUrl, { skip: 1 });
+ * console.log(dataSkippingFirstRow);
+ * // Expected output (example, assuming first row was metadata):
+ * // [
+ * //   { Header1: 'Value1', Header2: 'Value2' },
+ * //   { Header1: 'Value3', Header2: 'Value4' }
+ * // ]
+ * ```
+ * @example
+ * ```ts
+ * // Return the data as a raw CSV string, useful for direct writing to files or other systems.
+ * const csvString = await getSheetData(sheetUrl, { csv: true });
+ * console.log(csvString);
+ * // Expected output (example):
+ * // "Header1,Header2\nValue1,Value2\nValue3,Value4"
+ * ```
+ * @example
+ * ```ts
+ * // Use custom environment variable names for API email and key.
+ * const dataWithCustomCredentials = await getSheetData(sheetUrl, {
+ *   apiEmail: "GG_EMAIL",
+ *   apiKey: "GG_KEY"
+ * });
+ * console.log(dataWithCustomCredentials);
+ * ```
+ * @category Google
+ */
+export default async function getSheetData(sheetUrl, options = {}) {
+    const sheet = await logToSheet(sheetUrl, options);
+    const buffer = await sheet.downloadAsCSV();
+    const enc = new TextDecoder("utf-8");
+    let csv = enc.decode(buffer);
+    if (typeof options.skip === "number") {
+        csv = csv.split("\n").slice(options.skip).join("\n");
+    }
+    if (options.csv) {
+        return csv;
+    }
+    else {
+        const data = csvParse(csv);
+        delete data.columns;
+        return data;
+    }
+}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/cleanData.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cleans data by replacing null values with empty strings.
+ * @param data The data to clean.
+ * @returns The cleaned data.
+ */
+export default function cleanData(data: {
+    [key: string]: string | number | boolean | Date | null;
+}[]): {
+    [key: string]: string | number | boolean | Date;
+}[];
+//# sourceMappingURL=cleanData.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/cleanData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanData.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/cleanData.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAA;CAAE,EAAE,GACjE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;CAAE,EAAE,CAYvD"}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/cleanData.js

@@ -0,0 +1,19 @@
+/**
+ * Cleans data by replacing null values with empty strings.
+ * @param data The data to clean.
+ * @returns The cleaned data.
+ */
+export default function cleanData(data) {
+    return data.map((row) => {
+        const cleanedRow = {};
+        for (const key in row) {
+            if (row[key] === null) {
+                cleanedRow[key] = "";
+            }
+            else {
+                cleanedRow[key] = row[key];
+            }
+        }
+        return cleanedRow;
+    });
+}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/logToSheet.d.ts

@@ -0,0 +1,12 @@
+import { type GoogleSpreadsheetWorksheet } from "google-spreadsheet";
+/**
+ * Authenticates with Google Sheets and returns a worksheet object.
+ * @param sheetUrl The URL of the Google Sheet.
+ * @param options Optional authentication options.
+ * @returns A GoogleSpreadsheetWorksheet object.
+ */
+export default function logToSheet(sheetUrl: string, options?: {
+    apiEmail?: string;
+    apiKey?: string;
+}): Promise<GoogleSpreadsheetWorksheet>;
+//# sourceMappingURL=logToSheet.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/logToSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logToSheet.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/logToSheet.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,wBAA8B,UAAU,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,uCAmDrD"}

package/esm/deps/jsr.io/@nshiab/journalism-google/1.0.6/src/google/helpers/logToSheet.js

@@ -0,0 +1,46 @@
+import process from "node:process";
+import { existsSync, readFileSync } from "node:fs";
+import { JWT } from "google-auth-library";
+import { GoogleSpreadsheet, } from "google-spreadsheet";
+/**
+ * Authenticates with Google Sheets and returns a worksheet object.
+ * @param sheetUrl The URL of the Google Sheet.
+ * @param options Optional authentication options.
+ * @returns A GoogleSpreadsheetWorksheet object.
+ */
+export default async function logToSheet(sheetUrl, options = {}) {
+    const urlItems = sheetUrl.split("/");
+    const spreadsheetId = urlItems[5];
+    const sheetId = urlItems[6].split("=")[1];
+    const emailVar = options.apiEmail ?? "GOOGLE_SERVICE_ACCOUNT_EMAIL";
+    const keyVar = options.apiKey ?? "GOOGLE_PRIVATE_KEY";
+    let email = process.env[emailVar];
+    let key = process.env[keyVar];
+    // Support GOOGLE_APPLICATION_CREDENTIALS
+    if (process.env.GOOGLE_APPLICATION_CREDENTIALS !== undefined &&
+        process.env.GOOGLE_APPLICATION_CREDENTIALS !== "" &&
+        existsSync(process.env.GOOGLE_APPLICATION_CREDENTIALS)) {
+        const creds = JSON.parse(readFileSync(process.env.GOOGLE_APPLICATION_CREDENTIALS, "utf-8"));
+        email = creds.client_email;
+        key = creds.private_key;
+    }
+    if (email === undefined || email === "") {
+        throw new Error(`process.env.${emailVar} is undefined or ''.`);
+    }
+    if (key === undefined || key === "") {
+        throw new Error(`process.env.${keyVar} is undefined or ''.`);
+    }
+    const jwt = new JWT({
+        email,
+        key,
+        scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+    });
+    const spreadsheet = new GoogleSpreadsheet(spreadsheetId, jwt);
+    await spreadsheet.loadInfo();
+    // @ts-expect-error sheetId is a string, but indexes are number?
+    const sheet = spreadsheet.sheetsById[sheetId];
+    if (sheet === undefined) {
+        throw new Error(`Sheet with ID ${sheetId} not found. Make sure the sheet URL ends with just one gid=ID.`);
+    }
+    return sheet;
+}