@checkcourt/sdk 0.9.0 → 0.11.0

package/README.md

@@ -193,6 +193,36 @@ ui.form({
 });
 ```
 
+Blocks can carry an `icon` from `UI_ICONS` (text, heading, stat, badge, list items), a `stat`
+can be `size: "lg"`, badges have a soft amber `"warning"` variant, `ui.columns` lays out 2
+to 6 children in equal widths, and `ui.row(children, { justify: "between" })` spreads a row
+across the full width (first child left, last child right). A weather widget:
+
+```ts
+const days = [
+  ["Heute", "sun", "24°"],
+  ["Do", "cloud-sun", "21°"],
+  ["Fr", "cloud-rain", "17°"],
+  ["Sa", "cloud-drizzle", "18°"],
+  ["So", "sun", "23°"],
+] as const;
+
+ui.doc([
+  ui.row(
+    [
+      ui.stat("Jetzt", "24°", { icon: "sun", size: "lg", hint: "Sonnig" }),
+      ui.badge("Regen möglich", { variant: "warning", icon: "droplets" }),
+    ],
+    { justify: "between" },
+  ),
+  ui.divider(),
+  ui.columns(
+    days.map(([day, icon, temp]) => ui.stat(day, temp, { icon })),
+    { dividers: true, align: "center" },
+  ),
+]);
+```
+
 Compare `context.installation_id` and `context.tenant_id` with what you stored from
 `app.installed` before you act on a request. For the context token alone (for example in
 the backend of an iframe extension), use `verifyExtensionContext(token, secret)`.
@@ -246,6 +276,31 @@ if (ext.point === "nav.page") {
 }
 ```
 
+#### Permissions for the club's roles
+
+A club app can offer its own rights (at most `MAX_APP_PERMISSIONS`, keys matching
+`APP_PERMISSION_KEY_PATTERN`). The club decides in its role editor which roles hold them; only
+administrators hold them from the start. Every extension request carries the viewer's flags
+for all declared keys in `viewer.capabilities.permissions`, and a `nav.page` with `requires`
+is only listed and opened for holders:
+
+```ts
+defineManifest({
+  installTargets: ["tenant"],
+  permissions: [{ key: "manage_ladder", label: "Rangliste verwalten", description: "Darf Ergebnisse korrigieren" }],
+  extensions: [
+    { point: "nav.page", kind: "declarative", url: "https://ladder.example.de/ext/admin", label: "Rangliste", icon: "trophy", requires: "manage_ladder" },
+    { point: "dashboard.widget", kind: "declarative", url: "https://ladder.example.de/ext/widget" },
+  ],
+  dataProcessing: { categories: ["Spielergebnisse"], purpose: "Führt die Rangliste", storageLocation: "EU", avvRequired: false },
+});
+
+const { context } = ext; // from verifyExtensionRequest, as above
+if (context.viewer.capabilities.permissions?.manage_ladder) {
+  // show the edit buttons
+}
+```
+
 ### OAuth with PKCE (member apps)
 
 ```ts

package/dist/extensions.d.ts

@@ -55,6 +55,14 @@ export interface PointCapabilities {
     "sidebar.action": Record<string, never>;
     "nav.page": Record<string, never>;
 }
+/**
+ * Present at every point when the app's manifest declares `permissions`: each declared key with
+ * whether the viewer holds it (through a club role; administrators hold all). Absent otherwise.
+ * `false` at the kiosk, where nobody is signed in.
+ */
+export interface AppPermissionCapabilities {
+    permissions?: Record<string, boolean>;
+}
 export interface PointSubject {
     "app.settings": {
         type: "installation";
@@ -98,7 +106,7 @@ interface ContextClaimsOf<P extends ExtensionPoint> {
     viewer: {
         /** null on the kiosk; a stable `psn_…` pseudonym unless the installation holds `members:read`. */
         user_id: string | null;
-        capabilities: PointCapabilities[P];
+        capabilities: PointCapabilities[P] & AppPermissionCapabilities;
     };
     iat: number;
     exp: number;

package/dist/iframe.d.ts

@@ -6,7 +6,7 @@ export declare const MAX_TOAST_LENGTH = 200;
 /** Top-level areas `navigate()` may target; anything else is dropped by CheckCourt. */
 export declare const NAVIGABLE_SECTIONS: readonly ["dashboard", "booking", "my-bookings", "club", "team", "trainer", "fees", "arbeitsstunden", "settings", "admin"];
 /** CSS variables CheckCourt sends with every theme message. */
-export declare const THEME_TOKEN_NAMES: readonly ["--background", "--foreground", "--card", "--card-foreground", "--muted", "--muted-foreground", "--primary", "--primary-foreground", "--secondary", "--secondary-foreground", "--accent", "--accent-foreground", "--destructive", "--border", "--input", "--ring", "--radius"];
+export declare const THEME_TOKEN_NAMES: readonly ["--background", "--foreground", "--card", "--card-foreground", "--muted", "--muted-foreground", "--primary", "--primary-foreground", "--secondary", "--secondary-foreground", "--accent", "--accent-foreground", "--destructive", "--warning", "--warning-foreground", "--warning-muted", "--border", "--input", "--ring", "--radius"];
 export type ThemeTokenName = (typeof THEME_TOKEN_NAMES)[number];
 export type FrameMessage = {
     type: "checkcourt:resize";

package/dist/iframe.js

@@ -31,6 +31,9 @@ export const THEME_TOKEN_NAMES = [
     "--accent",
     "--accent-foreground",
     "--destructive",
+    "--warning",
+    "--warning-foreground",
+    "--warning-muted",
     "--border",
     "--input",
     "--ring",

package/dist/manifest.d.ts

@@ -86,6 +86,25 @@ export declare const STATIC_ACTION_LABEL_MAX = 24;
 /** Bounds of an iframe extension's initial `height` in pixels. */
 export declare const IFRAME_EXTENSION_HEIGHT_MIN = 120;
 export declare const IFRAME_EXTENSION_HEIGHT_MAX = 2000;
+/** Keys of app permissions: lowercase letters, digits and `_`, starting with a letter, at most 40 characters. */
+export declare const APP_PERMISSION_KEY_PATTERN: RegExp;
+/** Most permissions one manifest may declare. */
+export declare const MAX_APP_PERMISSIONS = 10;
+export declare const APP_PERMISSION_LABEL_MAX = 60;
+export declare const APP_PERMISSION_DESCRIPTION_MAX = 200;
+/**
+ * A right the app offers the club's roles, e.g. who may manage its ladder. The club decides in
+ * its role editor which roles hold it; only administrators hold it from the start. Viewers' flags
+ * arrive as `viewer.capabilities.permissions` in the extension context.
+ */
+export interface AppPermission {
+    /** Matches `APP_PERMISSION_KEY_PATTERN`, unique within the manifest. */
+    key: string;
+    /** Shown in the role editor, German, 1 to 60 characters, e.g. "Rangliste verwalten". */
+    label: string;
+    /** Up to 200 characters. */
+    description?: string;
+}
 /** lucide icon names a static action or `nav.page` may use as `icon`. */
 export declare const APP_ACTION_ICONS: readonly ["bell", "calendar", "calendar-check", "camera", "chart-column", "circle-help", "clipboard-list", "clock", "cloud-rain", "door-open", "file-text", "flag", "heart-pulse", "info", "key-round", "lightbulb", "link", "list-checks", "lock-open", "map-pin", "megaphone", "message-square", "receipt", "send", "sparkles", "star", "sun", "thermometer", "ticket", "triangle-alert", "trophy", "user-round", "users", "wallet", "wrench"];
 export type AppActionIcon = (typeof APP_ACTION_ICONS)[number];
@@ -115,6 +134,11 @@ type ExtensionOf<P extends ExtensionPoint> = {
     /** Navigation entry and page title, 1 to 24 characters (`STATIC_ACTION_LABEL_MAX`). */
     label: string;
     icon: AppActionIcon;
+    /**
+     * Key of one of the manifest's `permissions`: only holders see the entry and may open
+     * the page; CheckCourt enforces it for the page and its actions.
+     */
+    requires?: string;
 } : P extends "booking.action" ? {
     label: string;
     icon?: never;
@@ -247,6 +271,8 @@ export interface Manifest {
     /** At most 20. */
     extensions?: readonly ManifestExtension[];
     settingsSchema?: SettingsSchema;
+    /** Rights the app offers the club's roles (at most 10). Club installations only. */
+    permissions?: readonly AppPermission[];
     dataProcessing: DataProcessing;
     /** Metadata other apps may read (at most 20). Club installations only. */
     shares?: {

package/dist/manifest.js

@@ -41,6 +41,12 @@ export const STATIC_ACTION_LABEL_MAX = 24;
 /** Bounds of an iframe extension's initial `height` in pixels. */
 export const IFRAME_EXTENSION_HEIGHT_MIN = 120;
 export const IFRAME_EXTENSION_HEIGHT_MAX = 2000;
+/** Keys of app permissions: lowercase letters, digits and `_`, starting with a letter, at most 40 characters. */
+export const APP_PERMISSION_KEY_PATTERN = /^[a-z][a-z0-9_]{0,39}$/;
+/** Most permissions one manifest may declare. */
+export const MAX_APP_PERMISSIONS = 10;
+export const APP_PERMISSION_LABEL_MAX = 60;
+export const APP_PERMISSION_DESCRIPTION_MAX = 200;
 /** lucide icon names a static action or `nav.page` may use as `icon`. */
 export const APP_ACTION_ICONS = [
     "bell",

package/dist/ui.d.ts

@@ -2,34 +2,55 @@ export declare const UI_VERSION = "v1";
 export declare const MAX_UI_BLOCKS = 50;
 /** Top-level blocks sit at depth 1; a container's children one deeper. */
 export declare const MAX_UI_DEPTH = 3;
-export declare const BADGE_VARIANTS: readonly ["default", "secondary", "outline", "destructive"];
+export declare const BADGE_VARIANTS: readonly ["default", "secondary", "outline", "destructive", "warning"];
 export declare const BUTTON_VARIANTS: readonly ["default", "secondary", "outline", "destructive"];
 export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
 export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+/** Icons a block may show, by lucide name; CheckCourt draws them in the text color at text size. */
+export declare const UI_ICONS: readonly ["sun", "moon", "cloud", "cloud-sun", "cloud-moon", "cloud-sun-rain", "cloud-rain", "cloud-drizzle", "cloud-lightning", "cloud-snow", "cloud-fog", "snowflake", "wind", "droplet", "droplets", "umbrella", "thermometer", "sunrise", "sunset", "check", "x", "info", "alert-triangle", "triangle-alert", "alert-circle", "circle-alert", "clock", "calendar", "map-pin", "trophy", "users", "user", "lock", "unlock", "lock-open", "lightbulb", "zap", "euro", "star", "heart", "bell", "flag", "activity", "timer", "ticket", "door-open"];
+export type UiIcon = (typeof UI_ICONS)[number];
+/** `lg` shows the value as a large display figure, `md` (default) as a regular stat. */
+export declare const STAT_SIZES: readonly ["md", "lg"];
+export type StatSize = (typeof STAT_SIZES)[number];
+export declare const COLUMNS_ALIGNMENTS: readonly ["start", "center"];
+export type ColumnsAlignment = (typeof COLUMNS_ALIGNMENTS)[number];
+/** `between` spreads a row's children across the full width, first at the left edge, last at the right. */
+export declare const ROW_JUSTIFICATIONS: readonly ["start", "between"];
+export type RowJustify = (typeof ROW_JUSTIFICATIONS)[number];
+/** A `columns` block holds 2 to 6 children. */
+export declare const MIN_COLUMNS = 2;
+export declare const MAX_COLUMNS = 6;
 export type UiTextBlock = {
     type: "text";
     text: string;
     tone?: "muted";
+    icon?: UiIcon;
 };
 export type UiHeadingBlock = {
     type: "heading";
     text: string;
     level: 2 | 3;
+    icon?: UiIcon;
 };
+/** With `icon`, the icon sits before the value. */
 export type UiStatBlock = {
     type: "stat";
     label: string;
     value: string;
     hint?: string;
+    icon?: UiIcon;
+    size?: StatSize;
 };
 export type UiBadgeBlock = {
     type: "badge";
     label: string;
     variant?: BadgeVariant;
+    icon?: UiIcon;
 };
 export type UiListItem = {
     title: string;
     description?: string;
+    icon?: UiIcon;
 };
 export type UiListBlock = {
     type: "list";
@@ -136,8 +157,16 @@ export type UiStackBlock = {
 export type UiRowBlock = {
     type: "row";
     children: UiBlock[];
+    justify?: RowJustify;
 };
-export type UiBlock = UiTextBlock | UiHeadingBlock | UiStatBlock | UiBadgeBlock | UiListBlock | UiKeyValueBlock | UiLinkBlock | UiButtonBlock | UiFormBlock | UiDividerBlock | UiStackBlock | UiRowBlock;
+/** 2 to 6 children side by side in equal widths; on narrow cards 4 wrap to 2 per row, 5 and 6 to 3. */
+export type UiColumnsBlock = {
+    type: "columns";
+    children: UiBlock[];
+    dividers?: boolean;
+    align?: ColumnsAlignment;
+};
+export type UiBlock = UiTextBlock | UiHeadingBlock | UiStatBlock | UiBadgeBlock | UiListBlock | UiKeyValueBlock | UiLinkBlock | UiButtonBlock | UiFormBlock | UiDividerBlock | UiStackBlock | UiRowBlock | UiColumnsBlock;
 export type UiToast = {
     kind: "success" | "error";
     message: string;
@@ -265,12 +294,23 @@ export declare const ui: {
     readonly hidden: (options?: UiDocumentOptions) => UiHiddenDocument;
     readonly text: (text: string, options?: {
         tone?: "muted";
+        icon?: UiIcon;
     }) => UiTextBlock;
-    readonly heading: (text: string, level?: 2 | 3) => UiHeadingBlock;
+    /** `ui.heading(text, 3)` or `ui.heading(text, { level: 3, icon: "trophy" })`; level defaults to 2. */
+    readonly heading: (text: string, levelOrOptions?: 2 | 3 | {
+        level?: 2 | 3;
+        icon?: UiIcon;
+    }) => UiHeadingBlock;
     readonly stat: (label: string, value: string, options?: {
         hint?: string;
+        icon?: UiIcon;
+        size?: StatSize;
     }) => UiStatBlock;
-    readonly badge: (label: string, variant?: BadgeVariant) => UiBadgeBlock;
+    /** `ui.badge(label, "warning")` or `ui.badge(label, { variant: "warning", icon: "droplets" })`. */
+    readonly badge: (label: string, variantOrOptions?: BadgeVariant | {
+        variant?: BadgeVariant;
+        icon?: UiIcon;
+    }) => UiBadgeBlock;
     readonly list: (items: UiListItem[]) => UiListBlock;
     /** Pairs keep their order; a plain object is turned into pairs in key order. */
     readonly keyValue: (pairs: UiKeyValuePair[] | Record<string, string>) => UiKeyValueBlock;
@@ -294,8 +334,15 @@ export declare const ui: {
     };
     readonly divider: () => UiDividerBlock;
     readonly stack: (children: UiBlock[]) => UiStackBlock;
-    /** Horizontal, wraps on narrow screens. */
-    readonly row: (children: UiBlock[]) => UiRowBlock;
+    /** Horizontal, wraps on narrow screens; `justify: "between"` pushes the last child to the right edge. */
+    readonly row: (children: UiBlock[], options?: {
+        justify?: RowJustify;
+    }) => UiRowBlock;
+    /** 2 to 6 equal-width columns, optionally with vertical dividers; throws on any other count. */
+    readonly columns: (children: UiBlock[], options?: {
+        dividers?: boolean;
+        align?: ColumnsAlignment;
+    }) => UiColumnsBlock;
 };
 /** Toasts for `ui.doc(blocks, { toast })`, at most 200 characters. */
 export declare const toast: {

package/dist/ui.js

@@ -2,8 +2,65 @@ export const UI_VERSION = "v1";
 export const MAX_UI_BLOCKS = 50;
 /** Top-level blocks sit at depth 1; a container's children one deeper. */
 export const MAX_UI_DEPTH = 3;
-export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive"];
+export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive", "warning"];
 export const BUTTON_VARIANTS = ["default", "secondary", "outline", "destructive"];
+/** Icons a block may show, by lucide name; CheckCourt draws them in the text color at text size. */
+export const UI_ICONS = [
+    "sun",
+    "moon",
+    "cloud",
+    "cloud-sun",
+    "cloud-moon",
+    "cloud-sun-rain",
+    "cloud-rain",
+    "cloud-drizzle",
+    "cloud-lightning",
+    "cloud-snow",
+    "cloud-fog",
+    "snowflake",
+    "wind",
+    "droplet",
+    "droplets",
+    "umbrella",
+    "thermometer",
+    "sunrise",
+    "sunset",
+    "check",
+    "x",
+    "info",
+    "alert-triangle",
+    "triangle-alert",
+    "alert-circle",
+    "circle-alert",
+    "clock",
+    "calendar",
+    "map-pin",
+    "trophy",
+    "users",
+    "user",
+    "lock",
+    "unlock",
+    "lock-open",
+    "lightbulb",
+    "zap",
+    "euro",
+    "star",
+    "heart",
+    "bell",
+    "flag",
+    "activity",
+    "timer",
+    "ticket",
+    "door-open",
+];
+/** `lg` shows the value as a large display figure, `md` (default) as a regular stat. */
+export const STAT_SIZES = ["md", "lg"];
+export const COLUMNS_ALIGNMENTS = ["start", "center"];
+/** `between` spreads a row's children across the full width, first at the left edge, last at the right. */
+export const ROW_JUSTIFICATIONS = ["start", "between"];
+/** A `columns` block holds 2 to 6 children. */
+export const MIN_COLUMNS = 2;
+export const MAX_COLUMNS = 6;
 /** CheckCourt caps every render lifetime at this many seconds. */
 export const UI_CACHE_MAX_AGE_LIMIT = 300;
 /** Longest badge label of a `court.annotation`. */
@@ -75,6 +132,14 @@ function variantOf(variant, what) {
     }
     return variant;
 }
+function iconOf(icon) {
+    if (icon === undefined)
+        return undefined;
+    if (!UI_ICONS.includes(icon)) {
+        throw new TypeError(`Unknown icon ${String(icon)}; use one of UI_ICONS`);
+    }
+    return icon;
+}
 function entriesOf(list, what) {
     if (!Array.isArray(list))
         throw new TypeError(`${what} must be an array`);
@@ -157,19 +222,31 @@ export const ui = {
         return compact({ ui: UI_VERSION, hidden: true, toast: options.toast, cache: cacheOf(options.maxAge) });
     },
     text(text, options = {}) {
-        return compact({ type: "text", text, tone: options.tone });
+        return compact({ type: "text", text, tone: options.tone, icon: iconOf(options.icon) });
     },
-    heading(text, level = 2) {
-        return { type: "heading", text, level };
+    /** `ui.heading(text, 3)` or `ui.heading(text, { level: 3, icon: "trophy" })`; level defaults to 2. */
+    heading(text, levelOrOptions = 2) {
+        const options = typeof levelOrOptions === "object" ? levelOrOptions : { level: levelOrOptions };
+        return compact({ type: "heading", text, level: options.level ?? 2, icon: iconOf(options.icon) });
     },
     stat(label, value, options = {}) {
-        return compact({ type: "stat", label, value, hint: options.hint });
+        if (options.size !== undefined && !STAT_SIZES.includes(options.size)) {
+            throw new TypeError(`stat size must be one of ${STAT_SIZES.join(", ")}`);
+        }
+        return compact({ type: "stat", label, value, hint: options.hint, icon: iconOf(options.icon), size: options.size });
     },
-    badge(label, variant) {
-        return compact({ type: "badge", label, variant });
+    /** `ui.badge(label, "warning")` or `ui.badge(label, { variant: "warning", icon: "droplets" })`. */
+    badge(label, variantOrOptions) {
+        const options = typeof variantOrOptions === "object" ? variantOrOptions : { variant: variantOrOptions };
+        return compact({
+            type: "badge",
+            label,
+            variant: variantOf(options.variant, "badge variant"),
+            icon: iconOf(options.icon),
+        });
     },
     list(items) {
-        return { type: "list", items: items.map((item) => compact({ ...item })) };
+        return { type: "list", items: items.map((item) => compact({ ...item, icon: iconOf(item.icon) })) };
     },
     /** Pairs keep their order; a plain object is turned into pairs in key order. */
     keyValue(pairs) {
@@ -198,9 +275,22 @@ export const ui = {
     stack(children) {
         return { type: "stack", children };
     },
-    /** Horizontal, wraps on narrow screens. */
-    row(children) {
-        return { type: "row", children };
+    /** Horizontal, wraps on narrow screens; `justify: "between"` pushes the last child to the right edge. */
+    row(children, options = {}) {
+        if (options.justify !== undefined && !ROW_JUSTIFICATIONS.includes(options.justify)) {
+            throw new TypeError(`row justify must be one of ${ROW_JUSTIFICATIONS.join(", ")}`);
+        }
+        return compact({ type: "row", children, justify: options.justify });
+    },
+    /** 2 to 6 equal-width columns, optionally with vertical dividers; throws on any other count. */
+    columns(children, options = {}) {
+        if (!Array.isArray(children) || children.length < MIN_COLUMNS || children.length > MAX_COLUMNS) {
+            throw new RangeError(`columns takes ${MIN_COLUMNS} to ${MAX_COLUMNS} children`);
+        }
+        if (options.align !== undefined && !COLUMNS_ALIGNMENTS.includes(options.align)) {
+            throw new TypeError(`columns align must be one of ${COLUMNS_ALIGNMENTS.join(", ")}`);
+        }
+        return compact({ type: "columns", children, dividers: options.dividers, align: options.align });
     },
 };
 /** Toasts for `ui.doc(blocks, { toast })`, at most 200 characters. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkcourt/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Official TypeScript SDK for the CheckCourt app platform",
   "private": false,
   "license": "MIT",