be-components 7.4.8 → 7.5.1

package/lib/commonjs/BetRouter/types/README.md

@@ -0,0 +1,249 @@
+# BetRouter Types - Single Source of Truth
+
+This folder contains **ALL** TypeScript type definitions for the BetRouter project.
+
+## 📁 Structure
+
+```
+src/types/
+├── index.ts                   # Main export file
+├── opportunities.ts           # Opportunity types
+├── orders.ts                  # Order types
+├── accounts.ts                # Account types
+├── partners.ts                # Partner types
+├── leagues.ts                 # League types (router, raw, partner)
+├── contests.ts                # Contest types (router, raw, partner)
+├── participants.ts            # Participant types (router, raw, partner)
+├── markets.ts                 # Market types (router, raw, partner)
+├── liquidity.ts               # Liquidity types
+├── credentials.ts             # Partner credential types (Kalshi, BettorEdge, etc.)
+├── api-contracts.ts           # API endpoint contracts
+├── README.md                  # This file
+├── CREDENTIALS_EXAMPLE.md     # Examples for building credential forms
+└── ADMIN_PORTAL.md            # Complete guide for building admin portal
+```
+
+## 🏗️ One-to-Many Architecture
+
+BetRouter uses a **three-layer architecture** for core entities (leagues, contests, participants, markets):
+
+```
+┌─────────────────┐
+│  Router Layer   │  ← Canonical/normalized entities (single source of truth)
+│  (router_*)     │     Example: router_contests, router_participants
+└────────┬────────┘
+         │ one-to-many
+         ↓
+┌─────────────────┐
+│   Raw Layer     │  ← Partner-specific data (as-is from each partner)
+│   (raw_*)       │     Example: raw_contests (one per partner per game)
+└────────┬────────┘
+         │ linked via
+         ↓
+┌─────────────────┐
+│  Partner Layer  │  ← Junction table linking router ↔ raw
+│  (partner_*)    │     Example: partner_contests (creates the relationships)
+└─────────────────┘
+```
+
+**Key Principles:**
+- **Router entities** are the canonical source of truth (from BettorEdge)
+- **Raw entities** store partner-specific data exactly as received
+- **Partner entities** create many-to-many relationships via junction tables
+- Each router entity can link to multiple raw entities (one per partner)
+
+**Example:** Yankees vs Red Sox game
+- 1 `router_contest` (canonical representation)
+- 3 `raw_contests` (one from BettorEdge, one from Kalshi, one from BetOpenly)
+- 3 `partner_contests` (linking each raw contest to the router contest)
+
+See `ADMIN_PORTAL.md` for detailed architecture documentation and workflows.
+
+## 🎯 Usage in Server
+
+```typescript
+// Import types in your server code
+import {
+  RouterContestProps,
+  RawContestProps,
+  PartnerContestProps,
+  RouterParticipantProps,
+  OpportunityProps
+} from './types';
+import { ApiContracts, ExtractSuccessResponse } from './types/api-contracts';
+```
+
+## 📦 Usage in Client
+
+### Step 1: Copy to your client project
+
+```bash
+# From your client project root
+cp -r ../betrouter/src/types ./src/types/betrouter
+```
+
+**OR** add this to your client's `package.json`:
+
+```json
+{
+  "scripts": {
+    "sync-types": "cp -r ../betrouter/src/types ./src/types/betrouter"
+  }
+}
+```
+
+Then run: `npm run sync-types`
+
+### Step 2: Use in your client code
+
+```typescript
+import {
+  RouterContestProps,
+  RawContestProps,
+  PartnerContestProps,
+  RouterMarketProps,
+  ApiContracts,
+  ExtractSuccessResponse
+} from './types/betrouter';
+
+// Example 1: Display contests with their partner links
+interface ContestWithLinks {
+  contest: RouterContestProps;
+  partnerContests: PartnerContestProps[];
+  rawContests: RawContestProps[];
+}
+
+// Example 2: Load raw contests from a partner
+async function loadRawContestsFromPartner(
+  partnerId: string,
+  leagueId: string
+) {
+  const res = await fetch('/api/contests/load-raw', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      partner_id: partnerId,
+      router_league_id: leagueId
+    })
+  });
+
+  const data = await res.json();
+  return data.raw_contests as RawContestProps[];
+}
+
+// Example 3: Link raw contests to router contest
+async function linkContests(
+  rawContestIds: string[],
+  routerContestId: string
+) {
+  const res = await fetch('/api/contests/link', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      raw_contest_ids: rawContestIds,
+      router_contest_id: routerContestId
+    })
+  });
+
+  const data = await res.json();
+  return data.partner_contests as PartnerContestProps[];
+}
+
+// Example 4: Build admin UI showing linked data
+function ContestLinkingComponent() {
+  const [routerContests, setRouterContests] = useState<RouterContestProps[]>([]);
+  const [rawContests, setRawContests] = useState<RawContestProps[]>([]);
+  const [selectedRouter, setSelectedRouter] = useState<string | null>(null);
+
+  // ... component logic
+}
+```
+
+## 🔐 Partner Credentials
+
+Build dynamic credential forms in your client! Each partner has different credential requirements:
+
+**Kalshi:**
+- `api_key` (text)
+- `private_key_pem` (textarea)
+
+**BettorEdge:**
+- `username` (text)
+- `password` (password)
+- `device_id` (text)
+
+Use helper functions to build forms dynamically:
+
+```typescript
+import {
+  getRequiredCredentialFields,
+  getCredentialFieldLabels,
+  getCredentialFieldTypes
+} from './types/betrouter';
+
+const fields = getRequiredCredentialFields('Kalshi');
+// ['api_key', 'private_key_pem']
+
+const labels = getCredentialFieldLabels('Kalshi');
+// { api_key: 'API Key', private_key_pem: 'Private Key (PEM format)' }
+
+const types = getCredentialFieldTypes('Kalshi');
+// { api_key: 'text', private_key_pem: 'textarea' }
+```
+
+**See `CREDENTIALS_EXAMPLE.md` for complete examples!**
+
+## 🔄 Keeping Types in Sync
+
+When you update types or add new API endpoints:
+
+1. **Update in `src/types`** (this folder) - the single source of truth
+2. **Copy to client** - Run `npm run sync-types` in your client project
+3. **Done!** - Both server and client now have the same types
+
+## ⚠️ Important Rules
+
+1. **NEVER define types outside of `src/types`** - This is the single source of truth
+2. **Import types from `./types` or `../types`** - Always reference this folder
+3. **Update API contracts when adding routes** - Keep `api-contracts.ts` in sync with your routes
+4. **Don't manually edit in client** - Always copy from server
+
+## 📝 Type Helpers
+
+The `api-contracts.ts` file provides helper types:
+
+- `ExtractRequestBody<Route>` - Get request body type
+- `ExtractRequestQuery<Route>` - Get query parameters type
+- `ExtractRequestParams<Route>` - Get URL parameters type
+- `ExtractSuccessResponse<Route>` - Get success response type
+- `ExtractErrorResponse<Route>` - Get error response type
+
+Example:
+
+```typescript
+type BuyBody = ExtractRequestBody<'POST /opportunities/opportunity/buy'>;
+type PastQuery = ExtractRequestQuery<'GET /opportunities/past/me'>;
+type PastResponse = ExtractSuccessResponse<'GET /opportunities/past/me'>;
+```
+
+## 🔨 Building Admin Tools
+
+To build an admin portal for managing router/raw/partner entity linking:
+
+**📖 [ADMIN_PORTAL_SIMPLIFIED.md](./ADMIN_PORTAL_SIMPLIFIED.md)** - **START HERE** - Practical, contest-centric workflow guide:
+- League → Contest → Link workflow
+- New contest-specific endpoint: `GET /contests/:router_contest_id/available-raw/:partner_id`
+- Simple UI layouts
+- Recommended implementation order
+
+**📖 [ADMIN_PORTAL.md](./ADMIN_PORTAL.md)** - Complete reference guide with:
+- Architecture diagrams and deep-dive explanations
+- All entities (leagues, contests, participants, markets)
+- Complete endpoint reference
+- Advanced features and patterns

package/lib/commonjs/BetRouter/types/accounts.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=accounts.js.map

package/lib/commonjs/BetRouter/types/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["BetRouter/types/accounts.ts"],"mappings":"","ignoreList":[]}