@protobase/cli 0.66.3 → 0.66.4

package/dist/build/pdfkit-fonts.js

@@ -0,0 +1,22 @@
+//#region src/build/pdfkit-fonts.ts
+const nodeBuild = /[\\/]pdfkit[\\/]js[\\/]pdfkit\.node\.mjs$/;
+const fontLoad = /\b[\w$]+\('#standard-fonts\/(\w+)'\)/g;
+/**
+* Bundles pdfkit's standard fonts, which React PDF's renderer writes text in. pdfkit's Node build loads each with a
+* `require` of its own subpath import, `#standard-fonts/Helvetica`, made at run time, which a bundle cannot resolve
+* from its own folder; this turns each into an import of the font's module beside it.
+*/
+const pdfkitFonts = () => ({
+	name: "protobase-pdfkit-fonts",
+	transform(code, id) {
+		if (!nodeBuild.test(id)) return;
+		const fonts = new Set([...code.matchAll(fontLoad)].map(([, font]) => font));
+		if (fonts.size === 0) this.error("pdfkit no longer loads its standard fonts as `require(\"#standard-fonts/<Font>\")`; update pdfkitFonts");
+		return {
+			code: [...fonts].map((font) => `import __pdfkitFont${font} from './standard-fonts/${font}.mjs'\n`).join("") + code.replace(fontLoad, (_, font) => `__pdfkitFont${font}`),
+			map: null
+		};
+	}
+});
+//#endregion
+export { pdfkitFonts };

package/dist/build/serve-runtime.js

@@ -1,6 +1,7 @@
 import { moduleFile } from "../module-file.js";
 import { viteBundle } from "./vite-bundle.js";
 import { npmWs } from "./npm-ws.js";
+import { pdfkitFonts } from "./pdfkit-fonts.js";
 import { fileURLToPath } from "node:url";
 //#region src/build/serve-runtime.ts
 const cliRoot = fileURLToPath(new URL("../..", import.meta.url));
@@ -11,7 +12,7 @@ const buildServeRuntime = async ({ outFile, bun }) => {
 		entry: serveMain,
 		outFile,
 		bun,
-		plugins: [npmWs()]
+		plugins: [npmWs(), pdfkitFonts()]
 	});
 };
 //#endregion

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.66.3";
+var version = "0.66.4";
 //#endregion
 export { version };

package/dist/serve/host-module-ids.js

@@ -7,6 +7,7 @@ const hostModuleIds = [
 	"@protobase/layout/jsx-runtime",
 	"@protobase/query",
 	"@protobase/server",
+	"@protobase/server/pdf",
 	...lazyHostModuleIds,
 	"kysely",
 	"kysely/helpers/postgres",

package/dist/serve/host-modules.js

@@ -20,6 +20,7 @@ import * as react from "react";
 import * as reactJsxRuntime from "react/jsx-runtime";
 import * as zod from "zod";
 import * as protobaseConfig from "@protobase/config";
+import * as pdf from "@protobase/server/pdf";
 //#region src/serve/host-modules.ts
 const hostModules = {
 	"@protobase/config": protobaseConfig,
@@ -28,6 +29,7 @@ const hostModules = {
 	"@protobase/layout/jsx-runtime": layout.jsxRuntime,
 	"@protobase/query": query,
 	"@protobase/server": server,
+	"@protobase/server/pdf": pdf,
 	kysely,
 	"kysely/helpers/postgres": kyselyPostgres,
 	pg: pg$1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.66.3",
+  "version": "0.66.4",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -42,12 +42,12 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.66.3",
-    "@protobase/layout": "0.66.3",
-    "@protobase/query": "0.66.3",
-    "@protobase/schema": "0.66.3",
-    "@protobase/server": "0.66.3",
-    "@protobase/ui": "0.66.3",
+    "@protobase/config": "0.66.4",
+    "@protobase/layout": "0.66.4",
+    "@protobase/query": "0.66.4",
+    "@protobase/schema": "0.66.4",
+    "@protobase/server": "0.66.4",
+    "@protobase/ui": "0.66.4",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@tailwindcss/vite": "^4.3.3",

package/skills/protobase/SKILL.md

@@ -89,6 +89,7 @@ Reference:
 - When letting people without an account create records → read [Public forms](references/reference/forms.md)
 - When running background jobs → read [Jobs](references/reference/jobs.md)
 - When sending email → read [Email](references/reference/email.md)
+- When making a PDF file, such as an invoice, a quote or a report → read [PDF documents](references/reference/pdf.md)
 - When registering users' devices for push notifications → read [Notifications](references/reference/notifications.md)
 - When people should set themselves busy, do not disturb or a status text, or see others' beside their names → read [Status](references/reference/status.md)
 - When adding audio and video calls, through LiveKit or peer to peer → read [Calls](references/reference/calls.md)

package/skills/protobase/references/features/email-and-public-forms.md

@@ -2,12 +2,13 @@
 
 # Email and public forms
 
-Mail the app sends, and forms for people without an account.
+Mail the app sends, the PDF documents it makes, and forms for people without an account.
 
 - [Email](../reference/email.md#configuration): The app sends mail through one SMTP server or a mailer you supply.
 - [Built-in emails](../reference/email.md#protobases-own-mail): Sign-in codes, password resets, invitations and mentions are sent in the app's name.
 - [Email templates](../reference/email.md#templates): Your own emails are React components with typed data, sent from jobs, hooks or functions.
 - [Attachments](../reference/email.md#attachments): A message carries files, such as an invoice's PDF, through the app's mail or someone's own mailbox.
+- [PDF documents](../reference/pdf.md#documents): PDF files such as invoices and quotes are React components with typed data, rendered from jobs, hooks or functions and attached to mail as they are.
 - [Mail from your own mailbox](../reference/email.md#from-someones-own-mailbox) (beta): People link their Gmail on the account page, and the app's functions send mail from it, with a clear error when the link is missing or expired.
 - [Public forms](../reference/forms.md#what-the-visitor-sees): A form at its own address lets people without an account create a record, such as a contact request.
 - [Bot check](../reference/forms.md#bot-check): Each submission passes a check in the browser, without a third-party service or a puzzle.

package/skills/protobase/references/features.md

@@ -33,7 +33,7 @@ A feature without a mark is stable. The others say so after their name:
 - [Events, webhooks and jobs](features/events-webhooks-and-jobs.md): React to changes, deliver them to other systems, and run work in the background.
 - [Notifications](features/notifications.md): A bell in the top bar and push to browsers and phones, for what your app tells its users.
 - [Calls](features/calls.md): Audio and video calls between an app's users, with Protobase deciding who is in a call and who hears whom.
-- [Email and public forms](features/email-and-public-forms.md): Mail the app sends, and forms for people without an account.
+- [Email and public forms](features/email-and-public-forms.md): Mail the app sends, the PDF documents it makes, and forms for people without an account.
 - [AI](features/ai.md): Fields and actions filled by a model, the assistant beside the admin, and MCP.
 - [Compatibility and moving from other systems](features/compatibility.md): Apps written for other systems that keep working on Protobase, and moving their data and code over.
 - [Several apps](features/several-apps.md): Show another Protobase app's records and accept its users.

package/skills/protobase/references/reference/cli.md

@@ -262,10 +262,13 @@ The modules the app shares with plugins, `react`, `react/jsx-runtime`, `react-do
   | `better-auth`, `hono`, `jose`, `zod`, `aip-parsers`, `@hono/node-server`, `@scalar/hono-api-reference` | the main entry of each other dependency the `@protobase` packages run on the server |
   | `hono/cors`, `hono/http-exception`, `hono/validator` | Hono middleware for [API functions](../guides/api-functions.md) |
   | `react`, `react/jsx-runtime`, `@react-email/render` | what [email templates](email.md#in-a-bundle) render with, so a template's component and the renderer share one React |
+  | `@protobase/server/pdf` | React PDF's components, which [PDF documents](pdf.md#in-a-bundle) are built from; `definePdf` renders them with the runtime's React PDF, loaded on the first document rendered |
   | `@protobase/server/email` | the [look of Protobase's own mail](email.md#the-look-of-protobases-own-mail), loaded when the bundle first imports it rather than when the runtime starts |
 
   `react-email` is a dependency of `@protobase/server` that the runtime does not supply: the server loads it only to send its own mail, or for `@protobase/server/email`, so a config that imports it inlines its own copy, like any other package.
 
+  `@react-pdf/renderer` is a dependency of `@protobase/server` that the runtime keeps to itself: a config imports React PDF's components from `@protobase/server/pdf` instead.
+
   Importing any other `@protobase` package or dependency of one (`@protobase/ui`, `react-dom`, `better-auth/plugins`, `zod/v4`, ...) fails the build with this list, also from inside an inlined package, when the finished bundle still imports it: an inlined package may re-export a module that imports one, as `react-email` does with `tailwindcss`, as long as the project leaves that export unused. The runtime supplies them at its own versions, whichever the project installed. The list is `packages/cli/src/serve/host-module-ids.ts`; the set of packages comes from the `package.json` of `@protobase/cli` and of every `@protobase` package it depends on.
 - Packages with a native add-on stay imports too, and the bundle carries them in `node_modules/` (see [Native packages](#native-packages)). Node's built-in modules stay imports.
 - Everything else (the project's files and its other packages) is inlined. Nothing is minified.

package/skills/protobase/references/reference/pdf.md

@@ -0,0 +1,140 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/reference/pdf.mdx: run `bun run docs:skill`, do not edit. -->
+
+# PDF documents
+
+PDF files an app makes, such as invoices, quotes and reports, written as React components with typed data and rendered from jobs, hooks and API functions.
+
+An app makes a PDF file, such as an invoice, a quote or a report, from a React component of its data, the way it writes its [emails](email.md#templates). The component is built from the components of [React PDF](https://react-pdf.org) (`@react-pdf/renderer`), and Protobase renders it to the bytes of a PDF file with React PDF's renderer.
+
+## Documents
+
+A document is `definePdf`: a name and a React component whose props are the document's data, with React PDF's `<Document>` at its root. `@protobase/server` brings React PDF; the project adds React for its JSX, which a project with a UI has already:
+
+```sh
+bun add react
+bun add -d @types/react
+```
+
+```tsx title="documents/repair-quote.tsx"
+import { definePdf } from '@protobase/server'
+import { Document, Page, StyleSheet, Text, View } from '@protobase/server/pdf'
+
+export type RepairQuote = { number: string; customer: string; bike: string; problem: string; estimate: string }
+
+const styles = StyleSheet.create({
+  page: { padding: 48, fontSize: 11, fontFamily: 'Helvetica' },
+  heading: { fontSize: 20, fontFamily: 'Helvetica-Bold', marginBottom: 16 },
+  row: { flexDirection: 'row', justifyContent: 'space-between', borderBottom: '1pt solid #e4e4e7', paddingVertical: 6 },
+})
+
+// The document's data is the component's props: `render` takes exactly these.
+const RepairQuoteDocument = ({ number, customer, bike, problem, estimate }: RepairQuote) => (
+  <Document title={`Quote ${number}`}>
+    <Page size="A4" style={styles.page}>
+      <Text style={styles.heading}>Quote {number}</Text>
+      <Text>For {customer}</Text>
+      <View style={styles.row}>
+        <Text>
+          {bike}: {problem}
+        </Text>
+        <Text>{estimate}</Text>
+      </View>
+    </Page>
+  </Document>
+)
+
+export const repairQuote = definePdf({ name: 'repair-quote', component: RepairQuoteDocument })
+```
+
+| `definePdf` option | |
+| --- | --- |
+| `name` | Names the document. |
+| `component` | The document, a React component of the data with a `<Document>` at its root. |
+
+The definition that comes back has one method, typed by the component's props: `render(data)` gives the bytes of the PDF file, a `Uint8Array`. An email's [attachment](email.md#attachments) and a `Response` take them as they are.
+
+React and React PDF's renderer are loaded on the first document rendered, not when the app starts.
+
+## Components
+
+`@protobase/server/pdf` exports React PDF's components, typed as `@react-pdf/renderer` types them: `Document`, `Page`, `View`, `Text`, `Link`, `Image`, `ImageBackground`, `Note`, `Canvas`, the form fields `FieldSet`, `TextInput`, `Checkbox`, `Select` and `List`, and `Svg` with its shapes (`G`, `Path`, `Rect`, `Line`, `Circle`, `Ellipse`, `Polygon`, `Polyline`, `Tspan`, `Defs`, `Stop`, `ClipPath`, `Marker`, `LinearGradient`, `RadialGradient`). `StyleSheet.create` types a document's styles. React PDF's documentation explains each component and the styles they take: [components](https://react-pdf.org/components), [styling](https://react-pdf.org/styling).
+
+Importing them loads nothing of React PDF: they are only the names its renderer knows its elements by.
+
+- **Fonts:** text is set in the PDF standard fonts, `Helvetica` (the default), `Times-Roman` and `Courier`, each with its bold and italic faces, such as `Helvetica-Bold`, chosen with the `fontFamily` style. They write the characters of Windows-1252, the Latin script of Western European languages, the euro sign included.
+- <gap>Documents cannot use fonts of their own, nor scripts beyond Windows-1252, because registering a font with React PDF's renderer is not implemented.</gap>
+- **Images:** the renderer fetches an `<Image>` whose `src` is a URL, and reads one whose `src` is a file path, on the server. Give it the image's bytes, as a `Buffer` or a `data:` URI, or an address the app chose, never one a user typed.
+
+## Rendering
+
+An **[API function](../guides/api-functions.md)** may answer with the file, for the browser to show or save:
+
+```ts title="functions/repair-quote.ts"
+import { defineFunction } from '@protobase/server'
+import { repairQuote } from '../documents/repair-quote'
+
+// GET /api/functions/repair-quote/7: the repair's quote as a PDF file, which the browser shows or saves.
+export default defineFunction({ roles: ['desk'] }, async (request, { records }) => {
+  const id = Number(new URL(request.url).pathname.slice(1))
+  const { record: repair } = await records.get('repairs', id)
+  const { record: customer } = await records.get('customers', repair.customer_id as number)
+  const number = repair.number as string
+  const pdf = await repairQuote.render({
+    number,
+    customer: customer.name as string,
+    bike: repair.bike as string,
+    problem: repair.problem as string,
+    estimate: `${repair.currency} ${repair.estimate}`,
+  })
+  return new Response(pdf, { headers: { 'content-type': 'application/pdf', 'content-disposition': `inline; filename="quote-${number}.pdf"` } })
+})
+```
+
+A **job** renders it to send by mail, so the email goes out after the write that asked for it committed, and a message the server refuses is retried. A **write hook** enqueues such a job rather than rendering in the write's transaction, as for [email](email.md#sending):
+
+```ts title="jobs/email-repair-quote.ts"
+import { FatalJobError, type JobRun } from '@protobase/server'
+import { repairQuote } from '../documents/repair-quote'
+
+// Emails the customer their repair's quote, the PDF attached as it was rendered.
+export default (async ({ repairId }, { db, mail }) => {
+  if (!mail) throw new FatalJobError('Mail is off: set PROTOBASE_SMTP_URL and PROTOBASE_MAIL_FROM')
+  const repair = await db
+    .selectFrom('repairs')
+    .innerJoin('customers', 'customers.id', 'repairs.customer_id')
+    .select(['repairs.number', 'repairs.bike', 'repairs.problem', 'repairs.estimate', 'repairs.currency', 'customers.name', 'customers.email'])
+    .where('repairs.id', '=', repairId)
+    .executeTakeFirst()
+  if (!repair?.email) return
+  const pdf = await repairQuote.render({
+    number: repair.number,
+    customer: repair.name,
+    bike: repair.bike,
+    problem: repair.problem,
+    estimate: `${repair.currency} ${repair.estimate}`,
+  })
+  await mail.send({
+    to: repair.email,
+    subject: `Quote ${repair.number} for your ${repair.bike}`,
+    text: `Hi ${repair.name}, the quote for your ${repair.bike} is attached.`,
+    attachments: [{ filename: `quote-${repair.number}.pdf`, content: pdf, contentType: 'application/pdf' }],
+  })
+}) satisfies JobRun<{ repairId: number }>
+```
+
+```ts title="protobase.config.ts"
+import { defineConfig } from '@protobase/config'
+
+export default defineConfig({
+  jobs: {
+    // jobs/email-repair-quote.ts
+    'email-repair-quote': { description: "Emails a customer their repair's quote as a PDF.", arguments: { repairId: 'integer' } },
+  },
+})
+```
+
+A [template's](email.md#templates) `send` takes the same attachment as its fourth argument, and so does a function's `personalMail`, to send it from [someone's own mailbox](email.md#from-someones-own-mailbox).
+
+## In a bundle
+
+A [bundle](cli.md#the-config-module) gets `@protobase/server/pdf` from the serve runtime, as it gets `@protobase/server`, whose `definePdf` renders with the runtime's own React PDF. A served config imports React PDF's components from `@protobase/server/pdf`: `@react-pdf/renderer` is a dependency of `@protobase/server` that the runtime does not hand to a bundle, so importing it fails the build.