@press2ai/engine 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Durtan
+
+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,28 @@
+# @press2ai/engine
+
+Multi-tenant runtime + template contracts for Press2AI vertical landings. SSR on Cloudflare Workers, isomorphic renderer (SSG/browser on roadmap).
+
+Used by the `otwarty-*` verticals. See [press2ai](https://codeberg.org/press2ai) for the full ecosystem.
+
+## Install
+
+```
+npm install @press2ai/engine
+```
+
+## Subpath exports
+
+- `@press2ai/engine` — core runtime + types
+- `@press2ai/engine/template-trener` — fitness/trainer vertical template
+- `@press2ai/engine/template-blog` — blog template
+- `@press2ai/engine/types` — TypeScript type exports
+
+## Contract
+
+`OtwartyTemplate<C, T>` discriminated union (`Presence | Commerce`). Render = pure function, isomorphic (SSR / SSG / browser). Templates are bundled as subpath exports — adding a vertical does not require engine changes.
+
+Engine v0.1 is GET-only. Mutations (POST `/opt-out`, claim flow) live in per-vertical Hono wrappers.
+
+## License
+
+MIT — see `LICENSE`. Part of the [Press2AI ecosystem](https://codeberg.org/press2ai).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@press2ai/engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Multi-tenant runtime + template contracts dla otwarty-* verticali. SSR na Cloudflare Workers, isomorphic renderer (SSG/browser w roadmapie).",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,7 @@
     ".": "./src/index.ts",
     "./template-trener": "./src/template-trener.ts",
     "./template-blog": "./src/template-blog.ts",
+    "./ceidg-vertical": "./src/ceidg-vertical.ts",
     "./types": "./src/types.ts"
   },
   "scripts": {
@@ -23,7 +24,17 @@
   "dependencies": {
     "zod": "^3.23.8"
   },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260101.0",
+    "hono": "^4.6.0",
     "typescript": "^5.5.0"
   }
 }

package/src/ceidg-vertical.ts

@@ -0,0 +1,305 @@
+/**
+ * createVerticalApp — opinionated helper dla rodziny otwarty-* (CEIDG verticals).
+ *
+ * Każdy wertykal (`otwarty-trener`, `otwarty-terapeuta`, `otwarty-lekarz`, ...)
+ * dzielił dotąd ~230 LOC boilerplate'u: te same Hono routy, ten sam content
+ * loader, te same KV-cache helpery, te same opt-out handlery — różnica tylko
+ * w stałych. Helper wciąga to całe wnętrze do engine'u; wertykal staje się
+ * cienkim configiem (brand, copy, footer, kategoria SQL, pages, theme bundle).
+ *
+ * Co tu siedzi i dlaczego:
+ *   - Engine v0.1 jest GET-only (czysty SSR). Mutacje (`POST /opt-out`)
+ *     żyją tutaj, w warstwie `vertical`, bo to są handlery konkretnej rodziny
+ *     wertykali, nie generycznego runtime'u. Engine core (`createSSRWorker`)
+ *     pozostaje agnostyczny.
+ *   - Schema CEIDG (`leads`, `lead_pkd`, `lead_categories`, `cities`) jest
+ *     hard-coded w queries — to jest *cel* tego helpera. „Generic vertical
+ *     framework" nie istnieje, dopóki nie ma trzeciej rodziny niż otwarty-*.
+ *   - Theme bundle (`TrenerTheme`) jest **input**, nie tworzony tutaj. Engine
+ *     nie zna theme-specialist-glossy. Wertykal podaje gotowy bundle (~10 LOC
+ *     adaptera w landingu), helper tylko go wywołuje.
+ *   - `loadContent` filtruje po `EXISTS lead_categories WHERE category=?`
+ *     i — fix względem starego trener-landinga — `cities` query też filtruje
+ *     po kategorii (wcześniej trener pokazywał miasta z całej tabeli leads,
+ *     mieszając wszystkie wertykale).
+ *   - Opt-out jest **globalny** — UPDATE leads bez filtra category. RODO
+ *     sprzeciw to usunięcie danych osobowych, nie selektywne ukrycie w jednej
+ *     kategorii. Komentarz przeniesiony z terapeuta-landinga.
+ *
+ * Hono jest peer dependency (każdy wertykal i tak go ma). Engine core nie
+ * importuje Hono — tylko ten subpath go używa.
+ */
+
+import { Hono } from 'hono';
+import { createSSRWorker } from './runtime/ssr';
+import {
+  trenerTemplate,
+  type TrenerContent,
+  type TrenerProfile,
+  type TrenerTheme,
+} from './template-trener';
+
+/* ─────────────── Public types ─────────────── */
+
+/** Kształt wiersza z `leads` JOIN `cities` JOIN (subselect) `lead_pkd`. */
+export type CeidgLead = {
+  nip: string;
+  first_name: string;
+  last_name: string;
+  city: string | null;
+  company_name: string;
+  pkd: string | null;
+  slug: string;
+  claimed: number;
+  external_site_url: string | null;
+  fetched_at: number;
+  opted_out_at: number | null;
+};
+
+export type CeidgBindings = { DB: D1Database; CACHE: KVNamespace };
+
+/** Statyczna strona prawna/info — pełne body HTML, opcjonalny meta description. */
+export interface StaticPage {
+  title: string;
+  body: string;
+  description?: string;
+}
+
+export interface VerticalConfig {
+  /** Wartość `lead_categories.category`. Używana w SQL i w prefiksach KV cache. */
+  category: string;
+  /** Wersja landinga — wyświetlana w `/health` (debug) i w stopce. */
+  version: string;
+  brand: { siteName: string; description: string };
+  copy: {
+    heroBadge?: string;
+    heroTitle: string;
+    heroSubtitle?: string;
+    searchPlaceholder?: string;
+  };
+  /** PKD → human-readable jobTitle. Per-wertykal mapping. */
+  pkdToJobTitle(pkd: string | null | undefined): string;
+  /** Statyczne strony — RODO/regulamin/opt-out. Body HTML wkleja się w layout. */
+  pages: {
+    zasady: StaticPage;
+    optOutForm: StaticPage;
+    optOutDone: StaticPage;
+    /** Optional — RODO art. 14 dla linków społecznościowych. */
+    linkiInfo?: StaticPage;
+  };
+  /** llms.txt — header + intro paragraph. Lista profili dopisywana automatycznie. */
+  llms: { title: string; intro: string };
+  /** Theme bundle. Wertykal buduje adapter (Profile ↔ TrenerProfile) i podaje gotowy. */
+  theme: TrenerTheme;
+}
+
+/* ─────────────── Implementation ─────────────── */
+
+const KV_TTL = 86400;
+const OPTOUT_LIMIT = 5;
+const OPTOUT_WINDOW_SEC = 3600;
+
+export function createVerticalApp(config: VerticalConfig): Hono<{ Bindings: CeidgBindings }> {
+  const app = new Hono<{ Bindings: CeidgBindings }>();
+  app.onError((err, c) => c.json({ error: err.message, stack: err.stack }, 500));
+
+  const { category, version, brand, copy, pkdToJobTitle, pages, llms, theme } = config;
+
+  // ─────────── SQL ───────────
+  // EXISTS subselect zamiast JOIN: lead z N PKDs nie multiplikuje wierszy.
+  // (SELECT pkd ... LIMIT 1) wybiera jeden PKD per lead — wystarczy do
+  // pkdToJobTitle. To jest świadomy uproszczenie: lead z mieszanymi PKDs
+  // (np. fizjoterapia + psychologia) dostanie tylko jeden label.
+  const leadsQuery = `
+    SELECT l.nip, l.first_name, l.last_name, c.name as city,
+           l.company_name, l.slug, l.claimed, l.external_site_url, l.fetched_at,
+           l.opted_out_at,
+           (SELECT pkd FROM lead_pkd WHERE nip = l.nip LIMIT 1) as pkd
+    FROM leads l
+    LEFT JOIN cities c ON l.city_id = c.id
+    WHERE l.opted_out_at IS NULL
+      AND EXISTS (SELECT 1 FROM lead_categories WHERE lead_nip = l.nip AND category = ?)`;
+
+  // Cities query filtruje po kategorii — fix względem starego trener landinga
+  // który pokazywał miasta z całej tabeli leads (mieszane wertykale).
+  const citiesQuery = `
+    SELECT c.name, COUNT(*) as count
+    FROM leads l
+    JOIN cities c ON l.city_id = c.id
+    INNER JOIN lead_categories lc ON l.nip = lc.lead_nip AND lc.category = ?
+    WHERE l.opted_out_at IS NULL
+    GROUP BY c.name ORDER BY count DESC LIMIT 8`;
+
+  // ─────────── Content loader ───────────
+  function leadToProfile(l: CeidgLead): TrenerProfile {
+    return {
+      slug: l.slug,
+      firstName: l.first_name,
+      lastName: l.last_name,
+      jobTitle: pkdToJobTitle(l.pkd),
+      city: l.city ?? undefined,
+      specialties: [],
+      languages: [],
+      business: { name: l.company_name, taxId: l.nip, classification: l.pkd ? [l.pkd] : [] },
+      social: {},
+    };
+  }
+
+  async function loadContent(_host: string, env: unknown): Promise<TrenerContent> {
+    const e = env as CeidgBindings;
+    const [leadsRes, citiesRes] = await Promise.all([
+      e.DB.prepare(leadsQuery + ' ORDER BY c.name, l.last_name').bind(category).all<CeidgLead>(),
+      e.DB.prepare(citiesQuery).bind(category).all<{ name: string; count: number }>(),
+    ]);
+    return {
+      brand: { siteName: brand.siteName, description: brand.description },
+      copy: {
+        heroBadge: copy.heroBadge,
+        heroTitle: copy.heroTitle,
+        heroSubtitle: copy.heroSubtitle,
+        searchPlaceholder: copy.searchPlaceholder ?? 'Szukaj...',
+      },
+      profiles: (leadsRes.results ?? []).map(leadToProfile),
+      cities: citiesRes.results ?? [],
+    };
+  }
+
+  const engine = createSSRWorker({ template: trenerTemplate, theme, loadContent });
+
+  // ─────────── KV cache helper ───────────
+  async function cached<T>(kv: KVNamespace, key: string, fn: () => Promise<T>): Promise<T> {
+    const hit = await kv.get(key);
+    if (hit) return JSON.parse(hit) as T;
+    const data = await fn();
+    await kv.put(key, JSON.stringify(data), { expirationTtl: KV_TTL });
+    return data;
+  }
+
+  const ck = (suffix: string) => `vertical:${category}:${suffix}`;
+
+  // ─────────── Static page renderer ───────────
+  // Wszystkie strony statyczne idą przez ten helper — theme.layout dostarcza
+  // siteName/footer/CSS, wertykal podaje tylko {title, body, description}.
+  function renderStatic(page: StaticPage): string {
+    return theme.layout({ title: page.title, description: page.description }, page.body);
+  }
+
+  // ─────────── Routes: legacy / cached / mutations ───────────
+
+  app.get('/health', async (c) => {
+    const { results } = await c.env.DB
+      .prepare('SELECT COUNT(*) as cnt FROM lead_categories WHERE category = ?')
+      .bind(category)
+      .all();
+    return c.json({ ok: true, db: results, version, category });
+  });
+
+  app.get('/catalog.json', async (c) => {
+    const data = await cached(c.env.CACHE, ck('catalog.json'), async () => {
+      const { results } = await c.env.DB
+        .prepare(leadsQuery + ' ORDER BY c.name, l.last_name')
+        .bind(category)
+        .all<CeidgLead>();
+      const leads = results ?? [];
+      return {
+        version: 1,
+        source: 'ceidg',
+        category,
+        count: leads.length,
+        items: leads.map((l) => ({
+          slug: l.slug,
+          firstName: l.first_name,
+          lastName: l.last_name,
+          city: l.city,
+          companyName: l.company_name,
+          claimed: !!l.claimed,
+          url: '/' + l.slug,
+        })),
+      };
+    });
+    return c.json(data);
+  });
+
+  app.get('/llms.txt', async (c) => {
+    const text = await cached(c.env.CACHE, ck('llms.txt'), async () => {
+      const { results } = await c.env.DB
+        .prepare(leadsQuery + ' ORDER BY c.name, l.last_name')
+        .bind(category)
+        .all<CeidgLead>();
+      const leads = results ?? [];
+      return [
+        `# ${llms.title}`,
+        llms.intro,
+        '',
+        '## Wpisy',
+        ...leads.map((l) => `- ${l.first_name} ${l.last_name} (${l.city ?? '—'}) — /${l.slug}`),
+      ].join('\n');
+    });
+    return c.text(text);
+  });
+
+  app.get('/sitemap.xml', async (c) => {
+    const host = new URL(c.req.url).origin;
+    const xml = await cached(c.env.CACHE, ck(`sitemap:${host}`), async () => {
+      const { results } = await c.env.DB
+        .prepare(leadsQuery)
+        .bind(category)
+        .all<CeidgLead>();
+      const urls = [host + '/', ...(results ?? []).map((l) => host + '/' + l.slug)];
+      return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+        urls.map((u) => `  <url><loc>${u}</loc></url>`).join('\n') +
+        '\n</urlset>'
+      );
+    });
+    return c.body(xml, 200, { 'content-type': 'application/xml' });
+  });
+
+  app.get('/zasady', (c) => c.html(renderStatic(pages.zasady)));
+  if (pages.linkiInfo) {
+    app.get('/linki-info', (c) => c.html(renderStatic(pages.linkiInfo!)));
+  }
+  app.get('/opt-out', (c) => c.html(renderStatic(pages.optOutForm)));
+
+  app.post('/opt-out', async (c) => {
+    const form = await c.req.formData();
+    const nip = String(form.get('nip') ?? '').replace(/\D/g, '');
+    if (nip.length !== 10) return c.text('Nieprawidłowy NIP', 400);
+
+    const ip = c.req.header('cf-connecting-ip') ?? '0.0.0.0';
+    const rlKey = `vertical:${category}:rl:optout:${ip}`;
+    const rlVal = parseInt((await c.env.CACHE.get(rlKey)) ?? '0', 10);
+    if (rlVal >= OPTOUT_LIMIT) return c.text('Zbyt wiele prób. Spróbuj ponownie za godzinę.', 429);
+    await c.env.CACHE.put(rlKey, String(rlVal + 1), { expirationTtl: OPTOUT_WINDOW_SEC });
+
+    // Opt-out jest GLOBALNY — usuwa też z innych wertykali. RODO sprzeciw to
+    // usunięcie danych osobowych, nie selektywne ukrycie w jednej kategorii.
+    const res = await c.env.DB
+      .prepare(
+        'UPDATE leads SET opted_out_at = ?, opted_out_ip = ?, opted_out_ua = ? WHERE nip = ? AND opted_out_at IS NULL',
+      )
+      .bind(Math.floor(Date.now() / 1000), ip, c.req.header('user-agent') ?? '', nip)
+      .run();
+
+    if (!res.meta.changes) return c.text('Nie znaleziono wpisu', 404);
+    return c.html(renderStatic(pages.optOutDone));
+  });
+
+  // ─────────── /:slug — claim redirect → engine fallback ───────────
+  app.get('/:slug', async (c) => {
+    const slug = c.req.param('slug');
+    const claim = await c.env.DB
+      .prepare('SELECT claimed, external_site_url FROM leads WHERE slug = ?')
+      .bind(slug)
+      .first<{ claimed: number; external_site_url: string | null }>();
+    if (claim?.claimed && claim.external_site_url) {
+      return c.redirect(claim.external_site_url);
+    }
+    return engine.fetch(c.req.raw, c.env);
+  });
+
+  // ─────────── / — engine ───────────
+  app.get('/', (c) => engine.fetch(c.req.raw, c.env));
+
+  return app;
+}