@planet-a/affinity-node
Version:
API wrapper for the affinity.co API
211 lines (210 loc) • 8.77 kB
JavaScript
import { defaultTransformers } from './axios_default_transformers.js';
import { createSearchIteratorFn } from './create_search_iterator_fn.js';
import { transformInteractionDateResponseRaw } from './transform_interaction_date_response_raw.js';
import { transformListEntryReference } from './transform_list_entry_reference.js';
import { personFieldsUrl, personsUrl } from './urls.js';
/**
* The type of person.
*/
export var PersonType;
(function (PersonType) {
/**
* Default value. All people that your team has spoken with externally have this type.
*/
PersonType[PersonType["EXTERNAL"] = 0] = "EXTERNAL";
/**
* All people on your team that have Affinity accounts will have this type.
*/
PersonType[PersonType["INTERNAL"] = 1] = "INTERNAL";
})(PersonType || (PersonType = {}));
/**
* @module
* The persons API allows you to manage all the contacts of your organization.
* These people include anyone your team has ever been in email communications or meetings with, and all the people that your team has added to Affinity either manually or through the API. Affinity's data model also guarantees that only one person in your team's shared contact list has a given email address.
*
* *Notes*:
* - If you are looking to add or remove a person from a list, please check out the {@link ListEntries} section of the API.
* - If you are looking to modify a person's field values (one of the cells on Affinity's spreadsheet), please check out the {@link FieldValues} section of the API.
*/
export class Persons {
/** @hidden */
constructor(axios) {
Object.defineProperty(this, "axios", {
enumerable: true,
configurable: true,
writable: true,
value: axios
});
/**
* Returns an async iterator that yields all person entries matching the given search terms
* Each yielded array contains up to the number specified in {@link SearchPersonsRequest.page_size} of persons.
* Use this method if you want to process the persons in a streaming fashion.
*
* *Please note:* the yielded persons array may be empty on the last page.
*
* @example
* ```typescript
* let page = 0
* for await (const entries of affinity.persons.searchIterator({
* term: 'Alice',
* page_size: 10
* })) {
* console.log(`Page ${++page} of entries:`, entries)
* }
* ```
*/
Object.defineProperty(this, "searchIterator", {
enumerable: true,
configurable: true,
writable: true,
value: createSearchIteratorFn(this.search.bind(this), 'persons')
});
}
static transformSearchPersonsRequest(data) {
return Object.fromEntries(Object.entries(data).map(([key, value]) => [
key,
value instanceof Date ? value.toISOString() : value,
]));
}
/**
* Fetches a person with a specified `person_id`.
*
* @returns The person object corresponding to the `person_id`.
*
* @example
* ```typescript
* const person = await affinity.persons.get({
* person_id: 12345
* })
* console.log(person)
* ```
*/
async get(params) {
const { person_id, ...rest } = params;
const response = await this.axios.get(personsUrl(person_id), {
params: rest,
transformResponse: [
...defaultTransformers(),
(json) => {
const { list_entries, ...person } = json;
return {
...transformInteractionDateResponseRaw(person),
list_entries: json.list_entries.map(transformListEntryReference),
};
},
],
});
return response.data;
}
/**
* Searches your teams data and fetches all the persons that meet the search criteria.
*
* This result is paginated. An initial request returns an object with two fields: `persons` and {@link PagedResponse.next_page_token}. `persons` contains an array of person resources. The value of {@link PagedResponse.next_page_token} should be sent as the query parameter `page_token` in another request to retrieve the next page of results. While paginating through results, each request must have identical query parameters other than the changing `page_token`. Otherwise, an `Invalid page_token variable` error will be returned.
*
* The absence of a {@link PagedResponse.next_page_token} indicates that all the records have been fetched, though its presence does not necessarily indicate that there are *more* resources to be fetched. The next page may be empty (but then {@link PagedResponse.next_page_token} would be `null` to confirm that there are no more resources).
* Pass `{@link InteractionDatesQueryParams.with_interaction_dates}=true` as a query parameter to include dates of the most recent and upcoming interactions with persons. When this parameter is included, persons with no interactions will not be returned in the response. Pass `with_interaction_persons=true` as a query parameter if `with_interaction_dates=true` to also get the internal persons associated with the interaction.
* You can filter by interaction dates by providing additional query parameters like `min_last_email_date` or `max_next_event_date`. The value of these query parameters should be ISO 8601 formatted date strings.
*
* @param request - Object containing the data for the request
*
* @example
* ```typescript
* const { persons: allAlices } = await affinity.persons.search({
* term: 'Alice'
* })
* console.log(allAlices)
* ```
*/
async search(request) {
const response = await this.axios.get(personsUrl(), {
params: Persons.transformSearchPersonsRequest(request),
transformResponse: [
...defaultTransformers(),
(json) => {
return {
...json,
persons: json.persons.map(transformInteractionDateResponseRaw),
};
},
],
});
return response.data;
}
/**
* Creates a new person with the supplied parameters.
*
* @param data - Object containing the data for creating a new person
* @returns The person resource that was just created.
*
* @example
* ```typescript
* const newPerson = await affinity.persons.create({
* first_name: 'Alice',
* last_name: 'Doe',
* emails: ['alice@doe.com'],
* organization_ids: [123456]
* })
* console.log(newPerson)
* ```
*/
async create(data) {
const response = await this.axios.post(personsUrl(), {
...data,
emails: data.emails ?? [], // the API requires this field to be present
});
return response.data;
}
/**
* Updates an existing person with `person_id` with the supplied parameters.
*
* @param data - Object containing the data for updating a person
* @returns The person resource that was just updated.
*
* @example
* ```typescript
* const updatedPerson = await affinity.persons.update({
* person_id: 12345,
* name: 'Acme Corp.',
* person_ids: [38706, 89734]
* })
* console.log(updatedPerson)
* ```
*/
async update(data) {
const { person_id, ...rest } = data;
const response = await this.axios.put(personsUrl(person_id), rest);
return response.data;
}
/**
* Deletes a person with a specified `person_id`.
* @returns true if the deletion was successful
*
* @example
* ```typescript
* const success = await affinity.persons.delete({
* person_id: 12345
* })
* console.log(success ? 'Person deleted': 'Person not deleted')
* ```
*/
async delete(request) {
const { person_id } = request;
const response = await this.axios.delete(personsUrl(person_id));
return response.data.success === true;
}
/**
* Fetches an array of all the global fields that exist on persons.
*
* @returns An array of the fields that exist on all persons for your team.
*
* @example
* ```typescript
* const personFields = await affinity.persons.getFields()
* console.log(personFields)
* ```
*/
async getFields() {
const response = await this.axios.get(personFieldsUrl());
return response.data;
}
}