html-to-gutenberg 4.2.8 → 4.2.10

package/package.json

@@ -1,37 +1,57 @@
 {
   "dependencies": {
-    "@babel/core": "^7.28.5",
+    "@aws-sdk/client-s3": "^3.888.0",
+    "@babel/core": "^7.29.0",
     "@babel/preset-react": "^7.28.5",
     "@svgr/core": "^8.1.0",
-    "cheerio": "^1.1.2",
-    "css-scoping": "^1.0.1",
-    "fetch-page-assets": "^1.2.6",
+    "cheerio": "^1.2.0",
+    "css-scoping": "^1.0.5",
+    "dotenv": "^17.3.1",
+    "fetch-page-assets": "^1.2.7",
     "fs": "^0.0.1-security",
-    "html-screenshots": "^1.2.7",
-    "image-to-base64": "^2.2.0",
-    "node-html-to-jsx": "^1.3.7",
+    "jszip": "^3.10.1",
+    "mime-types": "^3.0.1",
+    "node-fetch": "^3.3.2",
+    "node-html-to-jsx": "^1.4.4",
     "path": "^0.12.7"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/babel__core": "^7.20.5",
     "@types/beautify": "^0.0.3",
+    "@types/chai": "^5.2.3",
     "@types/cheerio": "^1.0.0",
     "@types/image-to-base64": "^2.1.2",
+    "@types/mocha": "^10.0.10",
     "@types/prettier": "^3.0.0",
-    "@types/svgo": "^3.0.0"
+    "@types/svgo": "^3.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "chai": "^6.2.2",
+    "c8": "^11.0.0",
+    "coveralls": "^3.1.1",
+    "eslint": "^10.0.2",
+    "mocha": "^11.3.0",
+    "nyc": "^18.0.0",
+    "source-map-support": "^0.5.21",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript-eslint": "^8.56.1"
   },
-  "type": "module",
-  "types": "index.ts",
+  "types": "index.d.ts",
   "name": "html-to-gutenberg",
-  "version": "4.2.8",
+  "version": "4.2.10",
   "description": "Transform any valid HTML string into fully editable WP Gutenberg blocks in seconds rather than hours.",
   "main": "index.js",
   "directories": {
     "test": "test"
   },
   "scripts": {
-    "test": "jest",
-    "build": "tsc"
+    "postinstall": "mv ./node_modules/fetch-page-assets/index.ts ./node_modules/fetch-page-assets/index.ts.bak || true && node ./scripts/patch-fetch-page-assets.mjs",
+    "test": "mocha -r ts-node/register/transpile-only index.test.ts fetch-page-assets.test.ts",
+    "build": "tsc",
+    "coverage": "c8 mocha -r ts-node/register/transpile-only index.test.ts fetch-page-assets.test.ts",
+    "coveralls": "c8 mocha -r ts-node/register/transpile-only index.test.ts fetch-page-assets.test.ts && c8 report --reporter=lcov && cat coverage/lcov.info | coveralls"
   },
   "repository": {
     "type": "git",
@@ -55,5 +75,57 @@
   "bugs": {
     "url": "https://github.com/DiogoAngelim/html-to-gutenberg/issues"
   },
-  "homepage": "https://www.html-to-gutenberg.io"
-}
+  "homepage": "https://www.html-to-gutenberg.io",
+  "c8": {
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "include": [
+      "index.js",
+      "utils.ts",
+      "globals.js",
+      "vendor/fetch-page-assets/index.js"
+    ],
+    "exclude": [
+      "coverage",
+      "dist",
+      "node_modules",
+      "scripts",
+      "**/*.test.ts"
+    ],
+    "all": true
+  },
+  "jest": {
+    "preset": "ts-jest/presets/js-with-ts",
+    "testEnvironment": "node",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "useESM": true
+        }
+      ]
+    },
+    "globals": {
+      "ts-jest": {
+        "tsconfig": "tsconfig.json",
+        "useESM": true
+      }
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "dist/*.js",
+      "!dist/*.test.js"
+    ],
+    "testMatch": [
+      "<rootDir>/dist/*.test.js"
+    ]
+  }
+}

package/r2.js

@@ -0,0 +1,163 @@
+import crypto from 'crypto';
+import dotenv from 'dotenv';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import JSZip from 'jszip';
+import mime from 'mime-types';
+import path from 'path';
+
+dotenv.config({ quiet: true });
+
+let r2Client;
+
+const trimSlashes = (value = '') => value.replace(/^\/+|\/+$/g, '');
+
+export const createJobId = () => {
+  return `conv_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`;
+};
+
+export const inferContentType = (fileName, fallback = 'application/octet-stream') => {
+  return mime.lookup(fileName) || fallback;
+};
+
+export const getR2Config = () => {
+  const accountId = process.env.CLOUDFLARE_R2_ACCOUNT_ID;
+  const bucket = process.env.CLOUDFLARE_R2_BUCKET;
+  const accessKeyId = process.env.CLOUDFLARE_R2_ACCESS_KEY_ID;
+  const secretAccessKey = process.env.CLOUDFLARE_R2_SECRET_ACCESS_KEY;
+  const publicBaseUrl = process.env.CLOUDFLARE_R2_PUBLIC_BASE_URL || '';
+  const endpoint =
+    process.env.CLOUDFLARE_R2_ENDPOINT || (accountId ? `https://${accountId}.r2.cloudflarestorage.com` : '');
+
+  return {
+    accountId,
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    publicBaseUrl: publicBaseUrl.replace(/\/+$/, ''),
+    endpoint,
+    mockMode: process.env.HTG_R2_MOCK === '1',
+  };
+};
+
+export const getR2Client = () => {
+  if (r2Client) {
+    return r2Client;
+  }
+
+  const config = getR2Config();
+
+  if (!config.bucket) {
+    throw new Error('CLOUDFLARE_R2_BUCKET is required.');
+  }
+
+  if (!config.endpoint) {
+    throw new Error('CLOUDFLARE_R2_ACCOUNT_ID or CLOUDFLARE_R2_ENDPOINT is required.');
+  }
+
+  if (!config.accessKeyId || !config.secretAccessKey) {
+    throw new Error('CLOUDFLARE_R2_ACCESS_KEY_ID and CLOUDFLARE_R2_SECRET_ACCESS_KEY are required.');
+  }
+
+  r2Client = new S3Client({
+    region: 'auto',
+    endpoint: config.endpoint,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+  });
+
+  return r2Client;
+};
+
+export const buildR2Url = (storageKey) => {
+  const { publicBaseUrl, mockMode } = getR2Config();
+  if (!publicBaseUrl) {
+    if (mockMode) {
+      return `https://storage.example.com/${trimSlashes(storageKey)}`;
+    }
+    throw new Error('CLOUDFLARE_R2_PUBLIC_BASE_URL is required for real R2 uploads.');
+  }
+  return `${publicBaseUrl}/${trimSlashes(storageKey)}`;
+};
+
+export const uploadBufferToR2 = async ({
+  storageKey,
+  body,
+  contentType,
+  cacheControl,
+  metadata,
+}) => {
+  const config = getR2Config();
+  const normalizedKey = trimSlashes(storageKey);
+  const bufferBody = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  const resolvedContentType = contentType || inferContentType(path.basename(normalizedKey));
+
+  if (config.mockMode) {
+    return {
+      storageKey: normalizedKey,
+      path: `/${normalizedKey}`,
+      url: buildR2Url(normalizedKey),
+      size: bufferBody.byteLength,
+      type: resolvedContentType,
+    };
+  }
+
+  const client = getR2Client();
+
+  await client.send(
+    new PutObjectCommand({
+      Bucket: config.bucket,
+      Key: normalizedKey,
+      Body: bufferBody,
+      ContentType: resolvedContentType,
+      CacheControl: cacheControl,
+      Metadata: metadata,
+    })
+  );
+
+  return {
+    storageKey: normalizedKey,
+    path: `/${normalizedKey}`,
+    url: buildR2Url(normalizedKey),
+    size: bufferBody.byteLength,
+    type: resolvedContentType,
+  };
+};
+
+export const createFileRecord = ({
+  id,
+  name,
+  kind,
+  storageKey,
+  size,
+  type,
+  url,
+}) => {
+  return {
+    id,
+    name,
+    type,
+    size,
+    path: `/${trimSlashes(storageKey)}`,
+    url,
+    kind,
+  };
+};
+
+export const zipEntriesToBuffer = async (entries) => {
+  const zip = new JSZip();
+
+  for (const entry of entries) {
+    if (!entry || entry.body == null) {
+      continue;
+    }
+
+    zip.file(trimSlashes(entry.zipPath || entry.name), entry.body);
+  }
+
+  return zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+  });
+};

package/readme.md

@@ -1,116 +1,170 @@
-
 # HTML to Gutenberg Converter
 
-  
-
-Convert HTML strings to valid, editable WordPress Gutenberg blocks in seconds instead of hours. With this script, you can create and build valid Gutenberg blocks that feature editable text, forms, inline and background images, as well as SVGs. It includes support for TailwindCSS.
-
-  
-
-## Features
-
-  
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DiogoAngelim/html-to-gutenberg/blob/main/LICENSE.MD)
 
-- 🪄 **Instantly transforms static HTML into Gutenberg blocks**
-Saves hours of manual work by automating block creation from any valid HTML snippet.
+Convert HTML into editable WordPress Gutenberg blocks and publish the generated package to Cloudflare R2 without writing the output to disk.
 
-- 🔌 **Generates a complete, installable WordPress block plugin**
-Outputs all necessary plugin files (JS, CSS, PHP) so you can drop them into WordPress immediately.
-  
+## What changed
 
-- 🎨 **Keeps your design intact**
-Automatically extracts and preserves CSS from the original HTML into a separate `style.css`.
+- `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.
 
+## Installation
 
-- 🧩 **Modular and scalable**
-Separates assets (JS, CSS, components) into clean files, making it easy to maintain and extend.
-  
+```bash
+npm install html-to-gutenberg
+```
 
-- 📦 **Seamlessly integrates with dynamic block systems**
-Works perfectly for headless or custom Gutenberg setups where blocks are registered via JS, not PHP.
-  
+## Environment
 
-- 🚀 **Speeds up prototyping**
-Ideal for quickly testing block ideas or converting landing pages and templates into WordPress blocks.
+Copy `.env.example` to `.env` and keep the real values private.
 
-  
-- 🧠 **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.).
+```bash
+cp .env.example .env
+```
 
+Required for R2-backed job output:
 
-- 🧰 **Built for automation and customization**
-Can be embedded in custom tools, UIs, or pipelines to generate Gutenberg blocks on demand.
+- `CLOUDFLARE_R2_ACCOUNT_ID`
+- `CLOUDFLARE_R2_BUCKET`
+- `CLOUDFLARE_R2_ACCESS_KEY_ID`
+- `CLOUDFLARE_R2_SECRET_ACCESS_KEY`
+- `CLOUDFLARE_R2_PUBLIC_BASE_URL`
 
-  
-  
+Optional:
 
-## Installation
+- `CLOUDFLARE_API_TOKEN`
+- `SNAPAPI_KEY`
 
-  
+## Getting and rotating Cloudflare credentials
 
-Install html-to-gutenberg with npm:
+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.
 
-  
+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
 
-When provided with a valid HTML string and the required 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.
+If you still need the previous local-string output for existing tooling or tests, use:
 
-  
+```js
+const files = await block('<div>Hello world</div>', {
+  title: 'Legacy Block',
+  outputPath: process.cwd(),
+  writeFiles: false,
+  outputMode: 'legacy'
+});
+```
 
-## Example
+In `legacy` mode, the function returns the generated file contents instead of the R2 job manifest.
 
-  
+## Options
 
-[Working demo](https://www.html-to-gutenberg.io/)
+| 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:
 
-## Options object reference
+- `name` -> `title`
+- `prefix` -> `namespace`
+- `source` -> `baseUrl`
+- `basePath` -> `outputPath`
+- `shouldSaveFiles` -> `writeFiles`
+- `generateIconPreview` -> `generatePreviewImage`
 
+## Notes
 
-| 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 `true`, generates a static image preview (JPEG) of the block's icon for display in the block picker.                                              | 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                                                                                                  | []                |
+- 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.
 
+## Running tests
 
+```bash
+npm install
+npm test
+```
 
 ## 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 });
+}