@cosmicdrift/kumiko-samples 0.372.0 → 0.374.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.372.0",
+  "version": "0.374.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.372.0",
+  "version": "0.374.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.374.0",
+    "type": "improvement",
+    "title": "Client actions for password reset and email verification",
+    "detail": "emailPasswordClient registers auth-email-password:request-password-reset and auth-email-password:request-email-verification for clientAction row actions."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

package/packages/bundled-features/src/auth-email-password/i18n.ts

@@ -46,6 +46,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.signupEmailAlreadyRegistered":
       "An account already exists for this email. Please sign in or reset your password.",
     "auth.errors.unknownError": "Something went wrong. Please try again.",
+    "auth.errors.tooManyRequests": "Too many requests. Please wait briefly.",
     "auth.errors.originNotAllowed": "Requests from this origin are not allowed.",
     "auth.forgotPassword.title": "Reset password",
     "auth.forgotPassword.intro":

package/packages/bundled-features/src/auth-email-password/web/client-actions.ts

@@ -0,0 +1,36 @@
+// @runtime client
+// Handlers for RowAction `kind: "clientAction"`: an admin screen lists users and
+// triggers the same public mail flows the login screens use.
+
+import type { ClientActionHandler, ClientActionOutcome } from "@cosmicdrift/kumiko-renderer";
+import {
+  type AuthTokenFailure,
+  requestEmailVerification,
+  requestPasswordReset,
+} from "./auth-client.ts";
+
+type EmailFlow = (
+  email: string,
+) => Promise<{ readonly ok: true } | { readonly ok: false; readonly error: AuthTokenFailure }>;
+
+function failureMessageKey(failure: AuthTokenFailure): string {
+  return failure.reason === "rate_limited"
+    ? "auth.errors.tooManyRequests"
+    : "auth.errors.unknownError";
+}
+
+function emailFlowHandler(flow: EmailFlow): ClientActionHandler {
+  return async (payload): Promise<ClientActionOutcome> => {
+    const email = payload["email"];
+    if (typeof email !== "string" || email === "") {
+      return { ok: false, message: "auth.errors.invalidBody" };
+    }
+    const result = await flow(email);
+    return result.ok ? { ok: true } : { ok: false, message: failureMessageKey(result.error) };
+  };
+}
+
+export const emailPasswordClientActions: Readonly<Record<string, ClientActionHandler>> = {
+  "auth-email-password:request-password-reset": emailFlowHandler(requestPasswordReset),
+  "auth-email-password:request-email-verification": emailFlowHandler(requestEmailVerification),
+};

package/packages/bundled-features/src/auth-email-password/web/client-plugin.ts

@@ -5,7 +5,7 @@
 // Translations (de/en) mit. Alles ist overridbar — Login-Screen,
 // Strings pro Locale, pro Key.
 
-import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientActionHandler, TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n.ts";
 import {
@@ -14,6 +14,7 @@ import {
   type MfaVerifyComponentProps,
   makeSessionAuthGate,
 } from "./auth-gate.tsx";
+import { emailPasswordClientActions } from "./client-actions.ts";
 import type { LoginScreenProps } from "./login-screen.tsx";
 
 export type EmailPasswordClientOptions = {
@@ -55,6 +56,7 @@ export type EmailPasswordClientFeature = {
   readonly providers: readonly ComponentType<{ children: ReactNode }>[];
   readonly gates: readonly ComponentType<{ children: ReactNode }>[];
   readonly translations: TranslationsByLocale;
+  readonly clientActions: Readonly<Record<string, ClientActionHandler>>;
 };
 
 export function emailPasswordClient(
@@ -75,5 +77,6 @@ export function emailPasswordClient(
       }),
     ],
     translations,
+    clientActions: emailPasswordClientActions,
   };
 }

package/packages/bundled-features/src/cap-overview/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.374.0",
+    "type": "breaking",
+    "title": "tenant-caps:list pages by offset and rejects cursor",
+    "detail": "The cap overview list showed page 1 on every page because the pager sends offset and the query only read cursor. tenant-caps:list now takes offset like the pager; a cursor in the payload is rejected with a 400 validation error and sort is an enum of the sortable fields. The unused cap-overview.errors.invalidCursor and sortFieldUnsupported keys are gone.",
+    "migration": "Callers of cap-overview:query:tenant-caps:list must send offset instead of cursor, and only a sortable field name as sort. Apps that override the removed i18n keys cap-overview.errors.invalidCursor or cap-overview.errors.sortFieldUnsupported can delete them. No caller in the kumiko-enterprise, kumiko-platform, kumiko-studio or app repos sends a cursor or defines these keys."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -1,17 +1,12 @@
-import {
-  buildEntityTable,
-  decodeCursor,
-  encodeCursor,
-  selectMany,
-} from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigAccessor,
   definePagedQueryHandler,
-  MAX_LIST_LIMIT,
+  pagedListSchema,
+  pageRows,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
-import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.ts";
 import type { CapLimitContext } from "../../cap-counter/index.ts";
@@ -59,7 +54,6 @@ const FILTER_OP = z.enum(["eq", "ne", "lt", "gt", "in"]);
 type FilterOp = z.infer<typeof FILTER_OP>;
 
 const SORTABLE_FIELDS = ["name", "tier", "billing"] as const;
-type SortableField = (typeof SORTABLE_FIELDS)[number];
 
 function tenantCapKey(tenantId: string, capId: string): string {
   return JSON.stringify([tenantId, capId]);
@@ -83,10 +77,6 @@ async function resolveLimitsByTenantAndCap(
   return new Map(entries);
 }
 
-function isSortableField(field: string): field is SortableField {
-  return isOneOf(SORTABLE_FIELDS, field);
-}
-
 // tier is a plain string with no defined ordering — lt/gt have no meaning
 // on it and are rejected rather than silently treated as "no filter".
 function assertSupportedTierFilterOp(op: FilterOp): void {
@@ -152,16 +142,10 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
     name: "tenant-caps:list",
     description:
       "Lists every tenant on the platform with its tier, billing provider/status and per-cap usage, paged, searchable by name and filterable by tier; use it as the operator-wide capacity overview.",
-    schema: z.object({
-      cursor: z.string().optional(),
-      limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(50),
-      sort: z.string().optional(),
-      sortDirection: z.enum(["asc", "desc"]).optional(),
-      search: z.string().optional(),
+    schema: pagedListSchema(SORTABLE_FIELDS).extend({
       filters: z
         .array(z.object({ field: z.string(), op: FILTER_OP, value: z.unknown() }))
         .optional(),
-      totalCount: z.boolean().optional(),
     }),
     access: { roles: ["SystemAdmin"] },
     escapeHatch: {
@@ -190,68 +174,30 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
       const assignmentByTenant = new Map(assignments.map((row) => [row.tenantId, row]));
       const subscriptionByTenant = new Map(subscriptions.map((row) => [row.tenantId, row]));
 
-      // Case-insensitive substring search has no `ilike` operator in the
-      // query builder (only `like`, SQL-LIKE case-sensitive) — filtered here
-      // in JS, same as tenant/team-list.query.ts's search.
-      const search = query.payload.search?.trim().toLowerCase();
       const tierFilter = extractTierFilter(query.payload.filters ?? []);
 
       const merged = tenants
-        .filter(
-          (tenant) =>
-            search === undefined || search === "" || tenant.name.toLowerCase().includes(search),
-        )
         .map((tenant) => {
           const assignment = assignmentByTenant.get(tenant.id);
           return {
+            id: tenant.id,
             tenantId: tenant.id,
             name: tenant.name,
             tier: assignment?.tier ?? "",
-            source: assignment?.source ?? null,
             billing: billingLabel(subscriptionByTenant.get(tenant.id), assignment?.source ?? null),
           };
         })
         .filter((row) => matchesTierFilter(row.tier, tierFilter));
 
-      const sortField = query.payload.sort ?? "name";
-      if (!isSortableField(sortField)) {
-        throw new ValidationError({
-          fields: [
-            {
-              path: "sort",
-              code: "unsupported_field",
-              i18nKey: "cap-overview.errors.sortFieldUnsupported",
-              params: { field: sortField },
-            },
-          ],
-        });
-      }
-      const sortDirection = query.payload.sortDirection ?? "asc";
-      const directionMultiplier = sortDirection === "asc" ? 1 : -1;
-      const sorted = [...merged].sort(
-        (a, b) => a[sortField].localeCompare(b[sortField]) * directionMultiplier,
-      );
-
-      // ponytail: base64-wrapped offset, not a SQL keyset — rows come from a
-      // JS merge of three tables (tenant/tier-assignment/subscription), same
-      // rationale as tenant/team-list.query.ts. Holds up to tier-engine's
-      // documented "single-pass scan" scale (a few thousand tenants); past
-      // that the fix is a real combined read-projection, not a cursor
-      // bolted onto this merge.
-      const offset = query.payload.cursor ? Number(decodeCursor(query.payload.cursor)) : 0;
-      if (!Number.isInteger(offset) || offset < 0) {
-        throw new ValidationError({
-          fields: [
-            {
-              path: "cursor",
-              code: "invalid_cursor",
-              i18nKey: "cap-overview.errors.invalidCursor",
-            },
-          ],
-        });
-      }
-      const limit = query.payload.limit;
-      const page = sorted.slice(offset, offset + limit);
+      // Search and paging run in memory because the rows are a JS merge of
+      // three tables (tenant/tier-assignment/subscription), same rationale as
+      // tenant/team-list.query.ts. Holds up to tier-engine's documented
+      // "single-pass scan" scale (a few thousand tenants); past that the fix
+      // is a real combined read-projection.
+      const { rows: page, total } = pageRows(merged, query.payload, {
+        searchFields: ["name"],
+        defaultSort: "name",
+      });
 
       // Usage is computed only for this page's tenant ids, never for the
       // full tenant set; caps without usageBatch still cost one query per
@@ -302,14 +248,7 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
         };
       });
 
-      const nextCursor =
-        offset + limit < sorted.length ? encodeCursor(String(offset + limit)) : null;
-
-      return {
-        rows,
-        nextCursor,
-        ...(query.payload.totalCount === true && { total: merged.length }),
-      };
+      return { rows, nextCursor: null, ...(total !== undefined && { total }) };
     },
   });
 }

package/packages/bundled-features/src/cap-overview/i18n.ts

@@ -17,11 +17,9 @@ export const CAP_OVERVIEW_I18N: Readonly<Record<string, LocalizedString>> = {
   "cap-overview.errors.progressPrimitiveMissing": {
     en: "Usage bar unavailable — Progress primitive is not registered.",
   },
-  "cap-overview.errors.invalidCursor": { en: "The pagination cursor is invalid." },
   "cap-overview.errors.filterFieldUnsupported": {
     en: "Filtering by this field is not supported, or tier was filtered more than once.",
   },
-  "cap-overview.errors.sortFieldUnsupported": { en: "Sorting by this field is not supported." },
   "cap-overview.errors.tenantOverrideRequiresSystemAdmin": {
     en: "Only SystemAdmin may query another tenant's data.",
   },

package/samples/apps/styleguide/src/features/widgets/feature.ts

@@ -190,6 +190,21 @@ export const widgetsFeature = defineFeature("widgets", (r) => {
         label: "widgets:dashboard:goal-progress",
         query: "widgets:query:metrics:goal-progress",
       },
+      {
+        kind: "text",
+        id: "dashboard-help",
+        label: "widgets:dashboard:help-title",
+        blocks: [
+          { kind: "heading", text: "widgets:dashboard:help-heading" },
+          { kind: "paragraph", text: "widgets:dashboard:help-body" },
+          {
+            kind: "list",
+            items: ["widgets:dashboard:help-item-1", "widgets:dashboard:help-item-2"],
+          },
+          { kind: "code", code: "kumiko check --explain" },
+          { kind: "hint", text: "widgets:dashboard:help-hint" },
+        ],
+      },
       {
         kind: "custom",
         id: "filter-echo",
@@ -373,6 +388,8 @@ export const widgetsFeature = defineFeature("widgets", (r) => {
           value: openAmount(3200, ctx.locale),
           fraction: 0.92,
         },
+        { label: { i18nKey: "widgets:dashboard:demo-cap-users" }, used: 10, limit: 10 },
+        { label: { i18nKey: "widgets:dashboard:demo-cap-projects" }, used: 4, limit: null },
       ],
     }),
     access: {

package/samples/apps/styleguide/src/features/widgets/i18n.ts

@@ -36,6 +36,14 @@ export const WIDGETS_I18N = {
   "widgets:dashboard:col-status": { de: "Status", en: "Status" },
   "widgets:dashboard:upcoming": { de: "Nächste Termine", en: "Upcoming" },
   "widgets:dashboard:goal-progress": { de: "Tilgungsfortschritt", en: "Payoff progress" },
+  "widgets:dashboard:demo-cap-users": { de: "Nutzer", en: "Users" },
+  "widgets:dashboard:demo-cap-projects": { de: "Projekte", en: "Projects" },
+  "widgets:dashboard:help-title": { de: "Erste Schritte", en: "Getting started" },
+  "widgets:dashboard:help-heading": { de: "Schritt eins", en: "Step one" },
+  "widgets:dashboard:help-body": { de: "Lege einen Schlüssel an.", en: "Create a key." },
+  "widgets:dashboard:help-item-1": { de: "Erster Punkt", en: "First item" },
+  "widgets:dashboard:help-item-2": { de: "Zweiter Punkt", en: "Second item" },
+  "widgets:dashboard:help-hint": { de: "Dauert eine Minute.", en: "Takes a minute." },
   "widgets:dashboard:filter-region": { de: "Region", en: "Region" },
   "widgets:dashboard:filter-region-eu": { de: "Europa", en: "Europe" },
   "widgets:dashboard:filter-region-us": { de: "USA", en: "USA" },

package/samples/recipes/rate-limiting/README.md

@@ -5,8 +5,29 @@ End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
 ## What it shows
 
 - Handler `rateLimit: { per, limit, windowSeconds }`
+- Several buckets on one handler: `rateLimit: [{ per: "user", ... }, { per: "tenant+handler", ... }]`
 - How L1/L2 from `buildServer` stack with L3
 
+## Combined buckets
+
+Pass a list to enforce several budgets on one handler, for example a per-caller and a per-tenant cap:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  rateLimit: [
+    { per: "user", limit: 2, windowSeconds: 3600 },
+    { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
+  ],
+});
+```
+
+Each bucket applies on its own. The check is all-or-nothing: if any bucket is exhausted the call
+answers 429 `rate_limited` for that bucket (the one with the longest wait when several are
+exhausted) and no bucket is charged. Each `per` may appear once; an empty list fails at boot.
+An anonymous handler needs every bucket to be ip-keyed, and `{ disabled: true, reason }`
+stays a single declaration.
+
 ## Per-payload limits
 
 A public write handler that mails an address typed by the caller is also limited per

package/samples/recipes/rate-limiting/src/feature.ts

@@ -20,5 +20,18 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
       access: { roles: ["Admin", "User"] },
       rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
     });
+
+    // Combined budget: each caller gets 2 submits per hour and the tenant 3 per hour in
+    // total. Both buckets are checked together; a request one bucket rejects charges neither.
+    r.writeHandler({
+      name: "submit-report",
+      schema: z.object({}),
+      handler: async () => ({ isSuccess: true as const, data: {} }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: [
+        { per: "user", limit: 2, windowSeconds: 3600 },
+        { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
+      ],
+    });
   });
 }