chore: update docs + schema, cleanup + fixes

ahochsteger · ahochsteger · commit 077e5d2aae11 · 2025-03-02T14:25:08.000+01:00
diff --git a/docs/docs/community/CONTRIBUTING.md b/docs/docs/community/CONTRIBUTING.md
@@ -101,16 +101,22 @@ npm run pre-commit
 
 The recommended IDE for this project is [Visual Studio Code](https://code.visualstudio.com/), but any other IDEs with support for TypeScript and NPM will do. Make sure to configure the IDE to respect the [Code Style](#code-style) settings.
 
-### Testing
+### Code Style
+
+We use [Prettier](https://prettier.io/) to automatically format our code and ensure a consistent style. It is recommended to [configure your IDE](https://prettier.io/docs/en/editors) to format the code (e.g. on saving) using Prettier.
+
+### Testing Locally
 
 Please add/update the tests for any change to keep the codebase in a well-tested state. For every source file `*.ts` the corresponding test file is named `*.spec.ts` and they are implemented using [Jest](https://jestjs.io/) as the testing framework.
 Remote services are mocked (see [MockFactory.ts](https://github.com/ahochsteger/gmail-processor/blob/main/src/test/mocks/MockFactory.ts)) to simplify local testing in isolation.
 
 After the changes and tests are done run the `pre-commit` script that validates the changes and updates all generated artifacts (like documentation, examples, JSON schema files, ...) and include all updated files in your commit.
 
-### Code Style
+### Beta Testing on Google Apps Script
 
-We use [Prettier](https://prettier.io/) to automatically format our code and ensure a consistent style. It is recommended to [configure your IDE](https://prettier.io/docs/en/editors) to format the code (e.g. on saving) using Prettier.
+Use the following Script ID in combination with the version `HEAD` to test and give feedback before changes are released:
+
+`1yhOQyl_xWtnGJn_bzlL7oA4d_q5KoMyZyWIqXDJX1SY7bi22_lpjMiQK`
 
 ### Development Resources
 
diff --git a/docs/docs/reference/actions.mdx b/docs/docs/reference/actions.mdx
@@ -42,6 +42,18 @@ Store an attachment to a Google Drive location.
 | `location` | `string` | The location (path + filename) of the Google Drive file.<br />For shared folders or Team Drives prepend the location with the folder ID like `{id:<folderId>}/...`.<br />Supports [placeholder](placeholder.mdx) substitution. |
 | `toMimeType` | `string` | Convert to a Google file type using one of the <a href="https://developers.google.com/drive/api/guides/mime-types?hl=en">supported mime-types by Google Drive</a>, like:<br />* `application/vnd.google-apps.document`: Google Docs<br />* `application/vnd.google-apps.presentation`: Google Slides<br />* `application/vnd.google-apps.spreadsheet`: Google Sheets |
 
+### `attachment.storeDecryptedPdf`
+
+Decrypt a PDF attachment and store it to a Google Drive location.<br />NOTE: PDF decryption is done in an asynchronous process which causes<br />some limitations (failure detection, logs will appear later mixed with<br />other actions).
+
+| Arguments | Type | Description |
+|-----------|------|-------------|
+| `conflictStrategy` | `ConflictStrategy` | The strategy to be used in case a file already exists at the desired location. See [Enum Type `ConflictStrategy`](enum-types.mdx#conflictstrategy) for valid values. |
+| `description` | `string` | The description to be attached to the Google Drive file.<br />Supports [placeholder](placeholder.mdx) substitution. |
+| `location` | `string` | The location (path + filename) of the Google Drive file.<br />For shared folders or Team Drives prepend the location with the folder ID like `{id:<folderId>}/...`.<br />Supports [placeholder](placeholder.mdx) substitution. |
+| `password` | `string` | The password to be used PDF decryption. |
+| `toMimeType` | `string` | Convert to a Google file type using one of the <a href="https://developers.google.com/drive/api/guides/mime-types?hl=en">supported mime-types by Google Drive</a>, like:<br />* `application/vnd.google-apps.document`: Google Docs<br />* `application/vnd.google-apps.presentation`: Google Slides<br />* `application/vnd.google-apps.spreadsheet`: Google Sheets |
+
 ## Global Actions
 
 ### `global.log`
diff --git a/docs/docs/reference/placeholder.mdx b/docs/docs/reference/placeholder.mdx
@@ -16,9 +16,9 @@ These placeholder are valid globally and can also be used for internal purposes
 | <a id="placeholder.date.now">`date.now`</a> | Current Timestamp | The current timestamp. Use `"${<key>:date::<format>}"` to format the date/time using a custom [date-fns format strings](https://date-fns.org/docs/format) (default: `"yyyy-MM-dd HH:mm:ss"`). | `"2023-06-26 09:00:00"` |
 | <a id="placeholder.env.runMode">`env.runMode`</a> | Runmode | The runMode used for processing. | `"safe-mode"` |
 | <a id="placeholder.env.timezone">`env.timezone`</a> | Timezone | The timezone used for processing. | `"Etc/UTC"` |
-| <a id="placeholder.lib.description">`lib.description`</a> | Library Description | The description of the Gmail Processor library. | `""` |
-| <a id="placeholder.lib.name">`lib.name`</a> | Library Name | The name of the Gmail Processor library. | `"gmail-processor"` |
-| <a id="placeholder.lib.version">`lib.version`</a> | Library Version | The version of the Gmail Processor library. | `"0.0.0"` |
+| <a id="placeholder.lib.description">`lib.description`</a> | Library Description | The description of the Gmail Processor library. | `"__PACKAGE_DESCRIPTION__"` |
+| <a id="placeholder.lib.name">`lib.name`</a> | Library Name | The name of the Gmail Processor library. | `"__PACKAGE_NAME__"` |
+| <a id="placeholder.lib.version">`lib.version`</a> | Library Version | The version of the Gmail Processor library. | `"__PACKAGE_VERSION__"` |
 | <a id="placeholder.user.email">`user.email`</a> | User Email | The email address of the active user. | `"my.email@gmail.com"` |
 
 ## Processing Placeholder
diff --git a/global.d.ts b/global.d.ts
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -103,6 +103,7 @@
     "@rollup/plugin-commonjs": "28.0.2",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "16.0.0",
+    "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "0.4.4",
     "@rollup/plugin-typescript": "12.1.2",
     "@types/addressparser": "1.0.3",
diff --git a/rollup.config.mjs b/rollup.config.mjs
@@ -2,13 +2,17 @@ import { babel } from "@rollup/plugin-babel"
 import commonjs from "@rollup/plugin-commonjs"
 import json from "@rollup/plugin-json"
 import resolve from "@rollup/plugin-node-resolve"
+import replace from "@rollup/plugin-replace"
 import terser from "@rollup/plugin-terser"
 import typescript from "@rollup/plugin-typescript"
+import fs from "fs"
 import { defineConfig } from "rollup"
 import analyzer from "rollup-plugin-analyzer"
 import gas from "rollup-plugin-google-apps-script"
 import { visualizer } from "rollup-plugin-visualizer"
 
+const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"))
+
 export default defineConfig({
   context: "globalThis",
   input: "./build/lib/index.js",
@@ -18,6 +22,14 @@ export default defineConfig({
     name: "GmailProcessorLib",
   },
   plugins: [
+    replace({
+      preventAssignment: true,
+      values: {
+        __PACKAGE_DESCRIPTION__: pkg.description,
+        __PACKAGE_NAME__: pkg.name,
+        __PACKAGE_VERSION__: pkg.version,
+      },
+    }),
     json(),
     resolve({
       //preferBuiltins: false,
diff --git a/scripts/update-examples.sh b/scripts/update-examples.sh
@@ -6,6 +6,14 @@ export EXAMPLE_SRC_BASEDIR="${EXAMPLE_SRC_BASEDIR:-src/examples}"
 export GAS_EXAMPLES_BASEDIR="${GAS_EXAMPLES_BASEDIR:-src/gas/examples}"
 export TEMPLATES_BASEDIR="${TEMPLATES_BASEDIR:-src/templates}"
 
+# Validate examples (e.g. no direct lib includes - causes docs build failure):
+echo "Checking for invalid lib includes ... "
+(
+  find "${EXAMPLE_SRC_BASEDIR}" -type f -name '*.ts' \
+  | grep -E -v '\.spec\.ts$' \
+  | xargs grep -E 'from "../../lib"$'
+) && exit 1
+
 # Remove generated files (otherwise typedoc may fail):
 npx ts-node scripts/update-examples.ts clean
 
diff --git a/src/examples/advanced/decryptPdf.ts b/src/examples/advanced/decryptPdf.ts
@@ -1,7 +1,7 @@
-import { ConflictStrategy } from "../../lib"
-import { ProcessingStatus } from "../../lib/Context"
+import { ConflictStrategy } from "../../lib/adapter/GDriveAdapter"
 import { Config } from "../../lib/config/Config"
 import { MarkProcessedMethod } from "../../lib/config/SettingsConfig"
+import { ProcessingStatus } from "../../lib/Context"
 import { E2EInitConfig, E2ETest, E2ETestConfig } from "../../lib/e2e/E2E"
 import { Example, ExampleCategory, ExampleInfo } from "../Example"
 import { E2EDefaults } from "./../../lib/e2e/E2EDefaults"
diff --git a/src/lib/EnvProvider.ts b/src/lib/EnvProvider.ts
@@ -1,4 +1,3 @@
-import * as packageInfo from "../../package.json"
 import {
   ContextType,
   EnvContext,
@@ -32,19 +31,19 @@ export class EnvProvider {
       ),
       "lib.description": mi(
         MIT.STRING,
-        () => packageInfo.description,
+        () => "__PACKAGE_DESCRIPTION__", // NOTE: Is replaced during build
         "Library Description",
         "The description of the Gmail Processor library.",
       ),
       "lib.name": mi(
         MIT.STRING,
-        () => packageInfo.name,
+        () => "__PACKAGE_NAME__", // NOTE: Is replaced during build
         "Library Name",
         "The name of the Gmail Processor library.",
       ),
       "lib.version": mi(
         MIT.STRING,
-        () => packageInfo.version,
+        () => "__PACKAGE_VERSION__", // NOTE: Is replaced during build
         "Library Version",
         "The version of the Gmail Processor library.",
       ),
diff --git a/src/lib/actions/AttachmentActions.spec.ts b/src/lib/actions/AttachmentActions.spec.ts
@@ -32,6 +32,7 @@ it("should provide actions in the action registry", () => {
     "attachment.extractText",
     "attachment.noop",
     "attachment.store",
+    "attachment.storeDecryptedPdf",
   ])
 })
 
diff --git a/src/lib/config/config-schema-v2.json b/src/lib/config/config-schema-v2.json
@@ -197,6 +197,38 @@
                     ],
                     "type": "object"
                 },
+                {
+                    "additionalProperties": false,
+                    "properties": {
+                        "args": {
+                            "$ref": "#/definitions/StoreDecryptedPdfActionArgs",
+                            "title": "args"
+                        },
+                        "description": {
+                            "title": "description",
+                            "type": "string"
+                        },
+                        "name": {
+                            "const": "attachment.storeDecryptedPdf",
+                            "title": "name",
+                            "type": "string"
+                        },
+                        "processingStage": {
+                            "description": "The stage of action processing",
+                            "enum": [
+                                "main",
+                                "post-main",
+                                "pre-main"
+                            ],
+                            "title": "processingStage",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "name"
+                    ],
+                    "type": "object"
+                },
                 {
                     "additionalProperties": false,
                     "properties": {
@@ -2998,6 +3030,43 @@
             "title": "SettingsConfig",
             "type": "object"
         },
+        "StoreDecryptedPdfActionArgs": {
+            "additionalProperties": false,
+            "properties": {
+                "conflictStrategy": {
+                    "$ref": "#/definitions/ConflictStrategy",
+                    "description": "The strategy to be used in case a file already exists at the desired location.",
+                    "title": "conflictStrategy"
+                },
+                "description": {
+                    "description": "The description to be attached to the Google Drive file.\nSupports placeholder substitution.",
+                    "title": "description",
+                    "type": "string"
+                },
+                "location": {
+                    "description": "The location (path + filename) of the Google Drive file.\nFor shared folders or Team Drives prepend the location with the folder ID like `{id:<folderId>}/...`.\nSupports placeholder substitution.",
+                    "title": "location",
+                    "type": "string"
+                },
+                "password": {
+                    "description": "The password to be used PDF decryption.",
+                    "title": "password",
+                    "type": "string"
+                },
+                "toMimeType": {
+                    "description": "Convert to a Google file type using one of the <a href=\"https://developers.google.com/drive/api/guides/mime-types?hl=en\">supported mime-types by Google Drive</a>, like:\n* `application/vnd.google-apps.document`: Google Docs\n* `application/vnd.google-apps.presentation`: Google Slides\n* `application/vnd.google-apps.spreadsheet`: Google Sheets",
+                    "title": "toMimeType",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "conflictStrategy",
+                "location",
+                "password"
+            ],
+            "title": "StoreDecryptedPdfActionArgs",
+            "type": "object"
+        },
         "ThreadActionArgsStorePDF": {
             "additionalProperties": false,
             "properties": {
diff --git a/tsconfig.json b/tsconfig.json
@@ -20,5 +20,5 @@
     "target": "ES2019",
     "types": ["google-apps-script", "jest", "node"]
   },
-  "include": ["src/lib/**/*", "global.d.ts"]
+  "include": ["src/lib/**/*"]
 }
