@braintwopoint0/playback-commons 0.1.19 → 0.1.20

package/dist/playerdata/index.d.ts

@@ -0,0 +1,171 @@
+declare const PLAYERDATA_BASE_URL = "https://app.playerdata.co.uk";
+declare const PLAYERDATA_AUTH_URL = "https://app.playerdata.co.uk/api/oauth/authorize";
+declare const PLAYERDATA_TOKEN_URL = "https://app.playerdata.co.uk/api/oauth/token";
+declare const PLAYERDATA_GRAPHQL_URL = "https://app.playerdata.co.uk/api/graphql";
+
+interface PlayerDataCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+interface PlayerDataTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+}
+interface PlayerDataToken {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+interface GraphQLResponse<T = unknown> {
+    data?: T;
+    errors?: GraphQLError[];
+}
+interface GraphQLError {
+    message: string;
+    locations?: {
+        line: number;
+        column: number;
+    }[];
+    path?: string[];
+    extensions?: Record<string, unknown>;
+}
+interface PDOrganisation {
+    id: string;
+    name: string;
+    clubs: PDClub[];
+}
+interface PDClub {
+    id: string;
+    name: string;
+    initials?: string;
+    sportDefinition?: PDSportDefinition;
+    athletes?: PDAthlete[];
+}
+interface PDSportDefinition {
+    id: string;
+    name: string;
+    positionDefinitions?: PDPositionDefinition[];
+}
+interface PDPositionDefinition {
+    id: string;
+    name: string;
+    initial?: string;
+}
+interface PDAthlete {
+    id: string;
+    name: string;
+    initials: string;
+    customId?: string;
+    topSpeedKph?: number;
+    autoTopSpeedKph?: number;
+    defaultPosition?: PDPositionDefinition;
+    profilePicture?: PDProfilePicture;
+}
+interface PDProfilePicture {
+    thumbnailUrl?: string;
+}
+interface PDPerson {
+    id: string;
+    name: string;
+    email?: string;
+    athletes?: PDAthlete[];
+    clubs?: PDClub[];
+}
+interface PDSessionBase {
+    id: string;
+    startTime?: string;
+    endTime?: string;
+    description?: string;
+    club?: {
+        id: string;
+        name: string;
+    };
+    sessionParticipations?: PDSessionParticipation[];
+}
+interface PDTrainingSession extends PDSessionBase {
+    __typename: 'TrainingSession';
+}
+interface PDMatchSession extends PDSessionBase {
+    __typename: 'MatchSession';
+    opponent?: string;
+    opponentScore?: number;
+    ourTeam: string;
+}
+type PDSession = PDTrainingSession | PDMatchSession;
+interface PDSessionParticipation {
+    id: string;
+    athlete: {
+        id: string;
+        name: string;
+        initials: string;
+    };
+    configuredMetrics?: PDConfiguredMetrics;
+}
+interface PDConfiguredMetrics {
+    data?: PDGenericMetric[];
+}
+interface PDConfiguredAggMetrics {
+    data?: PDGenericMetric[];
+}
+interface PDGenericMetric {
+    key: string;
+    label?: string;
+    shortLabel?: string;
+    localValue?: number | string | null;
+    localUnitLabel?: string;
+    category?: string;
+    precision?: number;
+}
+interface PDAthleteMetricsSummary {
+    athlete: {
+        id: string;
+        name: string;
+    };
+    configuredAggMetrics?: PDConfiguredAggMetrics;
+}
+
+/**
+ * Generate the OAuth authorization URL for user-level access.
+ * Redirect the user's browser to this URL to start the OAuth flow.
+ */
+declare function generateAuthUrl(credentials: PlayerDataCredentials, redirectUri: string, state?: string): string;
+/**
+ * Exchange an authorization code for access + refresh tokens.
+ * Used after the user is redirected back from PlayerData.
+ */
+declare function exchangeCode(credentials: PlayerDataCredentials, code: string, redirectUri: string): Promise<PlayerDataToken>;
+/**
+ * Refresh an expired access token using a refresh token.
+ * IMPORTANT: PlayerData refresh tokens are single-use.
+ * The response contains a NEW refresh token that must replace the old one.
+ */
+declare function refreshToken(credentials: PlayerDataCredentials, currentRefreshToken: string): Promise<PlayerDataToken>;
+/**
+ * Get a service-level token using client credentials grant.
+ * Used for org-wide data access without user interaction.
+ */
+declare function getServiceToken(credentials: PlayerDataCredentials): Promise<PlayerDataToken>;
+
+/** Verify auth and get the current user's identity */
+declare const GET_CURRENT_PERSON = "\n  query GetCurrentPerson {\n    currentPerson {\n      id\n      name\n      email\n      athletes {\n        id\n        name\n        club {\n          id\n          name\n        }\n      }\n      clubs {\n        id\n        name\n      }\n    }\n  }\n";
+/** Get club info and its athlete roster */
+declare const GET_CLUB = "\n  query GetClub($clubId: ID!) {\n    club(id: $clubId) {\n      id\n      name\n      sportDefinition {\n        id\n        name\n        positionDefinitions {\n          id\n          name\n          initial\n        }\n      }\n      athletes {\n        id\n        name\n        initials\n        customId\n        topSpeedKph\n        autoTopSpeedKph\n        defaultPosition {\n          id\n          name\n          initial\n        }\n        profilePicture {\n          thumbnailUrl\n        }\n      }\n    }\n  }\n";
+/** List sessions for a club with optional date filters */
+declare const GET_CLUB_SESSIONS = "\n  query GetClubSessions($clubId: ID!, $startTimeGteq: ISO8601DateTime, $startTimeLteq: ISO8601DateTime, $limit: Int, $offset: Int!) {\n    club(id: $clubId) {\n      id\n      sessions(\n        filter: { startTimeGteq: $startTimeGteq, startTimeLteq: $startTimeLteq }\n        limit: $limit\n        offset: $offset\n      ) {\n        id\n        startTime\n        endTime\n        description\n        ... on TrainingSession {\n          __typename\n        }\n        ... on MatchSession {\n          __typename\n          opponent\n          opponentScore\n          ourTeam\n        }\n      }\n    }\n  }\n";
+/** Get an athlete's sessions */
+declare const GET_ATHLETE_SESSIONS = "\n  query GetAthleteSessions($athleteId: ID!, $limit: Int, $offset: Int) {\n    athlete(id: $athleteId) {\n      id\n      name\n      sessions(limit: $limit, offset: $offset) {\n        id\n        startTime\n        endTime\n        description\n        ... on TrainingSession {\n          __typename\n        }\n        ... on MatchSession {\n          __typename\n          opponent\n          opponentScore\n          ourTeam\n        }\n      }\n    }\n  }\n";
+/** Get a session with per-athlete metrics via participations */
+declare const GET_SESSION_DETAILS = "\n  query GetSessionDetails($sessionId: ID!) {\n    session(id: $sessionId) {\n      id\n      startTime\n      endTime\n      description\n      club {\n        id\n        name\n      }\n      ... on TrainingSession {\n        __typename\n        sessionParticipations {\n          id\n          athlete {\n            id\n            name\n            initials\n          }\n          configuredMetrics {\n            data {\n              key\n              label\n              shortLabel\n              localValue\n              localUnitLabel\n              category\n              precision\n            }\n          }\n        }\n      }\n      ... on MatchSession {\n        __typename\n        opponent\n        opponentScore\n        ourTeam\n        sessionParticipations {\n          id\n          athlete {\n            id\n            name\n            initials\n          }\n          configuredMetrics {\n            data {\n              key\n              label\n              shortLabel\n              localValue\n              localUnitLabel\n              category\n              precision\n            }\n          }\n        }\n      }\n    }\n  }\n";
+/** Get aggregated metrics for an athlete over a date range */
+declare const GET_ATHLETE_SUMMARY = "\n  query GetAthleteSummary($athleteId: ID!, $startTime: ISO8601DateTime!, $endTime: ISO8601DateTime) {\n    athlete(id: $athleteId) {\n      id\n      name\n      timeSafeMetricsSummary(startTime: $startTime, endTime: $endTime) {\n        athlete {\n          id\n          name\n        }\n        configuredAggMetrics {\n          data {\n            key\n            label\n            shortLabel\n            localValue\n            localUnitLabel\n            category\n            precision\n          }\n        }\n      }\n    }\n  }\n";
+
+/**
+ * Execute a GraphQL query against the PlayerData API.
+ * Stateless — caller provides the access token.
+ */
+declare function executeQuery<T = unknown>(token: string, query: string, variables?: Record<string, unknown>): Promise<T>;
+
+export { GET_ATHLETE_SESSIONS, GET_ATHLETE_SUMMARY, GET_CLUB, GET_CLUB_SESSIONS, GET_CURRENT_PERSON, GET_SESSION_DETAILS, type GraphQLError, type GraphQLResponse, type PDAthlete, type PDAthleteMetricsSummary, type PDClub, type PDConfiguredAggMetrics, type PDConfiguredMetrics, type PDGenericMetric, type PDMatchSession, type PDOrganisation, type PDPerson, type PDPositionDefinition, type PDProfilePicture, type PDSession, type PDSessionBase, type PDSessionParticipation, type PDSportDefinition, type PDTrainingSession, PLAYERDATA_AUTH_URL, PLAYERDATA_BASE_URL, PLAYERDATA_GRAPHQL_URL, PLAYERDATA_TOKEN_URL, type PlayerDataCredentials, type PlayerDataToken, type PlayerDataTokenResponse, exchangeCode, executeQuery, generateAuthUrl, getServiceToken, refreshToken };

package/dist/security/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sanitize a redirect path to prevent open redirect attacks.
+ * Returns '/' if the path is unsafe.
+ */
+declare function sanitizeRedirect(raw: string | null | undefined): string;
+/**
+ * Escape HTML special characters to prevent injection in templates.
+ */
+declare function escapeHtml(s: string): string;
+
+/**
+ * Verify an API key from a request header using timing-safe comparison.
+ * Prevents timing side-channel attacks on key verification.
+ *
+ * @param request - The incoming request
+ * @param expectedKey - The expected API key value
+ * @param headerName - The header to read (default: 'x-api-key')
+ */
+declare function verifyApiKey(request: Request, expectedKey: string, headerName?: string): boolean;
+
+export { escapeHtml, sanitizeRedirect, verifyApiKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braintwopoint0/playback-commons",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Shared UI components, auth utilities, and Supabase client for the PLAYBACK Sports ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "fonts"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "test": "vitest run"
   },