@checkcourt/sdk 0.0.0-stage → 0.3.1

package/dist/errors.js

@@ -0,0 +1,123 @@
+// Symbol.for, not Symbol(): two copies of the SDK (route bundles, duplicate installs) must agree.
+const CHECKCOURT_ERROR_BRAND = Symbol.for("checkcourt.sdk.error");
+const kindBrand = (kind) => Symbol.for(`checkcourt.sdk.error.${kind}`);
+const KIND = Symbol.for("checkcourt.sdk.error.kind");
+function brand(error, kind) {
+    // Hard-coded because minifiers rename classes, so constructor.name is unreliable.
+    error.name = kind;
+    Object.defineProperty(error, CHECKCOURT_ERROR_BRAND, { value: true, configurable: true });
+    Object.defineProperty(error, kindBrand(kind), { value: true, configurable: true });
+}
+function hasBrand(value, kind) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[CHECKCOURT_ERROR_BRAND] === true &&
+        value[kindBrand(kind)] === true);
+}
+/**
+ * Base class for every error the SDK throws on purpose. `instanceof` works across copies of the
+ * SDK (it checks a brand, not the prototype); `isCheckCourtError(err, kind)` does the same as a function.
+ */
+export class CheckCourtError extends Error {
+    static [KIND] = "CheckCourtError";
+    static [Symbol.hasInstance](value) {
+        if (Function.prototype[Symbol.hasInstance].call(this, value))
+            return true;
+        // Only SDK classes declare their own kind; user subclasses fall back to the prototype check.
+        if (!Object.prototype.hasOwnProperty.call(this, KIND))
+            return false;
+        return hasBrand(value, this[KIND]);
+    }
+    constructor(message, options) {
+        super(message, options);
+        brand(this, "CheckCourtError");
+    }
+}
+/** A non-2xx answer from `/api/v1`. Branch on `code`; `message` is German and may change. */
+export class CheckCourtApiError extends CheckCourtError {
+    static [KIND] = "CheckCourtApiError";
+    status;
+    code;
+    response;
+    constructor(status, code, message, response) {
+        super(message);
+        brand(this, "CheckCourtApiError");
+        this.status = status;
+        this.code = code;
+        this.response = response;
+    }
+    static fromBody(status, body, response) {
+        const error = body?.error;
+        const code = typeof error?.code === "string" ? error.code : `HTTP_${status}`;
+        const message = typeof error?.message === "string" ? error.message : `HTTP ${status}`;
+        return new CheckCourtApiError(status, code, message, response);
+    }
+}
+/** An RFC 6749 error from `/api/oauth/*`, e.g. `invalid_client` or `slow_down`. */
+export class OAuthError extends CheckCourtError {
+    static [KIND] = "OAuthError";
+    status;
+    error;
+    description;
+    constructor(status, error, description) {
+        super(`${error}: ${description}`);
+        brand(this, "OAuthError");
+        this.status = status;
+        this.error = error;
+        this.description = description;
+    }
+}
+/**
+ * `invalid_grant`: the refresh token or code is dead (expired, revoked, reused, chain older than
+ * 180 days, member disconnected everywhere). Only a new authorization helps.
+ */
+export class TokenRevokedError extends OAuthError {
+    static [KIND] = "TokenRevokedError";
+    constructor(status, error, description) {
+        super(status, error, description);
+        brand(this, "TokenRevokedError");
+    }
+}
+/**
+ * `temporarily_unavailable` on refresh: the grant is still valid but nothing may run right now
+ * (connection paused, app suspended, account banned). The refresh token was not consumed.
+ */
+export class AppTemporarilyUnavailableError extends OAuthError {
+    static [KIND] = "AppTemporarilyUnavailableError";
+    constructor(status, error, description) {
+        super(status, error, description);
+        brand(this, "AppTemporarilyUnavailableError");
+    }
+}
+export function oauthErrorFrom(status, body) {
+    const b = (body ?? {});
+    const error = typeof b.error === "string" ? b.error : `http_${status}`;
+    const description = typeof b.error_description === "string" ? b.error_description : `HTTP ${status}`;
+    if (error === "invalid_grant")
+        return new TokenRevokedError(status, error, description);
+    if (error === "temporarily_unavailable")
+        return new AppTemporarilyUnavailableError(status, error, description);
+    return new OAuthError(status, error, description);
+}
+export class WebhookSignatureError extends CheckCourtError {
+    static [KIND] = "WebhookSignatureError";
+    reason;
+    constructor(reason, message) {
+        super(message);
+        brand(this, "WebhookSignatureError");
+        this.reason = reason;
+    }
+}
+export class ExtensionVerificationError extends CheckCourtError {
+    static [KIND] = "ExtensionVerificationError";
+    reason;
+    constructor(reason, message) {
+        super(message);
+        brand(this, "ExtensionVerificationError");
+        this.reason = reason;
+    }
+}
+/** True for errors from any copy of the SDK; with `kind`, also for that class or a subclass of it. */
+export function isCheckCourtError(error, kind) {
+    return hasBrand(error, kind ?? "CheckCourtError");
+}

package/dist/events.d.ts

@@ -0,0 +1,72 @@
+export interface BookingEventData {
+    booking_id: string;
+    court_id: number;
+    date: string;
+    start_time: string;
+    end_time: string;
+    type: string;
+}
+export interface MemberEventData {
+    member_id: string;
+    user_id: string;
+}
+/** `date`, `start_time` and `end_time` are null when the whole court is (un)locked. */
+export interface CourtLockEventData {
+    court_id: number;
+    date: string | null;
+    start_time: string | null;
+    end_time: string | null;
+}
+export interface AppLifecycleEventData {
+    installation_id: string;
+    app_id: string;
+    version: number;
+}
+/** Payloads are thin on purpose: ids and non-personal facts. Fetch details through the API. */
+export interface EventDataMap {
+    "booking.created": BookingEventData;
+    "booking.updated": BookingEventData;
+    "booking.cancelled": BookingEventData;
+    "booking.checked_in": BookingEventData;
+    "member.joined": MemberEventData;
+    "member.updated": MemberEventData & {
+        changed_fields: string[];
+    };
+    "member.left": MemberEventData;
+    "court.locked": CourtLockEventData;
+    "court.unlocked": CourtLockEventData;
+    "webhook.test": {
+        webhook_endpoint_id: string;
+    };
+    "app.installed": AppLifecycleEventData;
+    "app.uninstalled": AppLifecycleEventData;
+    "app.upgraded": AppLifecycleEventData;
+    /** The club changed the app's settings; read them with `getInstallation`. */
+    "app.settings_updated": AppLifecycleEventData;
+}
+export type EventType = keyof EventDataMap;
+/** Events a manifest may list under `events`. */
+export declare const SUBSCRIBABLE_EVENT_TYPES: readonly ["booking.created", "booking.updated", "booking.cancelled", "booking.checked_in", "member.joined", "member.updated", "member.left", "court.locked", "court.unlocked"];
+export type SubscribableEventType = (typeof SUBSCRIBABLE_EVENT_TYPES)[number];
+/** Delivered to the app they concern without being listed in the manifest. */
+export declare const APP_LIFECYCLE_EVENT_TYPES: readonly ["app.installed", "app.uninstalled", "app.upgraded", "app.settings_updated"];
+export type AppLifecycleEventType = (typeof APP_LIFECYCLE_EVENT_TYPES)[number];
+export declare const EVENT_TYPES: readonly ["booking.created", "booking.updated", "booking.cancelled", "booking.checked_in", "member.joined", "member.updated", "member.left", "court.locked", "court.unlocked", "webhook.test", "app.installed", "app.uninstalled", "app.upgraded", "app.settings_updated"];
+export type EventObjectType = "booking" | "court" | "member" | "webhook_endpoint" | "app_installation";
+export interface WebhookEventOf<T extends EventType> {
+    /** `evt_…`, stable across retries and equal to the `CheckCourt-Event-Id` header: deduplicate on it. */
+    id: string;
+    type: T;
+    created_at: string;
+    tenant_id: string;
+    /** Present on deliveries to an app installation. */
+    installation_id?: string;
+    object: {
+        type: EventObjectType | (string & {});
+        id: string;
+    };
+    data: EventDataMap[T];
+}
+export type WebhookEvent = {
+    [T in EventType]: WebhookEventOf<T>;
+}[EventType];

package/dist/events.js

@@ -0,0 +1,24 @@
+/** Events a manifest may list under `events`. */
+export const SUBSCRIBABLE_EVENT_TYPES = [
+    "booking.created",
+    "booking.updated",
+    "booking.cancelled",
+    "booking.checked_in",
+    "member.joined",
+    "member.updated",
+    "member.left",
+    "court.locked",
+    "court.unlocked",
+];
+/** Delivered to the app they concern without being listed in the manifest. */
+export const APP_LIFECYCLE_EVENT_TYPES = [
+    "app.installed",
+    "app.uninstalled",
+    "app.upgraded",
+    "app.settings_updated",
+];
+export const EVENT_TYPES = [
+    ...SUBSCRIBABLE_EVENT_TYPES,
+    "webhook.test",
+    ...APP_LIFECYCLE_EVENT_TYPES,
+];

package/dist/extensions.d.ts

@@ -0,0 +1,124 @@
+import type { ExtensionPoint } from "./manifest.js";
+import type { UiFormValues } from "./ui.js";
+import { type RawBody } from "./webhooks.js";
+export * from "./ui.js";
+export { ExtensionVerificationError, type ExtensionVerificationFailure } from "./errors.js";
+export { EXTENSION_POINTS, type ExtensionKind, type ExtensionPoint } from "./manifest.js";
+export declare const CONTEXT_HEADER = "CheckCourt-Context";
+export declare const CONTEXT_ISSUER = "checkcourt";
+export declare const CONTEXT_TTL_SECONDS = 300;
+export declare const CLOCK_LEEWAY_SECONDS = 30;
+/** `action_id` a `booking.action` button sends when it is clicked. */
+export declare const BOOKING_ACTION_INVOKE = "invoke";
+export type ExtensionSubjectType = "booking" | "member" | "installation";
+export interface ExtensionSubject {
+    type: ExtensionSubjectType;
+    id: string;
+}
+export interface BookingCapabilities {
+    is_booker: boolean;
+    can_edit_bookings: boolean;
+    can_cancel_foreign_bookings: boolean;
+    can_see_booking_details: boolean;
+}
+export interface MemberCapabilities {
+    is_self: boolean;
+    can_see_member_details: boolean;
+    can_edit_members: boolean;
+}
+export interface DashboardCapabilities {
+    can_book: boolean;
+    can_manage_club: boolean;
+}
+export interface AppSettingsCapabilities {
+    can_manage_app: boolean;
+}
+export interface PointCapabilities {
+    "app.settings": AppSettingsCapabilities;
+    "booking.detail.panel": BookingCapabilities;
+    "booking.action": BookingCapabilities;
+    "member.profile.section": MemberCapabilities;
+    "dashboard.widget": DashboardCapabilities;
+    "kiosk.tile": Record<string, never>;
+}
+export interface PointSubject {
+    "app.settings": {
+        type: "installation";
+        id: string;
+    };
+    "booking.detail.panel": {
+        type: "booking";
+        id: string;
+    };
+    "booking.action": {
+        type: "booking";
+        id: string;
+    };
+    "member.profile.section": {
+        type: "member";
+        id: string;
+    };
+    "dashboard.widget": null;
+    "kiosk.tile": null;
+}
+interface ContextClaimsOf<P extends ExtensionPoint> {
+    iss: typeof CONTEXT_ISSUER;
+    installation_id: string;
+    /** "user": a member's own connection; `viewer.user_id` is then always that member. */
+    installation_kind: "tenant" | "user";
+    app_id: string;
+    tenant_id: string;
+    point: P;
+    subject: PointSubject[P];
+    viewer: {
+        /** null on the kiosk; a stable `psn_…` pseudonym unless the installation holds `members:read`. */
+        user_id: string | null;
+        capabilities: PointCapabilities[P];
+    };
+    iat: number;
+    exp: number;
+    nonce: string;
+}
+/** Claims of a verified context token, narrowed by `point`. */
+export type ExtensionContextClaims = {
+    [P in ExtensionPoint]: ContextClaimsOf<P>;
+}[ExtensionPoint];
+/**
+ * Verifies the context token (HS256 JWT keyed with the whole `whsec_…` secret): signature,
+ * `iss`, `iat` and `exp` with 30 s clock leeway, exactly as CheckCourt does. Throws
+ * `ExtensionVerificationError`. Then compare `installation_id` and `tenant_id` with what you
+ * stored from `app.installed`.
+ */
+export declare function verifyExtensionContext(token: string, secret: string, options?: {
+    now?: Date | number;
+}): Promise<ExtensionContextClaims>;
+/** Body of a declarative render request. */
+export interface ExtensionRenderRequest {
+    kind: "render";
+    context: ExtensionContextClaims;
+    point: ExtensionPoint;
+    subject: ExtensionSubject | null;
+}
+/** Body of a button click or form submission. `values` is `{}` for buttons. */
+export interface ExtensionActionRequest {
+    kind: "action";
+    context: ExtensionContextClaims;
+    point: ExtensionPoint;
+    subject: ExtensionSubject | null;
+    actionId: string;
+    values: UiFormValues;
+}
+export type ExtensionRequest = ExtensionRenderRequest | ExtensionActionRequest;
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Verifies a declarative extension POST: the `CheckCourt-Signature` over the raw body (it binds
+ * `action_id` and `values` to the token), the context token, and that body, header token and
+ * claims agree. Throws `ExtensionVerificationError`.
+ */
+export declare function verifyExtensionRequest(options: {
+    secret: string;
+    rawBody: RawBody;
+    headers: HeaderSource;
+    toleranceSeconds?: number;
+    now?: Date | number;
+}): Promise<ExtensionRequest>;

package/dist/extensions.js

@@ -0,0 +1,138 @@
+import { ExtensionVerificationError, WebhookSignatureError } from "./errors.js";
+import { base64UrlDecode, decodeUtf8, toBytes, utf8 } from "./internal/encoding.js";
+import { hmacSha256Verify } from "./internal/hmac.js";
+import { SIGNATURE_HEADER, verifySignature } from "./webhooks.js";
+export * from "./ui.js";
+export { ExtensionVerificationError } from "./errors.js";
+export { EXTENSION_POINTS } from "./manifest.js";
+export const CONTEXT_HEADER = "CheckCourt-Context";
+export const CONTEXT_ISSUER = "checkcourt";
+export const CONTEXT_TTL_SECONDS = 300;
+export const CLOCK_LEEWAY_SECONDS = 30;
+/** `action_id` a `booking.action` button sends when it is clicked. */
+export const BOOKING_ACTION_INVOKE = "invoke";
+const MAX_TOKEN_LENGTH = 8192;
+function unixSeconds(now) {
+    if (now === undefined)
+        return Math.floor(Date.now() / 1000);
+    return now instanceof Date ? Math.floor(now.getTime() / 1000) : Math.floor(now);
+}
+function decodeJson(part) {
+    const bytes = base64UrlDecode(part);
+    if (!bytes)
+        return null;
+    try {
+        return JSON.parse(decodeUtf8(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+const fail = (reason, message) => new ExtensionVerificationError(reason, message);
+/**
+ * Verifies the context token (HS256 JWT keyed with the whole `whsec_…` secret): signature,
+ * `iss`, `iat` and `exp` with 30 s clock leeway, exactly as CheckCourt does. Throws
+ * `ExtensionVerificationError`. Then compare `installation_id` and `tenant_id` with what you
+ * stored from `app.installed`.
+ */
+export async function verifyExtensionContext(token, secret, options = {}) {
+    if (typeof token !== "string" || token.length > MAX_TOKEN_LENGTH)
+        throw fail("malformed_token", "Token is not a string or too long");
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some((p) => !/^[A-Za-z0-9_-]+$/.test(p))) {
+        throw fail("malformed_token", "Token is not a compact JWT");
+    }
+    const [headerPart, payloadPart, signaturePart] = parts;
+    const header = decodeJson(headerPart);
+    if (!header || header.alg !== "HS256")
+        throw fail("unsupported_algorithm", "Only HS256 is accepted");
+    const signature = base64UrlDecode(signaturePart);
+    if (!signature || !(await hmacSha256Verify(secret, utf8(`${headerPart}.${payloadPart}`), signature))) {
+        throw fail("invalid_signature", "Token signature does not match");
+    }
+    const claims = decodeJson(payloadPart);
+    if (!claims || typeof claims !== "object")
+        throw fail("invalid_claims", "Token payload is not an object");
+    if (claims.iss !== CONTEXT_ISSUER)
+        throw fail("invalid_claims", "Token issuer is not checkcourt");
+    if (typeof claims.iat !== "number" || typeof claims.exp !== "number") {
+        throw fail("invalid_claims", "Token has no iat or exp");
+    }
+    const now = unixSeconds(options.now);
+    if (claims.iat > now + CLOCK_LEEWAY_SECONDS)
+        throw fail("not_yet_valid", "Token was issued in the future");
+    if (claims.exp < now - CLOCK_LEEWAY_SECONDS)
+        throw fail("expired", "Token has expired");
+    return claims;
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower)
+            return Array.isArray(value) ? value[0] : value;
+    }
+    return undefined;
+}
+function sameSubject(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.type === b.type && a.id === b.id;
+}
+/**
+ * Verifies a declarative extension POST: the `CheckCourt-Signature` over the raw body (it binds
+ * `action_id` and `values` to the token), the context token, and that body, header token and
+ * claims agree. Throws `ExtensionVerificationError`.
+ */
+export async function verifyExtensionRequest(options) {
+    try {
+        await verifySignature({
+            secret: options.secret,
+            rawBody: options.rawBody,
+            signatureHeader: header(options.headers, SIGNATURE_HEADER),
+            toleranceSeconds: options.toleranceSeconds,
+            now: options.now,
+        });
+    }
+    catch (err) {
+        if (err instanceof WebhookSignatureError)
+            throw fail("request_signature", err.message);
+        throw err;
+    }
+    let body;
+    try {
+        const raw = options.rawBody;
+        body = JSON.parse(typeof raw === "string" ? raw : decodeUtf8(toBytes(raw)));
+    }
+    catch {
+        throw fail("invalid_body", "Body is not valid JSON");
+    }
+    if (!body || typeof body !== "object" || typeof body.context !== "string") {
+        throw fail("invalid_body", "Body has no context");
+    }
+    const headerToken = header(options.headers, CONTEXT_HEADER);
+    if (headerToken !== undefined && headerToken !== body.context) {
+        throw fail("context_mismatch", `${CONTEXT_HEADER} differs from the body's context`);
+    }
+    const context = await verifyExtensionContext(body.context, options.secret, { now: options.now });
+    const subject = (body.subject ?? null);
+    if (body.point !== context.point || !sameSubject(subject, context.subject)) {
+        throw fail("context_mismatch", "point or subject differ from the context token");
+    }
+    if (body.action_id === undefined)
+        return { kind: "render", context, point: context.point, subject };
+    if (typeof body.action_id !== "string")
+        throw fail("invalid_body", "action_id is not a string");
+    const values = body.values ?? {};
+    if (typeof values !== "object" || Array.isArray(values))
+        throw fail("invalid_body", "values is not an object");
+    return {
+        kind: "action",
+        context,
+        point: context.point,
+        subject,
+        actionId: body.action_id,
+        values: values,
+    };
+}