@planet-a/affinity-node/esm/v1/fields.js

API wrapper for the affinity.co API

import { fieldsUrl } from './urls.js';
import { defaultTransformers } from './axios_default_transformers.js';
/**
 * @module
 * Fields as a data model represent the "columns" in a spreadsheet. A field can be specific to a given list, or it can be global. List-specific fields appear as a column whenever that list is being viewed while global fields are displayed on all lists.
 *
 * Let us consider two examples:
 *
 * 1. Assume you have a list called "Top Referrers", and a new list-specific field (column) called "Number of Referrals" is added to this list. In this case, the "Number of Referrals" column will only be visible on the "Top Referrers" list.
 * 2. Now assume you have three lists of people, "Top Referrers", "Friends in Media", "BD Leads", and a person X exists on all three lists. If you want to track where all the people in these 3 lists live, you might have a field called "Location". It makes sense to make this field global - in which case it will be shared across all three lists. Hence, if person X is a top referrer and lives in San Francisco, CA, that information will automatically appear on the "Friends in Media" list as well.
 *
 * By default, Affinity provides all teams with a few default global fields: For people, the global fields include Location, Job Titles, and Industries. For organizations, the global fields include Stage, Industry, Location, and more.
 *
 * *Notes*:
 * - The Field endpoint does not return any [Crunchbase](https://www.crunchbase.com/) fields.
 * - Global field IDs for persons are returned from `GET /persons/fields`
 * - Global field IDs for organizations are returned from `GET /organizations/fields`
 * - List-specific field IDs are also returned from `GET /lists/{list_id}`
 */
export class Fields {
    /** @hidden */
    constructor(axios) {
        Object.defineProperty(this, "axios", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: axios
        });
    }
    /**
     * Returns all fields based on the provided query parameters.
     *
     * @param params - The query parameters for filtering fields.
     * @returns A promise that resolves to an array of field objects.
     *
     * @example
     * ```typescript
     * const fields = await affinity.fields.all({
     *     list_id: 123,
     *     value_type: FieldValueType.TEXT,
     *     entity_type: ListType.PERSON,
     *     with_modified_names: true,
     * })
     * console.log(fields)
     * ```
     */
    async all(params = {}) {
        const response = await this.axios.get(fieldsUrl(), {
            params,
        });
        return response.data;
    }
    /**
     * Creates a new field.
     *
     * @param params - Object containing the data for creating a new field
     * @returns The created field object.
     *
     * @example
     * ```typescript
     * const newField = await affinity.fields.create({
     *     name: '[Deals] Amount',
     *     entity_type: 1,
     *     value_type: 3,
     *     list_id: 11,
     *     allows_multiple: false,
     *     is_list_specific: true,
     *     is_required: false
     * })
     * console.log(newField)
     * ```
     */
    async create(params) {
        const response = await this.axios.post(fieldsUrl(), params, {
            transformResponse: [
                ...defaultTransformers(),
                (json) => json,
            ],
        });
        return response.data;
    }
    /**
     * Deletes a specific field.
     *
     * @returns boolean indicating whether the field was successfully deleted.
     *
     * @example
     * ```typescript
     * const success = await affinity.fields.delete({ field_id: 1234 })
     * console.log(success ? 'Field deleted': 'Field not deleted')
     * ```
     */
    async delete(reference) {
        const { field_id } = reference;
        const response = await this.axios.delete(fieldsUrl(field_id));
        return response.data.success === true;
    }
}