be-components 7.7.2 → 7.7.4

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

@@ -0,0 +1,350 @@
+# Partner Credentials - Client Usage Guide
+
+This guide shows how to build dynamic credential forms in your client based on partner types.
+
+## 🎯 Usage in Client
+
+### Example 1: Dynamic Form Builder
+
+```typescript
+import {
+  RouterPartnerProps,
+  KalshiCredentialProps,
+  BettorEdgeCredentialProps,
+  BetOpenlyCredentialProps,
+  getRequiredCredentialFields,
+  getCredentialFieldLabels,
+  getCredentialFieldTypes
+} from './types/betrouter';
+
+interface CredentialFormProps {
+  partner: RouterPartnerProps;
+  onSubmit: (credentials: any) => void;
+}
+
+function CredentialForm({ partner, onSubmit }: CredentialFormProps) {
+  const fields = getRequiredCredentialFields(partner.name);
+  const labels = getCredentialFieldLabels(partner.name);
+  const types = getCredentialFieldTypes(partner.name);
+
+  const [formData, setFormData] = useState<Record<string, string>>({});
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onSubmit(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h2>Connect to {partner.name}</h2>
+      {fields.map(field => (
+        <div key={field}>
+          <label>{labels[field]}</label>
+          {types[field] === 'textarea' ? (
+            <textarea
+              value={formData[field] || ''}
+              onChange={(e) => setFormData({ ...formData, [field]: e.target.value })}
+              required
+            />
+          ) : (
+            <input
+              type={types[field]}
+              value={formData[field] || ''}
+              onChange={(e) => setFormData({ ...formData, [field]: e.target.value })}
+              required
+            />
+          )}
+        </div>
+      ))}
+      <button type="submit">Connect</button>
+    </form>
+  );
+}
+```
+
+### Example 2: Type-Safe Credential Update
+
+```typescript
+import {
+  ApiContracts,
+  ExtractRequestBody,
+  ExtractSuccessResponse,
+  KalshiCredentialProps,
+  BettorEdgeCredentialProps,
+  BetOpenlyCredentialProps
+} from './types/betrouter';
+
+type UpdateCredentialsBody = ExtractRequestBody<'POST /accounts/partner/credentials/update'>;
+type UpdateCredentialsResponse = ExtractSuccessResponse<'POST /accounts/partner/credentials/update'>;
+
+async function updatePartnerCredentials(
+  partnerId: string,
+  credentials: KalshiCredentialProps | BettorEdgeCredentialProps | BetOpenlyCredentialProps
+): Promise<UpdateCredentialsResponse> {
+  const body: UpdateCredentialsBody = {
+    partner_id: partnerId,
+    credentials
+  };
+
+  const response = await fetch('/api/accounts/partner/credentials/update', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${token}`
+    },
+    body: JSON.stringify(body)
+  });
+
+  return response.json();
+}
+```
+
+### Example 3: Partner-Specific Forms
+
+```typescript
+import { KalshiCredentialProps, BettorEdgeCredentialProps, BetOpenlyCredentialProps } from './types/betrouter';
+
+// Kalshi Form
+function KalshiCredentialsForm() {
+  const [credentials, setCredentials] = useState<KalshiCredentialProps>({
+    api_key: '',
+    private_key_pem: ''
+  });
+
+  return (
+    <form>
+      <input
+        type="text"
+        placeholder="API Key"
+        value={credentials.api_key}
+        onChange={(e) => setCredentials({ ...credentials, api_key: e.target.value })}
+      />
+      <textarea
+        placeholder="Private Key (PEM format)"
+        value={credentials.private_key_pem}
+        onChange={(e) => setCredentials({ ...credentials, private_key_pem: e.target.value })}
+      />
+    </form>
+  );
+}
+
+// BettorEdge Form
+function BettorEdgeCredentialsForm() {
+  const [credentials, setCredentials] = useState<BettorEdgeCredentialProps>({
+    username: '',
+    password: '',
+    device_id: ''
+  });
+
+  return (
+    <form>
+      <input
+        type="text"
+        placeholder="Username"
+        value={credentials.username}
+        onChange={(e) => setCredentials({ ...credentials, username: e.target.value })}
+      />
+      <input
+        type="password"
+        placeholder="Password"
+        value={credentials.password}
+        onChange={(e) => setCredentials({ ...credentials, password: e.target.value })}
+      />
+      <input
+        type="text"
+        placeholder="Device ID"
+        value={credentials.device_id}
+        onChange={(e) => setCredentials({ ...credentials, device_id: e.target.value })}
+      />
+    </form>
+  );
+}
+
+// BetOpenly Form
+function BetOpenlyCredentialsForm() {
+  const [credentials, setCredentials] = useState<BetOpenlyCredentialProps>({
+    username: '',
+    password: ''
+  });
+
+  return (
+    <form>
+      <input
+        type="text"
+        placeholder="Username"
+        value={credentials.username}
+        onChange={(e) => setCredentials({ ...credentials, username: e.target.value })}
+      />
+      <input
+        type="password"
+        placeholder="Password"
+        value={credentials.password}
+        onChange={(e) => setCredentials({ ...credentials, password: e.target.value })}
+      />
+    </form>
+  );
+}
+```
+
+### Example 4: Complete Flow with React Query
+
+```typescript
+import { useMutation } from '@tanstack/react-query';
+import {
+  RouterPartnerProps,
+  KalshiCredentialProps,
+  BettorEdgeCredentialProps,
+  BetOpenlyCredentialProps,
+  ExtractRequestBody,
+  ExtractSuccessResponse
+} from './types/betrouter';
+
+type UpdateCredentialsBody = ExtractRequestBody<'POST /accounts/partner/credentials/update'>;
+type UpdateCredentialsResponse = ExtractSuccessResponse<'POST /accounts/partner/credentials/update'>;
+
+function useUpdateCredentials() {
+  return useMutation({
+    mutationFn: async (body: UpdateCredentialsBody): Promise<UpdateCredentialsResponse> => {
+      const response = await fetch('/api/accounts/partner/credentials/update', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`
+        },
+        body: JSON.stringify(body)
+      });
+
+      if (!response.ok) throw new Error('Failed to update credentials');
+      return response.json();
+    }
+  });
+}
+
+function ConnectPartnerPage({ partner }: { partner: RouterPartnerProps }) {
+  const updateCredentials = useUpdateCredentials();
+  const [formData, setFormData] = useState<Record<string, string>>({});
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    // Type-safe credentials based on partner
+    let credentials: KalshiCredentialProps | BettorEdgeCredentialProps | BetOpenlyCredentialProps;
+
+    if (partner.name === 'Kalshi') {
+      credentials = {
+        api_key: formData.api_key,
+        private_key_pem: formData.private_key_pem
+      };
+    } else if (partner.name === 'BettorEdge') {
+      credentials = {
+        username: formData.username,
+        password: formData.password,
+        device_id: formData.device_id
+      };
+    } else if (partner.name === 'BetOpenly') {
+      credentials = {
+        username: formData.username,
+        password: formData.password
+      };
+    } else {
+      return;
+    }
+
+    await updateCredentials.mutateAsync({
+      partner_id: partner.partner_id,
+      credentials
+    });
+  };
+
+  // Use the helper functions for dynamic form rendering
+  // (see Example 1)
+}
+```
+
+## 📋 Available Helper Functions
+
+### `getRequiredCredentialFields(partnerName: string): string[]`
+Returns array of required field names for a partner.
+
+```typescript
+getRequiredCredentialFields('Kalshi')
+// Returns: ['api_key', 'private_key_pem']
+
+getRequiredCredentialFields('BettorEdge')
+// Returns: ['username', 'password', 'device_id']
+
+getRequiredCredentialFields('BetOpenly')
+// Returns: ['username', 'password']
+```
+
+### `getCredentialFieldLabels(partnerName: string): Record<string, string>`
+Returns human-readable labels for each field.
+
+```typescript
+getCredentialFieldLabels('Kalshi')
+// Returns: { api_key: 'API Key', private_key_pem: 'Private Key (PEM format)' }
+
+getCredentialFieldLabels('BetOpenly')
+// Returns: { username: 'Username', password: 'Password' }
+```
+
+### `getCredentialFieldTypes(partnerName: string): Record<string, 'text' | 'password' | 'textarea'>`
+Returns input types for each field.
+
+```typescript
+getCredentialFieldTypes('Kalshi')
+// Returns: { api_key: 'text', private_key_pem: 'textarea' }
+
+getCredentialFieldTypes('BetOpenly')
+// Returns: { username: 'text', password: 'password' }
+```
+
+## 🔐 Type Guards
+
+```typescript
+import { isKalshiCredentials, isBettorEdgeCredentials, isBetOpenlyCredentials } from './types/betrouter';
+
+function processCredentials(credentials: any) {
+  if (isKalshiCredentials(credentials)) {
+    // TypeScript knows this is KalshiCredentialProps
+    console.log(credentials.api_key);
+    console.log(credentials.private_key_pem);
+  } else if (isBettorEdgeCredentials(credentials)) {
+    // TypeScript knows this is BettorEdgeCredentialProps
+    console.log(credentials.username);
+    console.log(credentials.password);
+    console.log(credentials.device_id);
+  } else if (isBetOpenlyCredentials(credentials)) {
+    // TypeScript knows this is BetOpenlyCredentialProps
+    console.log(credentials.username);
+    console.log(credentials.password);
+  }
+}
+```
+
+## 🆕 Adding New Partner Credentials
+
+When you add a new partner:
+
+1. **Add the credential interface in `src/types/credentials.ts`:**
+   ```typescript
+   export interface NewPartnerCredentialProps {
+       field1: string
+       field2: string
+   }
+   ```
+
+2. **Update the union type:**
+   ```typescript
+   export type PartnerCredentialProps =
+       KalshiCredentialProps |
+       BettorEdgeCredentialProps |
+       BetOpenlyCredentialProps |
+       NewPartnerCredentialProps
+   ```
+
+3. **Update the helper functions** in the same file
+
+4. **Copy to your client** - `cp -r ../betrouter/src/types ./src/types/betrouter`
+
+5. **Your client automatically gets the new partner support!**