@k2b/cloud 0.6.0 → 0.8.0

package/src/services/notifications/batches.ts

@@ -4,6 +4,7 @@ import type { Worker } from "@k2b/sync";
 import { sql } from "bun";
 import { lazySync } from "../../_internal/process-sync";
 import { markdown } from "../../shared/markdown";
+import { type AuditActor, audit } from "../audit";
 import { logger, trace } from "../logging";
 import { parsePgJsonValue, toPgTextArray, toPgUuidArray } from "../postgres";
 
@@ -406,7 +407,7 @@ export const createDraft = async (params: {
   subject: string;
   bodyMarkdown: string;
   selection: NotificationBatchSelection;
-  createdBy: string;
+  actor: AuditActor & { userId: string };
 }): Promise<Result<NotificationBatch>> => {
   const subject = params.subject.trim();
   const bodyMarkdown = params.bodyMarkdown.trim();
@@ -422,12 +423,24 @@ export const createDraft = async (params: {
   }
   const hash = selectionHash(selection);
   const bodyHtml = markdown.renderSync(bodyMarkdown);
-  const rows = await sql<BatchRow[]>`
-    INSERT INTO notifications.batches (subject, body_markdown, body_html, selection, selection_hash, created_by)
-    VALUES (${subject}, ${bodyMarkdown}, ${bodyHtml}, ${JSON.stringify(selection)}::jsonb, ${hash}, ${params.createdBy}::uuid)
-    RETURNING *
-  `;
-  return ok(mapBatch(rows[0]!));
+  return sql.begin(async (tx) => {
+    const rows = await tx<BatchRow[]>`
+      INSERT INTO notifications.batches (subject, body_markdown, body_html, selection, selection_hash, created_by)
+      VALUES (${subject}, ${bodyMarkdown}, ${bodyHtml}, ${JSON.stringify(selection)}::text::jsonb, ${hash}, ${params.actor.userId}::uuid)
+      RETURNING *
+    `;
+    const batch = mapBatch(rows[0]!);
+    await audit.record(
+      {
+        action: "accounts.notification_batch.create",
+        outcome: "allowed",
+        actor: params.actor,
+        target: { type: "notification_batch", id: batch.id },
+      },
+      tx,
+    );
+    return ok(batch);
+  });
 };
 
 export const get = async (id: string): Promise<NotificationBatch | null> => {
@@ -504,7 +517,7 @@ export const listRecipients = async (params: {
 
 export const finalize = async (params: {
   id: string;
-  actorUserId: string;
+  actor: AuditActor & { userId: string };
   expectedSelectionHash: string;
   expectedDeliverableCount: number;
   expectedRecipientHash: string;
@@ -568,7 +581,7 @@ export const finalize = async (params: {
       UPDATE notifications.batches
       SET
         status = 'ready',
-        finalized_by = ${params.actorUserId}::uuid,
+        finalized_by = ${params.actor.userId}::uuid,
         finalized_at = now(),
         target_count = ${candidates.length},
         deliverable_count = ${deliverableCount},
@@ -576,6 +589,16 @@ export const finalize = async (params: {
       WHERE id = ${params.id}::uuid
       RETURNING *
     `;
+    await audit.record(
+      {
+        action: "accounts.notification_batch.finalize",
+        outcome: "allowed",
+        actor: params.actor,
+        target: { type: "notification_batch", id: params.id },
+        metadata: { targetCount: candidates.length, deliverableCount },
+      },
+      tx,
+    );
     return ok(mapBatch(updated[0]!));
   });
 
@@ -584,28 +607,45 @@ export const finalize = async (params: {
   return ok({ batch: result.data, jobId });
 };
 
-export const retryFailed = async (params: { id: string }): Promise<Result<{ batch: NotificationBatch; jobId: string }>> => {
+export const retryFailed = async (params: {
+  id: string;
+  actor: AuditActor & { userId: string };
+}): Promise<Result<{ batch: NotificationBatch; jobId: string }>> => {
   const batch = await get(params.id);
   if (!batch) return fail(err.notFound("Notification batch not found"));
   if (batch.status === "draft" || batch.status === "cancelled") {
     return fail(err.conflict("Only finalized notification batches can retry recipients"));
   }
 
-  const updated = await sql<BatchRow[]>`
-    UPDATE notifications.batch_recipients
-    SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
-    WHERE batch_id = ${params.id}::uuid AND status = 'error' AND recipient IS NOT NULL
-    RETURNING user_id
-  `;
-  if (updated.length === 0) {
-    return fail(err.conflict("No failed deliverable recipients can be retried"));
-  }
+  const result = await sql.begin(async (tx) => {
+    const updated = await tx<BatchRow[]>`
+      UPDATE notifications.batch_recipients
+      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      WHERE batch_id = ${params.id}::uuid AND status = 'error' AND recipient IS NOT NULL
+      RETURNING user_id
+    `;
+    if (updated.length === 0) {
+      return fail(err.conflict("No failed deliverable recipients can be retried"));
+    }
 
-  await sql`
-    UPDATE notifications.batches
-    SET status = 'ready', completed_at = NULL, last_error = NULL
-    WHERE id = ${params.id}::uuid AND status IN ('completed_with_errors', 'failed', 'running', 'ready', 'completed')
-  `;
+    await tx`
+      UPDATE notifications.batches
+      SET status = 'ready', completed_at = NULL, last_error = NULL
+      WHERE id = ${params.id}::uuid AND status IN ('completed_with_errors', 'failed', 'running', 'ready', 'completed')
+    `;
+    await audit.record(
+      {
+        action: "accounts.notification_batch.retry_failed",
+        outcome: "allowed",
+        actor: params.actor,
+        target: { type: "notification_batch", id: params.id },
+        metadata: { recipientCount: updated.length },
+      },
+      tx,
+    );
+    return ok(null);
+  });
+  if (!result.ok) return result;
   const refreshed = await refreshBatchCounters(params.id);
   // A completing worker may already have sampled zero remaining recipients.
   // Explicit retries need their own wakeup even while that worker holds its key.
@@ -615,6 +655,7 @@ export const retryFailed = async (params: { id: string }): Promise<Result<{ batc
 
 export const retryRecipient = async (params: {
   id: string;
+  actor: AuditActor & { userId: string };
   userId: string;
 }): Promise<Result<{ batch: NotificationBatch; jobId: string }>> => {
   const batch = await get(params.id);
@@ -623,30 +664,44 @@ export const retryRecipient = async (params: {
     return fail(err.conflict("Only finalized notification batches can retry recipients"));
   }
 
-  const updated = await sql<BatchRow[]>`
-    UPDATE notifications.batch_recipients
-    SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
-    WHERE batch_id = ${params.id}::uuid
-      AND user_id = ${params.userId}::uuid
-      AND status = 'error'
-      AND recipient IS NOT NULL
-    RETURNING *
-  `;
-  if (!updated[0]) {
-    const existing = await sql<BatchRow[]>`
-      SELECT status, recipient
-      FROM notifications.batch_recipients
-      WHERE batch_id = ${params.id}::uuid AND user_id = ${params.userId}::uuid
+  const result = await sql.begin(async (tx) => {
+    const updated = await tx<BatchRow[]>`
+      UPDATE notifications.batch_recipients
+      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      WHERE batch_id = ${params.id}::uuid
+        AND user_id = ${params.userId}::uuid
+        AND status = 'error'
+        AND recipient IS NOT NULL
+      RETURNING *
     `;
-    if (!existing[0]) return fail(err.notFound("Notification recipient not found"));
-    return fail(err.conflict("Only failed deliverable recipients can be retried"));
-  }
+    if (!updated[0]) {
+      const existing = await tx<BatchRow[]>`
+        SELECT status, recipient
+        FROM notifications.batch_recipients
+        WHERE batch_id = ${params.id}::uuid AND user_id = ${params.userId}::uuid
+      `;
+      if (!existing[0]) return fail(err.notFound("Notification recipient not found"));
+      return fail(err.conflict("Only failed deliverable recipients can be retried"));
+    }
 
-  await sql`
-    UPDATE notifications.batches
-    SET status = 'ready', completed_at = NULL, last_error = NULL
-    WHERE id = ${params.id}::uuid AND status IN ('completed_with_errors', 'failed', 'running', 'ready', 'completed')
-  `;
+    await tx`
+      UPDATE notifications.batches
+      SET status = 'ready', completed_at = NULL, last_error = NULL
+      WHERE id = ${params.id}::uuid AND status IN ('completed_with_errors', 'failed', 'running', 'ready', 'completed')
+    `;
+    await audit.record(
+      {
+        action: "accounts.notification_batch.retry_recipient",
+        outcome: "allowed",
+        actor: params.actor,
+        target: { type: "notification_batch", id: params.id },
+        metadata: { recipientUserId: params.userId },
+      },
+      tx,
+    );
+    return ok(null);
+  });
+  if (!result.ok) return result;
   const refreshed = await refreshBatchCounters(params.id);
   const { jobId } = await batchJob().submit({
     key: `${params.id}:retry:${crypto.randomUUID()}`,
@@ -655,17 +710,29 @@ export const retryRecipient = async (params: {
   return ok({ batch: refreshed ?? batch, jobId });
 };
 
-export const removeDraft = async (params: { id: string }): Promise<Result<{ id: string }>> => {
-  const rows = await sql<BatchRow[]>`
-    DELETE FROM notifications.batches
-    WHERE id = ${params.id}::uuid AND status = 'draft'
-    RETURNING id
-  `;
-  if (rows[0]) return ok({ id: rows[0].id as string });
-
-  const batch = await get(params.id);
-  if (!batch) return fail(err.notFound("Notification batch not found"));
-  return fail(err.conflict("Only draft notification batches can be deleted"));
+export const removeDraft = async (params: { id: string; actor: AuditActor & { userId: string } }): Promise<Result<{ id: string }>> => {
+  return sql.begin(async (tx) => {
+    const rows = await tx<BatchRow[]>`
+      DELETE FROM notifications.batches
+      WHERE id = ${params.id}::uuid AND status = 'draft'
+      RETURNING id
+    `;
+    if (rows[0]) {
+      await audit.record(
+        {
+          action: "accounts.notification_batch.delete",
+          outcome: "allowed",
+          actor: params.actor,
+          target: { type: "notification_batch", id: params.id },
+        },
+        tx,
+      );
+      return ok({ id: params.id });
+    }
+    const existing = await tx`SELECT id FROM notifications.batches WHERE id = ${params.id}::uuid`;
+    if (!existing[0]) return fail(err.notFound("Notification batch not found"));
+    return fail(err.conflict("Only draft notification batches can be deleted"));
+  });
 };
 
 export const start = async (): Promise<void> => {
@@ -719,4 +786,5 @@ export const __notificationBatchTest = {
   selectionHash,
   recipientHash,
   resolveCandidates,
+  processBatchChunk,
 };

package/src/services/notifications/browser.ts

@@ -152,6 +152,18 @@ const browserDriver = {
   },
   deliver: async (value: unknown) => {
     const payload: BrowserDeliveryPayload = BrowserDeliveryPayloadSchema.parse(value);
+    // A queued payload can outlive logout, disable, or rebinding this browser to another user.
+    const [endpoint] = await sql<{ id: string }[]>`
+      SELECT id FROM notifications.endpoints
+      WHERE id = ${payload.endpointId}::uuid AND channel = 'browser'
+        AND verified_at IS NOT NULL AND disabled_at IS NULL
+    `;
+    if (!endpoint) {
+      throw Object.assign(new Error("Browser notification endpoint is no longer registered"), {
+        code: "endpoint_gone",
+        retryable: false,
+      });
+    }
     await ensureWebPushConfigured();
     try {
       await sendPinnedWebPush(

package/src/services/notifications/index.ts

@@ -6,7 +6,6 @@ import { logger } from "../logging";
 import { escapeLikePattern } from "../postgres";
 import { sendEmail } from "./email";
 import "./browser";
-import { notificationLive } from "./live";
 import { notificationObservability } from "./observability";
 import { sendTypedNotification, type TypedNotificationSendResult } from "./platform";
 import { userNotifications } from "./user";
@@ -610,7 +609,6 @@ export const notifications = {
   sendAllPendingSystem,
   getStatusSummary,
   getSearchSummary,
-  live: notificationLive,
   observability: notificationObservability,
   user: userNotifications,
 };

package/src/services/notifications/platform.ts

@@ -15,7 +15,6 @@ import { encryptSecret } from "../secrets";
 import { ensureNotificationDefinition } from "./catalog";
 import { getNotificationChannel, type NotificationDestination, type ResolvedNotificationRecipient } from "./channels";
 import { processNotificationDelivery } from "./dispatcher";
-import { notificationLive } from "./live";
 import { enqueueNotificationDeliveries, enqueueNotificationDelivery } from "./runtime";
 
 export type TypedNotificationDeliveryStatus = "deferred" | "pending" | "sending" | "delivered" | "suppressed" | "failed";
@@ -406,9 +405,6 @@ export const sendTypedNotification = async <
   });
 
   if (persisted.prepared) {
-    if (resolved.recipient.userId && (requiredChannelSet.has("browser") || preferred.includes("browser"))) {
-      await notificationLive.publish({ userId: resolved.recipient.userId, eventId: identity.id, presentation });
-    }
     for (const deliveryId of persisted.requiredIds) {
       const result = await processNotificationDelivery(deliveryId);
       if (result.status === "retry") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);

package/src/services/oauth-tokens.ts

@@ -6,7 +6,7 @@ import { isAccountExpired } from "./account-model";
 import { IDENTITY_JWKS_MAX_AGE_SECONDS } from "./identity/constants";
 import { getIdentityRuntimeConfig } from "./identity/runtime-config";
 import type { ServiceAccount } from "./service-accounts";
-import { buildProjectedUser, userProjectionSql } from "./session/user";
+import { buildProjectedUser, userProjectionJoin, userProjectionSql } from "./session/user";
 
 type ServiceAccountActorRow = Record<string, unknown> & {
   service_account_id: string;
@@ -116,7 +116,7 @@ export const resolveOAuthTokenActor = async (
       FROM oauth.clients c
       JOIN auth.service_accounts sa ON sa.id = ${serviceAccountId}::uuid AND sa.status = 'active'
       LEFT JOIN auth.users u ON u.id = sa.delegated_user_id
-      LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+      ${userProjectionJoin()}
       WHERE c.client_id = ${clientId}
     `;
     const row = rows[0];
@@ -139,7 +139,7 @@ export const resolveOAuthTokenActor = async (
     SELECT ${userProjectionSql(groupsAdmin)}
     FROM oauth.clients c
     JOIN auth.users u ON ${predicate}
-    LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+    ${userProjectionJoin()}
     WHERE c.client_id = ${clientId}
   `;
   const user = rows[0] ? buildProjectedUser(rows[0]) : null;

package/src/services/pdf/gotenberg.ts

@@ -34,6 +34,18 @@ export type RenderHtmlToPdfInput = {
   headerHtml?: string | null;
   footerHtml?: string | null;
   filename?: string;
+  assets?: Array<{ name: string; data: Blob }>;
+  page?: {
+    format?: "A4" | "A3" | "A5" | "Letter" | "Legal";
+    landscape?: boolean;
+    margin?: { top?: number; right?: number; bottom?: number; left?: number };
+  };
+  tagged?: boolean;
+};
+
+export type AttachPdfFilesInput = {
+  document: Blob;
+  attachments: Array<{ name: string; data: Blob; relationship?: "Source" | "Data" | "Alternative" | "Supplement" | "Unspecified" }>;
 };
 
 export type RenderFacturXHtmlToPdfInput = RenderHtmlToPdfInput & {
@@ -59,6 +71,7 @@ export type GotenbergFetch = (input: string | URL | Request, init?: RequestInit)
 
 export type RenderHtmlToPdfOptions = {
   fetch?: GotenbergFetch;
+  signal?: AbortSignal;
 };
 
 const DEFAULT_PDF_CONTENT_TYPE = "application/pdf";
@@ -105,111 +118,154 @@ const sanitizeFetchError = (error: unknown): GotenbergRenderError => {
   return new GotenbergRenderError("request_failed", "Gotenberg request failed.");
 };
 
-export const renderHtmlToPdfWithConfig = async (
-  input: RenderHtmlToPdfInput,
-  config: GotenbergConfig,
-  options: RenderHtmlToPdfOptions = {},
-): Promise<RenderHtmlToPdfResult> => {
-  const htmlBytes = byteLength(input.html);
-  if (htmlBytes > config.maxHtmlBytes) {
-    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
-  }
+const dimensions = { A4: [210, 297], A3: [297, 420], A5: [148, 210], Letter: [215.9, 279.4], Legal: [215.9, 355.6] } as const;
+const fileName = (name: string) => {
+  if (!name || name.length > 180 || /[\\/\x00-\x1f]/.test(name) || name === "." || name === "..")
+    throw new GotenbergRenderError("bad_input", "Use a plain filename without directories.");
+  return name;
+};
 
-  const baseUrl = normalizeBaseUrl(config.url);
+function htmlForm(input: RenderHtmlToPdfInput, config: GotenbergConfig): FormData {
+  const total =
+    [input.html, input.headerHtml ?? "", input.footerHtml ?? ""].reduce((sum, value) => sum + byteLength(value), 0) +
+    (input.assets ?? []).reduce((sum, asset) => sum + asset.data.size, 0);
+  if (total > config.maxHtmlBytes) throw new GotenbergRenderError("html_too_large", "HTML and assets exceed the configured input budget.");
   const form = new FormData();
   form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
   if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
   if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
-  form.append("preferCssPageSize", "true");
+  const names = new Set(["index.html", "header.html", "footer.html", "factur-x.xml"]);
+  for (const asset of input.assets ?? []) {
+    const name = fileName(asset.name);
+    if (names.has(name.toLowerCase()))
+      throw new GotenbergRenderError("bad_input", "Asset filenames must be unique and cannot replace HTML documents.");
+    names.add(name.toLowerCase());
+    form.append("files", asset.data, name);
+  }
+  // Preserve the existing CSS page-size contract unless a caller supplies page options.
+  form.append("preferCssPageSize", String(!input.page));
   form.append("printBackground", "true");
+  if (input.tagged !== undefined) form.append("generateTaggedPdf", String(input.tagged));
+  if (input.page) {
+    const [width, height] = dimensions[input.page.format ?? "A4"];
+    form.append("paperWidth", String(width / 25.4));
+    form.append("paperHeight", String(height / 25.4));
+    form.append("landscape", String(input.page.landscape ?? false));
+    for (const side of ["top", "right", "bottom", "left"] as const) {
+      const value = input.page.margin?.[side] ?? 15;
+      if (!Number.isFinite(value) || value < 0)
+        throw new GotenbergRenderError("bad_input", "Page margins must be nonnegative millimeters.");
+      form.append(`margin${side[0]!.toUpperCase()}${side.slice(1)}`, String(value / 25.4));
+    }
+  }
+  return form;
+}
 
+/** Bounded transport shared by HTML conversion and attachment embedding. */
+async function requestPdf(
+  route: string,
+  form: FormData,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions,
+): Promise<RenderHtmlToPdfResult> {
   const headers = new Headers();
-  const authHeader = basicAuthHeader(config);
-  if (authHeader) headers.set("Authorization", authHeader);
-
-  const transport = options.fetch ?? fetch;
-  let response: Response;
+  const auth = basicAuthHeader(config);
+  if (auth) headers.set("Authorization", auth);
+  const signal = options.signal ? AbortSignal.any([options.signal, abortSignal(config.timeoutMs)]) : abortSignal(config.timeoutMs);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
   try {
-    response = await transport(`${baseUrl}/forms/chromium/convert/html`, {
+    const response = await (options.fetch ?? fetch)(`${normalizeBaseUrl(config.url)}${route}`, {
       method: "POST",
       headers,
       body: form,
-      signal: abortSignal(config.timeoutMs),
+      signal,
     });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
+    }
+    const contentType = response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE;
+    if (contentType.split(";")[0] !== DEFAULT_PDF_CONTENT_TYPE) {
+      await response.body?.cancel();
+      throw new GotenbergRenderError("bad_response", "Gotenberg did not return a PDF.");
+    }
+    if (!response.body) throw new GotenbergRenderError("bad_response", "Gotenberg returned an empty response.");
+    reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    while (true) {
+      signal.throwIfAborted();
+      const item = await reader.read();
+      if (item.done) break;
+      size += item.value.byteLength;
+      if (size > config.maxPdfBytes) throw new GotenbergRenderError("pdf_too_large", "PDF output exceeds the configured budget.");
+      chunks.push(item.value);
+    }
+    const pdf = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      pdf.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return { pdf, contentType };
   } catch (error) {
+    await reader?.cancel().catch(() => {});
     throw sanitizeFetchError(error);
+  } finally {
+    reader?.releaseLock();
   }
+}
 
-  if (!response.ok) {
-    throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
-  }
-
-  const buffer = await response.arrayBuffer();
-  if (buffer.byteLength > config.maxPdfBytes) {
-    throw new GotenbergRenderError(
-      "pdf_too_large",
-      `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`,
-    );
-  }
-
-  return {
-    pdf: new Uint8Array(buffer),
-    contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE,
-  };
-};
+export const renderHtmlToPdfWithConfig = async (
+  input: RenderHtmlToPdfInput,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => requestPdf("/forms/chromium/convert/html", htmlForm(input, config), config, options);
 
 export const renderFacturXHtmlToPdfWithConfig = async (
   input: RenderFacturXHtmlToPdfInput,
   config: GotenbergConfig,
   options: RenderHtmlToPdfOptions = {},
 ): Promise<RenderHtmlToPdfResult> => {
-  const htmlBytes = byteLength(input.html);
   const xmlBytes = byteLength(input.xml);
-  if (htmlBytes > config.maxHtmlBytes) {
-    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
-  }
-  if (xmlBytes === 0 || xmlBytes > config.maxHtmlBytes) {
+  if (!xmlBytes || xmlBytes > config.maxHtmlBytes)
     throw new GotenbergRenderError(
-      xmlBytes === 0 ? "bad_input" : "html_too_large",
-      xmlBytes === 0
-        ? "Factur-X XML must not be empty."
-        : `Factur-X XML input is too large (${xmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`,
+      xmlBytes ? "html_too_large" : "bad_input",
+      "Invoice XML is empty or exceeds the configured input budget.",
     );
-  }
-
-  const baseUrl = normalizeBaseUrl(config.url);
-  const form = new FormData();
-  form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
-  if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
-  if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
+  const form = htmlForm(input, { ...config, maxHtmlBytes: config.maxHtmlBytes - xmlBytes });
   form.append("facturxXml", new Blob([input.xml], { type: "application/xml" }), "factur-x.xml");
   form.append("facturxConformanceLevel", input.conformanceLevel ?? "EN 16931");
   form.append("facturxDocumentType", input.documentType ?? "INVOICE");
   form.append("facturxVersion", input.facturXVersion ?? "1.0");
   form.append("pdfa", "PDF/A-3b");
-  form.append("preferCssPageSize", "true");
-  form.append("printBackground", "true");
+  return requestPdf("/forms/chromium/convert/html", form, config, options);
+};
 
-  const headers = new Headers();
-  const authHeader = basicAuthHeader(config);
-  if (authHeader) headers.set("Authorization", authHeader);
-  let response: Response;
-  try {
-    response = await (options.fetch ?? fetch)(`${baseUrl}/forms/chromium/convert/html`, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: abortSignal(config.timeoutMs),
-    });
-  } catch (error) {
-    throw sanitizeFetchError(error);
-  }
-  if (!response.ok) throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
-  const buffer = await response.arrayBuffer();
-  if (buffer.byteLength > config.maxPdfBytes) {
-    throw new GotenbergRenderError("pdf_too_large", `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`);
+export const attachPdfFilesWithConfig = async (
+  input: AttachPdfFilesInput,
+  config: GotenbergConfig,
+  options: RenderHtmlToPdfOptions = {},
+): Promise<RenderHtmlToPdfResult> => {
+  if (!input.attachments.length) throw new GotenbergRenderError("bad_input", "At least one attachment is required.");
+  if (input.document.size + input.attachments.reduce((sum, file) => sum + file.data.size, 0) > config.maxPdfBytes)
+    throw new GotenbergRenderError("pdf_too_large", "PDF and attachments exceed the configured input budget.");
+  const form = new FormData();
+  form.append("files", input.document, "document.pdf");
+  const metadata: Record<string, { mimeType: string; relationship: string }> = Object.create(null);
+  const names = new Set<string>();
+  for (const attachment of input.attachments) {
+    const name = fileName(attachment.name);
+    if (names.has(name.toLowerCase())) throw new GotenbergRenderError("bad_input", "Attachment filenames must be unique.");
+    names.add(name.toLowerCase());
+    form.append("embeds", attachment.data, name);
+    metadata[name] = {
+      mimeType: attachment.data.type || "application/octet-stream",
+      relationship: attachment.relationship ?? "Unspecified",
+    };
   }
-  return { pdf: new Uint8Array(buffer), contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE };
+  form.append("embedsMetadata", JSON.stringify(metadata));
+  return requestPdf("/forms/pdfengines/embed", form, config, options);
 };
 
 export const mergePdfsWithConfig = async (
@@ -288,3 +344,6 @@ export const testGotenberg = async (options: RenderHtmlToPdfOptions = {}): Promi
   const result = await renderHtmlToPdf({ html: TEST_HTML, filename: "index.html" }, options);
   return { bytes: result.pdf.byteLength, contentType: result.contentType };
 };
+
+export const attachPdfFiles = async (input: AttachPdfFilesInput, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> =>
+  attachPdfFilesWithConfig(input, await getGotenbergConfig(), options);

package/src/services/pdf/index.ts

@@ -1,4 +1,5 @@
 export type {
+  AttachPdfFilesInput,
   GotenbergConfig,
   GotenbergRenderErrorCode,
   MergePdfsInput,
@@ -8,6 +9,8 @@ export type {
   RenderHtmlToPdfResult,
 } from "./gotenberg";
 export {
+  attachPdfFiles,
+  attachPdfFilesWithConfig,
   GotenbergRenderError,
   getGotenbergConfig,
   mergePdfs,
@@ -18,14 +21,6 @@ export {
   renderHtmlToPdfWithConfig,
   testGotenberg,
 } from "./gotenberg";
-export type {
-  RenderTemplatePdfPreviewInput,
-  RenderTemplatePdfPreviewOptions,
-  TemplatePdfPreviewError,
-  TemplatePdfPreviewPhase,
-  TemplatePdfPreviewResult,
-} from "./template-preview";
-export { renderTemplatePdfPreview } from "./template-preview";
 export type {
   MarkdownPdfErrorCode,
   MarkdownPdfTemplateId,
@@ -41,3 +36,11 @@ export {
   renderMarkdownToPdf,
   renderMarkdownToPdfWithConfig,
 } from "./markdown";
+export type {
+  RenderTemplatePdfPreviewInput,
+  RenderTemplatePdfPreviewOptions,
+  TemplatePdfPreviewError,
+  TemplatePdfPreviewPhase,
+  TemplatePdfPreviewResult,
+} from "./template-preview";
+export { renderTemplatePdfPreview } from "./template-preview";