@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

package/packages/bundled-features/src/managed-pages/web/markdown-to-document.ts

@@ -0,0 +1,27 @@
+import { isAllowedDocumentLinkHref } from "@cosmicdrift/kumiko-bundled-features/template-resolver/document-schema";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
+import { Marked } from "marked";
+
+// The server sanitizer rejects what it cannot keep, so the conversion drops it up front and the
+// lossy banner stays true: a link outside the document link policy keeps its text, an image
+// (no uploaded resource to point at) is dropped, and raw HTML is shown as text.
+const converter = new Marked({ gfm: false, breaks: false });
+converter.use({
+  renderer: {
+    html({ text }) {
+      return escapeHtml(text);
+    },
+    link({ href, tokens }) {
+      return isAllowedDocumentLinkHref(href) ? false : this.parser.parseInline(tokens);
+    },
+    image() {
+      return "";
+    },
+  },
+});
+
+export function markdownToDocumentHtml(markdown: string): string {
+  const html = converter.parse(markdown, { async: false });
+  if (typeof html !== "string") throw new Error("marked returned a promise for a sync parse");
+  return html;
+}

package/packages/bundled-features/src/managed-pages/web/page-body-section.tsx

@@ -0,0 +1,73 @@
+import {
+  type ExtensionSectionProps,
+  usePrimitives,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useMemo, useState } from "react";
+import { DocumentContentEditor } from "../../template-resolver/web/index.ts";
+import { effectiveBodyFormat } from "./constants.ts";
+import { detectLossyMarkdown, type LossyMarkdownFeature } from "./lossy-markdown.ts";
+import { markdownToDocumentHtml } from "./markdown-to-document.ts";
+
+const LOSSY_LABEL_KEYS: Readonly<Record<LossyMarkdownFeature, string>> = {
+  image: "managed-pages:body.lossy.image",
+  blockquote: "managed-pages:body.lossy.blockquote",
+  code: "managed-pages:body.lossy.code",
+  deepHeading: "managed-pages:body.lossy.deepHeading",
+  relativeLink: "managed-pages:body.lossy.relativeLink",
+};
+
+const BODY_EDITOR_ID = "managed-pages-page-body";
+
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+// A Markdown body is converted for display only: nothing is patched until the
+// user edits, so merely opening a page never turns it into a document.
+export function PageBodySection({ values, patch }: ExtensionSectionProps): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  const body = stringValue(values?.["body"]);
+  const isMarkdown = effectiveBodyFormat(values?.["bodyFormat"]) === "markdown";
+  const [editedHtml, setEditedHtml] = useState<string | null>(null);
+  const [lossyAtFirstEdit, setLossyAtFirstEdit] = useState<readonly LossyMarkdownFeature[] | null>(
+    null,
+  );
+
+  const pristine = editedHtml === null;
+  const convertedHtml = useMemo(
+    () => (isMarkdown ? markdownToDocumentHtml(body) : body),
+    [isMarkdown, body],
+  );
+  const liveLossy = useMemo(
+    () => (pristine && isMarkdown ? detectLossyMarkdown(body) : []),
+    [pristine, isMarkdown, body],
+  );
+  const lossy = lossyAtFirstEdit ?? liveLossy;
+
+  const handleChange = (next: string): void => {
+    if (pristine) setLossyAtFirstEdit(liveLossy);
+    setEditedHtml(next);
+    patch?.({ body: next, bodyFormat: "document" });
+  };
+
+  return (
+    <>
+      {lossy.length > 0 && (
+        <Banner variant="warning">
+          {t("managed-pages:body.lossy.warning", {
+            features: lossy.map((feature) => t(LOSSY_LABEL_KEYS[feature])).join(", "),
+          })}
+        </Banner>
+      )}
+      <DocumentContentEditor
+        id={BODY_EDITOR_ID}
+        value={editedHtml ?? convertedHtml}
+        onChange={handleChange}
+        variables={[]}
+        readOnly={false}
+      />
+    </>
+  );
+}

package/packages/bundled-features/src/subscription-paddle/changes.json

@@ -0,0 +1,15 @@
+[
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Add subscription-paddle, a Paddle Billing provider plugin",
+    "detail": "Checkout via the Paddle.js overlay on a page served by the feature at /billing/paddle-checkout. The Default Payment Link in the Paddle dashboard must point to <APP_BASE_URL>/billing/paddle-checkout; it is the only source, because transactions are created without a checkout url. Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries quantity and the app has to multiply its credits by it. Also ships customer portal, cancel, resume, batched price lookup, in-app plan switch and tenant binding of checkouts through an HMAC in custom_data."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Remove subscription-dodo, replaced by subscription-paddle",
+    "detail": "Removed exports of @cosmicdrift/kumiko-bundled-features/subscription-dodo: DODO_BASE_URLS, DODO_PROVIDER_NAME, DodoEnvironment, DodoEnvironments, SUBSCRIPTION_DODO_FEATURE, SubscriptionDodoOptions, createSubscriptionDodoFeature, dodoEnvSchema, subscriptionDodoEnvSchema.",
+    "migration": "Replace createSubscriptionDodoFeature with createSubscriptionPaddleFeature from @cosmicdrift/kumiko-bundled-features/subscription-paddle and dodoEnvSchema with paddleEnvSchema. Map Paddle price ids (pri_...) to tiers in priceToTier, set PADDLE_API_KEY, PADDLE_WEBHOOK_SECRET, PADDLE_TENANT_BINDING_KEY and PADDLE_CLIENT_TOKEN (or the matching config keys) and point the Default Payment Link at /billing/paddle-checkout. Point the Paddle notification destination at /webhooks/subscription/paddle when billing is mounted through the server-runtime boot option (SUBSCRIPTION_WEBHOOK_PATH), or at /api/subscription/webhook/paddle when createSubscriptionWebhookRoute is mounted by hand. In server-runtime boot options, billing.dodo becomes billing.paddle. An app-own credit-pack env such as DODO_PRODUCT_PACKS becomes a list of Paddle pri_ ids; the pack size comes from the price or product custom_data.credits, which surfaces as ProviderPrice.metadata.credits. Existing Dodo subscriptions are not migrated; a subscription stays with the provider stored on it."
+  }
+]

package/packages/bundled-features/src/subscription-paddle/checkout-config.query.ts

@@ -0,0 +1,17 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { PaddleRuntimes } from "./runtime.ts";
+
+// Anonymous on purpose: the checkout page is public. The answer is the public
+// Paddle.js client token and the environment, nothing else.
+export function makeCheckoutConfigQuery(readCheckoutConfig: PaddleRuntimes["readCheckoutConfig"]) {
+  return defineQueryHandler({
+    name: "checkout-config",
+    schema: z.object({}),
+    access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    description:
+      "Answers the public Paddle.js client token and the Paddle environment for the checkout page; the client token is public by design and no other config leaves this handler.",
+    handler: async (_query, ctx) => readCheckoutConfig(ctx),
+  });
+}

package/packages/bundled-features/src/subscription-paddle/checkout-methods.ts

@@ -0,0 +1,107 @@
+// Paddle plugin methods for checkout, portal, cancel and resume. Every response
+// is validated with Zod; every non-2xx throws a PaddleHttpError.
+
+import { SubscriptionCancelTimings } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
+import { signTenantBinding } from "./tenant-binding.ts";
+
+export function paddleSubscriptionPath(providerSubscriptionId: string): string {
+  return `/subscriptions/${encodeURIComponent(providerSubscriptionId)}`;
+}
+
+function relativeTarget(url: string): string {
+  const parsed = new URL(url);
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+
+const checkoutResponseSchema = z.object({
+  data: z.object({
+    id: z.string(),
+    checkout: z.object({ url: z.string().nullable() }).nullish(),
+  }),
+});
+
+export function createPaddleCheckoutSession(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"createCheckoutSession"> {
+  return async (ctx, options) => {
+    // No Paddle transaction may be created while billing is not live.
+    await runtime.assertBillingLive(ctx);
+    const bindingKey = await runtime.tenantBindingKey(ctx);
+    // No `checkout.url` in the body: Paddle rejects unapproved domains and otherwise
+    // answers with the dashboard's Default Payment Link plus `?_ptxn=`.
+    const { data } = checkoutResponseSchema.parse(
+      await runtime.call(ctx, {
+        method: "POST",
+        path: "/transactions",
+        body: {
+          items: [{ price_id: options.priceId, quantity: 1 }],
+          ...(options.providerCustomerId && { customer_id: options.providerCustomerId }),
+          custom_data: {
+            tenantId: options.tenantId,
+            tenantBinding: signTenantBinding(bindingKey, options.tenantId),
+            ...(options.consentId && { consentId: options.consentId }),
+          },
+        },
+      }),
+    );
+    if (!data.checkout?.url) {
+      throw new Error("subscription-paddle: transaction was created without a checkout url");
+    }
+    const url = new URL(data.checkout.url);
+    url.searchParams.set("success", relativeTarget(options.successUrl));
+    url.searchParams.set("cancel", relativeTarget(options.cancelUrl));
+    if (options.locale) url.searchParams.set("locale", options.locale);
+    return { url: url.href };
+  };
+}
+
+const portalResponseSchema = z.object({
+  data: z.object({ urls: z.object({ general: z.object({ overview: z.string() }) }) }),
+});
+
+// Paddle's portal has no return url, so options.returnUrl is not used.
+export function createPaddlePortalSession(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"createPortalSession"> {
+  return async (ctx, options) => {
+    const response = portalResponseSchema.parse(
+      await runtime.call(ctx, {
+        method: "POST",
+        path: `/customers/${encodeURIComponent(options.providerCustomerId)}/portal-sessions`,
+        body: {},
+      }),
+    );
+    return { url: response.data.urls.general.overview };
+  };
+}
+
+export function createPaddleCancelSubscription(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"cancelSubscription"> {
+  return async (ctx, options) => {
+    await runtime.call(ctx, {
+      method: "POST",
+      path: `${paddleSubscriptionPath(options.providerSubscriptionId)}/cancel`,
+      body: {
+        effective_from:
+          options.when === SubscriptionCancelTimings.periodEnd
+            ? "next_billing_period"
+            : "immediately",
+      },
+    });
+  };
+}
+
+export function createPaddleResumeSubscription(
+  runtime: PaddleCtxRuntime,
+): PaddlePluginMethod<"resumeSubscription"> {
+  return async (ctx, options) => {
+    await runtime.call(ctx, {
+      method: "PATCH",
+      path: paddleSubscriptionPath(options.providerSubscriptionId),
+      body: { scheduled_change: null },
+    });
+  };
+}

package/packages/bundled-features/src/subscription-paddle/checkout-page.ts

@@ -0,0 +1,154 @@
+// The Default Payment Link page. Paddle has no hosted checkout, so Paddle.js
+// runs on this page and opens the overlay for the `?_ptxn=` transaction by
+// itself. The page never reflects `_ptxn`.
+
+import { createHash } from "node:crypto";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
+import type { Context } from "hono";
+import * as z from "zod";
+import type { SystemQueryFn } from "../shared/index.ts";
+import { PADDLE_CHECKOUT_CONFIG_QUERY, PaddleEnvironments } from "./constants.ts";
+
+const PADDLE_JS_URL = "https://cdn.paddle.com/paddle/v2/paddle.js";
+const MAX_REDIRECT_LENGTH = 2048;
+const FALLBACK_REDIRECT = "/";
+const LOCALE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
+// Control characters, which browsers strip or reinterpret inside URLs.
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+
+// Static on purpose: its sha256 goes into the CSP, so nothing may be interpolated.
+export const PADDLE_INIT_SCRIPT = `(function () {
+  var data = document.getElementById("kumiko-paddle-checkout").dataset;
+  var completed = false;
+  if (data.environment === "sandbox") Paddle.Environment.set("sandbox");
+  var settings = { displayMode: "overlay", successUrl: new URL(data.successUrl, location.origin).href };
+  if (data.locale) settings.locale = data.locale;
+  Paddle.Initialize({
+    token: data.clientToken,
+    checkout: { settings: settings },
+    eventCallback: function (event) {
+      if (event.name === "checkout.completed") completed = true;
+      if (event.name === "checkout.closed" && !completed) {
+        location.assign(new URL(data.cancelUrl, location.origin).href);
+      }
+    }
+  });
+})();`;
+
+const INIT_SCRIPT_HASH = createHash("sha256").update(PADDLE_INIT_SCRIPT).digest("base64");
+
+export const PADDLE_CHECKOUT_CSP = [
+  "default-src 'none'",
+  `script-src 'sha256-${INIT_SCRIPT_HASH}' https://cdn.paddle.com`,
+  "style-src 'unsafe-inline' https://cdn.paddle.com",
+  "img-src data: https://*.paddle.com",
+  "connect-src https://*.paddle.com",
+  "frame-src https://buy.paddle.com https://sandbox-buy.paddle.com",
+  "frame-ancestors 'none'",
+  "base-uri 'none'",
+  "form-action 'none'",
+  "object-src 'none'",
+].join("; ");
+
+// Own header set: `securePageHeaders` pins `script-src 'none'`. The global
+// wrapper only fills headers that are absent, so these win.
+function pageHeaders(): Record<string, string> {
+  return {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "referrer-policy": "no-referrer",
+    "x-frame-options": "DENY",
+    "x-content-type-options": "nosniff",
+    "content-security-policy": PADDLE_CHECKOUT_CSP,
+  };
+}
+
+/** Same-origin path only: anything else would make the page an open redirector. */
+export function safeRedirectPath(raw: string | undefined): string {
+  if (
+    raw === undefined ||
+    raw.length > MAX_REDIRECT_LENGTH ||
+    !raw.startsWith("/") ||
+    raw.startsWith("//") ||
+    raw.startsWith("/\\") ||
+    CONTROL_CHARACTERS.test(raw)
+  ) {
+    return FALLBACK_REDIRECT;
+  }
+  return raw;
+}
+
+export function safeLocale(raw: string | undefined): string | undefined {
+  return raw !== undefined && LOCALE_PATTERN.test(raw) ? raw : undefined;
+}
+
+type CheckoutPageValues = {
+  readonly clientToken: string;
+  readonly environment: string;
+  readonly successUrl: string;
+  readonly cancelUrl: string;
+  readonly locale: string | undefined;
+};
+
+export function renderCheckoutPage(values: CheckoutPageValues): string {
+  const attributesHtml = [
+    ["data-client-token", values.clientToken],
+    ["data-environment", values.environment],
+    ["data-success-url", values.successUrl],
+    ["data-cancel-url", values.cancelUrl],
+    ...(values.locale ? [["data-locale", values.locale]] : []),
+  ]
+    .map(([name, value]) => `${name}="${escapeHtml(value ?? "")}"`)
+    .join(" ");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Checkout</title>
+</head>
+<body>
+<div id="kumiko-paddle-checkout" ${attributesHtml}></div>
+<noscript>JavaScript is required to complete the checkout.</noscript>
+<script src="${PADDLE_JS_URL}"></script>
+<script>${PADDLE_INIT_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+const checkoutConfigSchema = z.object({
+  clientToken: z.string().nullable(),
+  environment: z.string(),
+});
+
+export async function servePaddleCheckoutPage(
+  c: Context,
+  { systemQuery }: { readonly systemQuery: SystemQueryFn },
+): Promise<Response> {
+  let config: z.infer<typeof checkoutConfigSchema>;
+  try {
+    config = checkoutConfigSchema.parse(
+      await systemQuery(PADDLE_CHECKOUT_CONFIG_QUERY, {}, SYSTEM_TENANT_ID),
+    );
+  } catch {
+    return unavailable(c);
+  }
+  if (!config.clientToken) return unavailable(c);
+  const html = renderCheckoutPage({
+    clientToken: config.clientToken,
+    environment:
+      config.environment === PaddleEnvironments.live
+        ? PaddleEnvironments.live
+        : PaddleEnvironments.sandbox,
+    successUrl: safeRedirectPath(c.req.query("success")),
+    cancelUrl: safeRedirectPath(c.req.query("cancel")),
+    locale: safeLocale(c.req.query("locale")),
+  });
+  return new Response(html, { status: 200, headers: pageHeaders() });
+}
+
+function unavailable(c: Context): Response {
+  return c.text("checkout unavailable", 503, { "cache-control": "no-store" });
+}

package/packages/bundled-features/src/subscription-paddle/client.ts

@@ -0,0 +1,78 @@
+// Thin JSON-over-fetch client for the Paddle Billing REST API. All traffic goes
+// through the injected `send`, which defaults to the SSRF-safe egress in
+// feature.ts and is replaced by a mock in tests.
+
+import { parseJsonOrThrow, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+
+export type PaddleSend = (url: string, init?: RequestInit) => Promise<Response>;
+
+export type PaddleRequest = {
+  readonly method: "GET" | "POST" | "PATCH";
+  /** Path segments interpolated into it must already be encodeURIComponent'ed. */
+  readonly path: string;
+  readonly query?: Readonly<Record<string, string>>;
+  readonly body?: unknown;
+};
+
+export type PaddleTarget = { readonly baseUrl: string; readonly apiKey: string };
+
+const PADDLE_API_VERSION = "1";
+
+const paddleErrorBodySchema = z.object({ error: z.object({ type: z.string(), code: z.string() }) });
+// Both values come from outside; anything beyond a plain identifier is dropped so
+// no customer text reaches the logs.
+const ERROR_IDENTIFIER = /^[a-z0-9_]{1,100}$/;
+
+type PaddleErrorDetails = { readonly type?: string; readonly code?: string };
+
+function paddleErrorDetails(bodyText: string): PaddleErrorDetails {
+  const parsed = paddleErrorBodySchema.safeParse(parseJsonSafe<unknown>(bodyText, undefined));
+  if (!parsed.success) return {};
+  const { type, code } = parsed.data.error;
+  return {
+    ...(ERROR_IDENTIFIER.test(type) && { type }),
+    ...(ERROR_IDENTIFIER.test(code) && { code }),
+  };
+}
+
+// Carries only the status and Paddle's error type and code, never `detail`, the
+// rest of the body or the key: they can hold customer data or secrets.
+export class PaddleHttpError extends Error {
+  readonly status: number;
+  readonly paddleErrorType?: string;
+  readonly paddleErrorCode?: string;
+  constructor(request: PaddleRequest, status: number, details: PaddleErrorDetails = {}) {
+    const suffix = [details.type && `type ${details.type}`, details.code && `code ${details.code}`]
+      .filter(Boolean)
+      .join(", ");
+    super(
+      `subscription-paddle: ${request.method} ${request.path} failed with status ${status}${suffix ? ` (${suffix})` : ""}`,
+    );
+    this.name = "PaddleHttpError";
+    this.status = status;
+    if (details.type) this.paddleErrorType = details.type;
+    if (details.code) this.paddleErrorCode = details.code;
+  }
+}
+
+export function createPaddleHttp(send: PaddleSend) {
+  return async (target: PaddleTarget, request: PaddleRequest): Promise<unknown> => {
+    const query = request.query ? `?${new URLSearchParams(request.query).toString()}` : "";
+    const response = await send(`${target.baseUrl}${request.path}${query}`, {
+      method: request.method,
+      headers: {
+        Authorization: `Bearer ${target.apiKey}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "Paddle-Version": PADDLE_API_VERSION,
+      },
+      ...(request.body !== undefined && { body: JSON.stringify(request.body) }),
+    });
+    const text = await response.text();
+    if (!response.ok) throw new PaddleHttpError(request, response.status, paddleErrorDetails(text));
+    return text.length === 0
+      ? null
+      : parseJsonOrThrow<unknown>(text, "subscription-paddle response");
+  };
+}

package/packages/bundled-features/src/subscription-paddle/constants.ts

@@ -0,0 +1,32 @@
+export const SUBSCRIPTION_PADDLE_FEATURE = "subscription-paddle" as const;
+
+// Must match the last path segment of the webhook URL (`/webhooks/subscription/paddle` via the boot option).
+export const PADDLE_PROVIDER_NAME = "paddle" as const;
+
+// Paddle has no hosted checkout page, so the feature serves the Default Payment
+// Link itself; the same path goes into the Paddle dashboard.
+export const PADDLE_CHECKOUT_PATH = "/billing/paddle-checkout" as const;
+
+// Config-key short-names, qualified to `subscription-paddle:config:<name>` at
+// registry-build. api-key, webhook-secret and tenant-binding-key are backing:"secrets".
+export const PADDLE_API_KEY_CONFIG = "api-key" as const;
+export const PADDLE_WEBHOOK_SECRET_CONFIG = "webhook-secret" as const;
+export const PADDLE_TENANT_BINDING_KEY_CONFIG = "tenant-binding-key" as const;
+export const PADDLE_CLIENT_TOKEN_CONFIG = "client-token" as const;
+export const PADDLE_ENVIRONMENT_CONFIG = "environment" as const;
+export const PADDLE_BILLING_LIVE_CONFIG = "billingLive" as const;
+
+export const PADDLE_CHECKOUT_CONFIG_QUERY = `${SUBSCRIPTION_PADDLE_FEATURE}:query:checkout-config`;
+
+// Separate from billingLive on purpose: staging runs Paddle's sandbox with
+// billingLive on, production flips both.
+export const PaddleEnvironments = {
+  sandbox: "sandbox",
+  live: "live",
+} as const;
+export type PaddleEnvironment = (typeof PaddleEnvironments)[keyof typeof PaddleEnvironments];
+
+export const PADDLE_BASE_URLS: Readonly<Record<PaddleEnvironment, string>> = {
+  sandbox: "https://sandbox-api.paddle.com",
+  live: "https://api.paddle.com",
+};