@rawdash/connector-greenhouse 0.0.1

package/dist/index.js

@@ -0,0 +1,684 @@
+// ../../connector-shared/dist/index.js
+var HTTP_CLIENT_VERSION = "0.0.0";
+var DEFAULT_USER_AGENT = `rawdash-connector/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+function connectorUserAgent(connectorId) {
+  return `rawdash-connector-${connectorId}/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+}
+function standardRateLimitPolicy(config) {
+  const { remainingHeader, resetHeader, resetUnit, resetFallbackMs } = config;
+  const multiplier = resetUnit === "s" ? 1e3 : 1;
+  return {
+    parse(h) {
+      const remainingRaw = h.get(remainingHeader);
+      if (remainingRaw === null || remainingRaw.trim() === "") {
+        return null;
+      }
+      const remaining = Number(remainingRaw);
+      if (!Number.isFinite(remaining)) {
+        return null;
+      }
+      const resetRaw = h.get(resetHeader);
+      if (resetRaw === null) {
+        if (resetFallbackMs === void 0) {
+          return null;
+        }
+        return {
+          remaining,
+          resetAt: new Date(Date.now() + resetFallbackMs)
+        };
+      }
+      if (resetRaw.trim() === "") {
+        return null;
+      }
+      const reset = Number(resetRaw);
+      if (!Number.isFinite(reset) || reset < 0) {
+        return null;
+      }
+      const resetMs = reset * multiplier;
+      if (!Number.isFinite(resetMs)) {
+        return null;
+      }
+      return { remaining, resetAt: new Date(resetMs) };
+    }
+  };
+}
+function sanitizeAllowedUrl(options) {
+  const { url, host, pathname, protocol = "https:" } = options;
+  if (url === null) {
+    return null;
+  }
+  try {
+    const u = new URL(url);
+    if (u.protocol !== protocol || u.host !== host || u.pathname !== pathname) {
+      return null;
+    }
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+function parseLinkHeader(header) {
+  if (!header) {
+    return {};
+  }
+  const result = {};
+  for (const part of header.split(",")) {
+    const match = part.match(/<([^>]+)>\s*;\s*rel="([^"]+)"/);
+    if (match) {
+      result[match[2]] = match[1];
+    }
+  }
+  return result;
+}
+
+// src/greenhouse.ts
+import {
+  BaseConnector,
+  defineConfigFields,
+  defineConnectorDoc,
+  defineResources,
+  makeChunkedCursorGuard,
+  paginateChunked,
+  schemasFromResources,
+  selectActivePhases
+} from "@rawdash/core";
+import { z } from "zod";
+var configFields = defineConfigFields(
+  z.object({
+    apiKey: z.object({ $secret: z.string() }).meta({
+      label: "Harvest API key",
+      description: "Greenhouse Harvest API key with read-only access. Create one at Configure -> Dev Center -> API Credential Management.",
+      placeholder: "ghr_...",
+      secret: true
+    }),
+    resources: z.array(
+      z.enum([
+        "jobs",
+        "candidates",
+        "applications",
+        "application_events",
+        "offers"
+      ])
+    ).nonempty().optional().meta({
+      label: "Resources",
+      description: "Which Greenhouse resources to sync. Omit to sync all resources. The Harvest key only needs Get / List permissions for the resources listed here."
+    })
+  })
+);
+var doc = defineConnectorDoc({
+  displayName: "Greenhouse",
+  category: "hr",
+  brandColor: "#24A47F",
+  tagline: "Sync jobs, candidates, applications, and offers from the Greenhouse Harvest API for hiring-funnel, time-to-hire, and offer-rate analytics.",
+  vendor: {
+    name: "Greenhouse",
+    apiDocs: "https://developers.greenhouse.io/harvest.html",
+    website: "https://www.greenhouse.com"
+  },
+  auth: {
+    summary: "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.",
+    setup: [
+      "Open Greenhouse -> Configure -> Dev Center -> API Credential Management.",
+      "Create a new Harvest API key with Get / List permissions for the resources you intend to sync (Candidates, Applications, Jobs, Offers).",
+      "Copy the key once on creation - Greenhouse never shows it again.",
+      'Store the key as a secret and reference it from config as `apiKey: secret("GREENHOUSE_API_KEY")`.'
+    ]
+  },
+  rateLimit: "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.",
+  limitations: [
+    "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.",
+    "Greenhouse Onboard data and Recruiting custom fields are out of scope."
+  ]
+});
+var cost = {
+  recommendedInterval: "1 hour",
+  minInterval: "15 minutes",
+  warning: "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."
+};
+var greenhouseCredentials = {
+  apiKey: {
+    description: "Greenhouse Harvest API key",
+    auth: "required"
+  }
+};
+var PHASE_ORDER = [
+  "jobs",
+  "candidates",
+  "applications",
+  "application_events",
+  "offers"
+];
+var isGreenhouseSyncCursor = makeChunkedCursorGuard(PHASE_ORDER);
+var PER_PAGE = 100;
+var API_HOST = "harvest.greenhouse.io";
+var API_BASE = `https://${API_HOST}`;
+var JOB_ENTITY = "greenhouse_job";
+var CANDIDATE_ENTITY = "greenhouse_candidate";
+var APPLICATION_ENTITY = "greenhouse_application";
+var OFFER_ENTITY = "greenhouse_offer";
+var APPLICATION_EVENT = "greenhouse_application_event";
+var greenhouseRateLimit = standardRateLimitPolicy({
+  remainingHeader: "x-ratelimit-remaining",
+  resetHeader: "x-ratelimit-reset",
+  resetUnit: "s"
+});
+function resourceToPhase(resource) {
+  return resource;
+}
+var jobSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  status: z.string().nullish(),
+  requisition_id: z.string().nullish(),
+  notes: z.string().nullish(),
+  confidential: z.boolean().nullish(),
+  is_template: z.boolean().nullish(),
+  copied_from_id: z.number().nullish(),
+  departments: z.array(z.object({ id: z.number().nullish(), name: z.string().nullish() })).nullish(),
+  offices: z.array(z.object({ id: z.number().nullish(), name: z.string().nullish() })).nullish(),
+  opened_at: z.string().nullish(),
+  closed_at: z.string().nullish(),
+  created_at: z.string().nullish(),
+  updated_at: z.string().nullish()
+});
+var candidateSchema = z.object({
+  id: z.number().int(),
+  first_name: z.string().nullish(),
+  last_name: z.string().nullish(),
+  company: z.string().nullish(),
+  title: z.string().nullish(),
+  is_private: z.boolean().nullish(),
+  application_ids: z.array(z.number()).nullish(),
+  created_at: z.string().nullish(),
+  updated_at: z.string().nullish(),
+  last_activity: z.string().nullish()
+});
+var applicationSchema = z.object({
+  id: z.number().int(),
+  candidate_id: z.number().int(),
+  status: z.string().nullish(),
+  current_stage: z.object({ id: z.number().nullish(), name: z.string().nullish() }).nullish(),
+  applied_at: z.string().nullish(),
+  rejected_at: z.string().nullish(),
+  last_activity_at: z.string().nullish(),
+  source: z.object({ id: z.number().nullish(), public_name: z.string().nullish() }).nullish(),
+  jobs: z.array(z.object({ id: z.number().nullish(), name: z.string().nullish() })).nullish()
+});
+var offerSchema = z.object({
+  id: z.number().int(),
+  application_id: z.number().nullish(),
+  candidate_id: z.number().nullish(),
+  job_id: z.number().nullish(),
+  status: z.string().nullish(),
+  created_at: z.string().nullish(),
+  sent_at: z.string().nullish(),
+  resolved_at: z.string().nullish(),
+  starts_at: z.string().nullish()
+});
+var greenhouseResources = defineResources({
+  [JOB_ENTITY]: {
+    shape: "entity",
+    description: "Open, draft, and closed requisitions with department, office, and timestamps for opened / closed transitions.",
+    endpoint: "GET /v1/jobs",
+    fields: [
+      { name: "name", description: "Job title." },
+      {
+        name: "status",
+        description: "Greenhouse job status (open / closed / draft)."
+      },
+      { name: "requisitionId", description: "External requisition id." },
+      {
+        name: "departments",
+        description: "Flat list of department names attached to the job."
+      },
+      {
+        name: "offices",
+        description: "Flat list of office names attached to the job."
+      },
+      { name: "openedAt", description: "When the job was opened (Unix ms)." },
+      { name: "closedAt", description: "When the job was closed (Unix ms)." },
+      { name: "confidential", description: "Whether the job is confidential." }
+    ],
+    responses: { jobs: z.array(jobSchema) }
+  },
+  [CANDIDATE_ENTITY]: {
+    shape: "entity",
+    description: "Candidate records with name, title, company, and the count of attached applications.",
+    endpoint: "GET /v1/candidates",
+    fields: [
+      { name: "firstName", description: "Candidate first name." },
+      { name: "lastName", description: "Candidate last name." },
+      { name: "title", description: "Candidate current job title." },
+      { name: "company", description: "Candidate current company." },
+      {
+        name: "applicationCount",
+        description: "Number of applications attached to the candidate. Useful for spotting repeat applicants."
+      },
+      {
+        name: "isPrivate",
+        description: "Whether the candidate is marked private."
+      },
+      {
+        name: "createdAt",
+        description: "When the candidate was created (Unix ms)."
+      },
+      {
+        name: "lastActivityAt",
+        description: "Last activity timestamp on the candidate (Unix ms)."
+      }
+    ],
+    responses: { candidates: z.array(candidateSchema) }
+  },
+  [APPLICATION_ENTITY]: {
+    shape: "entity",
+    description: "Applications with status (active / hired / rejected), current stage, source, and the linked candidate / job.",
+    endpoint: "GET /v1/applications",
+    fields: [
+      {
+        name: "candidateId",
+        description: "Candidate the application belongs to."
+      },
+      {
+        name: "jobId",
+        description: "Primary job the application is attached to."
+      },
+      { name: "jobName", description: "Primary job name at sync time." },
+      {
+        name: "status",
+        description: "Application status (active / hired / rejected)."
+      },
+      {
+        name: "currentStage",
+        description: 'Name of the current stage (e.g. "Phone Screen").'
+      },
+      {
+        name: "source",
+        description: 'Public source name where the application originated (e.g. "LinkedIn").'
+      },
+      { name: "appliedAt", description: "When the application was submitted." },
+      {
+        name: "rejectedAt",
+        description: "When the application was rejected (null if not)."
+      },
+      {
+        name: "hiredAt",
+        description: "When the application was hired (derived from last_activity_at when status=hired)."
+      },
+      {
+        name: "lastActivityAt",
+        description: "Last activity timestamp on the application (Unix ms)."
+      }
+    ],
+    responses: { applications: z.array(applicationSchema) }
+  },
+  [APPLICATION_EVENT]: {
+    shape: "event",
+    description: "Application lifecycle events (applied / hired / rejected) derived from each application timestamps. The scope is cleared and rewritten on every sync (including incremental runs).",
+    endpoint: "GET /v1/applications",
+    notes: "Derived from each application's applied_at / rejected_at / last_activity_at fields, not from a separate API call.",
+    fields: [
+      {
+        name: "applicationId",
+        description: "Application the event belongs to."
+      },
+      { name: "candidateId", description: "Candidate id, denormalised." },
+      { name: "jobId", description: "Job id, denormalised." },
+      {
+        name: "transition",
+        description: '"applied", "hired", or "rejected".'
+      },
+      {
+        name: "source",
+        description: "Application source name at the time of the event."
+      }
+    ],
+    responses: { application_events: z.array(applicationSchema) }
+  },
+  [OFFER_ENTITY]: {
+    shape: "entity",
+    description: "Offers with status (pending / accepted / rejected), linked to their application, candidate, and job.",
+    endpoint: "GET /v1/offers",
+    fields: [
+      { name: "applicationId", description: "Linked application." },
+      { name: "candidateId", description: "Linked candidate." },
+      { name: "jobId", description: "Linked job." },
+      {
+        name: "status",
+        description: "Offer status (pending / accepted / rejected)."
+      },
+      { name: "sentAt", description: "When the offer was sent (Unix ms)." },
+      {
+        name: "resolvedAt",
+        description: "When the offer was accepted or rejected (Unix ms; null while pending)."
+      },
+      {
+        name: "startsAt",
+        description: "Proposed start date on the offer (Unix ms)."
+      }
+    ],
+    responses: { offers: z.array(offerSchema) }
+  }
+});
+function isoToMs(value) {
+  if (!value) {
+    return null;
+  }
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+function isoToMsOrZero(value) {
+  return isoToMs(value) ?? 0;
+}
+function listNames(items) {
+  if (!items) {
+    return [];
+  }
+  const names = [];
+  for (const item of items) {
+    if (item && typeof item.name === "string" && item.name !== "") {
+      names.push(item.name);
+    }
+  }
+  return names;
+}
+function primaryJobId(app) {
+  const first = app.jobs?.[0];
+  if (!first || first.id === null || first.id === void 0) {
+    return null;
+  }
+  return first.id;
+}
+function primaryJobName(app) {
+  return app.jobs?.[0]?.name ?? null;
+}
+function hiredAtMs(app) {
+  if (app.status !== "hired") {
+    return null;
+  }
+  return isoToMs(app.last_activity_at);
+}
+var id = "greenhouse";
+var GreenhouseConnector = class _GreenhouseConnector extends BaseConnector {
+  static id = id;
+  static resources = greenhouseResources;
+  static schemas = schemasFromResources(greenhouseResources);
+  static cost = cost;
+  static create(input, ctx) {
+    const parsed = configFields.parse(input);
+    return new _GreenhouseConnector(
+      { resources: parsed.resources },
+      { apiKey: parsed.apiKey },
+      ctx
+    );
+  }
+  id = id;
+  credentials = greenhouseCredentials;
+  buildHeaders() {
+    const basic = btoa(`${this.creds.apiKey}:`);
+    return {
+      Authorization: `Basic ${basic}`,
+      Accept: "application/json",
+      "User-Agent": connectorUserAgent("greenhouse")
+    };
+  }
+  apiGet(url, resource, signal) {
+    return this.get(url, {
+      resource,
+      headers: this.buildHeaders(),
+      signal,
+      rateLimit: greenhouseRateLimit
+    });
+  }
+  allowedPagePath(phase) {
+    switch (phase) {
+      case "jobs":
+        return "/v1/jobs";
+      case "candidates":
+        return "/v1/candidates";
+      case "applications":
+      case "application_events":
+        return "/v1/applications";
+      case "offers":
+        return "/v1/offers";
+    }
+  }
+  sanitizePageUrl(phase, pageUrl) {
+    return sanitizeAllowedUrl({
+      url: pageUrl,
+      host: API_HOST,
+      pathname: this.allowedPagePath(phase)
+    });
+  }
+  resolveCursor(cursor) {
+    if (!isGreenhouseSyncCursor(cursor)) {
+      return void 0;
+    }
+    if (cursor.phase === "application_events") {
+      return { phase: cursor.phase, page: null };
+    }
+    return {
+      phase: cursor.phase,
+      page: this.sanitizePageUrl(cursor.phase, cursor.page)
+    };
+  }
+  // Build the initial-page URL for a phase. Subsequent pages come from the
+  // Link header, validated through sanitizeAllowedUrl above.
+  buildInitialUrl(phase, options) {
+    const url = new URL(`${API_BASE}${this.allowedPagePath(phase)}`);
+    url.searchParams.set("per_page", String(PER_PAGE));
+    if (phase !== "application_events" && options.since) {
+      url.searchParams.set("updated_after", options.since);
+    }
+    return url.toString();
+  }
+  // -------------------------------------------------------------------------
+  // Page fetchers
+  // -------------------------------------------------------------------------
+  async fetchPhasePage(phase, page, options, signal) {
+    const resource = phase === "application_events" ? "application_events" : phase;
+    const url = page ?? this.buildInitialUrl(phase, options);
+    const res = await this.apiGet(url, resource, signal);
+    const rawNext = parseLinkHeader(res.headers.get("link"))["next"] ?? null;
+    const next = this.sanitizePageUrl(phase, rawNext);
+    return { items: res.body ?? [], next };
+  }
+  // -------------------------------------------------------------------------
+  // Writers
+  // -------------------------------------------------------------------------
+  async writeJobs(storage, items) {
+    for (const job of items) {
+      await storage.entity({
+        type: JOB_ENTITY,
+        id: String(job.id),
+        attributes: {
+          name: job.name,
+          status: job.status ?? null,
+          requisitionId: job.requisition_id ?? null,
+          confidential: job.confidential ?? null,
+          departments: listNames(job.departments),
+          offices: listNames(job.offices),
+          openedAt: isoToMs(job.opened_at),
+          closedAt: isoToMs(job.closed_at),
+          createdAt: isoToMs(job.created_at)
+        },
+        updated_at: isoToMsOrZero(job.updated_at ?? job.created_at)
+      });
+    }
+  }
+  async writeCandidates(storage, items) {
+    for (const cand of items) {
+      await storage.entity({
+        type: CANDIDATE_ENTITY,
+        id: String(cand.id),
+        attributes: {
+          firstName: cand.first_name ?? null,
+          lastName: cand.last_name ?? null,
+          title: cand.title ?? null,
+          company: cand.company ?? null,
+          applicationCount: cand.application_ids?.length ?? 0,
+          isPrivate: cand.is_private ?? null,
+          createdAt: isoToMs(cand.created_at),
+          lastActivityAt: isoToMs(cand.last_activity)
+        },
+        updated_at: isoToMsOrZero(
+          cand.updated_at ?? cand.last_activity ?? cand.created_at
+        )
+      });
+    }
+  }
+  async writeApplications(storage, items) {
+    for (const app of items) {
+      const attributes = {
+        candidateId: String(app.candidate_id),
+        jobId: primaryJobId(app) === null ? null : String(primaryJobId(app)),
+        jobName: primaryJobName(app),
+        status: app.status ?? null,
+        currentStage: app.current_stage?.name ?? null,
+        source: app.source?.public_name ?? null,
+        appliedAt: isoToMs(app.applied_at),
+        rejectedAt: isoToMs(app.rejected_at),
+        hiredAt: hiredAtMs(app),
+        lastActivityAt: isoToMs(app.last_activity_at)
+      };
+      await storage.entity({
+        type: APPLICATION_ENTITY,
+        id: String(app.id),
+        attributes,
+        updated_at: isoToMsOrZero(
+          app.last_activity_at ?? app.applied_at ?? app.rejected_at
+        )
+      });
+    }
+  }
+  async writeApplicationEvents(storage, items) {
+    for (const app of items) {
+      const base = {
+        applicationId: String(app.id),
+        candidateId: String(app.candidate_id),
+        jobId: primaryJobId(app) === null ? null : String(primaryJobId(app)),
+        source: app.source?.public_name ?? null
+      };
+      const appliedMs = isoToMs(app.applied_at);
+      if (appliedMs !== null) {
+        await storage.event({
+          name: APPLICATION_EVENT,
+          start_ts: appliedMs,
+          end_ts: null,
+          attributes: { ...base, transition: "applied" }
+        });
+      }
+      const rejectedMs = isoToMs(app.rejected_at);
+      if (rejectedMs !== null) {
+        await storage.event({
+          name: APPLICATION_EVENT,
+          start_ts: rejectedMs,
+          end_ts: null,
+          attributes: { ...base, transition: "rejected" }
+        });
+      }
+      const hiredMs = hiredAtMs(app);
+      if (hiredMs !== null) {
+        await storage.event({
+          name: APPLICATION_EVENT,
+          start_ts: hiredMs,
+          end_ts: null,
+          attributes: { ...base, transition: "hired" }
+        });
+      }
+    }
+  }
+  async writeOffers(storage, items) {
+    for (const offer of items) {
+      await storage.entity({
+        type: OFFER_ENTITY,
+        id: String(offer.id),
+        attributes: {
+          applicationId: offer.application_id === null || offer.application_id === void 0 ? null : String(offer.application_id),
+          candidateId: offer.candidate_id === null || offer.candidate_id === void 0 ? null : String(offer.candidate_id),
+          jobId: offer.job_id === null || offer.job_id === void 0 ? null : String(offer.job_id),
+          status: offer.status ?? null,
+          sentAt: isoToMs(offer.sent_at),
+          resolvedAt: isoToMs(offer.resolved_at),
+          startsAt: isoToMs(offer.starts_at)
+        },
+        updated_at: isoToMsOrZero(
+          offer.resolved_at ?? offer.sent_at ?? offer.created_at
+        )
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Scope clearing
+  // -------------------------------------------------------------------------
+  async clearScopeOnFirstPage(storage, phase, isFull) {
+    if (phase === "application_events") {
+      await storage.events([], { names: [APPLICATION_EVENT] });
+      return;
+    }
+    if (!isFull) {
+      return;
+    }
+    const entityType = ENTITY_TYPE_BY_PHASE[phase];
+    if (entityType) {
+      await storage.entities([], { types: [entityType] });
+    }
+  }
+  async writePhase(storage, phase, items) {
+    switch (phase) {
+      case "jobs":
+        return this.writeJobs(storage, items);
+      case "candidates":
+        return this.writeCandidates(storage, items);
+      case "applications":
+        return this.writeApplications(storage, items);
+      case "application_events":
+        return this.writeApplicationEvents(
+          storage,
+          items
+        );
+      case "offers":
+        return this.writeOffers(storage, items);
+    }
+  }
+  async sync(options, storage, signal) {
+    const cursor = this.resolveCursor(options.cursor);
+    const isFull = options.mode === "full";
+    const phases = selectActivePhases(
+      resourceToPhase,
+      PHASE_ORDER,
+      this.settings.resources
+    );
+    return paginateChunked({
+      phases,
+      cursor,
+      signal,
+      logger: this.logger,
+      fetchPage: async (phase, page, sig) => this.fetchPhasePage(phase, page, options, sig),
+      writeBatch: async (phase, items, page) => {
+        if (page === null) {
+          await this.clearScopeOnFirstPage(storage, phase, isFull);
+        }
+        await this.writePhase(storage, phase, items);
+      }
+    });
+  }
+};
+var ENTITY_TYPE_BY_PHASE = {
+  jobs: JOB_ENTITY,
+  candidates: CANDIDATE_ENTITY,
+  applications: APPLICATION_ENTITY,
+  offers: OFFER_ENTITY
+};
+
+// src/index.ts
+var index_default = GreenhouseConnector;
+export {
+  GreenhouseConnector,
+  configFields,
+  cost,
+  index_default as default,
+  doc,
+  id,
+  greenhouseResources as resources
+};
+//# sourceMappingURL=index.js.map