@globalscoutme/api-client 1.1.29 → 1.2.1

package/README.md

@@ -1,303 +1,334 @@
-# @globalscoutme/api-client
-
-Auto-generated TypeScript HTTP client for the GlobalScoutMe API, built with [`@hey-api/openapi-ts`](https://heyapi.dev/) and axios.
-
-## Install
-
-```bash
-npm install @globalscoutme/api-client
-```
-
-## Setup
-
-Configure the client once at app startup with your API base URL and auth token:
-
-```ts
-import { client } from '@globalscoutme/api-client';
-
-client.setConfig({
-  baseURL: 'https://your-api-url.com',
-  headers: {
-    Authorization: `Bearer ${yourSupabaseAccessToken}`,
-  },
-});
-```
-
-## Usage
-
-All endpoints are grouped by controller and fully typed:
-
-```ts
-import {
-  Auth,
-  Dashboard,
-  Players,
-  Profile,
-  Documents,
-  Videos,
-  Achievements,
-  Body,
-  Index,
-  Kyc,
-  Offers,
-  Organizations,
-  Clubs,
-  Challenges,
-  Training,
-  Invitations,
-  Storage,
-  Subscriptions,
-} from '@globalscoutme/api-client';
-
-// Auth
-const authMe = await Auth.getAuthMe();
-// Returns { id: string, userType: string | null, orgRole: 'admin' | 'user' | null }
-// orgRole is the caller's organization_members role (club_admin/scouter only); null for player/coach
-
-// Players
-const player = await Players.getMe();
-await Players.patchMe({ body: { fullName: 'John Doe' } });
-await Players.deleteMe();
-const dashboard = await Players.getMyDashboard();
-await Players.heartbeat({ body: { timezone: 'Europe/Bucharest' } });
-const results = await Players.searchPlayers({
-  body: {
-    search: 'John',
-    page: 1,
-    pageSize: 20,
-    sortBy: 'age_asc',
-    nationalities: ['EG', 'MA'],
-    positions: ['CM', 'CB'],
-    baseFoot: 'right',
-    isFreeAgent: true,
-    hasVideo: true,
-    heightOperator: 'gte',
-    heightCm: 180,
-  },
-});
-const playerProfile = await Players.getPlayerById({
-  path: { id: 'player-uuid' },
-});
-const playerMeasurements = await Players.getPlayerMeasurementProfile({
-  path: { id: 'player-uuid' },
-});
-// Returns { status, body, cmj, session, updatedAt } — accessible to all roles (no player-only restriction)
-// status: 'missing' | 'partial' | 'ready' | 'needs_update'
-const playerVideoMetrics = await Players.getPlayerVideoMetrics({
-  path: { id: 'player-uuid' },
-});
-// Returns { id, createdAt, videoDurationS, physicalMetrics, trackingQuality, trackedFrames, totalFrames }
-// physicalMetrics: { totalDistance, sprintDistance, maxSpeed, averageSpeed, highIntensityRuns, sprints }
-// Speed/distance values are strings with units already included (e.g. "31.0 km/h", "21.4 m")
-// trackingQuality: confidence label from the analysis service (e.g. "High Confidence") — null if unavailable
-// Returns 404 if the player has no completed video analysis yet
-const playerReport = await Players.getPlayerReport({
-  path: { id: 'player-uuid' },
-});
-// Returns { reportReferenceId, generatedAt, scouterView: { technicalPillar, physicalPillar, tacticalPillar, mentalPillar } }
-// Returns 404 if the player has no completed AI report yet
-
-// Profile
-const profile = await Profile.getProfileMe();
-await Profile.updateProfileMe({ body: { dominantFoot: 'Right' } });
-
-// Documents
-const docs = await Documents.getMyDocuments();
-await Documents.createDocument({ body: { type: 'license' } });
-
-// Videos
-const videos = await Videos.getMyVideos();
-await Videos.createVideo({
-  body: { type: 'cmj', storagePath: 'path/to/video' },
-});
-const playUrl = await Videos.getVideoPlayUrl({ path: { id: 'video-uuid' } });
-await Videos.deleteVideo({ path: { id: 'video-uuid' } });
-
-// Achievements
-const catalog = await Achievements.getAchievementsCatalog();
-const myAchievements = await Achievements.getMyAchievements();
-
-// Body measurements
-const measurement = await Body.getMyMeasurements();
-await Body.createMeasurement({ body: { heightCm: 180 } });
-
-// Index (lookup tables)
-const positions = await Index.getIndexItems({
-  path: { tableName: 'positions' },
-});
-const countries = await Index.getCountries();
-// Returns [{ code: 'BR', name: 'Brazil', nationalityName: 'Brazilian', flagEmoji: '🇧🇷' }, ...]
-
-// Dashboard (scout/club portal — single aggregated call)
-const dashboard = await Dashboard.getScoutDashboard();
-// Returns: stats (watchlisted, offersSent, playersViewed, videosWatched),
-//          lastPlayersViewed (last 6 distinct players),
-//          lastVideosWatched (last 6 distinct videos with player info)
-
-const videoUrl = await Dashboard.getScoutVideoPlayUrl({
-  path: { id: 'video-uuid' },
-});
-// Returns signed play URL + records the view in video_views
-
-// Offers (conversations between scouts and players)
-const conversations = await Offers.listConversations({
-  query: { filter: 'all', page: 1, pageSize: 20 },
-});
-const conversation = await Offers.createConversation({
-  body: { playerId: 'player-uuid', initialMessage: 'Hi!' },
-});
-const messages = await Offers.listMessages({
-  path: { id: 'conversation-uuid' },
-  query: { page: 1, pageSize: 20 },
-});
-await Offers.sendMessage({
-  path: { id: 'conversation-uuid' },
-  body: { body: 'Looking forward to it!' },
-});
-await Offers.markConversationRead({ path: { id: 'conversation-uuid' } });
-
-// Organizations
-const org = await Organizations.getMyOrganization();
-await Organizations.updateMyOrganization({ body: { name: 'FC Example' } });
-await Organizations.registerClub({
-  body: { name: 'FC Example', email: 'admin@example.com' },
-});
-
-// Clubs (coach/admin club entries within an organization)
-const clubs = await Clubs.getMyClubs();
-const club = await Clubs.createMyClub({ body: { name: 'U19 Team' } });
-await Clubs.updateMyClub({
-  path: { id: 'club-uuid' },
-  body: { name: 'U21 Team' },
-});
-await Clubs.deleteMyClub({ path: { id: 'club-uuid' } });
-
-// Challenges
-const challengeCatalog = await Challenges.getChallengesCatalog();
-const myChallenges = await Challenges.getMyChallenges();
-
-// Training
-const grouped = await Training.getTrainingGrouped();
-const trainingList = await Training.getTrainingList({
-  query: { categoryCode: 'fitness', page: 1, pageSize: 20 },
-});
-const trainingItem = await Training.getTrainingById({
-  path: { id: 'training-uuid' },
-});
-
-// Invitations (org admin invites members)
-await Invitations.sendInvitation({
-  body: { email: 'coach@example.com', role: 'coach' },
-});
-const invitations = await Invitations.listInvitations();
-await Invitations.resendInvitation({ path: { id: 'invitation-uuid' } });
-await Invitations.deleteInvitation({ path: { id: 'invitation-uuid' } });
-await Invitations.acceptInvitation(); // called after Supabase auth callback
-
-// KYC — SmileID Enhanced Document Verification
-//
-// Two integration options:
-
-// Option A — Smile Links (recommended for web)
-// Backend returns a hosted SmileID URL; redirect the user to it.
-// SmileID handles the full capture UI and fires the webhook when done.
-const linkResult = await Kyc.startSmileLink({
-  body: {
-    country: 'gh', // stored on the verification record; does NOT filter the SmileID dropdown
-    channel: 'web',
-    returnUrl: 'https://yourapp.com/onboarding/kyc/callback',
-  },
-});
-// linkResult: { url, jobId, status, retriesRemaining }
-// url is null when no redirect is needed (approved / blocked / processing).
-if (linkResult.data.url) {
-  window.location.href = linkResult.data.url; // redirect user to SmileID
-}
-// The SmileID hosted page shows all countries configured in index.kyc_supported_id_types.
-// The user selects their country and document type on that page.
-// After the user returns to returnUrl, poll getKycStatus to confirm the result.
-// markSubmittedKyc is NOT needed for Smile Links — SmileID fires the webhook directly.
-
-// Option B — SDK widget (embedded, for mobile / advanced web)
-const kycResult = await Kyc.startKyc({
-  body: { country: 'gh', channel: 'web' },
-});
-// kycResult: { token, partnerId, jobId, status, retriesRemaining }
-// Pass token + partnerId to the SmileID web SDK widget to start document capture.
-// After the SDK reports successful submission, call markSubmittedKyc with jobId.
-await Kyc.markSubmittedKyc({ body: { jobId: kycResult.data.jobId! } });
-// SmileID also calls POST /kyc/webhook under the configured API base/prefix
-// (for staging: https://staging.globalscoutme.com/api/kyc/webhook).
-
-const kycStatus = await Kyc.getKycStatus({
-  path: { userId: supabaseAuthUuid },
-});
-// kycStatus: { status, retryCount, retriesRemaining }
-// status: 'pending' | 'capture_started' | 'processing' | 'approved' | 'rejected' | 'blocked'
-// Older API clients may still see legacy 'in_progress', which maps to 'capture_started'.
-
-// QA/staging only — skip SmileID entirely and mark the current user KYC-approved.
-// Returns 403 outside test-like deployments (APP_ENV and NODE_ENV must both be non-production).
-const qaApproved = await Kyc.qaApproveKyc();
-// qaApproved: { jobId, status: 'approved', retryCount, retriesRemaining, country }
-
-// Subscriptions (Stripe recurring billing)
-const plans = await Subscriptions.getSubscriptionPlans();
-// Returns: { plans: [{ id, code, name, price, currency, billingInterval, trialDays, features, displayOrder }] }
-
-const mySubscription = await Subscriptions.getMySubscription();
-// Returns: { status, isActive, planId, planName, billingInterval,
-//            currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd, canceledAt, gracePeriodUntil }
-// status: 'inactive' when the user has never subscribed
-
-// Start a subscription — redirect the user to the returned URL
-const checkout = await Subscriptions.createCheckout({
-  body: {
-    providerProductId: 'billing-provider-products-uuid', // pick from billing_provider_products table
-    successUrl: 'https://yourapp.com/subscription/success', // or a mobile deep-link
-    cancelUrl: 'https://yourapp.com/subscription/cancel',
-  },
-});
-// redirect user to checkout.url
-
-// Open the Stripe Billing Portal (manage / cancel subscription)
-const portal = await Subscriptions.createPortal({
-  body: { returnUrl: 'https://yourapp.com/account' },
-});
-// redirect user to portal.url
-
-// Storage — get a signed upload URL, then PUT the file directly to Supabase Storage
-const { uploadUrl, token, path, bucket, expiresIn } = await Storage.createUploadUrl({
-  body: { bucket: 'avatars', contentType: 'image/jpeg', sizeBytes: 204800 },
-});
-await fetch(uploadUrl, {
-  method: 'PUT',
-  body: fileBlob,
-  headers: { 'Content-Type': 'image/jpeg' },
-});
-// persist `path` on the player record (e.g. patchMe with avatarPath: path)
-```
-
-## Updating auth token
-
-Update the Bearer token after sign-in or token refresh:
-
-```ts
-client.setConfig({
-  headers: {
-    Authorization: `Bearer ${newAccessToken}`,
-  },
-});
-```
-
-## Versioning
-
-This package is auto-generated from the backend OpenAPI spec. Version increments follow semver:
-
-- **patch** — no API shape changes
-- **minor** — new endpoints added
-- **major** — breaking changes (renamed/removed endpoints or fields)
-
-## Package format
-
-The published package ships compiled JavaScript (`dist/`) alongside the raw TypeScript source. `main` points to `dist/index.js` so all bundlers work without extra configuration.
+# @globalscoutme/api-client
+
+Auto-generated TypeScript HTTP client for the GlobalScoutMe API, built with [`@hey-api/openapi-ts`](https://heyapi.dev/) and axios.
+
+## Install
+
+```bash
+npm install @globalscoutme/api-client
+```
+
+## Setup
+
+Configure the client once at app startup with your API base URL and auth token:
+
+```ts
+import { client } from '@globalscoutme/api-client';
+
+client.setConfig({
+  baseURL: 'https://your-api-url.com',
+  headers: {
+    Authorization: `Bearer ${yourSupabaseAccessToken}`,
+  },
+});
+```
+
+## Usage
+
+All endpoints are grouped by controller and fully typed:
+
+```ts
+import {
+  Auth,
+  Dashboard,
+  Players,
+  GlobalChat,
+  Profile,
+  Documents,
+  Videos,
+  Achievements,
+  Body,
+  Index,
+  Kyc,
+  Offers,
+  Organizations,
+  Clubs,
+  Challenges,
+  Training,
+  Invitations,
+  Storage,
+  Subscriptions,
+} from '@globalscoutme/api-client';
+
+// Auth
+const authMe = await Auth.getAuthMe();
+// Returns { id: string, userType: string | null, orgRole: 'admin' | 'user' | null }
+// orgRole is the caller's organization_members role (club_admin/scouter only); null for player/coach
+
+// Players
+const player = await Players.getMe();
+await Players.patchMe({ body: { fullName: 'John Doe' } });
+await Players.deleteMe();
+const dashboard = await Players.getMyDashboard();
+await Players.heartbeat({ body: { timezone: 'Europe/Bucharest' } });
+const results = await Players.searchPlayers({
+  body: {
+    search: 'John',
+    page: 1,
+    pageSize: 20,
+    sortBy: 'age_asc',
+    nationalities: ['EG', 'MA'],
+    positions: ['CM', 'CB'],
+    baseFoot: 'right',
+    isFreeAgent: true,
+    hasVideo: true,
+    heightOperator: 'gte',
+    heightCm: 180,
+  },
+});
+const playerProfile = await Players.getPlayerById({
+  path: { id: 'player-uuid' },
+});
+const playerMeasurements = await Players.getPlayerMeasurementProfile({
+  path: { id: 'player-uuid' },
+});
+// Returns { status, body, cmj, session, updatedAt } — accessible to all roles (no player-only restriction)
+// status: 'missing' | 'partial' | 'ready' | 'needs_update'
+const playerVideoMetrics = await Players.getPlayerVideoMetrics({
+  path: { id: 'player-uuid' },
+});
+// Returns { id, createdAt, videoDurationS, physicalMetrics, trackingQuality, trackedFrames, totalFrames }
+// physicalMetrics: { totalDistance, sprintDistance, maxSpeed, averageSpeed, highIntensityRuns, sprints }
+// Speed/distance values are strings with units already included (e.g. "31.0 km/h", "21.4 m")
+// trackingQuality: confidence label from the analysis service (e.g. "High Confidence") — null if unavailable
+// Returns 404 if the player has no completed video analysis yet
+const playerReport = await Players.getPlayerReport({
+  path: { id: 'player-uuid' },
+});
+// Returns { reportReferenceId, generatedAt, scouterView: { technicalPillar, physicalPillar, tacticalPillar, mentalPillar } }
+// Returns 404 if the player has no completed AI report yet
+
+// Profile
+const profile = await Profile.getProfileMe();
+await Profile.updateProfileMe({ body: { dominantFoot: 'Right' } });
+
+// Documents
+const docs = await Documents.getMyDocuments();
+await Documents.createDocument({ body: { type: 'license' } });
+
+// Videos
+const videos = await Videos.getMyVideos();
+await Videos.createVideo({
+  body: { type: 'cmj', storagePath: 'path/to/video' },
+});
+const playUrl = await Videos.getVideoPlayUrl({ path: { id: 'video-uuid' } });
+await Videos.deleteVideo({ path: { id: 'video-uuid' } });
+
+// Achievements
+const catalog = await Achievements.getAchievementsCatalog();
+const myAchievements = await Achievements.getMyAchievements();
+
+// Body measurements
+const measurement = await Body.getMyMeasurements();
+await Body.createMeasurement({ body: { heightCm: 180 } });
+
+// Index (lookup tables)
+const positions = await Index.getIndexItems({
+  path: { tableName: 'positions' },
+});
+const countries = await Index.getCountries();
+// Returns [{ code: 'BR', name: 'Brazil', nationalityName: 'Brazilian', flagEmoji: '🇧🇷' }, ...]
+
+// Dashboard (scout/club portal — single aggregated call)
+const dashboard = await Dashboard.getScoutDashboard();
+// Returns: stats (watchlisted, offersSent, playersViewed, videosWatched),
+//          lastPlayersViewed (last 6 distinct players),
+//          lastVideosWatched (last 6 distinct videos with player info)
+
+const videoUrl = await Dashboard.getScoutVideoPlayUrl({
+  path: { id: 'video-uuid' },
+});
+// Returns signed play URL + records the view in video_views
+
+// Offers (conversations between scouts and players)
+const conversations = await Offers.listConversations({
+  query: { filter: 'all', page: 1, pageSize: 20 },
+});
+const conversation = await Offers.createConversation({
+  body: { playerId: 'player-uuid', initialMessage: 'Hi!' },
+});
+const messages = await Offers.listMessages({
+  path: { id: 'conversation-uuid' },
+  query: { page: 1, pageSize: 20 },
+});
+await Offers.sendMessage({
+  path: { id: 'conversation-uuid' },
+  body: { body: 'Looking forward to it!' },
+});
+await Offers.markConversationRead({ path: { id: 'conversation-uuid' } });
+
+// Community Chat
+const globalChat = new GlobalChat();
+const globalChatStatus = await globalChat.getGlobalChatStatus();
+await globalChat.joinGlobalChat({
+  body: {
+    acceptedRulesVersion: 1,
+    rulesLocale: 'en',
+    notificationsEnabled: false,
+  },
+});
+const globalChatMessages = await globalChat.listGlobalChatMessages({
+  query: { limit: 50 },
+});
+const sentGlobalChatMessage = await globalChat.sendGlobalChatMessage({
+  body: {
+    body: 'Hello, players!',
+    clientMessageId: '00000000-0000-4000-8000-000000000001',
+  },
+});
+await globalChat.markGlobalChatRead({
+  body: { messageId: sentGlobalChatMessage.data.id },
+});
+await globalChat.reportGlobalChatMessage({
+  path: { messageId: '00000000-0000-4000-8000-000000000002' },
+});
+await globalChat.updateGlobalChatNotifications({
+  body: { notificationsEnabled: true },
+});
+await globalChat.leaveGlobalChat();
+
+// Organizations
+const org = await Organizations.getMyOrganization();
+await Organizations.updateMyOrganization({ body: { name: 'FC Example' } });
+await Organizations.registerClub({
+  body: { name: 'FC Example', email: 'admin@example.com' },
+});
+
+// Clubs (coach/admin club entries within an organization)
+const clubs = await Clubs.getMyClubs();
+const club = await Clubs.createMyClub({ body: { name: 'U19 Team' } });
+await Clubs.updateMyClub({
+  path: { id: 'club-uuid' },
+  body: { name: 'U21 Team' },
+});
+await Clubs.deleteMyClub({ path: { id: 'club-uuid' } });
+
+// Challenges
+const challengeCatalog = await Challenges.getChallengesCatalog();
+const myChallenges = await Challenges.getMyChallenges();
+
+// Training
+const grouped = await Training.getTrainingGrouped();
+const trainingList = await Training.getTrainingList({
+  query: { categoryCode: 'fitness', page: 1, pageSize: 20 },
+});
+const trainingItem = await Training.getTrainingById({
+  path: { id: 'training-uuid' },
+});
+
+// Invitations (org admin invites members)
+await Invitations.sendInvitation({
+  body: { email: 'coach@example.com', role: 'coach' },
+});
+const invitations = await Invitations.listInvitations();
+await Invitations.resendInvitation({ path: { id: 'invitation-uuid' } });
+await Invitations.deleteInvitation({ path: { id: 'invitation-uuid' } });
+await Invitations.acceptInvitation(); // called after Supabase auth callback
+
+// KYC — SmileID Enhanced Document Verification
+//
+// Two integration options:
+
+// Option A — Smile Links (recommended for web)
+// Backend returns a hosted SmileID URL; redirect the user to it.
+// SmileID handles the full capture UI and fires the webhook when done.
+const linkResult = await Kyc.startSmileLink({
+  body: {
+    country: 'gh', // stored on the verification record; does NOT filter the SmileID dropdown
+    channel: 'web',
+    returnUrl: 'https://yourapp.com/onboarding/kyc/callback',
+  },
+});
+// linkResult: { url, jobId, status, retriesRemaining }
+// url is null when no redirect is needed (approved / blocked / processing).
+if (linkResult.data.url) {
+  window.location.href = linkResult.data.url; // redirect user to SmileID
+}
+// The SmileID hosted page shows all countries configured in index.kyc_supported_id_types.
+// The user selects their country and document type on that page.
+// After the user returns to returnUrl, poll getKycStatus to confirm the result.
+// markSubmittedKyc is NOT needed for Smile Links — SmileID fires the webhook directly.
+
+// Option B — SDK widget (embedded, for mobile / advanced web)
+const kycResult = await Kyc.startKyc({
+  body: { country: 'gh', channel: 'web' },
+});
+// kycResult: { token, partnerId, jobId, status, retriesRemaining }
+// Pass token + partnerId to the SmileID web SDK widget to start document capture.
+// After the SDK reports successful submission, call markSubmittedKyc with jobId.
+await Kyc.markSubmittedKyc({ body: { jobId: kycResult.data.jobId! } });
+// SmileID also calls POST /kyc/webhook under the configured API base/prefix
+// (for staging: https://staging.globalscoutme.com/api/kyc/webhook).
+
+const kycStatus = await Kyc.getKycStatus({
+  path: { userId: supabaseAuthUuid },
+});
+// kycStatus: { status, retryCount, retriesRemaining }
+// status: 'pending' | 'capture_started' | 'processing' | 'approved' | 'rejected' | 'blocked'
+// Older API clients may still see legacy 'in_progress', which maps to 'capture_started'.
+
+// QA/staging only — skip SmileID entirely and mark the current user KYC-approved.
+// Returns 403 outside test-like deployments (APP_ENV and NODE_ENV must both be non-production).
+const qaApproved = await Kyc.qaApproveKyc();
+// qaApproved: { jobId, status: 'approved', retryCount, retriesRemaining, country }
+
+// Subscriptions (Stripe recurring billing)
+const plans = await Subscriptions.getSubscriptionPlans();
+// Returns: { plans: [{ id, code, name, price, currency, billingInterval, trialDays, features, displayOrder }] }
+
+const mySubscription = await Subscriptions.getMySubscription();
+// Returns: { status, isActive, planId, planName, billingInterval,
+//            currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd, canceledAt, gracePeriodUntil }
+// status: 'inactive' when the user has never subscribed
+
+// Start a subscription — redirect the user to the returned URL
+const checkout = await Subscriptions.createCheckout({
+  body: {
+    providerProductId: 'billing-provider-products-uuid', // pick from billing_provider_products table
+    successUrl: 'https://yourapp.com/subscription/success', // or a mobile deep-link
+    cancelUrl: 'https://yourapp.com/subscription/cancel',
+  },
+});
+// redirect user to checkout.url
+
+// Open the Stripe Billing Portal (manage / cancel subscription)
+const portal = await Subscriptions.createPortal({
+  body: { returnUrl: 'https://yourapp.com/account' },
+});
+// redirect user to portal.url
+
+// Storage — get a signed upload URL, then PUT the file directly to Supabase Storage
+const { uploadUrl, token, path, bucket, expiresIn } = await Storage.createUploadUrl({
+  body: { bucket: 'avatars', contentType: 'image/jpeg', sizeBytes: 204800 },
+});
+await fetch(uploadUrl, {
+  method: 'PUT',
+  body: fileBlob,
+  headers: { 'Content-Type': 'image/jpeg' },
+});
+// persist `path` on the player record (e.g. patchMe with avatarPath: path)
+```
+
+## Updating auth token
+
+Update the Bearer token after sign-in or token refresh:
+
+```ts
+client.setConfig({
+  headers: {
+    Authorization: `Bearer ${newAccessToken}`,
+  },
+});
+```
+
+## Versioning
+
+This package is auto-generated from the backend OpenAPI spec. Version increments follow semver:
+
+- **patch** — no API shape changes
+- **minor** — new endpoints added
+- **major** — breaking changes (renamed/removed endpoints or fields)
+
+## Package format
+
+The published package ships compiled JavaScript (`dist/`) alongside the raw TypeScript source. `main` points to `dist/index.js` so all bundlers work without extra configuration.