@ever-works/hubspot-connector-plugin 1.0.0
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.
- package/README.md +55 -0
- package/dist/index.cjs +487 -0
- package/dist/index.d.cts +157 -0
- package/dist/index.d.ts +157 -0
- package/dist/index.js +471 -0
- package/package.json +116 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { IConnectorPlugin, IEventSourcePlugin, PluginCategory, ConnectorMetadata, JsonSchema, ChannelTargetConfig, ConnectorCallOptions, ChannelVerification, ChannelSendInput, ChannelSendResult, ConnectorRecordInput, ConnectorRecordResult, EventSourcePullInput, EventSourcePullResult, PluginSettings } from '@ever-works/plugin';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Payload text cap for ingested envelopes. Envelope payloads are
|
|
5
|
+
* size-capped platform-side (32 KB serialized); a CRM property value
|
|
6
|
+
* never needs more than this to be useful in Memory/Activities.
|
|
7
|
+
*/
|
|
8
|
+
declare const HUBSPOT_EVENT_TEXT_MAX_CHARS = 4000;
|
|
9
|
+
/** Records requested per HubSpot search page. */
|
|
10
|
+
declare const HUBSPOT_PULL_PAGE_SIZE = 50;
|
|
11
|
+
/**
|
|
12
|
+
* Historical backfill bound: at most this many search pages per phase
|
|
13
|
+
* (per CRM object type) during the opt-in first-pull backfill, so a
|
|
14
|
+
* large portal can never turn activation into an unbounded crawl.
|
|
15
|
+
*/
|
|
16
|
+
declare const HUBSPOT_BACKFILL_MAX_PAGES = 10;
|
|
17
|
+
/** Object types swept when `objectTypes` is left empty. */
|
|
18
|
+
declare const HUBSPOT_DEFAULT_OBJECT_TYPES: readonly ["contacts", "companies", "deals"];
|
|
19
|
+
/** Per-object-type ingest/deep-link metadata. */
|
|
20
|
+
interface HubSpotObjectMeta {
|
|
21
|
+
/** Envelope `kind` (source-namespaced, singular). */
|
|
22
|
+
readonly kind: string;
|
|
23
|
+
/** Property carrying the record's last-modified timestamp. */
|
|
24
|
+
readonly lastModifiedProperty: string;
|
|
25
|
+
/** Properties requested from search (also the payload whitelist). */
|
|
26
|
+
readonly properties: readonly string[];
|
|
27
|
+
/** Numeric object-type id used in HubSpot record deep links. */
|
|
28
|
+
readonly objectTypeId?: string;
|
|
29
|
+
/**
|
|
30
|
+
* `associationTypeId` for a HUBSPOT_DEFINED note → record
|
|
31
|
+
* association. Absent means outbound notes are unsupported for the
|
|
32
|
+
* type and `send` fails loudly rather than writing an orphan note.
|
|
33
|
+
*/
|
|
34
|
+
readonly noteAssociationTypeId?: number;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Known first-class CRM object types. Custom objects still work — they
|
|
38
|
+
* fall back to {@link GENERIC_OBJECT_META} (the `hs_lastmodifieddate`
|
|
39
|
+
* property every HubSpot object carries).
|
|
40
|
+
*/
|
|
41
|
+
declare const HUBSPOT_OBJECT_META: Readonly<Record<string, HubSpotObjectMeta>>;
|
|
42
|
+
/** Metadata for a type, falling back to the generic custom-object shape. */
|
|
43
|
+
declare function objectMeta(objectType: string): HubSpotObjectMeta;
|
|
44
|
+
/** Clamp the opt-in backfill window to the supported 0–90 day range. */
|
|
45
|
+
declare function clampBackfillDays(value: unknown): number;
|
|
46
|
+
/** Parse the object-type list: comma/space separated → array (defaulted). */
|
|
47
|
+
declare function resolveObjectTypes(settings: PluginSettings | undefined): string[];
|
|
48
|
+
/** Minimal shape of a CRM record the search API returns. */
|
|
49
|
+
interface HubSpotRecord {
|
|
50
|
+
id?: string;
|
|
51
|
+
properties?: Record<string, unknown>;
|
|
52
|
+
createdAt?: Date | string;
|
|
53
|
+
updatedAt?: Date | string;
|
|
54
|
+
archived?: boolean;
|
|
55
|
+
}
|
|
56
|
+
interface HubSpotSearchPage {
|
|
57
|
+
results?: HubSpotRecord[];
|
|
58
|
+
paging?: {
|
|
59
|
+
next?: {
|
|
60
|
+
after?: string;
|
|
61
|
+
};
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
/** The subset of the `@hubspot/api-client` surface this plugin calls. */
|
|
65
|
+
interface HubSpotClientLike {
|
|
66
|
+
crm: {
|
|
67
|
+
objects: {
|
|
68
|
+
basicApi: {
|
|
69
|
+
create(objectType: string, input: Record<string, unknown>): Promise<{
|
|
70
|
+
id?: string;
|
|
71
|
+
}>;
|
|
72
|
+
getPage(objectType: string, limit?: number): Promise<HubSpotSearchPage>;
|
|
73
|
+
};
|
|
74
|
+
searchApi: {
|
|
75
|
+
doSearch(objectType: string, request: Record<string, unknown>): Promise<HubSpotSearchPage>;
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Resolve which CRM record an outbound note attaches to. A per-send
|
|
82
|
+
* `associatedObjectId` overrides the connection default; the resolved
|
|
83
|
+
* plugin `settings` default is the final fallback.
|
|
84
|
+
*/
|
|
85
|
+
declare function resolveNoteTarget(config: ChannelTargetConfig, options: ConnectorCallOptions): {
|
|
86
|
+
objectType: string;
|
|
87
|
+
objectId: string;
|
|
88
|
+
};
|
|
89
|
+
/** Best-effort human title for a record, per object type. */
|
|
90
|
+
declare function recordTitle(objectType: string, properties: Record<string, unknown> | undefined): string | undefined;
|
|
91
|
+
/**
|
|
92
|
+
* HubSpot CRM connector — first-party native connector.
|
|
93
|
+
*
|
|
94
|
+
* Outbound: `send` appends a Note engagement to a CRM record and
|
|
95
|
+
* `createRecord` writes a contact / company / deal (or a custom
|
|
96
|
+
* object) through the official `@hubspot/api-client` (private-app
|
|
97
|
+
* token auth; the SDK pins the API host, so there is no SSRF surface).
|
|
98
|
+
*
|
|
99
|
+
* Event source: `pullEvents` sweeps each configured CRM object type in
|
|
100
|
+
* turn via the Search API, filtered server-side on the type's
|
|
101
|
+
* last-modified property, normalized into `IngestedEventEnvelope`s
|
|
102
|
+
* (`hubspot.contact` / `.company` / `.deal` / `.record`) for the
|
|
103
|
+
* platform's event-ingest spine. When a `portalId` is configured every
|
|
104
|
+
* envelope carries a record deep link as `sourceUrl`. The opt-in
|
|
105
|
+
* historical backfill (`backfillDays`, default 0 = off, max 90) widens
|
|
106
|
+
* the FIRST pull's window only, with a per-phase page bound so
|
|
107
|
+
* activation never becomes an unbounded crawl. Re-delivery across
|
|
108
|
+
* overlapping windows is fine — the ingest pipeline dedupes on
|
|
109
|
+
* `(source, sourceEventId)`.
|
|
110
|
+
*
|
|
111
|
+
* Unconfigured is always LOUD: `verifyConnection` reports the missing
|
|
112
|
+
* token, `send`/`createRecord` throw, and `pullEvents` throws
|
|
113
|
+
* `EventSourceNotConfiguredError`. Nothing silently no-ops.
|
|
114
|
+
*/
|
|
115
|
+
declare class HubSpotConnectorPlugin implements IConnectorPlugin, IEventSourcePlugin {
|
|
116
|
+
readonly id = "hubspot-connector";
|
|
117
|
+
readonly name = "HubSpot Connector";
|
|
118
|
+
readonly version = "1.0.0";
|
|
119
|
+
readonly category: PluginCategory;
|
|
120
|
+
readonly capabilities: readonly ["connector", "connector-hubspot", "event-source"];
|
|
121
|
+
readonly providerName = "hubspot";
|
|
122
|
+
readonly connector: ConnectorMetadata;
|
|
123
|
+
readonly settingsSchema: JsonSchema;
|
|
124
|
+
private readonly idempotencyCache;
|
|
125
|
+
private readonly recordIdempotencyCache;
|
|
126
|
+
onLoad(): Promise<void>;
|
|
127
|
+
onUnload(): Promise<void>;
|
|
128
|
+
/** Testable seam — specs stub this; production uses the real SDK. */
|
|
129
|
+
protected createClient(accessToken: string): HubSpotClientLike;
|
|
130
|
+
verifyConnection(config: ChannelTargetConfig, options: ConnectorCallOptions): Promise<ChannelVerification>;
|
|
131
|
+
/** Outbound leg — append a Note engagement to a CRM record. */
|
|
132
|
+
send(payload: ChannelSendInput, options: ConnectorCallOptions): Promise<ChannelSendResult>;
|
|
133
|
+
/** Outbound record leg — create a CRM record of any object type. */
|
|
134
|
+
createRecord(record: ConnectorRecordInput, options: ConnectorCallOptions): Promise<ConnectorRecordResult>;
|
|
135
|
+
private rememberSend;
|
|
136
|
+
/**
|
|
137
|
+
* Pull one search page of the current object-type phase since the
|
|
138
|
+
* effective watermark, normalized to envelopes. The returned cursor
|
|
139
|
+
* resumes the same phase (HubSpot `after` token) or advances to the
|
|
140
|
+
* next configured object type; no cursor means the sweep is done.
|
|
141
|
+
*
|
|
142
|
+
* First pull (epoch/absent watermark, no cursor): the window is
|
|
143
|
+
* `now - backfillDays` when the opt-in backfill is on, otherwise
|
|
144
|
+
* `now` — history stays untouched unless the user asked for it.
|
|
145
|
+
*/
|
|
146
|
+
pullEvents(input: EventSourcePullInput): Promise<EventSourcePullResult>;
|
|
147
|
+
private normalizeRecord;
|
|
148
|
+
/**
|
|
149
|
+
* Payload properties are limited to the whitelist the sweep asked
|
|
150
|
+
* for and each string value is capped, so a CRM record with a
|
|
151
|
+
* huge free-text field can never blow the envelope byte budget.
|
|
152
|
+
*/
|
|
153
|
+
private sanitizeProperties;
|
|
154
|
+
}
|
|
155
|
+
declare const hubspotConnectorPlugin: HubSpotConnectorPlugin;
|
|
156
|
+
|
|
157
|
+
export { HUBSPOT_BACKFILL_MAX_PAGES, HUBSPOT_DEFAULT_OBJECT_TYPES, HUBSPOT_EVENT_TEXT_MAX_CHARS, HUBSPOT_OBJECT_META, HUBSPOT_PULL_PAGE_SIZE, HubSpotConnectorPlugin, clampBackfillDays, HubSpotConnectorPlugin as default, hubspotConnectorPlugin, objectMeta, recordTitle, resolveNoteTarget, resolveObjectTypes };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { IConnectorPlugin, IEventSourcePlugin, PluginCategory, ConnectorMetadata, JsonSchema, ChannelTargetConfig, ConnectorCallOptions, ChannelVerification, ChannelSendInput, ChannelSendResult, ConnectorRecordInput, ConnectorRecordResult, EventSourcePullInput, EventSourcePullResult, PluginSettings } from '@ever-works/plugin';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Payload text cap for ingested envelopes. Envelope payloads are
|
|
5
|
+
* size-capped platform-side (32 KB serialized); a CRM property value
|
|
6
|
+
* never needs more than this to be useful in Memory/Activities.
|
|
7
|
+
*/
|
|
8
|
+
declare const HUBSPOT_EVENT_TEXT_MAX_CHARS = 4000;
|
|
9
|
+
/** Records requested per HubSpot search page. */
|
|
10
|
+
declare const HUBSPOT_PULL_PAGE_SIZE = 50;
|
|
11
|
+
/**
|
|
12
|
+
* Historical backfill bound: at most this many search pages per phase
|
|
13
|
+
* (per CRM object type) during the opt-in first-pull backfill, so a
|
|
14
|
+
* large portal can never turn activation into an unbounded crawl.
|
|
15
|
+
*/
|
|
16
|
+
declare const HUBSPOT_BACKFILL_MAX_PAGES = 10;
|
|
17
|
+
/** Object types swept when `objectTypes` is left empty. */
|
|
18
|
+
declare const HUBSPOT_DEFAULT_OBJECT_TYPES: readonly ["contacts", "companies", "deals"];
|
|
19
|
+
/** Per-object-type ingest/deep-link metadata. */
|
|
20
|
+
interface HubSpotObjectMeta {
|
|
21
|
+
/** Envelope `kind` (source-namespaced, singular). */
|
|
22
|
+
readonly kind: string;
|
|
23
|
+
/** Property carrying the record's last-modified timestamp. */
|
|
24
|
+
readonly lastModifiedProperty: string;
|
|
25
|
+
/** Properties requested from search (also the payload whitelist). */
|
|
26
|
+
readonly properties: readonly string[];
|
|
27
|
+
/** Numeric object-type id used in HubSpot record deep links. */
|
|
28
|
+
readonly objectTypeId?: string;
|
|
29
|
+
/**
|
|
30
|
+
* `associationTypeId` for a HUBSPOT_DEFINED note → record
|
|
31
|
+
* association. Absent means outbound notes are unsupported for the
|
|
32
|
+
* type and `send` fails loudly rather than writing an orphan note.
|
|
33
|
+
*/
|
|
34
|
+
readonly noteAssociationTypeId?: number;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Known first-class CRM object types. Custom objects still work — they
|
|
38
|
+
* fall back to {@link GENERIC_OBJECT_META} (the `hs_lastmodifieddate`
|
|
39
|
+
* property every HubSpot object carries).
|
|
40
|
+
*/
|
|
41
|
+
declare const HUBSPOT_OBJECT_META: Readonly<Record<string, HubSpotObjectMeta>>;
|
|
42
|
+
/** Metadata for a type, falling back to the generic custom-object shape. */
|
|
43
|
+
declare function objectMeta(objectType: string): HubSpotObjectMeta;
|
|
44
|
+
/** Clamp the opt-in backfill window to the supported 0–90 day range. */
|
|
45
|
+
declare function clampBackfillDays(value: unknown): number;
|
|
46
|
+
/** Parse the object-type list: comma/space separated → array (defaulted). */
|
|
47
|
+
declare function resolveObjectTypes(settings: PluginSettings | undefined): string[];
|
|
48
|
+
/** Minimal shape of a CRM record the search API returns. */
|
|
49
|
+
interface HubSpotRecord {
|
|
50
|
+
id?: string;
|
|
51
|
+
properties?: Record<string, unknown>;
|
|
52
|
+
createdAt?: Date | string;
|
|
53
|
+
updatedAt?: Date | string;
|
|
54
|
+
archived?: boolean;
|
|
55
|
+
}
|
|
56
|
+
interface HubSpotSearchPage {
|
|
57
|
+
results?: HubSpotRecord[];
|
|
58
|
+
paging?: {
|
|
59
|
+
next?: {
|
|
60
|
+
after?: string;
|
|
61
|
+
};
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
/** The subset of the `@hubspot/api-client` surface this plugin calls. */
|
|
65
|
+
interface HubSpotClientLike {
|
|
66
|
+
crm: {
|
|
67
|
+
objects: {
|
|
68
|
+
basicApi: {
|
|
69
|
+
create(objectType: string, input: Record<string, unknown>): Promise<{
|
|
70
|
+
id?: string;
|
|
71
|
+
}>;
|
|
72
|
+
getPage(objectType: string, limit?: number): Promise<HubSpotSearchPage>;
|
|
73
|
+
};
|
|
74
|
+
searchApi: {
|
|
75
|
+
doSearch(objectType: string, request: Record<string, unknown>): Promise<HubSpotSearchPage>;
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Resolve which CRM record an outbound note attaches to. A per-send
|
|
82
|
+
* `associatedObjectId` overrides the connection default; the resolved
|
|
83
|
+
* plugin `settings` default is the final fallback.
|
|
84
|
+
*/
|
|
85
|
+
declare function resolveNoteTarget(config: ChannelTargetConfig, options: ConnectorCallOptions): {
|
|
86
|
+
objectType: string;
|
|
87
|
+
objectId: string;
|
|
88
|
+
};
|
|
89
|
+
/** Best-effort human title for a record, per object type. */
|
|
90
|
+
declare function recordTitle(objectType: string, properties: Record<string, unknown> | undefined): string | undefined;
|
|
91
|
+
/**
|
|
92
|
+
* HubSpot CRM connector — first-party native connector.
|
|
93
|
+
*
|
|
94
|
+
* Outbound: `send` appends a Note engagement to a CRM record and
|
|
95
|
+
* `createRecord` writes a contact / company / deal (or a custom
|
|
96
|
+
* object) through the official `@hubspot/api-client` (private-app
|
|
97
|
+
* token auth; the SDK pins the API host, so there is no SSRF surface).
|
|
98
|
+
*
|
|
99
|
+
* Event source: `pullEvents` sweeps each configured CRM object type in
|
|
100
|
+
* turn via the Search API, filtered server-side on the type's
|
|
101
|
+
* last-modified property, normalized into `IngestedEventEnvelope`s
|
|
102
|
+
* (`hubspot.contact` / `.company` / `.deal` / `.record`) for the
|
|
103
|
+
* platform's event-ingest spine. When a `portalId` is configured every
|
|
104
|
+
* envelope carries a record deep link as `sourceUrl`. The opt-in
|
|
105
|
+
* historical backfill (`backfillDays`, default 0 = off, max 90) widens
|
|
106
|
+
* the FIRST pull's window only, with a per-phase page bound so
|
|
107
|
+
* activation never becomes an unbounded crawl. Re-delivery across
|
|
108
|
+
* overlapping windows is fine — the ingest pipeline dedupes on
|
|
109
|
+
* `(source, sourceEventId)`.
|
|
110
|
+
*
|
|
111
|
+
* Unconfigured is always LOUD: `verifyConnection` reports the missing
|
|
112
|
+
* token, `send`/`createRecord` throw, and `pullEvents` throws
|
|
113
|
+
* `EventSourceNotConfiguredError`. Nothing silently no-ops.
|
|
114
|
+
*/
|
|
115
|
+
declare class HubSpotConnectorPlugin implements IConnectorPlugin, IEventSourcePlugin {
|
|
116
|
+
readonly id = "hubspot-connector";
|
|
117
|
+
readonly name = "HubSpot Connector";
|
|
118
|
+
readonly version = "1.0.0";
|
|
119
|
+
readonly category: PluginCategory;
|
|
120
|
+
readonly capabilities: readonly ["connector", "connector-hubspot", "event-source"];
|
|
121
|
+
readonly providerName = "hubspot";
|
|
122
|
+
readonly connector: ConnectorMetadata;
|
|
123
|
+
readonly settingsSchema: JsonSchema;
|
|
124
|
+
private readonly idempotencyCache;
|
|
125
|
+
private readonly recordIdempotencyCache;
|
|
126
|
+
onLoad(): Promise<void>;
|
|
127
|
+
onUnload(): Promise<void>;
|
|
128
|
+
/** Testable seam — specs stub this; production uses the real SDK. */
|
|
129
|
+
protected createClient(accessToken: string): HubSpotClientLike;
|
|
130
|
+
verifyConnection(config: ChannelTargetConfig, options: ConnectorCallOptions): Promise<ChannelVerification>;
|
|
131
|
+
/** Outbound leg — append a Note engagement to a CRM record. */
|
|
132
|
+
send(payload: ChannelSendInput, options: ConnectorCallOptions): Promise<ChannelSendResult>;
|
|
133
|
+
/** Outbound record leg — create a CRM record of any object type. */
|
|
134
|
+
createRecord(record: ConnectorRecordInput, options: ConnectorCallOptions): Promise<ConnectorRecordResult>;
|
|
135
|
+
private rememberSend;
|
|
136
|
+
/**
|
|
137
|
+
* Pull one search page of the current object-type phase since the
|
|
138
|
+
* effective watermark, normalized to envelopes. The returned cursor
|
|
139
|
+
* resumes the same phase (HubSpot `after` token) or advances to the
|
|
140
|
+
* next configured object type; no cursor means the sweep is done.
|
|
141
|
+
*
|
|
142
|
+
* First pull (epoch/absent watermark, no cursor): the window is
|
|
143
|
+
* `now - backfillDays` when the opt-in backfill is on, otherwise
|
|
144
|
+
* `now` — history stays untouched unless the user asked for it.
|
|
145
|
+
*/
|
|
146
|
+
pullEvents(input: EventSourcePullInput): Promise<EventSourcePullResult>;
|
|
147
|
+
private normalizeRecord;
|
|
148
|
+
/**
|
|
149
|
+
* Payload properties are limited to the whitelist the sweep asked
|
|
150
|
+
* for and each string value is capped, so a CRM record with a
|
|
151
|
+
* huge free-text field can never blow the envelope byte budget.
|
|
152
|
+
*/
|
|
153
|
+
private sanitizeProperties;
|
|
154
|
+
}
|
|
155
|
+
declare const hubspotConnectorPlugin: HubSpotConnectorPlugin;
|
|
156
|
+
|
|
157
|
+
export { HUBSPOT_BACKFILL_MAX_PAGES, HUBSPOT_DEFAULT_OBJECT_TYPES, HUBSPOT_EVENT_TEXT_MAX_CHARS, HUBSPOT_OBJECT_META, HUBSPOT_PULL_PAGE_SIZE, HubSpotConnectorPlugin, clampBackfillDays, HubSpotConnectorPlugin as default, hubspotConnectorPlugin, objectMeta, recordTitle, resolveNoteTarget, resolveObjectTypes };
|