@checkcourt/sdk 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { createCheckCourtClient, unwrap, retryAfterMs, TENANT_HEADER } from "./c
 export type { CheckCourtClient, CheckCourtClientOptions, RetryOptions } from "./client.js";
 export { apiKeyAuth, installationAuth, userAuth } from "./auth.js";
 export { getInstallation, getMe, type AppInstallation, type Me } from "./installation.js";
+export { deleteObjectMetadata, getObjectMetadata, publishAppEvent, putObjectMetadata, type ObjectMetadata, type ObjectMetadataEntry, type ObjectMetadataWritten, type PublishAppEventRequest, type PublishedAppEvent, } from "./connections.js";
+export { sendNotification, NOTIFICATION_TITLE_MAX, NOTIFICATION_BODY_MAX, type SendNotificationInput, type SendNotificationResponse, } from "./notifications.js";
 export type { AuthContext, AuthStrategy, InstallationAuth, StoredUserTokens, UserAuth } from "./auth.js";
 export * from "./errors.js";
 export * from "./oauth.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export { createCheckCourtClient, unwrap, retryAfterMs, TENANT_HEADER } from "./client.js";
 export { apiKeyAuth, installationAuth, userAuth } from "./auth.js";
 export { getInstallation, getMe } from "./installation.js";
+export { deleteObjectMetadata, getObjectMetadata, publishAppEvent, putObjectMetadata, } from "./connections.js";
+export { sendNotification, NOTIFICATION_TITLE_MAX, NOTIFICATION_BODY_MAX, } from "./notifications.js";
 export * from "./errors.js";
 export * from "./oauth.js";
 export * from "./webhooks.js";

package/dist/manifest.d.ts

@@ -32,6 +32,30 @@ export declare const EXTENSION_POINTS: {
         readonly targets: readonly ["tenant"];
         readonly kinds: readonly ["declarative"];
     };
+    readonly "court.annotation": {
+        readonly targets: readonly ["tenant"];
+        readonly kinds: readonly ["declarative"];
+    };
+    readonly "member.list.column": {
+        readonly targets: readonly ["tenant"];
+        readonly kinds: readonly ["declarative"];
+    };
+    readonly "member.settings.section": {
+        readonly targets: readonly ["user"];
+        readonly kinds: readonly ["declarative", "iframe"];
+    };
+    readonly "booking.hint": {
+        readonly targets: readonly ["tenant"];
+        readonly kinds: readonly ["declarative"];
+    };
+    readonly "booking_plan.action": {
+        readonly targets: readonly ["tenant"];
+        readonly kinds: readonly ["declarative"];
+    };
+    readonly "sidebar.action": {
+        readonly targets: readonly ["tenant", "user"];
+        readonly kinds: readonly ["declarative"];
+    };
 };
 export type ExtensionPoint = keyof typeof EXTENSION_POINTS;
 /** Scope the installation needs (in `tenantScopes` or `userScopes`) before the point hands it a subject id. */
@@ -42,21 +66,47 @@ export declare const EXTENSION_POINT_SCOPE: {
     readonly "member.profile.section": "members:read";
     readonly "dashboard.widget": null;
     readonly "kiosk.tile": null;
+    readonly "court.annotation": "courts:read";
+    readonly "member.list.column": "members:read";
+    readonly "member.settings.section": null;
+    readonly "booking.hint": "bookings:read";
+    readonly "booking_plan.action": "courts:read";
+    readonly "sidebar.action": 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`. */
+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"];
+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 ExtensionOf<P extends ExtensionPoint> = {
     point: P;
     kind: (typeof EXTENSION_POINTS)[P]["kinds"][number];
     /** https; http://localhost is accepted outside production. */
     url: string;
-} & (P extends "booking.action" ? {
+} & (P extends StaticActionPoint ? {
+    /** Button text, 1 to 24 characters (`STATIC_ACTION_LABEL_MAX`). */
+    label: string;
+    icon?: AppActionIcon;
+} : P extends "booking.action" ? {
     label: string;
+    icon?: never;
+} : P extends "member.list.column" ? {
+    label?: string;
+    icon?: never;
 } : {
     label?: string;
+    icon?: never;
 });
-/** One entry of `extensions`; `kind` and `label` are checked per point at compile time. */
+/**
+ * One entry of `extensions`; `kind`, `label` and `icon` are checked per point at compile time.
+ * Every point may appear once, except `booking.action`.
+ */
 export type ManifestExtension = {
     [P in ExtensionPoint]: ExtensionOf<P>;
 }[ExtensionPoint];
@@ -97,6 +147,72 @@ export interface DataProcessing {
     storageLocation: "EU" | "non-EU";
     avvRequired: boolean;
 }
+/** Club objects apps can attach metadata to. */
+export declare const SHARED_OBJECT_TYPES: readonly ["booking", "court", "member"];
+export type SharedObjectType = (typeof SHARED_OBJECT_TYPES)[number];
+/** Read scope both the sharing and the reading app need in `tenantScopes` for an object type. */
+export declare const SHARED_OBJECT_SCOPE: {
+    readonly booking: "bookings:read";
+    readonly court: "courts:read";
+    readonly member: "members:read";
+};
+/** Metadata keys and event names: `^[a-z][a-z0-9_]{0,39}$`. */
+export declare const CONNECTION_NAME_PATTERN: RegExp;
+/** Serialized size limit of a metadata value and of event data. */
+export declare const MAX_SHARED_VALUE_BYTES = 4096;
+/** A metadata key the app writes on club objects and lets other apps read once the club approves. */
+export interface SharedMetadata {
+    key: string;
+    object: SharedObjectType;
+    /** Shown to the club when it approves a connection, 1 to 200 characters, e.g. "Videolink". */
+    description: string;
+    /** 1 to 10 categories, shown in the approval dialog, e.g. ["Videoaufzeichnung"]. */
+    data_categories: readonly string[];
+}
+/** Metadata of another app this app wants to read: that app's slug, the key and the object type. */
+export interface ReadMetadata {
+    app: string;
+    key: string;
+    object: SharedObjectType;
+}
+export type AppEventProperty = {
+    type: "string";
+    description?: string;
+    /** Excludes `maxLength`. */
+    enum?: readonly string[];
+    maxLength?: number;
+} | {
+    type: "number" | "integer";
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: "boolean";
+    description?: string;
+};
+/** JSON-Schema subset for event data: flat objects of strings, numbers, integers and booleans (at most 30 properties). */
+export interface AppEventSchema {
+    type: "object";
+    /** Keys match `^[a-zA-Z][a-zA-Z0-9_]{0,39}$`. */
+    properties: Record<string, AppEventProperty>;
+    required?: readonly string[];
+    /** `false` rejects unknown keys. */
+    additionalProperties?: boolean;
+}
+/** An event the app publishes with `publishAppEvent`; subscribers receive it as `app.<your slug>.<name>`. */
+export interface EmittedEvent {
+    name: string;
+    /** 1 to 200 characters, shown in the approval dialog. */
+    description: string;
+    data_categories: readonly string[];
+    /** Published data is validated against it. */
+    schema?: AppEventSchema;
+}
+/** An event of another app this app wants to receive. */
+export interface SubscribedEvent {
+    app: string;
+    event: string;
+}
 export interface Manifest {
     manifestVersion?: typeof MANIFEST_VERSION;
     installTargets: readonly InstallTarget[];
@@ -110,6 +226,18 @@ export interface Manifest {
     extensions?: readonly ManifestExtension[];
     settingsSchema?: SettingsSchema;
     dataProcessing: DataProcessing;
+    /** Metadata other apps may read (at most 20). Club installations only. */
+    shares?: {
+        metadata: readonly SharedMetadata[];
+    };
+    /** Metadata of other apps this app reads (at most 50). Club installations only. */
+    reads?: {
+        metadata: readonly ReadMetadata[];
+    };
+    /** Events this app publishes to connected apps (at most 20). Club installations only. */
+    emits?: readonly EmittedEvent[];
+    /** Events of other apps this app receives (at most 50). Club installations only. */
+    subscribes?: readonly SubscribedEvent[];
 }
 /**
  * Identity function that gives editor completion and compile-time checks for a manifest.

package/dist/manifest.js

@@ -10,6 +10,12 @@ export const EXTENSION_POINTS = {
     "dashboard.widget": { targets: ["tenant", "user"], kinds: ["declarative"] },
     "booking.action": { targets: ["tenant", "user"], kinds: ["declarative"] },
     "kiosk.tile": { targets: ["tenant"], kinds: ["declarative"] },
+    "court.annotation": { targets: ["tenant"], kinds: ["declarative"] },
+    "member.list.column": { targets: ["tenant"], kinds: ["declarative"] },
+    "member.settings.section": { targets: ["user"], kinds: ["declarative", "iframe"] },
+    "booking.hint": { targets: ["tenant"], kinds: ["declarative"] },
+    "booking_plan.action": { targets: ["tenant"], kinds: ["declarative"] },
+    "sidebar.action": { targets: ["tenant", "user"], kinds: ["declarative"] },
 };
 /** Scope the installation needs (in `tenantScopes` or `userScopes`) before the point hands it a subject id. */
 export const EXTENSION_POINT_SCOPE = {
@@ -19,7 +25,55 @@ export const EXTENSION_POINT_SCOPE = {
     "member.profile.section": "members:read",
     "dashboard.widget": null,
     "kiosk.tile": null,
+    "court.annotation": "courts:read",
+    "member.list.column": "members:read",
+    "member.settings.section": null,
+    "booking.hint": "bookings:read",
+    "booking_plan.action": "courts:read",
+    "sidebar.action": 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`. */
+export const APP_ACTION_ICONS = [
+    "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",
+];
 /** Every scope an app may request. Role, app, webhook, key, billing and AVV management are reserved for people. */
 export const GRANTABLE_SCOPES = [
     "courts:read",
@@ -69,7 +123,21 @@ export const GRANTABLE_SCOPES = [
     "analytics:read",
     "embeds:manage",
     "webhooks:read",
+    // App-only: no club role holds it; a member app gets it from the member's consent.
+    "notifications:send",
 ];
+/** Club objects apps can attach metadata to. */
+export const SHARED_OBJECT_TYPES = ["booking", "court", "member"];
+/** Read scope both the sharing and the reading app need in `tenantScopes` for an object type. */
+export const SHARED_OBJECT_SCOPE = {
+    booking: "bookings:read",
+    court: "courts:read",
+    member: "members:read",
+};
+/** Metadata keys and event names: `^[a-z][a-z0-9_]{0,39}$`. */
+export const CONNECTION_NAME_PATTERN = /^[a-z][a-z0-9_]{0,39}$/;
+/** Serialized size limit of a metadata value and of event data. */
+export const MAX_SHARED_VALUE_BYTES = 4096;
 /**
  * Identity function that gives editor completion and compile-time checks for a manifest.
  * CheckCourt validates the rest on upload (scope and event pairing, URL rules, lengths).

package/dist/notifications.d.ts

@@ -0,0 +1,29 @@
+import { type CheckCourtClient } from "./client.js";
+import type { components } from "./generated/schema.js";
+export type SendNotificationResponse = components["schemas"]["SendNotificationResponse"];
+export declare const NOTIFICATION_TITLE_MAX = 80;
+export declare const NOTIFICATION_BODY_MAX = 500;
+export interface SendNotificationInput {
+    /**
+     * Who gets it: the CheckCourt user id (club apps with `members:read`), the `psn_…` pseudonym
+     * from an extension context, or the pairwise `usr_…` id from `getMe`. A member app may only
+     * notify its own member. Anything else answers 404.
+     */
+    recipient: string;
+    /** One line of plain text, 1 to 80 characters. */
+    title: string;
+    /** Plain text, 1 to 500 characters; line breaks are kept. */
+    body: string;
+    /** A path inside CheckCourt (`/booking?date=…`) or an https link on an origin your app registered. */
+    url?: string;
+    /** Your own label for the kind of message, e.g. `reminder`. */
+    category?: string;
+    /** The same key within 24 hours returns the first notification instead of sending again. */
+    idempotencyKey?: string;
+}
+/**
+ * `POST /api/v1/app/notifications`: CheckCourt delivers a message to one member, in CheckCourt and
+ * by email if they allow it. Needs `notifications:send`. The answer never says whether the member
+ * muted your app.
+ */
+export declare function sendNotification(client: CheckCourtClient, input: SendNotificationInput): Promise<SendNotificationResponse>;

package/dist/notifications.js

@@ -0,0 +1,14 @@
+import { unwrap } from "./client.js";
+export const NOTIFICATION_TITLE_MAX = 80;
+export const NOTIFICATION_BODY_MAX = 500;
+/**
+ * `POST /api/v1/app/notifications`: CheckCourt delivers a message to one member, in CheckCourt and
+ * by email if they allow it. Needs `notifications:send`. The answer never says whether the member
+ * muted your app.
+ */
+export async function sendNotification(client, input) {
+    const { idempotencyKey, ...rest } = input;
+    return unwrap(client.POST("/app/notifications", {
+        body: { ...rest, ...(idempotencyKey !== undefined ? { idempotency_key: idempotencyKey } : {}) },
+    }));
+}

package/dist/ui.d.ts

@@ -62,6 +62,10 @@ export type UiTextField = {
     default?: string;
     required?: boolean;
     max_length?: number;
+    /** Renders a multi-line text box instead of a single-line input. The value stays a string. */
+    multiline?: boolean;
+    /** Visible rows of the text box when `multiline` is set; 1 to 12. */
+    rows?: number;
 };
 export type UiNumberField = {
     type: "number";
@@ -112,37 +116,127 @@ export type UiToast = {
     kind: "success" | "error";
     message: string;
 };
-/** The response of a declarative extension: `{ ui: "v1", blocks, toast? }`. */
+/** CheckCourt caps every render lifetime at this many seconds. */
+export declare const UI_CACHE_MAX_AGE_LIMIT = 300;
+/**
+ * How long CheckCourt may reuse a render, in whole seconds. `0` means never. Without it
+ * CheckCourt follows the response's `Cache-Control` header, else keeps a render for 30 seconds.
+ */
+export type UiCache = {
+    max_age: number;
+};
+/** The response of a declarative extension: `{ ui: "v1", blocks, toast?, cache? }`. */
 export interface UiDocument {
     ui: typeof UI_VERSION;
     blocks: UiBlock[];
     toast?: UiToast;
+    cache?: UiCache;
 }
 /** Tells CheckCourt to show no card for this subject and viewer; on an action, removes the panel. */
 export interface UiHiddenDocument {
     ui: typeof UI_VERSION;
     hidden: true;
     toast?: UiToast;
+    cache?: UiCache;
 }
 /** Anything a declarative extension may answer with. */
 export type UiResponse = UiDocument | UiHiddenDocument;
+/** Longest badge label of a `court.annotation`. */
+export declare const ANNOTATION_LABEL_MAX = 24;
+/** Badges CheckCourt shows per court across all apps, by app name; the rest is not shown. */
+export declare const MAX_ANNOTATIONS_PER_COURT = 2;
+/** Longest `column.title` of a `member.list.column`. */
+export declare const COLUMN_TITLE_MAX = 20;
+/** Longest cell text of a `member.list.column`. */
+export declare const COLUMN_TEXT_MAX = 24;
+/** App columns CheckCourt shows on the member list, by app name. */
+export declare const MAX_APP_COLUMNS = 2;
+/** App entries CheckCourt shows in the sidebar, by app name. */
+export declare const MAX_SIDEBAR_ACTIONS = 2;
+/** CheckCourt waits this long for a `booking.hint` answer, then shows nothing. */
+export declare const BOOKING_HINT_TIMEOUT_MS = 1000;
+/** Block types a `booking.hint` document may contain, top level only. */
+export declare const BOOKING_HINT_BLOCKS: readonly ["text", "badge", "key_value", "link"];
+export declare const MAX_HINT_BLOCKS = 6;
+/** Apps whose hints CheckCourt shows in the booking dialog, by app name. */
+export declare const MAX_BOOKING_HINTS = 2;
+/** One badge in a court header of the booking plan. */
+export interface CourtAnnotation {
+    court_id: number;
+    /** 1 to 24 characters. */
+    label: string;
+    variant?: BadgeVariant;
+}
+/** The answer to `court.annotation`: at most one annotation per court. */
+export interface AnnotationsDocument {
+    ui: typeof UI_VERSION;
+    annotations: CourtAnnotation[];
+    cache?: UiCache;
+}
+/** One cell of an app column on the member list; a badge when `variant` is set, plain text otherwise. */
+export interface ColumnValue {
+    member_id: string;
+    /** 1 to 24 characters. */
+    text: string;
+    variant?: BadgeVariant;
+}
+/** The answer to `member.list.column`: at most one value per member. */
+export interface ColumnDocument {
+    ui: typeof UI_VERSION;
+    column: {
+        title: string;
+        values: ColumnValue[];
+    };
+    cache?: UiCache;
+}
+export type UiHintBlock = UiTextBlock | UiBadgeBlock | UiKeyValueBlock | UiLinkBlock;
+/** The answer to `booking.hint`: display-only blocks; toasts are ignored. */
+export interface UiHintDocument extends UiDocument {
+    blocks: UiHintBlock[];
+    toast?: never;
+}
+/** Options of `ui.annotations`, `ui.column` and `ui.hint`. */
+export interface UiSurfaceOptions {
+    /** Seconds CheckCourt may reuse this render, sent as `cache.max_age`; `0` disables caching. Capped at 300. */
+    maxAge?: number;
+}
 /** Values a submitted form sends back, keyed by field name. Empty optional fields are omitted. */
 export type UiFormValues = Record<string, string | number | boolean>;
 type Opt<T> = {
     [K in keyof T]?: T[K];
 };
+/** Options shared by `ui.doc` and `ui.hidden`. */
+export interface UiDocumentOptions {
+    toast?: UiToast;
+    /** Seconds CheckCourt may reuse this render, sent as `cache.max_age`; `0` disables caching. Capped at 300. */
+    maxAge?: number;
+}
 /**
  * Builds `ui: "v1"` documents. Strings are plain text (no HTML, no Markdown); CheckCourt
  * renders them with its own design system.
  */
 export declare const ui: {
-    readonly doc: (blocks: UiBlock[], options?: {
-        toast?: UiToast;
-    }) => UiDocument;
+    readonly doc: (blocks: UiBlock[], options?: UiDocumentOptions) => UiDocument;
+    /**
+     * The answer to `court.annotation`: badges for some of the requested courts, at most one per
+     * court. Throws on a label outside 1 to 24 characters or a court listed twice.
+     */
+    readonly annotations: (annotations: CourtAnnotation[], options?: UiSurfaceOptions) => AnnotationsDocument;
+    /**
+     * The answer to `member.list.column`: a title and one value per member you have something for.
+     * Throws on a title over 20 or a text over 24 characters, or a member listed twice.
+     */
+    readonly column: (column: {
+        title: string;
+        values: ColumnValue[];
+    }, options?: UiSurfaceOptions) => ColumnDocument;
+    /**
+     * The answer to `booking.hint`: at most 6 text, badge, key_value or link blocks. Throws on any
+     * other block, which CheckCourt would reject together with the whole hint.
+     */
+    readonly hint: (blocks: UiHintBlock[], options?: UiSurfaceOptions) => UiHintDocument;
     /** Nothing relevant here: no card at all. Answering `204 No Content` does the same. */
-    readonly hidden: (options?: {
-        toast?: UiToast;
-    }) => UiHiddenDocument;
+    readonly hidden: (options?: UiDocumentOptions) => UiHiddenDocument;
     readonly text: (text: string, options?: {
         tone?: "muted";
     }) => UiTextBlock;

package/dist/ui.js

@@ -4,6 +4,29 @@ export const MAX_UI_BLOCKS = 50;
 export const MAX_UI_DEPTH = 3;
 export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive"];
 export const BUTTON_VARIANTS = ["default", "secondary", "outline", "destructive"];
+/** CheckCourt caps every render lifetime at this many seconds. */
+export const UI_CACHE_MAX_AGE_LIMIT = 300;
+/** Longest badge label of a `court.annotation`. */
+export const ANNOTATION_LABEL_MAX = 24;
+/** Badges CheckCourt shows per court across all apps, by app name; the rest is not shown. */
+export const MAX_ANNOTATIONS_PER_COURT = 2;
+/** Longest `column.title` of a `member.list.column`. */
+export const COLUMN_TITLE_MAX = 20;
+/** Longest cell text of a `member.list.column`. */
+export const COLUMN_TEXT_MAX = 24;
+/** App columns CheckCourt shows on the member list, by app name. */
+export const MAX_APP_COLUMNS = 2;
+/** App entries CheckCourt shows in the sidebar, by app name. */
+export const MAX_SIDEBAR_ACTIONS = 2;
+/** CheckCourt waits this long for a `booking.hint` answer, then shows nothing. */
+export const BOOKING_HINT_TIMEOUT_MS = 1000;
+/** Block types a `booking.hint` document may contain, top level only. */
+export const BOOKING_HINT_BLOCKS = ["text", "badge", "key_value", "link"];
+export const MAX_HINT_BLOCKS = 6;
+/** Apps whose hints CheckCourt shows in the booking dialog, by app name. */
+export const MAX_BOOKING_HINTS = 2;
+/** Annotations or column values one document may carry. */
+const MAX_SURFACE_ENTRIES = 200;
 const field = {
     text(name, label, options = {}) {
         return { type: "text", name, label, ...options };
@@ -21,17 +44,111 @@ const field = {
 function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
 }
+function cacheOf(maxAge) {
+    if (maxAge === undefined)
+        return undefined;
+    if (!Number.isInteger(maxAge) || maxAge < 0) {
+        throw new RangeError(`maxAge must be a whole number of seconds >= 0, got ${maxAge}`);
+    }
+    return { max_age: maxAge };
+}
+function shortText(value, max, what) {
+    if (typeof value !== "string")
+        throw new TypeError(`${what} must be a string`);
+    const text = value.trim();
+    if (text.length < 1 || text.length > max) {
+        throw new RangeError(`${what} must be 1 to ${max} characters, got ${text.length}`);
+    }
+    return text;
+}
+function variantOf(variant, what) {
+    if (variant === undefined)
+        return undefined;
+    if (!BADGE_VARIANTS.includes(variant)) {
+        throw new TypeError(`${what} must be one of ${BADGE_VARIANTS.join(", ")}`);
+    }
+    return variant;
+}
+function entriesOf(list, what) {
+    if (!Array.isArray(list))
+        throw new TypeError(`${what} must be an array`);
+    if (list.length > MAX_SURFACE_ENTRIES)
+        throw new RangeError(`${what}: at most ${MAX_SURFACE_ENTRIES} entries`);
+    return list;
+}
 /**
  * Builds `ui: "v1"` documents. Strings are plain text (no HTML, no Markdown); CheckCourt
  * renders them with its own design system.
  */
 export const ui = {
     doc(blocks, options = {}) {
-        return compact({ ui: UI_VERSION, blocks, toast: options.toast });
+        return compact({ ui: UI_VERSION, blocks, toast: options.toast, cache: cacheOf(options.maxAge) });
+    },
+    /**
+     * The answer to `court.annotation`: badges for some of the requested courts, at most one per
+     * court. Throws on a label outside 1 to 24 characters or a court listed twice.
+     */
+    annotations(annotations, options = {}) {
+        const seen = new Set();
+        const list = entriesOf(annotations, "annotations").map((a, i) => {
+            if (!Number.isInteger(a.court_id) || a.court_id <= 0) {
+                throw new TypeError(`annotations[${i}].court_id must be a positive integer`);
+            }
+            if (seen.has(a.court_id))
+                throw new RangeError(`annotations: court ${a.court_id} appears twice`);
+            seen.add(a.court_id);
+            return compact({
+                court_id: a.court_id,
+                label: shortText(a.label, ANNOTATION_LABEL_MAX, `annotations[${i}].label`),
+                variant: variantOf(a.variant, `annotations[${i}].variant`),
+            });
+        });
+        return compact({ ui: UI_VERSION, annotations: list, cache: cacheOf(options.maxAge) });
+    },
+    /**
+     * The answer to `member.list.column`: a title and one value per member you have something for.
+     * Throws on a title over 20 or a text over 24 characters, or a member listed twice.
+     */
+    column(column, options = {}) {
+        const seen = new Set();
+        const values = entriesOf(column.values, "column.values").map((v, i) => {
+            if (typeof v.member_id !== "string" || v.member_id.length < 1 || v.member_id.length > 100) {
+                throw new TypeError(`column.values[${i}].member_id must be a member id`);
+            }
+            if (seen.has(v.member_id))
+                throw new RangeError(`column.values: member ${v.member_id} appears twice`);
+            seen.add(v.member_id);
+            return compact({
+                member_id: v.member_id,
+                text: shortText(v.text, COLUMN_TEXT_MAX, `column.values[${i}].text`),
+                variant: variantOf(v.variant, `column.values[${i}].variant`),
+            });
+        });
+        return compact({
+            ui: UI_VERSION,
+            column: { title: shortText(column.title, COLUMN_TITLE_MAX, "column.title"), values },
+            cache: cacheOf(options.maxAge),
+        });
+    },
+    /**
+     * The answer to `booking.hint`: at most 6 text, badge, key_value or link blocks. Throws on any
+     * other block, which CheckCourt would reject together with the whole hint.
+     */
+    hint(blocks, options = {}) {
+        if (!Array.isArray(blocks))
+            throw new TypeError("blocks must be an array");
+        if (blocks.length > MAX_HINT_BLOCKS)
+            throw new RangeError(`booking.hint: at most ${MAX_HINT_BLOCKS} blocks`);
+        for (const [i, block] of blocks.entries()) {
+            if (!BOOKING_HINT_BLOCKS.includes(block.type)) {
+                throw new TypeError(`blocks[${i}]: ${block.type} is not allowed in booking.hint`);
+            }
+        }
+        return compact({ ui: UI_VERSION, blocks, cache: cacheOf(options.maxAge) });
     },
     /** Nothing relevant here: no card at all. Answering `204 No Content` does the same. */
     hidden(options = {}) {
-        return compact({ ui: UI_VERSION, hidden: true, toast: options.toast });
+        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 });

package/dist/webhooks.d.ts

@@ -1,6 +1,6 @@
 import type { WebhookEvent } from "./events.js";
-export type { AppLifecycleEventData, BookingEventData, CourtLockEventData, EventDataMap, EventObjectType, EventType, MemberEventData, SubscribableEventType, AppLifecycleEventType, WebhookEvent, WebhookEventOf, } from "./events.js";
-export { APP_LIFECYCLE_EVENT_TYPES, EVENT_TYPES, SUBSCRIBABLE_EVENT_TYPES } from "./events.js";
+export type { AppEvent, AppEventType, AppMetadataChangedEvent, AppMetadataChangedEventData, ConnectionEvent, AppLifecycleEventData, BookingEventData, CourtLockEventData, EventDataMap, EventObjectType, EventType, MemberEventData, SubscribableEventType, AppLifecycleEventType, WebhookEvent, WebhookEventOf, } from "./events.js";
+export { APP_LIFECYCLE_EVENT_TYPES, EVENT_TYPES, METADATA_CHANGED_EVENT_TYPE, SUBSCRIBABLE_EVENT_TYPES, appEventType, isAppEvent, isMetadataChangedEvent, } from "./events.js";
 export { WebhookSignatureError, type WebhookSignatureFailure } from "./errors.js";
 export declare const SIGNATURE_HEADER = "CheckCourt-Signature";
 export declare const EVENT_ID_HEADER = "CheckCourt-Event-Id";

package/dist/webhooks.js

@@ -1,7 +1,7 @@
 import { WebhookSignatureError } from "./errors.js";
 import { decodeUtf8, hexDecode, hexEncode, toBytes, utf8 } from "./internal/encoding.js";
 import { hmacSha256, hmacSha256Verify } from "./internal/hmac.js";
-export { APP_LIFECYCLE_EVENT_TYPES, EVENT_TYPES, SUBSCRIBABLE_EVENT_TYPES } from "./events.js";
+export { APP_LIFECYCLE_EVENT_TYPES, EVENT_TYPES, METADATA_CHANGED_EVENT_TYPE, SUBSCRIBABLE_EVENT_TYPES, appEventType, isAppEvent, isMetadataChangedEvent, } from "./events.js";
 export { WebhookSignatureError } from "./errors.js";
 export const SIGNATURE_HEADER = "CheckCourt-Signature";
 export const EVENT_ID_HEADER = "CheckCourt-Event-Id";

package/package.json

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