@cosmicdrift/kumiko-samples 0.398.0 → 0.399.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.398.0",
+  "version": "0.399.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

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

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Shorter documents checkbox text in the consent box",
+    "detail": "With `consumerProtection.documentsAcknowledgement: true` the checkbox now reads \"I have read and agree to the Terms and the Refund Policy.\" (de: \"Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.\"), or without a refund link only the terms. The privacy policy stays a link. The text is part of `consentTextVersion`, so apps with the option on get a new version hash; consents recorded earlier keep their stored version."
+  },
   {
     "version": "0.398.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-text.ts

@@ -45,14 +45,12 @@ const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS: Readonly<
 > = {
   de: {
     withRefund:
-      "Ich habe die AGB, die Erstattungsrichtlinie und die Datenschutzerklärung gelesen. Mit den AGB und der Erstattungsrichtlinie bin ich einverstanden.",
-    withoutRefund:
-      "Ich habe die AGB und die Datenschutzerklärung gelesen. Mit den AGB bin ich einverstanden.",
+      "Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.",
+    withoutRefund: "Ich habe die AGB gelesen und bin mit ihnen einverstanden.",
   },
   en: {
-    withRefund:
-      "I have read the Terms, the Refund Policy and the Privacy Policy, and I agree to the Terms and the Refund Policy.",
-    withoutRefund: "I have read the Terms and the Privacy Policy, and I agree to the Terms.",
+    withRefund: "I have read and agree to the Terms and the Refund Policy.",
+    withoutRefund: "I have read and agree to the Terms.",
   },
 };
 

package/packages/bundled-features/src/channel-in-app/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Inbox cursor, total and navigation target for the shell bell",
+    "detail": "`channel-in-app:query:inbox` accepts a `cursor` and answers `{ rows, nextCursor, total }`; each row carries `target` (`{ screenId, entityId? }` or null) parsed from `data.target`. Build the target with `inAppTarget(screenId, entityId?)`; a malformed target is dropped and the notification is still delivered. The SSE frame `channel-in-app:event:delivered` now carries only `{ id, userId, notificationType }`, and a failing push no longer fails the delivery because the row is already stored. The shared contract lives in `@cosmicdrift/kumiko-types/in-app-notification-types`."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/channel-in-app/constants.ts

@@ -1,11 +1,11 @@
-export const CHANNEL_IN_APP_FEATURE = "channel-in-app" as const;
+import {
+  IN_APP_NOTIFICATION_FEATURE,
+  IN_APP_NOTIFICATION_QUERIES,
+  IN_APP_NOTIFICATION_WRITES,
+} from "@cosmicdrift/kumiko-types/in-app-notification-types";
 
-export const InAppHandlers = {
-  markRead: "channel-in-app:write:mark-read",
-  markAllRead: "channel-in-app:write:mark-all-read",
-} as const;
+export const CHANNEL_IN_APP_FEATURE = IN_APP_NOTIFICATION_FEATURE;
 
-export const InAppQueries = {
-  inbox: "channel-in-app:query:inbox",
-  unreadCount: "channel-in-app:query:unread-count",
-} as const;
+export const InAppHandlers = IN_APP_NOTIFICATION_WRITES;
+
+export const InAppQueries = IN_APP_NOTIFICATION_QUERIES;

package/packages/bundled-features/src/channel-in-app/feature.ts

@@ -10,7 +10,7 @@ import { inAppMessagesTableMeta } from "./tables.ts";
 export function createChannelInAppFeature(): FeatureDefinition {
   return defineFeature("channel-in-app", (r) => {
     r.describe(
-      "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
+      "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
     );
     r.uiHints({
       displayLabel: "In-App Inbox",

package/packages/bundled-features/src/channel-in-app/handlers/inbox.query.ts

@@ -1,13 +1,17 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { parseStoredNotificationData, targetOfNotificationData } from "../in-app-target.ts";
 import { inAppMessagesTable } from "../tables.ts";
 
+const SERIAL_ID_PATTERN = /^\d{1,15}$/;
+
 export const inboxQuery = defineQueryHandler({
   name: "inbox",
   schema: z.object({
     limit: z.number().min(1).max(100).default(50),
     unreadOnly: z.boolean().default(false),
+    cursor: z.string().regex(SERIAL_ID_PATTERN).optional(),
   }),
   access: {
     openToAll: {
@@ -17,14 +21,34 @@ export const inboxQuery = defineQueryHandler({
     },
   },
   description:
-    "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
+    "Lists the calling user's own in-app notification messages newest-first with a parsed navigation target, optionally only the unread ones. Pass the returned nextCursor as cursor for the next page; total counts all matching messages, not just the page. Use it to show or inspect a user's notification inbox.",
   handler: async (query, ctx) => {
-    const where: Record<string, unknown> = { userId: query.user.id };
-    if (query.payload.unreadOnly) where["isRead"] = false;
-    const rows = await selectMany(ctx.db, inAppMessagesTable, where, {
-      limit: query.payload.limit,
-      orderBy: { col: "createdAt", direction: "desc" },
+    const { limit, unreadOnly, cursor } = query.payload;
+    const ownMessages: Record<string, unknown> = { userId: query.user.id };
+    if (unreadOnly) ownMessages["isRead"] = false;
+
+    const pageWhere =
+      cursor === undefined ? ownMessages : { ...ownMessages, id: { lt: Number(cursor) } };
+    // One extra row tells whether another page exists without a second query.
+    const fetched = await selectMany(ctx.db, inAppMessagesTable, pageWhere, {
+      limit: limit + 1,
+      orderBy: { col: "id", direction: "desc" },
+    });
+    const page = fetched.slice(0, limit);
+    const lastRow = page[page.length - 1];
+    const nextCursor = fetched.length > limit && lastRow ? String(lastRow["id"]) : null;
+
+    const [totalRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      ownMessages,
+    );
+
+    const rows = page.map((row) => {
+      const storedData = row["data"];
+      const data = parseStoredNotificationData(typeof storedData === "string" ? storedData : null);
+      return { ...row, target: targetOfNotificationData(data) };
     });
-    return { rows };
+    return { rows, nextCursor, total: totalRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.ts";
@@ -16,13 +15,11 @@ export const unreadCountQuery = defineQueryHandler({
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
-    // The query helpers in db/query.ts have no aggregate helper, so selectMany returns all matching
-    // rows and count() runs in JS. This is acceptable because unread counts are low-cardinality and
-    // user-scoped, with at most a few hundred rows; use raw .unsafe() with COUNT(*) if that grows.
-    const rows = await selectMany(ctx.db, inAppMessagesTable, {
-      userId: query.user.id,
-      isRead: false,
-    });
-    return { count: rows.length };
+    const [countRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      { userId: query.user.id, isRead: false },
+    );
+    return { count: countRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/in-app-channel.ts

@@ -1,7 +1,12 @@
 import { tenantChannel } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import type { DeliveryChannel } from "../delivery/index.ts";
+import { targetOfNotificationData } from "./in-app-target.ts";
 import { inAppMessagesTable } from "./tables.ts";
 
+const log = createFallbackLogger("channel-in-app");
+
 export const inAppChannel: DeliveryChannel = {
   name: "inApp",
   mode: "inline",
@@ -15,25 +20,34 @@ export const inAppChannel: DeliveryChannel = {
     // address is the user-id string after the ES migration — keep it as-is.
     const userId = address;
 
+    // A malformed target drops only the link, never the notification.
+    const target = targetOfNotificationData(message.data);
+    const storedData =
+      message.data === undefined
+        ? null
+        : JSON.stringify({ ...message.data, target: target ?? undefined });
+
     const row = await ctx.db.insertOne<{ id: string }>(inAppMessagesTable, {
       userId,
       notificationType: message.notificationType,
       title: message.title,
       body: message.body ?? null,
-      data: message.data ? JSON.stringify(message.data) : null,
+      data: storedData,
     });
 
     if (ctx.sseBroker) {
-      await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
-        type: "channel-in-app:event:delivered",
-        data: {
-          id: row?.id,
-          userId,
-          notificationType: message.notificationType,
-          title: message.title,
-          body: message.body,
-        },
-      });
+      // The row is stored, so a failing push (e.g. Redis down) must not turn the delivery into
+      // a failure that gets retried and stored twice. Clients fetch the inbox on reconnect.
+      try {
+        await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
+          type: IN_APP_NOTIFICATION_DELIVERED_EVENT,
+          data: { id: row?.id, userId, notificationType: message.notificationType },
+        });
+      } catch (error) {
+        log.warn("in-app SSE push failed; the notification is stored", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
     }
 
     return { status: "sent", address };

package/packages/bundled-features/src/channel-in-app/in-app-target.ts

@@ -0,0 +1,37 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import * as z from "zod";
+
+const SCREEN_ID_PATTERN = /^[^\s:]+:screen:[^\s:]+$/;
+
+const targetSchema = z.object({
+  screenId: z.string().regex(SCREEN_ID_PATTERN),
+  entityId: z.string().min(1).optional(),
+});
+
+export function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget {
+  return entityId === undefined ? { screenId } : { screenId, entityId };
+}
+
+// Returns null for anything that is not a well-formed target, so a malformed `data.target`
+// drops only the link and never the notification.
+export function parseInAppTarget(value: unknown): InAppNotificationTarget | null {
+  const parsed = targetSchema.safeParse(value);
+  if (!parsed.success) return null;
+  const { screenId, entityId } = parsed.data;
+  return inAppTarget(screenId, entityId);
+}
+
+// Reads `target` out of the stored notification data (a JSON string) or out of a raw data object.
+export function targetOfNotificationData(data: unknown): InAppNotificationTarget | null {
+  if (typeof data !== "object" || data === null || !("target" in data)) return null;
+  return parseInAppTarget(data.target);
+}
+
+export function parseStoredNotificationData(stored: string | null): unknown {
+  if (stored === null) return null;
+  try {
+    return JSON.parse(stored);
+  } catch {
+    return null;
+  }
+}

package/packages/bundled-features/src/channel-in-app/index.ts

@@ -1,4 +1,5 @@
 export { CHANNEL_IN_APP_FEATURE, InAppHandlers, InAppQueries } from "./constants.ts";
 export { createChannelInAppFeature } from "./feature.ts";
 export { inAppChannel } from "./in-app-channel.ts";
+export { inAppTarget } from "./in-app-target.ts";
 export { inAppMessagesTable } from "./tables.ts";

package/packages/bundled-features/src/metrics/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Metric access roles and group names from a source table",
+    "detail": "A metric declares `access: { roles }` to open its tenant query to roles other than the admin roles; an empty list fails boot validation and no `access` keeps the admin-only default. A `groupBy` metric on an entity-table source whose column is a single reference names the rows after the referenced row's label field; the lookup runs through the caller's read access on the target entity, so unreadable or foreign-tenant rows keep their key, and static `groupLabels` still win."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/metrics/compute.ts

@@ -26,6 +26,10 @@ export type MetricRunParams = {
   readonly filterWhere: WhereObject;
   /** Extra filter that narrows the source to the caller's scope. */
   readonly scopeWhere: WhereObject;
+  /** Names for referenced-row group keys; absent where the caller cannot resolve them (system scope). */
+  readonly referenceLabels?: (
+    keys: readonly AggregateKey[],
+  ) => Promise<ReadonlyMap<string, string>>;
 };
 
 const NULL_KEY_TEXT = "—";
@@ -153,6 +157,7 @@ function buildRows(
   aggregates: MetricAggregates,
   total: number | null,
   labelOf: (key: string) => string,
+  groupLabelOf: (key: string) => string,
 ): readonly MetricRow[] {
   const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
   return aggregates.groups.map((row) => {
@@ -161,7 +166,7 @@ function buildRows(
     return {
       id: key,
       key,
-      label: labelOf(key),
+      label: groupLabelOf(key),
       value: rowValue,
       fraction: fractionOf(rowValue, total),
       ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
@@ -188,6 +193,15 @@ function buildSeries(
   }));
 }
 
+async function resolveReferencedGroupLabels(
+  metric: MetricDefinition,
+  params: MetricRunParams,
+  groups: readonly AggregateRow[],
+): Promise<ReadonlyMap<string, string>> {
+  if (params.referenceLabels === undefined || metric.groupBy === undefined) return new Map();
+  return params.referenceLabels(groups.map((row) => row.keys[0] ?? null));
+}
+
 export async function runMetric(
   db: TenantDb,
   metric: MetricDefinition,
@@ -230,7 +244,10 @@ export async function runMetric(
           ),
         )
       : [];
-  const rows = buildRows(metric, aggregates, value, labelOf);
+  const referencedLabels = await resolveReferencedGroupLabels(metric, params, aggregates.groups);
+  const groupLabelOf = (key: string): string =>
+    metric.groupLabels?.[key] ?? referencedLabels.get(key) ?? key;
+  const rows = buildRows(metric, aggregates, value, labelOf, groupLabelOf);
 
   return {
     value,

package/packages/bundled-features/src/metrics/feature.ts

@@ -1,9 +1,11 @@
+import { extractTableInfo } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   defineFeature,
   defineQueryHandler,
   type FeatureDefinition,
   type QueryHandlerDefinition,
+  referenceGroupLabels,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -78,7 +80,7 @@ function createTenantMetricQuery(
     name: metric.id,
     description: metric.description,
     schema: tenantPayloadSchema(metric),
-    access: { roles: access.admin },
+    access: { roles: metric.access?.roles ?? access.admin },
     handler: async (query, ctx) =>
       runMetric(ctx.db, metric, {
         range: query.payload.range,
@@ -87,6 +89,17 @@ function createTenantMetricQuery(
         filterWhere: await resolveMetricFilterWhere(metric, query.payload, ctx),
         // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
         scopeWhere: { tenantId: query.user.tenantId },
+        referenceLabels: (keys) =>
+          metric.groupBy === undefined
+            ? Promise.resolve(new Map())
+            : referenceGroupLabels(
+                ctx,
+                query.user,
+                extractTableInfo(metric.source).name,
+                metric.groupBy,
+                keys,
+                ctx.db,
+              ),
       }),
   });
 }

package/packages/bundled-features/src/metrics/types.ts

@@ -41,8 +41,10 @@ export type MetricDefinition = {
   readonly groupBy?: string;
   /** Second dimension, becomes `rows[].segments`; only without bucket. */
   readonly stackBy?: string;
-  /** Key value → i18n key, applied to groupBy and stackBy keys. */
+  /** Key value → i18n key, applied to groupBy and stackBy keys. Without an entry, a groupBy that is a single reference of an entity-table source is named after the referenced row (tenant scope, through the caller's read access); otherwise the key stays. */
   readonly groupLabels?: Readonly<Record<string, string>>;
+  /** Roles that may read the tenant query; default is the admin roles. Ignored for scope "system", which stays SystemAdmin only. */
+  readonly access?: { readonly roles: readonly string[] };
   readonly scopes: readonly MetricScope[];
 };
 

package/packages/bundled-features/src/metrics/validate.ts

@@ -31,6 +31,9 @@ function validateMetric(metric: MetricDefinition): void {
   };
   if (!KEBAB_ID.test(metric.id)) fail("has an id that is not kebab-case");
   if (metric.scopes.length === 0) fail("declares no scopes");
+  if (metric.access !== undefined && metric.access.roles.length === 0) {
+    fail("declares access with an empty roles list");
+  }
 
   const info = extractTableInfo(metric.source);
   validateColumns(metric, info, fail);

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -472,7 +472,7 @@
     },
     {
       "name": "channel-in-app",
-      "description": "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
+      "description": "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
       "toggleableDefault": null,
       "requires": [
         "delivery"