@checkcourt/sdk 0.10.0 → 0.11.1

package/README.md

@@ -276,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/generated/spec-hash.d.ts

@@ -1 +1 @@
-export declare const OPENAPI_SPEC_SHA256 = "838f8beb1f933593ea8eea8ea14eb78b12e0e8d61109254f5e72bec10b57e58a";
+export declare const OPENAPI_SPEC_SHA256 = "2bf34f4fbfba9e950b8f44b09a760f4df37b47935001c5500612f1a3cc71b909";

package/dist/generated/spec-hash.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generate.mjs from the CheckCourt OpenAPI spec. Do not edit.
-export const OPENAPI_SPEC_SHA256 = "838f8beb1f933593ea8eea8ea14eb78b12e0e8d61109254f5e72bec10b57e58a";
+export const OPENAPI_SPEC_SHA256 = "2bf34f4fbfba9e950b8f44b09a760f4df37b47935001c5500612f1a3cc71b909";

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/package.json

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