@planet-a/affinity-node/types/v1/field_value_changes.d.ts

API wrapper for the affinity.co API

import type { AxiosInstance } from 'axios';
import type { ValueRaw } from './field_values.js';
import type { Person } from './list_entries.js';
import type { DateTime, Replace, RequireOnlyOne } from './types.js';
/**
 * Enum for Action Type.
 */
export declare enum ActionType {
    /**
     * Represents the action type for creating a field value change.
     */
    CREATE = 0,
    /**
     * Represents the action type for deleting a field value change.
     */
    DELETE = 1,
    /**
     * Represents the action type for updating a field value change.
     */
    UPDATE = 2
}
export type Changer = Person & {
    /**
     * The unique identifier of the changer.
     */
    id: number;
};
/**
 * Represents the response object for a field value change.
 *
 * *Note*: There are some extra attributes returned by this endpoint; they will be deprecated soon and should not be used.
 */
export type FieldValueChangeRaw = {
    /**
     * The unique identifier of the field value change object.
     */
    id: number;
    /**
     * The unique identifier of the field the value change is associated with.
     */
    field_id: number;
    /**
     * The unique identifier of the person, organization, or opportunity object the field value change is associated with.
     */
    entity_id: number;
    /**
     * The unique identifier of the list entry object the field value change is associated with.
     */
    list_entry_id: number;
    /**
     * Describes the action behind this field value change.
     */
    action_type: ActionType;
    /**
     * The changer object.
     */
    changer: Changer;
    /**
     * The timestamp when the field value change occurred.
     */
    changed_at: DateTime;
    /**
     * Represents the field's value.
     *
     * This attribute can take on many different types, depending on the field `value_type`.
     * When the action type is {@link ActionType.DELETE}, `value` represents the old value; otherwise, it represents the new value.
     */
    value: ValueRaw;
};
export type FieldValueChangeResponseRaw = FieldValueChangeRaw[];
export type FieldValueChange = Replace<FieldValueChangeRaw, {
    changed_at: Date;
}>;
export type FieldValueChangeResponse = FieldValueChange[];
export interface EntityRequestFilter {
    /**
     * A unique ID that represents a person object whose field value changes are to be retrieved.
     */
    person_id: number;
    /**
     * A unique ID that represents an organization object whose field value changes are to be retrieved.
     */
    organization_id: number;
    /**
     * A unique ID that represents an opportunity object whose field value changes are to be retrieved.
     */
    opportunity_id: number;
}
/**
 * Only one of these properties can be present at a time
 */
export interface GetFieldValueChangesRequestFilter extends EntityRequestFilter {
    /**
     * A unique ID that represents a list entry object whose field value changes are to be retrieved.
     */
    list_entry_id: number;
}
export type GetFieldValueChangesRequestBase = {
    /**
     * A unique ID that represents a field object whose field values changes are to be retrieved.
     */
    field_id: number;
    /**
     * An integer that filters field value changes that were created with this specific action type.
     */
    action_type?: ActionType;
};
export type GetFieldValueChangesRequest = GetFieldValueChangesRequestBase | (GetFieldValueChangesRequestBase & RequireOnlyOne<GetFieldValueChangesRequestFilter>);
/**
 * Field value changes allow you to see historical changes to the values of fields in Affinity.
 * This is especially useful for tracking progress through statuses (e.g. Lead --> Closed Won).
 *
 * *Supported field types*:
 * Not all fields can track historical changes.
 * Fields that are automatically created and "enriched" by Affinity do not support change tracking.
 *
 * Among fields that are not enriched, only the ones with the following data types support change tracking:
 *
 * Multi-valued fields:
 * - {@link FieldValueType.PERSON}
 * - {@link FieldValueType.ORGANIZATION}
 * - {@link FieldValueType.NUMBER}
 * - {@link FieldValueType.LOCATION}
 *
 * Single-valued fields:
 * - {@link FieldValueType.PERSON}
 * - {@link FieldValueType.ORGANIZATION}
 * - {@link FieldValueType.NUMBER}
 * - {@link FieldValueType.DATE}
 * - {@link FieldValueType.LOCATION}
 * - {@link FieldValueType.RANKED_DROPDOWN}
 *
 * You can also see if a field does so by looking at the {@link Field.track_changes} attribute in the Field Resource. The API will return an appropriate error if the field doesn't support historical tracking.
 */
export declare class FieldValueChanges {
    private readonly axios;
    /** @hidden */
    constructor(axios: AxiosInstance);
    /**
     * TODO(@joscha): transform DateTime values to Date objects and then change type {@link ValueRaw} to {@link Value}
     */
    private static transformFieldValueChange;
    /**
     * Returns all field values changes attached to a specific field.
     * Field value changes can be filtered by `action_type`, person, organization, opportunity or `list_entry` by passing in the appropriate parameter.
     */
    all(params: GetFieldValueChangesRequest): Promise<FieldValueChangeResponse>;
}