html-to-gutenberg 4.2.9 → 4.2.10

package/readme.md

@@ -1,136 +1,170 @@
 # HTML to Gutenberg Converter
 
-<!-- [![Build Status](https://github.com/DiogoAngelim/html-to-gutenberg/actions/workflows/main.yml/badge.svg?cacheBust=1)](https://github.com/DiogoAngelim/html-to-gutenberg/actions)
-[![Coverage Status](https://coveralls.io/repos/github/DiogoAngelim/html-to-gutenberg/badge.svg?branch=main&cacheBust=1)](https://coveralls.io/github/DiogoAngelim/html-to-gutenberg?branch=main) -->
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DiogoAngelim/html-to-gutenberg/blob/main/LICENSE.MD)
 
-  
+Convert HTML into editable WordPress Gutenberg blocks and publish the generated package to Cloudflare R2 without writing the output to disk.
 
-Convert HTML strings to valid, editable WordPress Gutenberg blocks in seconds instead of hours. With this lib, you can create and build valid Gutenberg blocks that feature editable text, forms, inline and background images, as well as SVGs.
+## What changed
 
+- `html-to-gutenberg` now supports a `job` output mode that uploads generated files to R2 and returns a JSON manifest.
+- `fetch-page-assets` can upload downloaded assets directly to R2 and return their metadata.
+- Output bundles are zipped in memory and uploaded to R2 as `output.zip`.
+- Secrets stay in `.env` and should never be committed.
 
-## Features
-
-  
-
-- 🪄 **Instantly transforms static HTML into Gutenberg blocks**
-Saves hours of manual work by automating block creation from any valid HTML snippet.
-
-- 🔌 **Generates a complete, installable WordPress block plugin**
-Outputs all necessary plugin files (JS, CSS, PHP) so you can drop them into WordPress immediately.
-  
-
-- 🎨 **Keeps your design intact**
-Automatically extracts and preserves CSS from the original HTML into a separate `style.css`.
-
-
-- 🧩 **Modular and scalable**
-Separates assets (JS, CSS, components) into clean files, making it easy to maintain and extend.
-  
-
-- 📦 **Seamlessly integrates with dynamic block systems**
-Works perfectly for headless or custom Gutenberg setups where blocks are registered via JS, not PHP.
-  
-
-- 🚀 **Speeds up prototyping**
-Ideal for quickly testing block ideas or converting landing pages and templates into WordPress blocks.
-
-  
-- 🧠 **Works with your file system or plugin builder logic**
-Since it returns all files as either strings or source files, you can save them however you like (via PHP, APIs, etc.).
-
-
-- 🧰 **Built for automation and customization**
-Can be embedded in custom tools, UIs, or pipelines to generate Gutenberg blocks on demand.
+## Installation
 
-## How it works
+```bash
+npm install html-to-gutenberg
+```
 
-This package is actually an alternative when AI fails converting it, which is usually very common.
+## Environment
 
-Most of the logic is just hard-coded patterns. It first converts from plain HTML to Jsx (using the `html-to-jsx` package), which is the supported format of Gutenberg. Then, it follows structured conversion rules that build the WordPress block, which is then validated and parsed using Babel.
+Copy `.env.example` to `.env` and keep the real values private.
 
+```bash
+cp .env.example .env
+```
 
-## The Building Process - An Overview
+Required for R2-backed job output:
 
+- `CLOUDFLARE_R2_ACCOUNT_ID`
+- `CLOUDFLARE_R2_BUCKET`
+- `CLOUDFLARE_R2_ACCESS_KEY_ID`
+- `CLOUDFLARE_R2_SECRET_ACCESS_KEY`
+- `CLOUDFLARE_R2_PUBLIC_BASE_URL`
 
-Below is a visual overview of the block generation process:
+Optional:
 
-![Block Generation Process](process.png)  
+- `CLOUDFLARE_API_TOKEN`
+- `SNAPAPI_KEY`
 
+## Getting and rotating Cloudflare credentials
 
-## Installation
+1. Open the Cloudflare dashboard.
+2. Create or update your R2 access keys for the target bucket.
+3. Store the new values in `.env`.
+4. If you use a Cloudflare API token for verification or account workflows, create a new token in the API Tokens section and update `.env`.
+5. Restart your app or redeploy after updating `.env`.
+6. Revoke the old token or key after the new one is live.
 
-  
-Install html-to-gutenberg with npm:
+To verify a Cloudflare API token without exposing it in code, use an environment variable:
 
 ```bash
-
-npm  install  html-to-gutenberg
-
+curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
 ```
 
-  
-
-## Usage/Examples
-
-  
+## Usage
 
-```javascript
+```js
+import block from 'html-to-gutenberg';
 
-// block-generator.js
+const result = await block('<div>Hello world</div>', {
+  title: 'Marketing Hero',
+  slug: 'marketing-hero',
+  namespace: 'wp',
+  baseUrl: 'https://example.com',
+  outputMode: 'job',
+  uploadToR2: true,
+  jobId: 'conv_123'
+});
 
-import  block  from  'html-to-gutenberg';
+console.log(result);
+```
 
-const  htmlString = '<div>My content</div>';
+Example response:
 
+```json
 {
-	const files = await  block(htmlString, { name:  'My Block' });
-	console.log(files);
+  "jobId": "conv_123",
+  "status": "completed",
+  "output": {
+    "files": [
+      {
+        "id": "file_1",
+        "name": "block.js",
+        "type": "text/javascript",
+        "size": 18234,
+        "path": "/generated/conv_123/block.js",
+        "url": "https://storage.example.com/generated/conv_123/block.js",
+        "kind": "source"
+      },
+      {
+        "id": "file_2",
+        "name": "asset.png",
+        "type": "image/png",
+        "size": 48211,
+        "path": "/generated/conv_123/assets/asset.png",
+        "url": "https://storage.example.com/generated/conv_123/assets/asset.png",
+        "kind": "asset"
+      }
+    ],
+    "bundle": {
+      "name": "output.zip",
+      "path": "/generated/conv_123/output.zip",
+      "url": "https://storage.example.com/generated/conv_123/output.zip",
+      "zipUrl": "https://storage.example.com/generated/conv_123/output.zip"
+    }
+  }
 }
-
 ```
 
-  
+## Legacy mode
 
+If you still need the previous local-string output for existing tooling or tests, use:
 
-When provided with a valid HTML string with the desired options, the block function will generate the necessary WordPress block files with the specified configuration. To install the block and its assets, simply load the generated folder into the plugins folder and activate it as a plugin.
-  
-
-## Options reference
+```js
+const files = await block('<div>Hello world</div>', {
+  title: 'Legacy Block',
+  outputPath: process.cwd(),
+  writeFiles: false,
+  outputMode: 'legacy'
+});
+```
 
+In `legacy` mode, the function returns the generated file contents instead of the R2 job manifest.
 
-| Option              | Description                                                                                                                                           | Type     | Required?                                                                                          | Default            |
-|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------|-------------------|
-| name                | The name of your block. This will also be used for the folder name and internal references.                                                          | string   | Yes                                                                                                 | My block          |
-| source              | A URL where relative paths resolve. E.g., `http://localhost/website`.                                                                     | string   | Yes, only if the HTML string or the stylesheet has relative paths.                             | null              |
-| prefix              | A namespace prefix for the block name, typically aligned with your project (e.g., "wp" or "myplugins").                                              | string   | No                                                                                                  | wp                |
-| category            | The WordPress block category where the block appears in the editor. Use an existing one or register a custom category if needed.                    | string   | No                                                                                                  | common            |
-| basePath            | The absolute path where the output files and folders will be saved.                                                                                  | string   | No                                                                                                  | Current directory |
-| generateIconPreview | If you enable the `generateIconPreview` option by setting it to `true`, this package will generate a static image preview of your block using the [SnapAPI](https://snapapi.pics/) screenshot service. You must provide a SnapAPI key in a `.env` file (see below), which will display it a replacement for the block icons in the WP dashboard. | boolean  | No                                                                                                  | false             |
-| shouldSaveFiles     | When `true`, the generated block files are saved directly to disk. When `false`, returns an object containing the file contents as strings instead. | boolean  | No                                                                                                  | true              |
-| jsFiles             | An array of external JavaScript file URLs to enqueue with the block on the editor and the frontend. Useful for adding remote libraries.             | string[] | No                                                                                                  | []                |
-| cssFiles            | An array of external CSS file URLs to enqueue with the block on the editor and the frontend. Useful for adding additional remote stylesheets.        | string[] | No                                                                                                  | []                |
+## Options
 
+| Option | Description | Type | Default |
+| --- | --- | --- | --- |
+| `title` | Human-readable block title shown in the editor. | `string` | `My block` |
+| `slug` | Filesystem-safe internal block name. Defaults to a slugified title. | `string` | slugified `title` |
+| `baseUrl` | Base URL used to resolve relative asset paths in HTML and CSS. | `string \| null` | `null` |
+| `namespace` | Gutenberg block namespace. | `string` | `wp` |
+| `category` | Gutenberg block category. | `string` | `common` |
+| `registerCategoryIfMissing` | Adds a custom editor category before block registration when needed. | `boolean` | `false` |
+| `outputPath` | Absolute directory used for local legacy output. In `job` mode it is only a logical working base. | `string` | current directory |
+| `writeFiles` | Writes local files in `legacy` mode. When `false`, returns generated files in memory. | `boolean` | `false` in the streamlined API |
+| `generatePreviewImage` | Generates and uploads `preview.jpeg` using SnapAPI. | `boolean` | `false` |
+| `jsFiles` | Remote JS dependencies to enqueue. | `string[]` | `[]` |
+| `cssFiles` | Remote CSS dependencies to enqueue. | `string[]` | `[]` |
+| `outputMode` | Advanced option. `job` uploads to R2 and returns JSON. `legacy` returns raw file contents. | `'job' \| 'legacy'` | `job`, unless local-output options imply `legacy` |
+| `uploadToR2` | Advanced option to force or disable R2 uploads. | `boolean` | `true` in `job` mode |
+| `jobId` | Advanced stable conversion identifier. | `string` | autogenerated |
 
+Legacy aliases still work for backwards compatibility:
 
-**Special thanks to [Alex Serebryakov](https://snapapi.pics/) for creating and maintaining SnapAPI!**
+- `name` -> `title`
+- `prefix` -> `namespace`
+- `source` -> `baseUrl`
+- `basePath` -> `outputPath`
+- `shouldSaveFiles` -> `writeFiles`
+- `generateIconPreview` -> `generatePreviewImage`
 
+## Notes
 
-## Running Tests
+- Generated output is zipped in memory before upload.
+- R2 uploads use the values from `.env`.
+- Do not hardcode real tokens or keys in source code, docs, or tests.
 
-To run the test suite, use:
+## Running tests
 
 ```bash
-cd html-to-gutenberg && npm install
+npm install
 npm test
 ```
 
-This will execute all unit and integration tests using Mocha and Chai. Make sure all dependencies are installed with `npm install` before running tests.
-
-Some tests (such as screenshot preview generation) may require a valid SnapAPI key in your `.env` file.
-
-
 ## License
-  
 
-[MIT](https://github.com/DiogoAngelim/html-to-gutenberg/blob/main/LICENSE.MD)
+[MIT](https://github.com/DiogoAngelim/html-to-gutenberg/blob/main/LICENSE.MD)

package/scripts/patch-fetch-page-assets.mjs

@@ -0,0 +1,13 @@
+import fs from "fs";
+import path from "path";
+
+const projectRoot = process.cwd();
+const sourcePath = path.join(projectRoot, "vendor", "fetch-page-assets", "index.js");
+const targetPath = path.join(projectRoot, "node_modules", "fetch-page-assets", "index.js");
+
+if (!fs.existsSync(sourcePath) || !fs.existsSync(targetPath)) {
+  process.exit(0);
+}
+
+fs.copyFileSync(sourcePath, targetPath);
+console.log("Applied local fetch-page-assets performance patch");

package/scripts/sync-from-npm.mjs

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+
+const repoRoot = process.cwd();
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-from-npm-'));
+const targetDir = process.env.NPM_SYNC_TARGET_DIR?.trim() || '.';
+const targetRoot = path.resolve(repoRoot, targetDir);
+
+const readPackageName = () => {
+  const packageJsonPath = path.join(targetRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson.name;
+};
+
+const parsePreserveList = (value) => {
+  const rawEntries = (value || '.git,.github,node_modules,.env,scripts')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return new Set(rawEntries);
+};
+
+const shouldPreserve = (entryName, preserveList) => {
+  return preserveList.has(entryName);
+};
+
+const removeUnsyncedEntries = (sourceRoot, preserveList, dryRun) => {
+  if (!fs.existsSync(targetRoot)) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(targetRoot)) {
+    if (shouldPreserve(entry, preserveList)) {
+      continue;
+    }
+
+    const targetPath = path.join(targetRoot, entry);
+    const sourcePath = path.join(sourceRoot, entry);
+
+    if (fs.existsSync(sourcePath)) {
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`Would remove ${entry}`);
+      continue;
+    }
+
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+};
+
+const copyPackageEntries = (sourceRoot, preserveList, dryRun) => {
+  if (!dryRun) {
+    fs.mkdirSync(targetRoot, { recursive: true });
+  }
+
+  for (const entry of fs.readdirSync(sourceRoot)) {
+    if (shouldPreserve(entry, preserveList)) {
+      console.log(`Skipping preserved path ${entry}`);
+      continue;
+    }
+
+    const sourcePath = path.join(sourceRoot, entry);
+    const targetPath = path.join(targetRoot, entry);
+
+    if (dryRun) {
+      console.log(`Would sync ${entry}`);
+      continue;
+    }
+
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    fs.cpSync(sourcePath, targetPath, { recursive: true });
+  }
+};
+
+const packageName = process.env.NPM_PACKAGE_NAME || readPackageName();
+const requestedVersion = process.env.NPM_SYNC_VERSION?.trim();
+const distTag = process.env.NPM_SYNC_DIST_TAG?.trim() || 'latest';
+const preserveList = parsePreserveList(process.env.NPM_SYNC_PRESERVE_PATHS);
+const dryRun = process.env.NPM_SYNC_DRY_RUN === '1';
+const packageSpec = requestedVersion ? `${packageName}@${requestedVersion}` : `${packageName}@${distTag}`;
+
+try {
+  console.log(`Packing ${packageSpec} into ${targetDir}`);
+  const packedTarball = execFileSync('npm', ['pack', packageSpec, '--silent'], {
+    cwd: tempRoot,
+    encoding: 'utf8',
+  }).trim().split('\n').pop();
+
+  if (!packedTarball) {
+    throw new Error(`Failed to pack ${packageSpec}`);
+  }
+
+  execFileSync('tar', ['-xzf', packedTarball], { cwd: tempRoot });
+
+  const sourceRoot = path.join(tempRoot, 'package');
+  if (!fs.existsSync(sourceRoot)) {
+    throw new Error('Packed npm tarball did not contain a package/ directory.');
+  }
+
+  removeUnsyncedEntries(sourceRoot, preserveList, dryRun);
+  copyPackageEntries(sourceRoot, preserveList, dryRun);
+
+  const syncedPackageJson = JSON.parse(
+    fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8')
+  );
+
+  console.log(`Synced ${packageName} version ${syncedPackageJson.version} into ${targetDir}`);
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}

package/tsconfig.json

@@ -13,7 +13,22 @@
     ],
     "esModuleInterop": true,
   },
+  "include": [
+    "@types.d.ts",
+    "globals.ts",
+    "utils.ts",
+    "src/**/*.ts"
+  ],
   "exclude": [
-    "node_modules"
+    "node_modules",
+    "dist",
+    "coverage",
+    "vendor",
+    "**/*.test.ts",
+    "index.ts",
+    "fetch-page-assets.test.ts",
+    "index.test.ts",
+    "coverage-demo.test.ts",
+    "snapapi-screenshot.test.ts"
   ]
-}
+}

package/vendor/fetch-page-assets/LICENSE.MD

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Diogo Angelim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/fetch-page-assets/README.md

@@ -0,0 +1,117 @@
+# fetch-page-assets
+
+Download page assets, rewrite the HTML to point at the fetched assets, and optionally upload those downloads directly to Cloudflare R2 instead of writing them to disk.
+
+## Installation
+
+```bash
+npm install fetch-page-assets
+```
+
+## Environment
+
+Keep real secrets in `.env` and never commit them.
+
+```bash
+cp .env.example .env
+```
+
+Required for R2 uploads:
+
+- `CLOUDFLARE_R2_ACCOUNT_ID`
+- `CLOUDFLARE_R2_BUCKET`
+- `CLOUDFLARE_R2_ACCESS_KEY_ID`
+- `CLOUDFLARE_R2_SECRET_ACCESS_KEY`
+- `CLOUDFLARE_R2_PUBLIC_BASE_URL`
+
+Optional:
+
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_R2_ENDPOINT`
+
+## Getting and rotating Cloudflare credentials
+
+1. Open the Cloudflare dashboard.
+2. Create or rotate the R2 access keys for the bucket you want to use.
+3. Update `.env` with the new key values.
+4. If you use a Cloudflare API token for verification or other account workflows, rotate it in the API Tokens section and update `.env`.
+5. Restart the service after updating `.env`.
+6. Revoke the old token or key after the new one is confirmed working.
+
+To verify a token without exposing it in source code:
+
+```bash
+curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+## Usage
+
+### Legacy local mode
+
+```js
+import extractAssets from 'fetch-page-assets';
+
+const html = await extractAssets('<img src="/logo.png" />', {
+  source: 'https://example.com',
+  basePath: process.cwd(),
+  saveFile: true
+});
+```
+
+### R2 upload mode
+
+```js
+import extractAssets from 'fetch-page-assets';
+
+const result = await extractAssets('<img src="/logo.png" />', {
+  source: 'https://example.com',
+  uploadToR2: true,
+  returnDetails: true,
+  jobId: 'conv_123',
+  r2Prefix: 'generated/conv_123/assets'
+});
+
+console.log(result);
+```
+
+Example response:
+
+```json
+{
+  "html": "<img src=\"https://storage.example.com/generated/conv_123/assets/logo.png\">",
+  "assets": [
+    {
+      "id": "file_1",
+      "name": "logo.png",
+      "type": "image/png",
+      "size": 48211,
+      "path": "/generated/conv_123/assets/logo.png",
+      "url": "https://storage.example.com/generated/conv_123/assets/logo.png",
+      "kind": "asset"
+    }
+  ]
+}
+```
+
+## Options
+
+| Option | Description | Type | Default |
+| --- | --- | --- | --- |
+| `source` | Base URL used to resolve relative asset paths. | `string` | `''` |
+| `basePath` | Local base path used in legacy mode. | `string` | current directory |
+| `saveFile` | Writes downloaded assets to disk in legacy mode. | `boolean` | `true` |
+| `uploadToR2` | Uploads resolved assets to Cloudflare R2. | `boolean` | `false` |
+| `returnDetails` | Returns `{ html, assets }` metadata instead of only the rewritten HTML string. | `boolean` | `false` |
+| `jobId` | Stable conversion identifier used to build remote paths. | `string` | `conv_local` |
+| `r2Prefix` | Remote storage prefix for uploaded assets. | `string` | derived from `jobId` |
+| `concurrency` | Maximum number of simultaneous downloads. | `number` | `8` |
+| `maxRetryAttempts` | Maximum attempts per asset. | `number` | `3` |
+| `retryDelay` | Delay between attempts in milliseconds. | `number` | `1000` |
+| `verbose` | Enables console logging. | `boolean` | `true` |
+
+## Notes
+
+- `returnDetails: true` is the recommended mode when using R2 because it gives you the uploaded asset metadata.
+- Keep all Cloudflare credentials in `.env`.
+- Do not hardcode tokens or access keys in code, documentation, tests, or shell history.