Janady13/missionmatch / internal/platform/connector/icims.go

1package connector 2 3import ( 4 "context" 5 "encoding/json" 6 "fmt" 7 "io" 8 "net/http" 9 "net/url" 10 "strings" 11 "time" 12 13 "github.com/missionworkforce/missionmatch/internal/platform/sourcing" 14) 15 16// ICIMS is the iCIMS ATS Connector. It authenticates with OAuth 2.0 client credentials (the client id and 17// secret load from the server side env only), caches the bearer token until just before it expires, and pages 18// through candidates updated since the incremental watermark. It maps each iCIMS candidate to the shared 19// provider independent SourcedPerson shape; the sync orchestration ingests them through the proven sourcing 20// path. It carries NO clearance (iCIMS clearance, if present, is self reported and stays unknown in scoring). 21// 22// The endpoint paths and the candidate field mapping follow the iCIMS Customer API and are the ONE thin layer 23// to confirm against a pilot tenant's live credentials; the OAuth flow, the token cache, the incremental 24// window, the pagination, the throttle handling, and the mapping mechanics are complete and unit tested against 25// a fake server. iCIMS is a FedRAMP relevant ATS, so it is admitted on the CUI path; a non authorized cloud 26// aggregator is not. 27type ICIMS struct { 28 customerID string 29 clientID string 30 clientSecret string 31 base string 32 http *http.Client 33 34 token string 35 tokenExp time.Time 36} 37 38// ICIMSBase is the default iCIMS API host. NewICIMS accepts an override so a test points at a fake server. 39const ICIMSBase = "https://api.icims.com" 40 41// NewICIMS builds the iCIMS connector. An empty base uses the public host. 42func NewICIMS(customerID, clientID, clientSecret, base string, httpClient *http.Client) *ICIMS { 43 if strings.TrimSpace(base) == "" { 44 base = ICIMSBase 45 } 46 if httpClient == nil { 47 httpClient = &http.Client{Timeout: 45 * time.Second} 48 } 49 return &ICIMS{customerID: customerID, clientID: clientID, clientSecret: [credential removed], base: strings.TrimRight(base, "/"), http: httpClient} 50} 51 52func (c *ICIMS) Name() string { return "icims" } 53 54// bearer returns a valid access token, fetching a new one via the OAuth client credentials grant when the cache 55// is empty or within a minute of expiry. The token request carries the client id and secret; the response 56// carries the token and its lifetime. 57func (c *ICIMS) bearer(ctx context.Context) (string, error) { 58 if c.token != "" && time.Now().Before(c.tokenExp.Add(-time.Minute)) { 59 return c.token, nil 60 } 61 form := url.Values{ 62 "grant_type": {"client_credentials"}, 63 "client_id": {c.clientID}, 64 "client_secret": {c.clientSecret}, 65 } 66 req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.base+"/oauth/token", strings.NewReader(form.Encode())) 67 if err != nil { 68 return "", fmt.Errorf("connector: build token request: %w", err) 69 } 70 req.Header.Set("Content-Type", "application/x-www-form-urlencoded") 71 resp, err := c.http.Do(req) 72 if err != nil { 73 return "", fmt.Errorf("connector: token request failed") 74 } 75 defer func() { _ = resp.Body.Close() }() 76 if resp.StatusCode != http.StatusOK { 77 snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256)) 78 return "", fmt.Errorf("connector: token status %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet))) 79 } 80 var tok struct { 81 AccessToken string `json:"access_token"` 82 ExpiresIn int `json:"expires_in"` 83 } 84 if err := json.NewDecoder(resp.Body).Decode(&tok); err != nil { 85 return "", fmt.Errorf("connector: decode token: %w", err) 86 } 87 if tok.AccessToken == "" { 88 return "", fmt.Errorf("connector: empty access token") 89 } 90 c.token = tok.AccessToken 91 life := tok.ExpiresIn 92 if life <= 0 { 93 life = 3600 94 } 95 c.tokenExp = time.Now().Add(time.Duration(life) * time.Second) 96 return c.token, nil 97} 98 99// icimsCandidate is one candidate in a search page. The field paths follow the iCIMS Customer API and are the 100// layer to confirm with live credentials; the shape here is provider independent enough that a small mapping 101// change does not touch the sync mechanics. 102type icimsCandidate struct { 103 ID string `json:"id"` 104 Name string `json:"name"` 105 Title string `json:"title"` 106 Location string `json:"location"` 107 Skills []string `json:"skills"` 108 Years int `json:"years"` 109 Email string `json:"email"` 110 Updated string `json:"updated"` // RFC3339 last updated timestamp 111} 112 113type icimsPage struct { 114 People []icimsCandidate `json:"people"` 115 NextPage string `json:"nextPage"` 116} 117 118// FetchPage pulls one page of candidates updated at or after since, maps them to SourcedPerson, and reports the 119// next page cursor and the max updated timestamp on the page. A 429 maps to sourcing.ErrThrottled so the sync 120// stops gracefully within the iCIMS daily cap. 121func (c *ICIMS) FetchPage(ctx context.Context, since time.Time, page string) ([]sourcing.SourcedPerson, string, time.Time, error) { 122 token, err := c.bearer(ctx) 123 if err != nil { 124 return nil, "", time.Time{}, err 125 } 126 q := url.Values{"updatedSince": {since.UTC().Format(time.RFC3339)}} 127 if page != "" { 128 q.Set("page", page) 129 } 130 endpoint := fmt.Sprintf("%s/customers/%s/search/people?%s", c.base, url.PathEscape(c.customerID), q.Encode()) 131 req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil) 132 if err != nil { 133 return nil, "", time.Time{}, fmt.Errorf("connector: build search request: %w", err) 134 } 135 req.Header.Set("Authorization", "Bearer "+token) 136 req.Header.Set("Accept", "application/json") 137 resp, err := c.http.Do(req) 138 if err != nil { 139 return nil, "", time.Time{}, fmt.Errorf("connector: search request failed") 140 } 141 defer func() { _ = resp.Body.Close() }() 142 if resp.StatusCode == http.StatusTooManyRequests { 143 return nil, "", time.Time{}, sourcing.ErrThrottled 144 } 145 if resp.StatusCode != http.StatusOK { 146 snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 256)) 147 return nil, "", time.Time{}, fmt.Errorf("connector: search status %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet))) 148 } 149 var pageResp icimsPage 150 if err := json.NewDecoder(resp.Body).Decode(&pageResp); err != nil { 151 return nil, "", time.Time{}, fmt.Errorf("connector: decode search: %w", err) 152 } 153 154 people := make([]sourcing.SourcedPerson, 0, len(pageResp.People)) 155 var maxUpdated time.Time 156 for _, cand := range pageResp.People { 157 sp, updated, ok := mapICIMS(cand) 158 if !ok { 159 continue 160 } 161 people = append(people, sp) 162 if updated.After(maxUpdated) { 163 maxUpdated = updated 164 } 165 } 166 return people, pageResp.NextPage, maxUpdated, nil 167} 168 169// mapICIMS maps an iCIMS candidate to a SourcedPerson (clearance intentionally absent, treated as unknown) and 170// parses its updated timestamp. A record with no id or name is skipped, never a partial candidate. 171func mapICIMS(cand icimsCandidate) (sourcing.SourcedPerson, time.Time, bool) { 172 id := strings.TrimSpace(cand.ID) 173 name := strings.TrimSpace(cand.Name) 174 if id == "" || name == "" { 175 return sourcing.SourcedPerson{}, time.Time{}, false 176 } 177 raw, _ := json.Marshal(cand) 178 sp := sourcing.SourcedPerson{ 179 ExternalID: id, 180 FullName: name, 181 JobTitle: strings.TrimSpace(cand.Title), 182 Location: strings.TrimSpace(cand.Location), 183 Skills: cand.Skills, 184 Years: cand.Years, 185 Raw: raw, 186 } 187 if e := strings.TrimSpace(cand.Email); e != "" { 188 sp.Emails = []string{e} 189 } 190 updated, _ := time.Parse(time.RFC3339, cand.Updated) 191 return sp, updated, true 192} 193