@getvitops/utils 8.1.0 → 8.2.0-alpha.0

package/dist/crm/index.d.mts

@@ -0,0 +1,288 @@
+import { t as ConversionEvent } from "../types-7ELci8RQ.mjs";
+//#region src/crm/types.d.ts
+/**
+ * The CRM module's own option surface.
+ *
+ * Deliberately structural rather than `Config['site']['crm']` imported from
+ * `@getvitops/generator`: the generator already depends on this package, so
+ * importing back would be a cycle. The vocabulary mirrors that block field for
+ * field — the same arrangement, and for the same reason, as `IndexingConfig`
+ * and `NotifyContext` beside it.
+ *
+ * Optional fields are written `?: T | undefined` throughout: `exactOptionalPropertyTypes`
+ * is on, and these describe a *parsed JSON config* where an absent key and an
+ * explicit `undefined` are the same thing.
+ */
+type CrmProvider = 'hubspot' | 'bigin' | 'jobber';
+/** Human-readable label per provider, for the notification email's Delivery
+ * line (`describeCrmResult`) and anywhere else a provider must be named
+ * without a hand-written ternary. Exhaustive by type — a provider missing
+ * here is a compile error, not a mislabelled email. */
+export declare const PROVIDER_LABELS: Record<CrmProvider, string>;
+/** Bigin's data centre — the region a self-client's tokens and API host belong to. */
+type BiginDataCenter = 'com' | 'ca' | 'eu' | 'in' | 'com.au' | 'jp';
+interface HubSpotConfig {
+  portalId: string;
+  formGuid: string;
+  /** Default `na`. Only affects the submissions API host. */
+  dataCenter?: 'na' | 'eu' | undefined;
+}
+interface BiginPipelineConfig {
+  enabled: boolean;
+  subPipeline?: string | undefined;
+  stage?: string | undefined;
+}
+interface BiginConfig {
+  dataCenter: BiginDataCenter;
+  /** Default `Email` — Bigin's own unique field, used for `upsert`'s dedupe. */
+  duplicateCheckField?: string | undefined;
+  pipeline?: BiginPipelineConfig | undefined;
+}
+interface JobberConfig {
+  /**
+   * The pinned `X-JOBBER-GRAPHQL-VERSION` date this integration was built and
+   * tested against. Overriding it is an escape hatch for a client's app
+   * pinned to a different version — not something to reach for casually,
+   * since Jobber's schema can change field names between versions.
+   */
+  apiVersion?: string | undefined;
+  /**
+   * Look up an existing client by email before creating one (default
+   * **false**). Jobber's `clientCreate` has no upsert, so a resubmitting
+   * visitor creates a second client unless this runs — but the lookup query's
+   * filter shape is not yet verified against a live Jobber schema (see
+   * `jobber.ts`'s docblock), so it defaults off rather than risk a wrong
+   * query silently blocking a real submission. Set `true` once verified for
+   * your account.
+   */
+  dedupe?: boolean | undefined;
+  note?: {
+    /** Attach a best-effort note carrying the message + unmapped
+     * attribution (default true). A failure here never downgrades the
+     * client write's own success — see `jobber.ts`. */
+    enabled?: boolean | undefined;
+  } | undefined;
+}
+interface CrmConfig {
+  provider: CrmProvider;
+  enabled?: boolean | undefined;
+  hubspot?: HubSpotConfig | undefined;
+  bigin?: BiginConfig | undefined;
+  jobber?: JobberConfig | undefined;
+  /** Submitted field name → CRM property name. Unmapped fields are dropped, not guessed. */
+  fieldMap?: Record<string, string> | undefined;
+  /** `_ac` tracking key → CRM property name. Same drop-if-unmapped rule. */
+  trackingFields?: Record<string, string> | undefined;
+}
+/** Credentials, never config — always injected by the caller from env vars. */
+interface HubSpotCredentials {
+  accessToken: string;
+}
+interface BiginCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Jobber's self-client OAuth credential. The refresh token is expected to be
+ * static — Refresh Token Rotation must be OFF in the app's Developer Center
+ * settings, since a Worker reading a static env var cannot persist a rotated
+ * one. See `jobber-token.ts` for the detection when a client's app has it on
+ * anyway.
+ */
+interface JobberCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+type CrmCredentials = {
+  provider: 'hubspot';
+  hubspot: HubSpotCredentials;
+} | {
+  provider: 'bigin';
+  bigin: BiginCredentials;
+} | {
+  provider: 'jobber';
+  jobber: JobberCredentials;
+};
+/** A channel's decision: on, or off with a stated reason. Mirrors `ChannelPlan`. */
+interface CrmPlan {
+  enabled: boolean;
+  provider?: CrmProvider | undefined;
+  /** Why it's off. Present iff `enabled` is false. */
+  skip?: string | undefined;
+}
+/** A provider-neutral record — what a submission maps to, before either executor
+ * renders it into that CRM's own request shape. */
+interface CrmRecord {
+  firstName?: string | undefined;
+  lastName?: string | undefined;
+  email?: string | undefined;
+  phone?: string | undefined;
+  company?: string | undefined;
+  message?: string | undefined;
+  /** Mapped fields beyond the identity ones above, keyed by the CRM property name. */
+  extra: Record<string, string>;
+  /** `trackingFields`-mapped attribution, keyed by the CRM property name. Empty
+   * when the visitor arrived with no `_ac` cookie — never an error. */
+  attribution: Record<string, string>;
+}
+/**
+ * The outcome of one delivery attempt. Never thrown — a CRM write is
+ * best-effort and its failure is a fact for the caller to log or notify with,
+ * not an exception to propagate into the request that produced the submission.
+ */
+interface CrmResult {
+  ok: boolean;
+  provider: CrmProvider;
+  /** The created/updated record's id, when the CRM returned one. */
+  recordId?: string | undefined;
+  /** Why it didn't write, or what the classification of the failure was. */
+  reason?: string | undefined;
+  /** The provider's own error/status code, when it gave one. */
+  code?: string | undefined;
+}
+//#endregion
+//#region src/crm/hubspot.d.ts
+interface HubSpotSubmitContext {
+  hutk?: string | undefined;
+  pageUri?: string | undefined;
+  pageName?: string | undefined;
+}
+/**
+ * Submit one record to HubSpot's secure forms endpoint.
+ *
+ * Never throws — a network failure or an unparsable response both come back
+ * as a `CrmResult` with `ok: false`, the same "structured result, not an
+ * exception" rule `security/turnstile.ts` and `indexing/gsc.ts` follow. Status
+ * classification: 401 is a rejected/expired token; 400 naming
+ * `MISSING_REQUIRED_FIELDS` or an unrecognised field name is a mapping
+ * problem (`fieldMap`/`trackingFields` naming a property that isn't on the
+ * form); 429 is the per-portal rate limit.
+ */
+export declare function submitToHubSpot(record: CrmRecord, config: HubSpotConfig, credentials: HubSpotCredentials, context?: HubSpotSubmitContext, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/map.d.ts
+/**
+ * Bigin requires `Last_Name`; a form that only asked for a full name or an
+ * email needs one derived rather than 400ing on insert.
+ *
+ * The fallback chain, in order: an explicit last name field → the last space-
+ * separated token of a full name → the local part of the email address →
+ * refuse, with a stated reason, rather than fabricate a name from nothing.
+ * `map.ts` never emits an empty `lastName` for Bigin — `deliverToCrm` reads
+ * the refusal and skips the write instead of letting the CRM reject it.
+ */
+export declare function deriveLastName(identity: {
+  firstName?: string | undefined;
+  lastName?: string | undefined;
+  fullName: string;
+  email?: string | undefined;
+}): {
+  lastName: string;
+} | {
+  refusal: string;
+};
+export declare function mapSubmission(event: ConversionEvent, config: CrmConfig): CrmRecord;
+//#endregion
+//#region src/crm/plan.d.ts
+export declare function planCrm(config: CrmConfig | undefined, credentials: CrmCredentials | undefined): CrmPlan;
+//#endregion
+//#region src/crm/bigin.d.ts
+export declare function zohoApiHost(dataCenter: string): string;
+/**
+ * Write one record to Bigin. Never throws — a token-exchange failure, a
+ * network error and a rejected response all come back as `CrmResult`.
+ */
+export declare function submitToBigin(record: CrmRecord, config: BiginConfig, credentials: BiginCredentials, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/jobber.d.ts
+/**
+ * Write one record to Jobber. Never throws — a token-exchange failure, a
+ * network error, a top-level GraphQL `errors[]`, and a `userErrors[]` all
+ * come back as a `CrmResult` with `ok: false`.
+ */
+export declare function submitToJobber(record: CrmRecord, config: JobberConfig, credentials: JobberCredentials, pageUri: string | undefined, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/zoho-token.d.ts
+export declare function zohoAccountsHost(dataCenter: string): string;
+interface ZohoOAuth {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Exchange a refresh token for a short-lived Bigin access token, reusing a
+ * cached one while it's still valid.
+ *
+ * `now` is a parameter so cache expiry is testable without a fake clock, the
+ * same convention `google/token.ts`'s `googleAccessToken` uses.
+ */
+export declare function zohoAccessToken(oauth: ZohoOAuth, dataCenter: string, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+/** Test-only: clear the module-level cache between cases. */
+export declare function clearZohoTokenCache(): void;
+//#endregion
+//#region src/crm/jobber-token.d.ts
+/**
+ * Jobber OAuth2 refresh-token exchange.
+ *
+ * A plain `application/x-www-form-urlencoded` POST, same shape as Zoho's —
+ * see `zoho-token.ts` for why that keeps this Worker-safe (no `node:crypto`,
+ * unlike `google/token.ts`'s service-account JWT).
+ *
+ * One thing Zoho's grant never does: Jobber's Refresh Token Rotation is ON by
+ * default for a new app, and when it's on, every exchange returns a *new*
+ * refresh token and invalidates the old one. A Worker reading a static env
+ * var (`VITOPS_JOBBER_REFRESH_TOKEN`) cannot persist that new value, so this
+ * integration requires rotation turned OFF in the app's Developer Center
+ * settings — a legitimate setup requirement, since a per-client private app
+ * is never published to Jobber's Marketplace (where rotation ON is
+ * mandatory). `zohoAccessToken`'s Zoho equivalent has no such failure mode to
+ * detect, because Zoho's grant is long-lived by default.
+ *
+ * Cached per isolate, keyed on the refresh token, with an expiry margin —
+ * same rationale as `zoho-token.ts`.
+ */
+interface JobberOAuth {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Exchange a refresh token for a short-lived Jobber access token, reusing a
+ * cached one while it's still valid.
+ *
+ * Throws a specific, actionable error when Jobber's response carries a
+ * *different* refresh token than the one sent — the rotation case above.
+ * Without this check, rotation surfaces an hour later as an opaque 401 on a
+ * lead that is already lost; with it, the first submission after rotation
+ * turns on names the fix.
+ *
+ * `now` is a parameter so cache expiry is testable without a fake clock, the
+ * same convention `zoho-token.ts`'s `zohoAccessToken` uses.
+ */
+export declare function jobberAccessToken(oauth: JobberOAuth, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+/** Test-only: clear the module-level cache between cases. */
+export declare function clearJobberTokenCache(): void;
+//#endregion
+//#region src/crm/index.d.ts
+export interface CrmDeps {
+  credentials?: CrmCredentials | undefined;
+  fetch?: typeof fetch | undefined;
+  timeoutMs?: number | undefined;
+  /**
+   * The visitor's page context, provider-neutral. HubSpot reads `hutk` (its
+   * own session cookie) to stitch the submission to its tracking; Jobber
+   * reads `pageUri` for the note body. Not every provider uses every field —
+   * an unused one is simply ignored, which is why this is one shape rather
+   * than a per-provider option the caller has to pick correctly.
+   */
+  pageContext?: HubSpotSubmitContext | undefined;
+}
+export declare function deliverToCrm(event: ConversionEvent, config: CrmConfig | undefined, deps?: CrmDeps): Promise<CrmResult | null>;
+/** A one-line, human-readable delivery note — what `conversion.ts` folds into
+ * the notification email's "Delivery" section. */
+export declare function describeCrmResult(result: CrmResult | null): string | null;
+//#endregion
+export type { BiginConfig, BiginCredentials, BiginDataCenter, BiginPipelineConfig, CrmConfig, CrmCredentials, CrmPlan, CrmProvider, CrmRecord, CrmResult, HubSpotConfig, HubSpotCredentials, HubSpotSubmitContext, JobberConfig, JobberCredentials, JobberOAuth };
+//# sourceMappingURL=index.d.mts.map

package/dist/crm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/crm/types.ts","../../src/crm/hubspot.ts","../../src/crm/map.ts","../../src/crm/plan.ts","../../src/crm/bigin.ts","../../src/crm/jobber.ts","../../src/crm/zoho-token.ts","../../src/crm/jobber-token.ts","../../src/crm/index.ts"],"mappings":";;;;;;;;;;;;;;;KAcY;;;;;qBAMC,iBAAiB,OAAO;;KAOzB;UAEK;EACf;EACA;;EAEA;;UAGe;EACf;EACA;EACA;;UAGe;EACf,YAAY;;EAEZ;EACA,WAAW;;UAGI;;;;;;;EAOf;;;;;;;;;;EAUA;EACA;;;;IAKM;;;UAKS;EACf,UAAU;EACV;EACA,UAAU;EACV,QAAQ;EACR,SAAS;;EAET,WAAW;;EAEX,iBAAiB;;;UAIF;EACf;;UAGe;EACf;EACA;EACA;;;;;;;;;UAUe;EACf;EACA;EACA;;KAGU;EACN;EAAqB,SAAS;;EAC9B;EAAmB,OAAO;;EAC1B;EAAoB,QAAQ;;;UAGjB;EACf;EACA,WAAW;;EAEX;;;;UAKe;EACf;EACA;EACA;EACA;EACA;EACA;;EAEA,OAAO;;;EAGP,aAAa;;;;;;;UAQE;EACf;EACA,UAAU;;EAEV;;EAEA;;EAEA;;;;UCjHe;EACf;EACA;EACA;;;;;;;;;;;;;wBAcoB,gBACpB,QAAQ,WACR,QAAQ,eACR,aAAa,oBACb,UAAS,sBACT,mBAAkB,OAClB,qBACC,QAAQ;;;;;;;;;;;;;wBCtCK,eAAe;EAC7B;EACA;EACA;EACA;;EACI;;EAAuB;;wBAgDb,cAAc,OAAO,iBAAiB,QAAQ,YAAY;;;wBC/C1D,QACd,QAAQ,uBACR,aAAa,6BACZ;;;wBCba,YAAY;;;;;wBAsBN,cACpB,QAAQ,WACR,QAAQ,aACR,aAAa,kBACb,mBAAkB,OAClB,qBACC,QAAQ;;;;;;;;wBCoJW,eACpB,QAAQ,WACR,QAAQ,cACR,aAAa,mBACb,6BACA,mBAAkB,OAClB,qBACC,QAAQ;;;wBCpLK,iBAAiB;UAehB;EACf;EACA;EACA;;;;;;;;;wBAUoB,gBACpB,OAAO,WACP,oBACA,mBAAkB,OAClB,eACC;;wBAkCa;;;;;;;;;;;;;;;;;;;;;;;UC3DC;EACf;EACA;EACA;;;;;;;;;;;;;;;wBAgBoB,kBACpB,OAAO,aACP,mBAAkB,OAClB,eACC;;wBA8Ca;;;iBCvEC;EACf,cAAc;EACd,eAAe;EACf;;;;;;;;EAQA,cAAc;;wBAGM,aACpB,OAAO,iBACP,QAAQ,uBACR,OAAM,UACL,QAAQ;;;wBAwDK,kBAAkB,QAAQ"}