@rawdash/connector-greenhouse 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +153 -0
  2. package/dist/index.d.ts +635 -0
  3. package/dist/index.js +684 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +43 -0
package/README.md ADDED
@@ -0,0 +1,153 @@
1
+ <!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
2
+
3
+ # @rawdash/connector-greenhouse
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@rawdash/connector-greenhouse)](https://www.npmjs.com/package/@rawdash/connector-greenhouse)
6
+ [![license](https://img.shields.io/npm/l/@rawdash/connector-greenhouse)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
7
+
8
+ Sync jobs, candidates, applications, and offers from the Greenhouse Harvest API for hiring-funnel, time-to-hire, and offer-rate analytics.
9
+
10
+ > **Cost & frequency.** Greenhouse Harvest is rate-limited to 50 requests / 10 seconds per key; on large hiring funnels the full backfill spans many pages, so syncing more often than the recommended interval can starve other integrations on the same key. Recommended sync interval: **1 hour**. Minimum sensible interval: **15 minutes**.
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install @rawdash/connector-greenhouse
16
+ ```
17
+
18
+ ## Authentication
19
+
20
+ A Harvest API key with read-only access to candidates, applications, jobs, and offers. Greenhouse authenticates via HTTP Basic with the key as the username and an empty password.
21
+
22
+ 1. Open Greenhouse -> Configure -> Dev Center -> API Credential Management.
23
+ 2. Create a new Harvest API key with Get / List permissions for the resources you intend to sync (Candidates, Applications, Jobs, Offers).
24
+ 3. Copy the key once on creation - Greenhouse never shows it again.
25
+ 4. Store the key as a secret and reference it from config as `apiKey: secret("GREENHOUSE_API_KEY")`.
26
+
27
+ ## Configuration
28
+
29
+ | Field | Type | Required | Description |
30
+ | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
31
+ | `apiKey` | secret | Yes | Greenhouse Harvest API key with read-only access. Create one at Configure -> Dev Center -> API Credential Management. |
32
+ | `resources` | array | No | Which Greenhouse resources to sync. Omit to sync all resources. The Harvest key only needs Get / List permissions for the resources listed here. |
33
+
34
+ ## Resources
35
+
36
+ - **`greenhouse_job`** _(entity)_ - Open, draft, and closed requisitions with department, office, and timestamps for opened / closed transitions.
37
+ - Endpoint: `GET /v1/jobs`
38
+ - `name`: Job title.
39
+ - `status`: Greenhouse job status (open / closed / draft).
40
+ - `requisitionId`: External requisition id.
41
+ - `departments`: Flat list of department names attached to the job.
42
+ - `offices`: Flat list of office names attached to the job.
43
+ - `openedAt`: When the job was opened (Unix ms).
44
+ - `closedAt`: When the job was closed (Unix ms).
45
+ - `confidential`: Whether the job is confidential.
46
+ - **`greenhouse_candidate`** _(entity)_ - Candidate records with name, title, company, and the count of attached applications.
47
+ - Endpoint: `GET /v1/candidates`
48
+ - `firstName`: Candidate first name.
49
+ - `lastName`: Candidate last name.
50
+ - `title`: Candidate current job title.
51
+ - `company`: Candidate current company.
52
+ - `applicationCount`: Number of applications attached to the candidate. Useful for spotting repeat applicants.
53
+ - `isPrivate`: Whether the candidate is marked private.
54
+ - `createdAt`: When the candidate was created (Unix ms).
55
+ - `lastActivityAt`: Last activity timestamp on the candidate (Unix ms).
56
+ - **`greenhouse_application`** _(entity)_ - Applications with status (active / hired / rejected), current stage, source, and the linked candidate / job.
57
+ - Endpoint: `GET /v1/applications`
58
+ - `candidateId`: Candidate the application belongs to.
59
+ - `jobId`: Primary job the application is attached to.
60
+ - `jobName`: Primary job name at sync time.
61
+ - `status`: Application status (active / hired / rejected).
62
+ - `currentStage`: Name of the current stage (e.g. "Phone Screen").
63
+ - `source`: Public source name where the application originated (e.g. "LinkedIn").
64
+ - `appliedAt`: When the application was submitted.
65
+ - `rejectedAt`: When the application was rejected (null if not).
66
+ - `hiredAt`: When the application was hired (derived from last_activity_at when status=hired).
67
+ - `lastActivityAt`: Last activity timestamp on the application (Unix ms).
68
+ - **`greenhouse_application_event`** _(event)_ - Application lifecycle events (applied / hired / rejected) derived from each application timestamps. The scope is cleared and rewritten on every sync (including incremental runs).
69
+ - Endpoint: `GET /v1/applications`
70
+ - Derived from each application's applied_at / rejected_at / last_activity_at fields, not from a separate API call.
71
+ - `applicationId`: Application the event belongs to.
72
+ - `candidateId`: Candidate id, denormalised.
73
+ - `jobId`: Job id, denormalised.
74
+ - `transition`: "applied", "hired", or "rejected".
75
+ - `source`: Application source name at the time of the event.
76
+ - **`greenhouse_offer`** _(entity)_ - Offers with status (pending / accepted / rejected), linked to their application, candidate, and job.
77
+ - Endpoint: `GET /v1/offers`
78
+ - `applicationId`: Linked application.
79
+ - `candidateId`: Linked candidate.
80
+ - `jobId`: Linked job.
81
+ - `status`: Offer status (pending / accepted / rejected).
82
+ - `sentAt`: When the offer was sent (Unix ms).
83
+ - `resolvedAt`: When the offer was accepted or rejected (Unix ms; null while pending).
84
+ - `startsAt`: Proposed start date on the offer (Unix ms).
85
+
86
+ ## Example
87
+
88
+ ```ts
89
+ import {
90
+ defineConfig,
91
+ defineDashboard,
92
+ defineMetric,
93
+ secret,
94
+ } from '@rawdash/core';
95
+
96
+ const greenhouse = {
97
+ name: 'greenhouse',
98
+ connectorId: 'greenhouse',
99
+ config: {
100
+ apiKey: secret('GREENHOUSE_API_KEY'),
101
+ },
102
+ };
103
+
104
+ export default defineConfig({
105
+ connectors: [greenhouse],
106
+ dashboards: {
107
+ hiring: defineDashboard({
108
+ widgets: {
109
+ open_roles: {
110
+ kind: 'stat',
111
+ title: 'Open roles',
112
+ metric: defineMetric({
113
+ connector: greenhouse,
114
+ shape: 'entity',
115
+ entityType: 'greenhouse_job',
116
+ fn: 'count',
117
+ filter: [{ field: 'status', op: 'eq', value: 'open' }],
118
+ }),
119
+ },
120
+ offers_extended: {
121
+ kind: 'stat',
122
+ title: 'Offers extended',
123
+ metric: defineMetric({
124
+ connector: greenhouse,
125
+ shape: 'entity',
126
+ entityType: 'greenhouse_offer',
127
+ fn: 'count',
128
+ }),
129
+ },
130
+ },
131
+ }),
132
+ },
133
+ });
134
+ ```
135
+
136
+ ## Rate limits
137
+
138
+ Greenhouse Harvest enforces 50 requests per 10 seconds per key and surfaces remaining quota via the X-RateLimit-\* headers; the shared HTTP client backs off on 429, preferring the Retry-After header.
139
+
140
+ ## Limitations
141
+
142
+ - Application stage-transition history is derived from each application's built-in timestamps (applied_at, hired_at, rejected_at, last_activity_at) rather than the per-application /activity_feed endpoint, which avoids an N+1 sync.
143
+ - Greenhouse Onboard data and Recruiting custom fields are out of scope.
144
+
145
+ ## Links
146
+
147
+ - [Rawdash docs](https://rawdash.dev/docs/connectors/)
148
+ - [Greenhouse API docs](https://developers.greenhouse.io/harvest.html)
149
+ - [GitHub](https://github.com/rawdash/rawdash)
150
+
151
+ ## License
152
+
153
+ Apache-2.0