@checkcourt/sdk 0.7.0 → 0.9.0

package/README.md

@@ -210,6 +210,7 @@ with the matching builder; each throws when the answer would break CheckCourt's
 | `booking_plan.action` | `ext.date`, `ext.courts` (and the day as subject) | `ui.doc([...])`, shown in a dialog after a click; `ui.hidden()` closes it |
 | `sidebar.action` | nothing extra | `ui.doc([...])`, shown in a dialog after a click; `ui.hidden()` closes it |
 | `member.settings.section` | nothing extra | `ui.doc([...])`, a card on the member's own settings page |
+| `nav.page` | nothing extra | `ui.doc([...])` (or an iframe), the content of the app's own page |
 
 ```ts
 if (ext.kind === "render" && ext.point === "court.annotation" && ext.date && ext.courts) {
@@ -227,6 +228,24 @@ if (ext.kind === "render" && ext.point === "court.annotation" && ext.date && ext
 manifest and may set an `icon` from `APP_ACTION_ICONS`. In every declarative document,
 CheckCourt places content first, then the buttons, then the links of each level.
 
+`nav.page` gives your app an entry in the main navigation and a full page of its own at
+`/apps/<installation id>/<index>`. It needs a `label` (at most 24 characters, also the page
+title) and an `icon` from `APP_ACTION_ICONS`, may be declarative or an iframe, and appears at
+most once per manifest. A club installation's entry is shown to every member of the club, a
+member installation's entry only to that member:
+
+```ts
+defineManifest({
+  installTargets: ["tenant"],
+  extensions: [{ point: "nav.page", kind: "declarative", url: "https://app.example.de/ext/page", label: "Trainingsplan", icon: "calendar" }],
+  dataProcessing: { categories: ["Trainingsdaten"], purpose: "Zeigt den Trainingsplan", storageLocation: "EU", avvRequired: false },
+});
+
+if (ext.point === "nav.page") {
+  return Response.json(ui.doc([ui.heading("Diese Woche"), ui.text("Dienstag 18 Uhr: Jugendtraining")]));
+}
+```
+
 ### OAuth with PKCE (member apps)
 
 ```ts
@@ -273,6 +292,19 @@ frame.navigate("/booking?date=2026-10-07");
 
 Import the browser entry point `@checkcourt/sdk/iframe` only; it needs no secrets.
 
+The frame starts at 240 pixels, a `nav.page` frame fills the page. Set `height` on the
+manifest entry (whole pixels, `IFRAME_EXTENSION_HEIGHT_MIN` to `IFRAME_EXTENSION_HEIGHT_MAX`,
+120 to 2000) to start at another height; `height` is for iframe extensions only.
+Resize messages from `connectExtensionFrame` replace either value:
+
+```ts
+{ point: "nav.page", kind: "iframe", url: "https://app.example.de/page", label: "Homepage", icon: "calendar", height: 900 }
+```
+
+Every app has a signing secret (`whsec_…`) from the moment it is created, with or without a
+webhook URL. Verify the context token with it in your backend; you can show it once and
+rotate it in the developer portal (your app → *Webhooks* → *Signatur-Secret*).
+
 ## Entry points
 
 | Import | Runs in | Contents |

package/dist/extensions.d.ts

@@ -53,6 +53,7 @@ export interface PointCapabilities {
     "booking.hint": Record<string, never>;
     "booking_plan.action": BookingPlanCapabilities;
     "sidebar.action": Record<string, never>;
+    "nav.page": Record<string, never>;
 }
 export interface PointSubject {
     "app.settings": {
@@ -83,6 +84,7 @@ export interface PointSubject {
         id: string;
     };
     "sidebar.action": null;
+    "nav.page": null;
 }
 interface ContextClaimsOf<P extends ExtensionPoint> {
     iss: typeof CONTEXT_ISSUER;

package/dist/manifest.d.ts

@@ -56,6 +56,10 @@ export declare const EXTENSION_POINTS: {
         readonly targets: readonly ["tenant", "user"];
         readonly kinds: readonly ["declarative"];
     };
+    readonly "nav.page": {
+        readonly targets: readonly ["tenant", "user"];
+        readonly kinds: readonly ["declarative", "iframe"];
+    };
 };
 export type ExtensionPoint = keyof typeof EXTENSION_POINTS;
 /** Scope the installation needs (in `tenantScopes` or `userScopes`) before the point hands it a subject id. */
@@ -72,27 +76,45 @@ export declare const EXTENSION_POINT_SCOPE: {
     readonly "booking.hint": "bookings:read";
     readonly "booking_plan.action": "courts:read";
     readonly "sidebar.action": null;
+    readonly "nav.page": null;
 };
 /** Buttons CheckCourt draws from the manifest alone, before the app is ever called. */
 export declare const STATIC_ACTION_POINTS: readonly ["booking_plan.action", "sidebar.action"];
 export type StaticActionPoint = (typeof STATIC_ACTION_POINTS)[number];
 /** Longest `label` of a static action. */
 export declare const STATIC_ACTION_LABEL_MAX = 24;
-/** lucide icon names a static action may use as `icon`. */
+/** 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;
+/** 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];
 /** Every scope an app may request. Role, app, webhook, key, billing and AVV management are reserved for people. */
 export declare const GRANTABLE_SCOPES: readonly ["courts:read", "courts:read_confidential", "courts:write", "bookings:read", "bookings:read_confidential", "bookings:write", "bookings:cancel", "bookings:edit", "bookings:export", "members:read", "members:read_confidential", "members:invite", "members:write", "members:delete", "teams:read", "teams:write", "policies:read", "policies:read_confidential", "policies:write", "categories:read", "categories:write", "invites:read", "invites:write", "settings:read", "settings:read_confidential", "settings:write", "guest_fees:read", "guest_fees:write", "audit:read", "announcements:read", "announcements:write", "events:read", "events:write", "posts:read", "posts:write", "posts:moderate", "court_layout:read", "court_layout:write", "work_hours:read", "work_hours:write", "work_hours:manage", "compliance:read", "kiosk:manage", "trainer_blocks:write", "analytics:read", "embeds:manage", "webhooks:read", "notifications:send"];
 export type GrantableScope = (typeof GRANTABLE_SCOPES)[number];
+type KindOf<K extends ExtensionKind> = K extends "iframe" ? {
+    kind: K;
+    /**
+     * Initial frame height in whole pixels, `IFRAME_EXTENSION_HEIGHT_MIN` to `IFRAME_EXTENSION_HEIGHT_MAX`.
+     * Without it the frame starts at 240 pixels, a `nav.page` fills the page. Resize messages override it.
+     */
+    height?: number;
+} : {
+    kind: K;
+    height?: never;
+};
 type ExtensionOf<P extends ExtensionPoint> = {
     point: P;
-    kind: (typeof EXTENSION_POINTS)[P]["kinds"][number];
     /** https; http://localhost is accepted outside production. */
     url: string;
-} & (P extends StaticActionPoint ? {
+} & KindOf<(typeof EXTENSION_POINTS)[P]["kinds"][number]> & (P extends StaticActionPoint ? {
     /** Button text, 1 to 24 characters (`STATIC_ACTION_LABEL_MAX`). */
     label: string;
     icon?: AppActionIcon;
+} : P extends "nav.page" ? {
+    /** Navigation entry and page title, 1 to 24 characters (`STATIC_ACTION_LABEL_MAX`). */
+    label: string;
+    icon: AppActionIcon;
 } : P extends "booking.action" ? {
     label: string;
     icon?: never;
@@ -104,8 +126,8 @@ type ExtensionOf<P extends ExtensionPoint> = {
     icon?: never;
 });
 /**
- * One entry of `extensions`; `kind`, `label` and `icon` are checked per point at compile time.
- * Every point may appear once, except `booking.action`.
+ * One entry of `extensions`; `kind`, `label`, `icon` and `height` are checked per point at compile time.
+ * Every point may appear once, except `booking.action`; an app has at most one `nav.page`.
  */
 export type ManifestExtension = {
     [P in ExtensionPoint]: ExtensionOf<P>;

package/dist/manifest.js

@@ -16,6 +16,7 @@ export const EXTENSION_POINTS = {
     "booking.hint": { targets: ["tenant"], kinds: ["declarative"] },
     "booking_plan.action": { targets: ["tenant"], kinds: ["declarative"] },
     "sidebar.action": { targets: ["tenant", "user"], kinds: ["declarative"] },
+    "nav.page": { targets: ["tenant", "user"], kinds: ["declarative", "iframe"] },
 };
 /** Scope the installation needs (in `tenantScopes` or `userScopes`) before the point hands it a subject id. */
 export const EXTENSION_POINT_SCOPE = {
@@ -31,12 +32,16 @@ export const EXTENSION_POINT_SCOPE = {
     "booking.hint": "bookings:read",
     "booking_plan.action": "courts:read",
     "sidebar.action": null,
+    "nav.page": null,
 };
 /** Buttons CheckCourt draws from the manifest alone, before the app is ever called. */
 export const STATIC_ACTION_POINTS = ["booking_plan.action", "sidebar.action"];
 /** Longest `label` of a static action. */
 export const STATIC_ACTION_LABEL_MAX = 24;
-/** lucide icon names a static action may use as `icon`. */
+/** Bounds of an iframe extension's initial `height` in pixels. */
+export const IFRAME_EXTENSION_HEIGHT_MIN = 120;
+export const IFRAME_EXTENSION_HEIGHT_MAX = 2000;
+/** lucide icon names a static action or `nav.page` may use as `icon`. */
 export const APP_ACTION_ICONS = [
     "bell",
     "calendar",

package/package.json

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