feat: persons endpoint

.coderabbit.yaml

@@ -0,0 +1,3 @@
+reviews:
+  auto_review:
+    drafts: true

.yamlfmt

@@ -1,3 +1,4 @@
 gitignore_excludes: true
+eof_newline: true
 exclude:
   - .yamllint

README.md

@@ -32,7 +32,7 @@ examples, etc.
 - ✅ [Fields](src/v1/fields.ts)
 - ✅ [Field Values](src/v1/field_values.ts)
 - ✅ [Field Value Changes](src/v1/field_value_changes.ts)
-- ❌ [Persons](src/v1/persons.ts)
+- ✅ [Persons](src/v1/persons.ts)
 - ✅ [Organizations](src/v1/organizations.ts)
 - ❌ [Opportunities](src/v1/opportunities.ts)
 - ❌ Interactions

src/v1/auth.ts

@@ -2,6 +2,7 @@ import { AxiosInstance } from 'axios'
 import { enumFromValue } from './enum_from_value.ts'
 import { defaultTransformers } from './axios_default_transformers.ts'
 import { whoAmIUrl } from './urls.ts'
+import type { DateTime, Replace } from './types.ts'
 
 /**
  * TODO(@joscha): Enum is most likely incomplete
@@ -36,17 +37,13 @@ export type User = {
     email: string
 }
 
-type WhoAmIResponseRaw = {
-    tenant: Tenant
-    user: User
-    grant: {
-        type: string
-        scope: string
-        createdAt: string
-    }
+type GrantRaw = {
+    type: string
+    scope: string
+    createdAt: DateTime
 }
 
-export type WhoAmIResponse = {
+type WhoAmIResponseRaw = {
     /**
      * Information about the Affinity instance the user belongs to.
      */
@@ -58,12 +55,16 @@ export type WhoAmIResponse = {
     /**
      * Data about the type of authentication and metadata about the API key.
      */
+    grant: GrantRaw
+}
+
+export type WhoAmIResponse = Replace<WhoAmIResponseRaw, {
     grant: {
         type: GrantType
         scope: Scope
         createdAt: Date
     }
-}
+}>
 
 /**
  * @module

src/v1/create_search_iterator_fn.ts

@@ -0,0 +1,39 @@
+import type { PagedResponse } from './paged_response.ts'
+import type { PagedRequest } from './paged_request.ts'
+
+export const createSearchIteratorFn = <
+    FN extends (r: PAGED_REQUEST) => Promise<PAGED_RESPONSE>,
+    PAGED_REQUEST extends PagedRequest,
+    PAGED_RESPONSE extends
+        & PagedResponse
+        & Record<PAYLOAD_KEY, SINGLE_RESPONSE[]>,
+    PAYLOAD_KEY extends string =
+        & keyof Omit<PAGED_RESPONSE, keyof PagedResponse>
+        & string,
+    SINGLE_RESPONSE = object,
+>(searchFn: FN, key: PAYLOAD_KEY) => {
+    async function* searchIterator(
+        params: Omit<PAGED_REQUEST, 'page_token'>,
+    ): AsyncGenerator<PAGED_RESPONSE[]> {
+        let page_token: string | undefined = undefined
+        while (true) {
+            const response: PAGED_RESPONSE = await searchFn(
+                // TODO(@joscha): remove cast
+                (page_token
+                    ? { ...params, page_token }
+                    : params) as PAGED_REQUEST,
+            )
+
+            // TODO(@joscha): remove cast
+            yield response[key] as unknown as PAGED_RESPONSE[]
+
+            if (response.next_page_token === null) {
+                // no more pages to fetch
+                return
+            } else {
+                page_token = response.next_page_token
+            }
+        }
+    }
+    return searchIterator
+}

src/v1/field_value_changes.ts

@@ -1,22 +1,11 @@
 import type { AxiosInstance } from 'axios'
 
-import type { Person } from './list_entries.ts'
-import type { DateTime } from './types.ts'
-import { fieldValueChangesUrl } from './urls.ts'
 import { defaultTransformers } from './axios_default_transformers.ts'
-import type { Field } from './lists.ts'
 import type { Value, ValueRaw } from './field_values.ts'
-
-/**
- * Via https://stackoverflow.com/questions/40510611
- */
-export type RequireOnlyOne<T, Keys extends keyof T = keyof T> =
-    & Pick<T, Exclude<keyof T, Keys>>
-    & {
-        [K in Keys]-?:
-            & Required<Pick<T, K>>
-            & Partial<Record<Exclude<Keys, K>, never>>
-    }[Keys]
+import type { Person } from './list_entries.ts'
+import type { Field } from './lists.ts'
+import type { DateTime, Replace, RequireOnlyOne } from './types.ts'
+import { fieldValueChangesUrl } from './urls.ts'
 
 /**
  * Enum for Action Type.
@@ -90,11 +79,9 @@ export type FieldValueChangeRaw = {
 
 export type FieldValueChangeResponseRaw = FieldValueChangeRaw[]
 
-export type FieldValueChange =
-    & Omit<FieldValueChangeRaw, 'changed_at'>
-    & {
-        changed_at: Date
-    }
+export type FieldValueChange = Replace<FieldValueChangeRaw, {
+    changed_at: Date
+}>
 
 export type FieldValueChangeResponse = FieldValueChange[]
 

src/v1/field_values.ts

@@ -3,7 +3,7 @@ import { fieldValuesUrl } from './urls.ts'
 import { defaultTransformers } from './axios_default_transformers.ts'
 import { FieldValueType } from './lists.ts'
 import { Field } from './lists.ts'
-import type { DateTime } from './types.ts'
+import type { DateTime, Replace } from './types.ts'
 import { FieldBase } from './fields.ts'
 export type { DateTime } from './types.ts'
 
@@ -155,13 +155,14 @@ export type FieldValueRaw =
 
 export type FieldValueResponseRaw = FieldValueRaw[]
 
-export type FieldValue =
-    & Omit<FieldValueRaw, 'value' | 'updated_at' | 'created_at' | 'value_type'>
+export type FieldValue = Replace<
+    FieldValueRaw,
     & {
         updated_at: Date | null
         created_at: Date
     }
     & ValueTypeMixin<FieldValueValues>
+>
 
 export type FieldValueResponse = FieldValue[]
 

src/v1/index.ts

@@ -6,6 +6,7 @@ import { Fields } from './fields.ts'
 import { FieldValues } from './field_values.ts'
 import { FieldValueChanges } from './field_value_changes.ts'
 import { Organizations } from './organizations.ts'
+import { Persons } from './persons.ts'
 export type * as ListEntries from './list_entries.ts'
 export type * as Lists from './lists.ts'
 export type * as Fields from './fields.ts'
@@ -51,6 +52,7 @@ export class Affinity {
         this.fieldValues = new FieldValues(this.axios)
         this.fieldValueChanges = new FieldValueChanges(this.axios)
         this.organizations = new Organizations(this.axios)
+        this.persons = new Persons(this.axios)
     }
 
     public readonly auth: Auth
@@ -66,4 +68,6 @@ export class Affinity {
     public readonly fieldValueChanges: FieldValueChanges
 
     public readonly organizations: Organizations
+
+    public readonly persons: Persons
 }

src/v1/list_entries.ts

@@ -2,9 +2,10 @@ import type { AxiosInstance } from 'axios'
 import type { EntityType, GetQuery } from './lists.ts'
 import { listEntriesUrl } from './urls.ts'
 import { defaultTransformers } from './axios_default_transformers.ts'
-import type { DateTime } from './types.ts'
+import type { DateTime, Replace } from './types.ts'
 import { PersonType } from './persons.ts'
 import { Organization } from './organizations.ts'
+import { transformListEntryReference } from './transform_list_entry_reference.ts'
 
 export type Person = {
     id: number
@@ -52,7 +53,6 @@ export type ListEntryReferenceRaw = {
 }
 
 export type ListEntryResponseRaw =
-    & ListEntryReferenceRaw
     & {
         /**
          * The type of the entity corresponding to the list entry.
@@ -63,25 +63,24 @@ export type ListEntryResponseRaw =
          */
         entity: Entity
     }
+    & ListEntryReferenceRaw
 
 export type PagedListEntryResponseRaw = {
     list_entries: ListEntryResponseRaw[]
     /**
-     * The absence of a `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 `next_page_token` would be `null` to confirm that there are no more resources).
+     * 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).
      */
     next_page_token: string | null
 }
 
-export type ListEntryResponse = Omit<ListEntryResponseRaw, 'created_at'> & {
+export type ListEntryResponse = Replace<ListEntryResponseRaw, {
     created_at: Date
-}
+}>
 
-export type PagedListEntryResponse =
-    & Omit<PagedListEntryResponseRaw, 'list_entries'>
-    & {
-        list_entries: ListEntryResponse[]
-    }
+export type PagedListEntryResponse = Replace<PagedListEntryResponseRaw, {
+    list_entries: ListEntryResponse[]
+}>
 
 /**
  * Paging parameters for retrieving list entries.
@@ -144,15 +143,6 @@ export class ListEntries {
     constructor(private readonly axios: AxiosInstance) {
     }
 
-    private static transformEntry = (
-        entry: ListEntryResponseRaw,
-    ): ListEntryResponse => {
-        return {
-            ...entry,
-            created_at: new Date(entry.created_at),
-        }
-    }
-
     /**
      * Fetches all list entries in the list with the supplied list id.
      *
@@ -215,11 +205,11 @@ export class ListEntries {
                             return {
                                 ...json,
                                 list_entries: json.list_entries.map(
-                                    ListEntries.transformEntry,
+                                    transformListEntryReference,
                                 ),
                             }
                         } else {
-                            return json.map(ListEntries.transformEntry)
+                            return json.map(transformListEntryReference)
                         }
                     },
                 ],
@@ -248,9 +238,7 @@ export class ListEntries {
             {
                 transformResponse: [
                     ...defaultTransformers(),
-                    (json: ListEntryResponseRaw) => {
-                        return ListEntries.transformEntry(json)
-                    },
+                    transformListEntryReference,
                 ],
             },
         )
@@ -347,9 +335,7 @@ export class ListEntries {
             {
                 transformResponse: [
                     ...defaultTransformers(),
-                    (json: ListEntryResponseRaw) => {
-                        return ListEntries.transformEntry(json)
-                    },
+                    transformListEntryReference,
                 ],
             },
         )