notion-static-exporter 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0
+
+- Initial release: Puppeteer BFS scrape of public `notion.site` pages
+- Freezes live Notion UI (not admin HTML-export styling)
+- Cloudflare handling: wait for clearance, persistent Chrome profile, delays,
+  retries, SPA clicks for subpages
+- Downloads CSS/fonts/images; strips client JS for offline static hosting
+- CLI: `sync`, `trigger`, `init-config`, `help`
+- Sample GitHub Actions workflow (cron every 4h + workflow_dispatch)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 novailoveyou
+
+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/README.md

@@ -0,0 +1,223 @@
+# notion-static-exporter
+
+Scrape a **public** Notion site (`*.notion.site`) into a static mirror that looks
+like the **live Notion UI** — not Notion’s admin “Export → HTML” look.
+
+Compare:
+
+- Live UI (target): https://almond-brownie-c82.notion.site/Elementary-3b515e0e4a098053bb74c985cebfd777
+- Old export style (different UI): https://elementary.english.orlov.app/
+
+This tool freezes the painted Notion SPA (HTML + CSS + fonts + images), strips
+client JS that would blank the page offline, rewrites links, and writes files
+you can host on GitHub Pages (installable PWA with offline cache).
+
+No Notion API token. Exhaustive BFS: every same-site link on every page is
+queued until the tree is done.
+
+```bash
+bunx notion-static-exporter sync \
+  --url "https://almond-brownie-c82.notion.site/Elementary-3b515e0e4a098053bb74c985cebfd777" \
+  --out ./_site
+```
+
+## Publishing
+
+Publish this package to npm so Pages repos can call it from GitHub Actions:
+
+```bash
+# one-time: login to npm (browser or token)
+npm login
+# or: npm config set //registry.npmjs.org/:_authToken=npm_…
+
+bun run build
+bun run publish:prod   # → bun publish --access public
+```
+
+That publishes `notion-static-exporter` (version from `package.json`). After that,
+anywhere can run:
+
+```bash
+npx notion-static-exporter sync --url "…" --out .
+# or
+bunx notion-static-exporter sync --url "…" --out .
+```
+
+Bump `version` in `package.json` before each publish if the previous version is
+already on the registry.
+
+## Usage
+
+### Install / run locally
+
+```bash
+bunx notion-static-exporter sync --url "https://….notion.site/…" --out ./_site
+bun add -g notion-static-exporter
+notion-static-exporter sync --url "…" --out ./_site
+```
+
+Optional config `notion-static-exporter.config.json`:
+
+```json
+{
+  "url": "https://almond-brownie-c82.notion.site/Elementary-3b515e0e4a098053bb74c985cebfd777",
+  "out": "./_site",
+  "keepCname": true,
+  "maxPages": 0
+}
+```
+
+```bash
+bunx notion-static-exporter init-config
+```
+
+### Wire each GitHub Pages repo
+
+Use the ready template: [`examples/sync-notion.yml`](examples/sync-notion.yml).
+
+#### [elementary.english.orlov.app](https://github.com/Novailoveyou/elementary.english.orlov.app)
+
+1. Add `.github/workflows/sync-notion.yml` (copy from the example).
+2. Repo **Settings → Secrets and variables → Actions → Variables**:
+   - `NOTION_URL` = `https://almond-brownie-c82.notion.site/Elementary-3b515e0e4a098053bb74c985cebfd777`
+3. Ensure **GitHub Pages** serves from `main` (root or `/docs` — whatever you use now).
+4. Keep existing `CNAME` — the workflow uses `--keep-cname`.
+5. Remove / stop the old `publish.yml` (notion4ever + `NOTION_TOKEN`) so you don’t have two deployers fighting.
+
+#### [english.orlov.app](https://github.com/Novailoveyou/english.orlov.app)
+
+Same workflow file, different variable:
+
+- `NOTION_URL` = `https://almond-brownie-c82.notion.site/Elena-Pilip-61ff5f4c44a34429944ea190ee690cc9`  
+  (drop the `#…` hash for the crawl root)
+
+No Notion API token needed — public `*.notion.site` only.
+
+### What the Action does
+
+On schedule (every 4h in the example) or **Actions → Sync Notion → Run workflow**:
+
+1. Checkout the Pages repo
+2. Install Chrome + Bun
+3. Cache Chrome profile (Cloudflare cookies)
+4. `bunx notion-static-exporter sync --url "$NOTION_URL" --out . --keep-cname …`
+5. Commit & push if anything changed → Pages updates
+
+The workflow also:
+
+- Points Puppeteer at Chrome via `PUPPETEER_EXECUTABLE_PATH`
+- Runs headless with container-safe flags (`--no-sandbox`, `--disable-dev-shm-usage`, …)
+- Uses lower concurrency (`2`) to fit runner memory
+
+Local override for a custom Chrome binary:
+
+```bash
+PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome \
+  bunx notion-static-exporter sync --url "…" --out ./_site
+```
+
+### Trigger from this machine
+
+After the workflow exists:
+
+```bash
+export GITHUB_TOKEN=ghp_…   # workflow scope
+bunx notion-static-exporter trigger \
+  --repo Novailoveyou/elementary.english.orlov.app \
+  --workflow sync-notion.yml \
+  --ref main
+```
+
+Same for `english.orlov.app`.
+
+### Order of operations
+
+| Step | Where |
+|------|--------|
+| 1. `bun run publish:prod` | `notion-static-exporter` |
+| 2. Add workflow + `NOTION_URL` | each Pages repo |
+| 3. Disable old notion4ever `publish.yml` | each Pages repo |
+| 4. Manual “Run workflow” once | verify scrape + commit |
+| 5. Leave schedule on | ongoing sync |
+
+## Commands
+
+| Command | Purpose |
+|--------|---------|
+| `sync` | Crawl public URL → write static files (default) |
+| `restore` | Restore `--out` from the previous `.nsp-backup` |
+| `trigger` | `workflow_dispatch` on a consumer GitHub repo |
+| `help` | Usage |
+
+### Sync flags
+
+- `--url` / `NOTION_URL` — public Notion root
+- `--out` / `OUT_DIR` — output directory (default `.`)
+- `--keep-cname` — keep existing `CNAME` across sync
+- `--max-pages <n>` — safety cap (`0` = unlimited)
+- `--delay-ms <n>` — pause between pages (default `1500`)
+- `--concurrency <n>` — parallel browser tabs (default `3`)
+- `--retries <n>` — retries when Cloudflare blocks (default `3`)
+- `--user-data-dir <path>` — Chrome profile (keeps CF cookies)
+- `--headed` — show Chromium (helps pass hard challenges)
+- `--full` — ignore fingerprints; re-freeze every page
+
+### Resync / cache
+
+Sync builds into a staging folder, then swaps into `--out` and keeps **one**
+backup (`--out.nsp-backup`). Unchanged pages (content fingerprint match) skip
+freeze/asset download. Use `--full` to force a complete re-scrape. On failure
+the live `--out` is left untouched.
+
+```bash
+bunx notion-static-exporter restore --out ./_site
+```
+
+## Cloudflare
+
+Notion’s public sites sit behind Cloudflare (“Just a moment…”). The crawler:
+
+1. Uses a **persistent Chrome profile** (`~/.notion-static-exporter/chrome-profile`) so `cf_clearance` cookies stick across runs
+2. **Waits** for challenges to clear before saving a page
+3. **Delays** between page loads (`--delay-ms`)
+4. **Retries** blocked pages (`--retries`, default 3)
+5. Never saves a challenge interstitial as content
+
+If challenges still stick in headless CI, warm the profile once locally:
+
+```bash
+bunx notion-static-exporter sync --url "…" --out ./_site --headed --max-pages 5
+```
+
+Then re-run headless using the same `--user-data-dir` (or let Actions restore the cached profile).
+
+## How it works
+
+1. Launch Chromium (Puppeteer) — system Chrome, `PUPPETEER_EXECUTABLE_PATH`, or bundled
+2. Open each public page and wait for the **live Notion UI** to paint
+3. Collect **all** same-origin page links → BFS queue
+4. Download CSS / fonts / images into `assets/`
+5. **Freeze** the rendered DOM (inline accessible CSS, remove Notion client JS)
+6. Rewrite links to local `.html` files + PWA service worker
+7. Publish via staging → backup → swap
+
+CLI shows an animated spinner, a progress bar (`done/known`, grows as the queue
+discovers pages), and rotating status text for the current phase (navigate,
+Cloudflare, views, assets, freeze, …). In GitHub Actions (no TTY) it prints
+phase lines every few seconds instead.
+
+## Library
+
+```ts
+import { syncNotionSite, triggerWorkflow } from "notion-static-exporter";
+
+await syncNotionSite({
+  url: "https://….notion.site/…",
+  out: "./_site",
+  keepCname: true,
+});
+```
+
+## License
+
+MIT

package/dist/assets.d.ts

@@ -0,0 +1,47 @@
+import type { HTTPResponse, Page } from "puppeteer";
+export type AssetStore = {
+    map: Map<string, string>;
+    /** relative asset path → source URL(s) */
+    reverse: Map<string, string>;
+    dir: string;
+    outRoot: string;
+};
+export declare function createAssetStore(outRoot: string): AssetStore;
+export declare function normalizeAssetKey(url: string): string;
+/** Notion page URLs must never be saved as static assets. */
+export declare function isNotionPageAssetUrl(url: string): boolean;
+export declare function saveAsset(store: AssetStore, url: string, body: Buffer, contentType: string | null): string | null;
+export declare function downloadUrl(store: AssetStore, url: string, page: Page): Promise<string | null>;
+export declare function attachResponseCollector(page: Page): {
+    urls: Set<string>;
+    responses: Map<string, HTTPResponse>;
+    detach: () => void;
+};
+/** Persist bodies Chrome already fetched (best source for images/fonts). */
+export declare function saveCollectedResponses(store: AssetStore, responses: Map<string, HTTPResponse>): Promise<void>;
+export declare function downloadAssetUrls(store: AssetStore, page: Page, urls: Iterable<string>, concurrency?: number): Promise<void>;
+export declare function collectDomAssetUrls(page: Page): Promise<string[]>;
+export declare function rewriteHtml(html: string, pageLocalPath: string, pageUrl: string, store: AssetStore, pageUrlMap: Map<string, string>): string;
+/** Fix <a href="#"> using the enclosing element's data-block-id when it matches a scraped page. */
+export declare function repairDeadPageLinks(html: string, pageUrlMap: Map<string, string>, pageLocalPath: string): string;
+export declare function rewriteCssFiles(store: AssetStore, pageUrl: string): void;
+export declare function findRemainingRemoteUrls(html: string, baseUrl?: string): string[];
+/** Map Notion block UUID (32-hex) → best local audio/image asset path. */
+export declare function buildBlockAssetIndex(entries: Iterable<[string, string]>): Map<string, {
+    audio?: string;
+    image?: string;
+    imageWidth: number;
+}>;
+/**
+ * Inject <audio>/<img> into empty Notion media shells and replace gif
+ * placeholders using assets keyed by ?id=<blockId> in the CDN URL.
+ */
+export declare function injectBlockMedia(html: string, store: AssetStore, pageLocalPath: string): string;
+/**
+ * Replace 1×1 gif placeholders in Notion bookmark cards with the target
+ * page's og:image (downloaded locally). Generic — works for any future
+ * bookmark links, not just Wordwall.
+ */
+export declare function enrichBookmarkCovers(html: string, store: AssetStore, pageLocalPath: string): Promise<string>;
+export declare function ensureParentDir(filePath: string): void;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,10 @@
+import { type Browser, type Page } from "puppeteer";
+export type LaunchBrowserOptions = {
+    headless?: boolean;
+    /** Persist cookies / CF clearance across runs */
+    userDataDir?: string;
+};
+export declare function defaultUserDataDir(): string;
+export declare function launchBrowser(opts?: LaunchBrowserOptions): Promise<Browser>;
+export declare function preparePage(browser: Browser): Promise<Page>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAGA,OAAkB,EAAE,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAG/D,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AA6CD,wBAAsB,aAAa,CACjC,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,OAAO,CAAC,CA4ClB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjE"}

package/dist/cache.d.ts

@@ -0,0 +1,54 @@
+import type { Page } from "puppeteer";
+import type { AssetStore } from "./assets.ts";
+export declare const CACHE_VERSION: 1;
+export declare const CACHE_FILE = ".nsp-cache.json";
+export type PageCacheEntry = {
+    url: string;
+    file: string;
+    fingerprint: string;
+    links: string[];
+};
+export type SyncCache = {
+    version: typeof CACHE_VERSION;
+    rootUrl: string;
+    pages: Record<string, PageCacheEntry>;
+    /** Normalized asset URL → relative path under site root (e.g. assets/abc.png) */
+    assets: Record<string, string>;
+};
+export declare function stagingDir(outRoot: string): string;
+export declare function backupDir(outRoot: string): string;
+export declare function emptyCache(rootUrl: string): SyncCache;
+export declare function loadCache(dir: string): SyncCache | null;
+export declare function saveCache(dir: string, cache: SyncCache): void;
+/** Seed asset store from a previous cache so downloads/rewrites can reuse files. */
+export declare function hydrateAssetStore(store: AssetStore, cache: SyncCache): number;
+export declare function snapshotAssets(store: AssetStore): Record<string, string>;
+/**
+ * Light content fingerprint after Notion has rendered.
+ * Avoids re-freezing / re-downloading when the page body is unchanged.
+ */
+export declare function pageFingerprint(page: Page): Promise<string>;
+export declare function siteHasContent(dir: string): boolean;
+/**
+ * Prepare a clean staging directory.
+ * Copies assets + cache + a few root files (fast). HTML is copied on demand
+ * for cache hits, or written fresh when a page is re-scraped.
+ */
+export declare function prepareStaging(outRoot: string, keepCname?: boolean): {
+    staging: string;
+    copied: boolean;
+};
+/** Ensure a previously scraped HTML page exists in staging (for cache hits). */
+export declare function ensureCachedPageInStaging(outRoot: string, staging: string, file: string): boolean;
+/**
+ * Atomically publish staging → outRoot, keeping one previous copy at backup.
+ * Live outRoot is never wiped until staging is complete.
+ */
+export declare function publishStaging(outRoot: string): {
+    backup: string | null;
+};
+/** Restore the single backup over outRoot (if present). */
+export declare function restoreBackup(outRoot: string): boolean;
+/** Remove HTML pages in staging that were not part of this crawl. */
+export declare function pruneOrphanHtml(staging: string, keepFiles: Set<string>): number;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,eAAO,MAAM,aAAa,EAAG,CAAU,CAAC;AACxC,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,OAAO,aAAa,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAWvD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAG7D;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAa7E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxE;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBjE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,OAAO,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAsCtC;AAED,gFAAgF;AAChF,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAQT;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA+BzE;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA4BtD;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,MAAM,CASR"}

package/dist/challenge.d.ts

@@ -0,0 +1,23 @@
+import type { Page } from "puppeteer";
+/** Cloudflare / bot interstitial ("Just a moment..."). */
+export declare function isChallengePage(page: Page): Promise<boolean>;
+/**
+ * Wait until Cloudflare clears (cf_clearance / title change) or timeout.
+ * Returns true if the page looks clear of the challenge.
+ */
+export declare function waitOutChallenge(page: Page, timeoutMs?: number): Promise<boolean>;
+export declare function sleep(ms: number): Promise<void>;
+/** Human-like pause between navigations. Uses small jitter; skip when baseMs ≤ 0. */
+export declare function crawlDelay(baseMs: number): Promise<void>;
+/**
+ * Global spacing between navigations across workers (avoids N×delay with concurrency).
+ */
+export declare function createNavGate(baseMs: number): () => Promise<void>;
+/**
+ * Navigate to a Notion page. Prefer in-app link click (SPA) to avoid
+ * re-triggering Cloudflare; fall back to full goto.
+ */
+export declare function navigateToPage(page: Page, url: string, opts?: {
+    allowSpaClick?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../src/challenge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAItC,0DAA0D;AAC1D,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBlE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,SAAS,SAAS,GACjB,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAED,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED,qFAAqF;AACrF,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAUjE;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,OAAO,CAAC,IAAI,CAAC,CAsCf"}