# SatLoc Partner Integration API Specification

## Overview

This document specifies the integration between AgMission and SatLoc Cloud services using a dual-user system:

1. **Partner Users**: Organizations like SatLoc that provide services
2. **Partner System Users**: Customer/applicator accounts within each partner system

## Architecture

### User Model Structure

```javascript
// Partner Organization (e.g., SatLoc company)
const Partner = User.discriminator('PARTNER', {
  partnerCode: 'SATLOC',
  partnerName: 'SatLoc Cloud',
  configuration: { /* partner-specific settings */ }
});

// Customer account in SatLoc system
const PartnerSystemUser = User.discriminator('PARTNER_SYSTEM_USER', {
  partner: ObjectId,          // Reference to Partner
  customer: ObjectId,         // AgMission customer  
  partnerUserId: String,      // SatLoc user ID
  companyId: String,          // SatLoc company ID
  apiKey: String,             // Customer's SatLoc API key
  // ... additional SatLoc-specific fields
});
```

### Environment Configuration

Partner system settings are managed via environment variables:

```bash
# SatLoc Configuration
SATLOC_API_ENDPOINT=https://www.satloccloud.com/api/Satloc
SATLOC_API_KEY=default_api_key
SATLOC_API_SECRET=default_api_secret
SATLOC_API_TIMEOUT=30000
SATLOC_RETRY_ATTEMPTS=3
SATLOC_RATE_LIMIT=60
```

## SatLoc Cloud API Endpoints

#### Authenticate API User
```http
GET /api/Satloc/AuthenticateAPIUser?userLogin={userLogin}&password={password}
```

**Example:**
```http
GET /api/Satloc/AuthenticateAPIUser?userLogin=vendor%40myk.com&password=Home4663%23
```

**Response:**
```json
{
  "userId": "a2991888-5c7f-4101-8e0d-0a390c26720c",
  "companyId": "36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff",
  "email": "vendor@myk.com"
}
```

### 2. Health Check

#### Is Alive Check
```http
GET /api/Satloc/IsAlive
```

**Response:**
```
true
```

### 3. Aircraft Management

#### Get Aircraft List
```http
GET /api/Satloc/GetAircraftList?userId={userId}&companyId={companyId}
```

**Example:**
```http
GET /api/Satloc/GetAircraftList?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&companyId=36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff
```

**Response:**
```json
[
  {
    "id": "23bee7aa-c949-4089-854a-2ab58b40294f",
    "tailNumber": "MYK AIR01"
  },
  {
    "id": "ced67805-41c8-4dc7-b8fd-7bcabc0ce6c4",
    "tailNumber": "MYK AIR03"
  },
  {
    "id": "b2ae08d8-6ff5-43d4-9fe1-a8f91dbcb0fb",
    "tailNumber": "AIR 02"
  }
]
```

### 4. Flight Logs

#### Get Aircraft Logs
```http
GET /api/Satloc/GetAircraftLogs?userId={userId}&aircraftId={aircraftId}
```

**Example:**
```http
GET /api/Satloc/GetAircraftLogs?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&aircraftId=23bee7aa-c949-4089-854a-2ab58b40294f
```

**Response:**
```json
[
  {
    "id": "d4bbbebf-ea9d-44af-a901-aab9f81bc841",
    "logFileName": "Liquid_NAAA_200.log",
    "uploadedDate": "2020-07-04T15:59:54.577"
  },
  {
    "id": "f425cea7-1644-48ef-9fbf-b2c9642c6cbe",
    "logFileName": "Liquid_NAAA_800.log",
    "uploadedDate": "2020-07-04T15:56:19.167"
  },
  {
    "id": "2e38fc84-431c-4473-a6c0-e0a24a3ab07a",
    "logFileName": "Liquid_NAAA_150.log",
    "uploadedDate": "2020-07-04T15:53:53.74"
  }
]
```

#### Get Aircraft Log Data
```http
GET /api/Satloc/GetAircraftLogData?userId={userId}&logId={logId}
```

**Example:**
```http
GET /api/Satloc/GetAircraftLogData?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&logId=d4bbbebf-ea9d-44af-a901-aab9f81bc841
```

**Response:**
```json
{
  "id": "d4bbbebf-ea9d-44af-a901-aab9f81bc841",
  "logFile": "QVM0LjAxL0FUVCAzLjE5LjExOC4xNjI1ICAgICBI~",
  "logFileName": "Liquid_NAAA_200.log"
}
```

**Note:** The `logFile` field contains base64-encoded binary data that should be decoded to access the actual log file content.

### 5. Job Upload

#### Upload Job Data
```http
POST /api/Satloc/UploadJobData
```

**Request Body Structure:**
```json
{
  "CompanyId": "36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff",
  "UserId": "a2991888-5c7f-4101-8e0d-0a390c26720c",
  "JobDataList": [
    {
      "AircraftId": "23bee7aa-c949-4089-854a-2ab58b40294f",
      "JobName": "Binary.PMD",
      "Notes": null,
      "JobData": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA~",
      "Overwrite": true,
      "Id": "275e3dba-1a06-4bc2-bd3c-f06f65fdcaa5",
      "LastModified": "2020-07-07T14:51:01.4147813-05:00",
      "LastModifiedBy": "Bay",
      "CreatedDate": "2020-07-07T14:51:01.4307691-05:00",
      "CreatedBy": "Bay"
    }
  ]
}
```

**Fields Explanation:**
- `CompanyId`: Company identifier from authentication
- `UserId`: User identifier from authentication  
- `JobDataList`: Array of job data objects
  - `AircraftId`: Target aircraft ID (maps to `partnerAircraftId` in AgMission)
  - `JobName`: Job file name
  - `Notes`: Optional notes for the job
  - `JobData`: Base64-encoded job file content
  - `Overwrite`: Whether to overwrite existing job (default: false)
  - `Id`: Unique job identifier
  - Audit fields: `LastModified`, `LastModifiedBy`, `CreatedDate`, `CreatedBy`