@cosmicdrift/kumiko-bundled-features 0.398.0 → 0.399.0

package/dist/billing-foundation/consumer-protection/consent-text.js

@@ -17,12 +17,12 @@ export const CONSENT_TEXTS = {
 };
 const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS = {
     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.",
+        withRefund: "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.",
     },
 };
 export function legalLinksPerLocale(legalLinks) {

package/dist/channel-in-app/constants.js

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

package/dist/channel-in-app/feature.js

@@ -8,7 +8,7 @@ import { inAppChannel } from "./in-app-channel.js";
 import { inAppMessagesTableMeta } from "./tables.js";
 export function createChannelInAppFeature() {
     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.");
+        r.describe("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",
             category: "notifications",

package/dist/channel-in-app/handlers/inbox.query.d.ts

@@ -2,6 +2,9 @@ import * as z from "zod";
 export declare const inboxQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"inbox", z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     unreadOnly: z.ZodDefault<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
-    rows: readonly any[];
+    rows: any[];
+    nextCursor: string | null;
+    total: number;
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/channel-in-app/handlers/inbox.query.js

@@ -1,12 +1,15 @@
 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.js";
 import { inAppMessagesTable } from "../tables.js";
+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: {
@@ -14,15 +17,27 @@ export const inboxQuery = defineQueryHandler({
                 "inAppMessagesTable by the caller's own id",
         },
     },
-    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.",
+    description: "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 = { 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 = { 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" },
         });
-        return { rows };
+        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, nextCursor, total: totalRow?.value ?? 0 };
     },
 });

package/dist/channel-in-app/handlers/unread-count.query.js

@@ -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.js";
@@ -13,13 +12,7 @@ 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/dist/channel-in-app/in-app-channel.js

@@ -1,5 +1,9 @@
 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 { targetOfNotificationData } from "./in-app-target.js";
 import { inAppMessagesTable } from "./tables.js";
+const log = createFallbackLogger("channel-in-app");
 export const inAppChannel = {
     name: "inApp",
     mode: "inline",
@@ -10,24 +14,32 @@ export const inAppChannel = {
     async send(address, message, ctx) {
         // 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(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/dist/channel-in-app/in-app-target.d.ts

@@ -0,0 +1,5 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget;
+export declare function parseInAppTarget(value: unknown): InAppNotificationTarget | null;
+export declare function targetOfNotificationData(data: unknown): InAppNotificationTarget | null;
+export declare function parseStoredNotificationData(stored: string | null): unknown;

package/dist/channel-in-app/in-app-target.js

@@ -0,0 +1,34 @@
+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, entityId) {
+    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) {
+    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) {
+    if (typeof data !== "object" || data === null || !("target" in data))
+        return null;
+    return parseInAppTarget(data.target);
+}
+export function parseStoredNotificationData(stored) {
+    if (stored === null)
+        return null;
+    try {
+        return JSON.parse(stored);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/channel-in-app/index.d.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/dist/channel-in-app/index.js

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

package/dist/metrics/compute.d.ts

@@ -1,4 +1,5 @@
 import type { WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import type { AggregateKey } from "@cosmicdrift/kumiko-types/aggregate-types";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import type { MetricDefinition, MetricResult } from "./types.ts";
@@ -11,5 +12,7 @@ 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>>;
 };
 export declare function runMetric(db: TenantDb, metric: MetricDefinition, params: MetricRunParams): Promise<MetricResult>;

package/dist/metrics/compute.js

@@ -75,7 +75,7 @@ function groupSegments(stackRows, labelOf) {
     }
     return segmentsByGroup;
 }
-function buildRows(metric, aggregates, total, labelOf) {
+function buildRows(metric, aggregates, total, labelOf, groupLabelOf) {
     const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
     return aggregates.groups.map((row) => {
         const key = keyText(row.keys[0]);
@@ -83,7 +83,7 @@ function buildRows(metric, aggregates, total, labelOf) {
         return {
             id: key,
             key,
-            label: labelOf(key),
+            label: groupLabelOf(key),
             value: rowValue,
             fraction: fractionOf(rowValue, total),
             ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
@@ -104,6 +104,11 @@ function buildSeries(rows, seriesRows, fillBuckets) {
         points: fillBuckets(bucketsByGroup.get(row.key) ?? new Map()),
     }));
 }
+async function resolveReferencedGroupLabels(metric, params, groups) {
+    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, metric, params) {
     const range = metric.window ?? params.range;
     const bucket = resolveBucket(metric, range);
@@ -129,7 +134,9 @@ export async function runMetric(db, metric, params) {
             row.value,
         ])))
         : [];
-    const rows = buildRows(metric, aggregates, value, labelOf);
+    const referencedLabels = await resolveReferencedGroupLabels(metric, params, aggregates.groups);
+    const groupLabelOf = (key) => metric.groupLabels?.[key] ?? referencedLabels.get(key) ?? key;
+    const rows = buildRows(metric, aggregates, value, labelOf, groupLabelOf);
     return {
         value,
         previousValue,

package/dist/metrics/feature.js

@@ -1,4 +1,5 @@
-import { access, defineFeature, defineQueryHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { extractTableInfo } from "@cosmicdrift/kumiko-framework/db";
+import { access, defineFeature, defineQueryHandler, referenceGroupLabels, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
@@ -45,7 +46,7 @@ function createTenantMetricQuery(metric, now) {
         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,
             timeZone: query.payload.timeZone,
@@ -53,6 +54,9 @@ function createTenantMetricQuery(metric, now) {
             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/dist/metrics/types.d.ts

@@ -33,8 +33,12 @@ 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[];
 };
 export declare function defineMetric(definition: MetricDefinition): MetricDefinition;

package/dist/metrics/validate.js

@@ -25,6 +25,9 @@ function validateMetric(metric) {
         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);
     validateFilters(metric, info, fail);

package/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>",
@@ -566,9 +566,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.398.0",
-    "@cosmicdrift/kumiko-renderer": "0.398.0",
-    "@cosmicdrift/kumiko-types": "0.398.0",
+    "@cosmicdrift/kumiko-framework": "0.399.0",
+    "@cosmicdrift/kumiko-renderer": "0.399.0",
+    "@cosmicdrift/kumiko-types": "0.399.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@tiptap/core": "^3.31.3",
@@ -1158,17 +1158,17 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.8",
-    "@cosmicdrift/kumiko-locale-de": "0.398.0",
-    "@cosmicdrift/kumiko-locale-es": "0.398.0",
-    "@cosmicdrift/kumiko-locale-fr": "0.398.0",
-    "@cosmicdrift/kumiko-locale-it": "0.398.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.398.0",
+    "@cosmicdrift/kumiko-locale-de": "0.399.0",
+    "@cosmicdrift/kumiko-locale-es": "0.399.0",
+    "@cosmicdrift/kumiko-locale-fr": "0.399.0",
+    "@cosmicdrift/kumiko-locale-it": "0.399.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.399.0",
     "jsqr": "^1.4.0",
     "unpdf": "^1.8.1",
-    "@cosmicdrift/kumiko-testing": "0.398.0"
+    "@cosmicdrift/kumiko-testing": "0.399.0"
   },
   "peerDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.398.0"
+    "@cosmicdrift/kumiko-testing": "0.399.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-testing": {

package/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/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/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",