-
Notifications
You must be signed in to change notification settings - Fork 0
/
organizations.ts
516 lines (474 loc) · 17.6 KB
/
organizations.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
import type { AxiosInstance } from 'axios'
import { defaultTransformers } from './axios_default_transformers.ts'
import { createSearchIteratorFn } from './create_search_iterator_fn.ts'
import type { DateTime } from './field_values.ts'
import type { ListEntryReferenceRaw } from './list_entries.ts'
import type { Field } from './lists.ts'
import type { Opportunity } from './opportunities.ts'
import type { PagedRequest } from './paged_request.ts'
import type { PagedResponse } from './paged_response.ts'
import type { PersonResponse as Person } from './persons.ts'
import type { Replace } from './types.ts'
import { organizationFieldsUrl, organizationsUrl } from './urls.ts'
import { transformInteractionDateResponseRaw } from './transform_interaction_date_response_raw.ts'
import { transformListEntryReference } from './transform_list_entry_reference.ts'
export type InteractionOccurrenceQuantifier = 'first' | 'last'
export type InteractionType =
| `${InteractionOccurrenceQuantifier}_email`
| `${InteractionOccurrenceQuantifier}_event`
| 'next_event'
| 'last_chat_message'
| 'last_interaction'
export type InteractionDateKey = `${InteractionType}_date`
export type Organization = {
/**
* The unique identifier of the organization object.
*/
id: number
/**
* The name of the organization.
*/
name: string
/**
* The website name of the organization. This is used by Affinity to automatically associate {@link Person} objects with an organization.
*/
domain: string
/**
* An array of all the websites associated with the organization. These are also used to automatically associate {@link Person} objects with an organization.
*/
domains: string[]
/**
* The unique identifier of the organization in Crunchbase.
*/
crunchbase_uuid: null | string
/** Whether this is a global organization or not */
global: boolean
}
export type OpportunityIdResponseRaw = {
/**
* An array of unique identifiers of opportunities ({@link Opportunity.id}) that are associated with the entity.
* Only returned when passing `{@link OpportunitiesQueryParams.with_opportunities}=true`.
*
* TODO(@joscha): model this in the type system, so the return type is based on the query parameter type.
*/
opportunity_ids?: number[]
}
export type InteractionDateResponseBase = {
interaction_dates?: {
[key in InteractionDateKey]: never
}
interactions?: {
[key in InteractionType]: never
}
}
export type InteractionDateResponseRaw = Replace<InteractionDateResponseBase, {
/**
* An object with string date fields representing the most recent and upcoming interactions with this entity.
* Only returned when passing `{@link InteractionDatesQueryParams.with_interaction_dates}=true`.
*
* TODO(@joscha): model this in the type system, so the return type is based on the query parameter type.
*/
interaction_dates?: {
[key in InteractionDateKey]: DateTime
}
/**
* An object with seven fields nested underneath.
* Each field corresponds to one of the seven interactions, and includes nested fields for date and person_ids which indicates the internal people associated with that event (people only returned if passing `{@link InteractionDatesQueryParams.with_interaction_persons}=true`).
* Only returned when passing `{@link InteractionDatesQueryParams.with_interaction_dates}=true`.
*
* TODO(@joscha): model this in the type system, so the return type is based on the query parameter type.
*/
interactions?: {
[key in InteractionType]: InteractionDateRaw
}
}>
export type InteractionDateResponse = Replace<InteractionDateResponseRaw, {
/**
* An object with string date fields representing the most recent and upcoming interactions with this entity.
* Only returned when passing `{@link InteractionDatesQueryParams.with_interaction_dates}=true`.
*
* TODO(@joscha): model this in the type system, so the return type is based on the query parameter type.
*/
interaction_dates?: {
[key in InteractionDateKey]: Date
}
/**
* An object with seven fields nested underneath.
* Each field corresponds to one of the seven interactions, and includes nested fields for date and person_ids which indicates the internal people associated with that event (people only returned if passing `{@link InteractionDatesQueryParams.with_interaction_persons}=true`).
* Only returned when passing `{@link InteractionDatesQueryParams.with_interaction_dates}=true`.
*
* TODO(@joscha): model this in the type system, so the return type is based on the query parameter type.
*/
interactions?: {
[key in InteractionType]: InteractionDate
}
}>
/**
* Each organization object has a unique id. It also has a name, domain (the website of the organization), and persons associated with it.
* The domain is an important attribute from an automation perspective, as it helps Affinity automatically link all the appropriate person objects to the organization.
*
* Each organization also has a flag determining whether it's global or not.
* As mentioned above, Affinity maintains its own database of global organizations that each customer has access to.
* Note that you cannot change the name or the domain of a global organization.
* You also cannot delete a global organization.
*
* Of course, if an organization is manually created by your team, all fields can be modified and the organization can be deleted.
*
* Dates of the most recent and upcoming interactions with an organization are available in the interaction_dates field.
* This data is only included when passing `{@link InteractionDatesQueryParams.with_interaction_dates}=true` as a query parameter to the `GET /organizations` or the `GET /organizations/{organization_id}` endpoints.
*/
export type OrganizationResponseRaw =
& Organization
& OpportunityIdResponseRaw
& InteractionDateResponseRaw
& {
/**
* An array of unique identifiers of people ({@link Person.id}) that are associated with the organization.
*/
person_ids?: number[]
}
export type SimpleOrganizationResponse =
& Organization
& Pick<
OrganizationResponse,
'person_ids'
>
export type InteractionDateRaw = {
date: DateTime
/**
* only returned if passing `with_interaction_persons=true`
*/
person_ids?: number[]
}
export type InteractionDate = Replace<InteractionDateRaw, {
date: Date
}>
export type OrganizationResponse = Replace<
OrganizationResponseRaw,
InteractionDateResponse
>
export type ListEntryReference = Replace<ListEntryReferenceRaw, {
created_at: Date
}>
export type PagedOrganizationResponseRaw =
& {
organizations: OrganizationResponseRaw[]
}
& PagedResponse
export type PagedOrganizationResponse = Replace<PagedOrganizationResponseRaw, {
organizations: OrganizationResponse[]
}>
export type SingleOrganizationResponseRaw =
& {
/**
* An array of list entry resources associated with the organization, only returned as part of the {@link Organizations.get} a specific organization endpoint.
*/
list_entries: ListEntryReferenceRaw[]
}
& OrganizationResponseRaw
export type SingleOrganizationResponse =
& {
list_entries: ListEntryReference[]
}
& OrganizationResponse
export type CreateOrganizationRequest = {
/**
* The name of the organization.
*/
name: string
/**
* The domain name of the organization.
*/
domain?: string
/**
* An array of unique identifiers of persons that the new organization will be associated with.
*/
person_ids?: number[]
}
export type UpdateOrganizationRequest =
& {
/**
* The name of the organization.
*/
name?: string
/**
* The domain name of the organization.
*/
domain?: string
/**
* An array of unique identifiers of persons that the organization will be associated with.
* *Note*: If you are trying to add a person to an organization, the existing values for `person_ids` must also be passed into the endpoint.
*/
person_ids?: number[]
}
& OrganizationReference
export type InteractionTypeWithoutChat = Exclude<
InteractionType,
'last_chat_message'
>
export type OptionalMinQueryParams = {
[key in InteractionTypeWithoutChat & string as `min_${key}_date`]?: Date
}
export type OptionalMaxQueryParams = {
[key in InteractionTypeWithoutChat & string as `max_${key}_date`]?: Date
}
export type InteractionDatesQueryParams =
| {
/** When true, interaction dates will be present on the returned resources. */
with_interaction_dates?: boolean
}
| {
with_interaction_dates: true
/**
* When true, persons for each interaction will be returned. Used in conjunction with {@link InteractionDatesQueryParams.with_interaction_dates}
*/
with_interaction_persons: true
}
export type OpportunitiesQueryParams = {
/**
* When true, opportunity IDs associated with this organization will be returned.
*/
with_opportunities?: boolean
}
export type SearchOrganizationsRequest =
& {
/**
* The search term to filter organizations.
*/
term?: string
}
& PagedRequest
& OpportunitiesQueryParams
& OptionalMinQueryParams
& OptionalMaxQueryParams
& InteractionDatesQueryParams
export type GetOrganizationRequest =
& OrganizationReference
& OpportunitiesQueryParams
& InteractionDatesQueryParams
export type OrganizationReference = {
/** The unique ID of the organization */
organization_id: number
}
export type EntityField = Pick<
Field,
'id' | 'name' | 'value_type' | 'allows_multiple' | 'dropdown_options'
>
/**
* @module
* An organization in Affinity represents an external company that your team is in touch with- this could be an organization you're trying to invest in, sell to, or establish a relationship with.
*
* An organization has many people associated with it - these are your team's points of contacts at that organization. Just like people, organizations can be added to multiple lists and can be assigned field values.
*
* To make the data quality as good as possible, we have our own proprietary database of organizations that we have developed through third-party partnerships and web scraping. We use this database to minimize data entry for you as you use Affinity's CRM products.
*
* *Notes*:
* - If you are looking to add or remove an organization from a list, please check out the {@link ListEntries} section of the API.
* - If you are looking to modify a field value (one of the cells on Affinity's spreadsheet), please check out the {@link FieldValues} section of the API.
*/
export class Organizations {
/** @hidden */
constructor(private readonly axios: AxiosInstance) {
}
private static transformSearchOrganizationsRequest(
data: SearchOrganizationsRequest,
) {
return Object.fromEntries(
Object.entries(data).map(([key, value]) => [
key,
value instanceof Date ? value.toISOString() : value,
]),
)
}
/**
* Fetches an organization with a specified organization_id.
*
* @returns The organization object corresponding to the organization_id.
*
* @example
* ```typescript
* const organization = await affinity.organizations.get({
* organization_id: 12345
* })
* console.log(organization)
* ```
*/
async get(
params: GetOrganizationRequest,
): Promise<SingleOrganizationResponse> {
const { organization_id, ...rest } = params
const response = await this.axios.get<SingleOrganizationResponse>(
organizationsUrl(organization_id),
{
params: rest,
transformResponse: [
...defaultTransformers(),
(
json: SingleOrganizationResponseRaw,
): SingleOrganizationResponse => {
const { list_entries, ...organization } = json
return {
...transformInteractionDateResponseRaw(
organization,
),
list_entries: json.list_entries.map(
transformListEntryReference,
),
}
},
],
},
)
return response.data
}
/**
* Searches your team's data and fetches all the organizations that meet the search criteria.
*
* @param request - Object containing the data for the request
*
* @example
* ```typescript
* const result = await affinity.organizations.search({
* term: 'affinity'
* })
* console.log(result.organizations)
* ```
*/
async search(
request: SearchOrganizationsRequest,
): Promise<PagedOrganizationResponse> {
const response = await this.axios.get<PagedOrganizationResponse>(
organizationsUrl(),
{
params: Organizations.transformSearchOrganizationsRequest(
request,
),
transformResponse: [
...defaultTransformers(),
(
json: PagedOrganizationResponseRaw,
): PagedOrganizationResponse => {
return {
...json,
organizations: json.organizations.map(
transformInteractionDateResponseRaw,
),
}
},
],
},
)
return response.data
}
/**
* Returns an async iterator that yields all organization entries matching the given search terms
* Each yielded array contains up to the number specified in {@link SearchOrganizationsRequest.page_size} of organizations.
* Use this method if you want to process the organizations in a streaming fashion.
*
* *Please note:* the yielded organizations array may be empty on the last page.
*
* @example
* ```typescript
* let page = 0
* for await (const entries of affinity.organizations.searchIterator({
* term: 'Ltd',
* page_size: 10
* })) {
* console.log(`Page ${++page} of entries:`, entries)
* }
* ```
*/
searchIterator = createSearchIteratorFn(
this.search.bind(this),
'organizations',
)
/**
* Creates a new organization with the supplied parameters.
*
* @param data - Object containing the data for creating a new organization
* @returns The organization resource that was just created.
*
* @example
* ```typescript
* const newOrganization = await affinity.organizations.create({
* name: 'Acme Corporation',
* domain: 'acme.co',
* person_ids: [38706]
* })
* console.log(newOrganization)
* ```
*/
async create(
data: CreateOrganizationRequest,
): Promise<SimpleOrganizationResponse> {
const response = await this.axios.post<SimpleOrganizationResponse>(
organizationsUrl(),
data,
)
return response.data
}
/**
* Updates an existing organization with `organization_id` with the supplied parameters.
*
* @param data - Object containing the data for updating an organization
* @returns The organization resource that was just updated.
*
* @example
* ```typescript
* const updatedOrganization = await affinity.organizations.update({
* organization_id: 12345,
* name: 'Acme Corp.',
* person_ids: [38706, 89734]
* })
* console.log(updatedOrganization)
* ```
*/
async update(
data: UpdateOrganizationRequest,
): Promise<SimpleOrganizationResponse> {
const { organization_id, ...rest } = data
const response = await this.axios.put<SimpleOrganizationResponse>(
organizationsUrl(organization_id),
rest,
)
return response.data
}
/**
* Deletes an organization with a specified `organization_id`.
* @returns true if the deletion was successful
*
* @example
* ```typescript
* const success = await affinity.organizations.delete({
* organization_id: 12345
* })
* console.log(success ? 'Organization deleted': 'Organization not deleted')
* ```
*/
async delete(request: OrganizationReference): Promise<boolean> {
const { organization_id } = request
const response = await this.axios.delete<{ success: boolean }>(
organizationsUrl(organization_id),
)
return response.data.success === true
}
/**
* Fetches an array of all the global fields that exist on organizations.
*
* @returns An array of the fields that exist on all organizations for your team.
*
* @example
* ```typescript
* const organizationFields = await affinity.organizations.getFields()
* console.log(organizationFields)
* ```
*/
async getFields(): Promise<EntityField[]> {
const response = await this.axios.get<
EntityField[]
>(
organizationFieldsUrl(),
)
return response.data
}
}