@symbiote-native/contacts 0.1.0

package/src/core/enums.ts

@@ -0,0 +1,55 @@
+export enum ContactField {
+  IS_FAVOURITE = 'isFavourite',
+  FULL_NAME = 'fullName',
+  GIVEN_NAME = 'givenName',
+  MIDDLE_NAME = 'middleName',
+  FAMILY_NAME = 'familyName',
+  MAIDEN_NAME = 'maidenName',
+  NICKNAME = 'nickname',
+  PREFIX = 'prefix',
+  SUFFIX = 'suffix',
+  PHONETIC_GIVEN_NAME = 'phoneticGivenName',
+  PHONETIC_MIDDLE_NAME = 'phoneticMiddleName',
+  PHONETIC_FAMILY_NAME = 'phoneticFamilyName',
+  COMPANY = 'company',
+  PHONETIC_COMPANY_NAME = 'phoneticCompanyName',
+  DEPARTMENT = 'department',
+  JOB_TITLE = 'jobTitle',
+  NOTE = 'note',
+  IMAGE = 'image',
+  THUMBNAIL = 'thumbnail',
+  BIRTHDAY = 'birthday',
+  NON_GREGORIAN_BIRTHDAY = 'nonGregorianBirthday',
+  EMAILS = 'emails',
+  PHONES = 'phones',
+  ADDRESSES = 'addresses',
+  EXTRA_NAMES = 'extraNames',
+  DATES = 'dates',
+  RELATIONS = 'relations',
+  URL_ADDRESSES = 'urlAddresses',
+  SOCIAL_PROFILES = 'socialProfiles',
+  IM_ADDRESSES = 'imAddresses',
+}
+
+export enum ContactsSortOrder {
+  UserDefault = 'userDefault',
+  GivenName = 'givenName',
+  FamilyName = 'familyName',
+  None = 'none',
+}
+
+/** @platform ios */
+export enum NonGregorianCalendar {
+  buddhist = 'buddhist',
+  chinese = 'chinese',
+  coptic = 'coptic',
+  ethiopicAmeteMihret = 'ethiopicAmeteMihret',
+  ethiopicAmeteAlem = 'ethiopicAmeteAlem',
+  hebrew = 'hebrew',
+  indian = 'indian',
+  islamic = 'islamic',
+  islamicCivil = 'islamicCivil',
+  japanese = 'japanese',
+  persian = 'persian',
+  republicOfChina = 'republicOfChina',
+}

package/src/core/group.ts

@@ -0,0 +1,4 @@
+import { expoContactsNext, FallbackGroup } from './native-module';
+
+/** @platform ios - Android has no Group concept in expo-contacts. */
+export class Group extends (expoContactsNext.Group ?? FallbackGroup) {}

package/src/core/index.ts

@@ -0,0 +1,14 @@
+export * from './enums';
+export * from './types';
+export type {
+  IContactAccessButtonCaption,
+  IContactAccessButtonProps,
+} from './contact-access-button';
+export { Contact } from './contact';
+export { Group } from './group';
+export { Container } from './container';
+export { getPermissionsAsync, requestPermissionsAsync } from './permissions';
+export {
+  addContactsChangeListener,
+  removeAllContactsChangeListeners,
+} from './listeners';

package/src/core/listeners.ts

@@ -0,0 +1,19 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import {
+  expoContactsNext,
+  ON_CONTACTS_CHANGE_EVENT_NAME,
+} from './native-module';
+
+export function addContactsChangeListener(
+  listener: () => void,
+): EventSubscription {
+  if (!expoContactsNext.addListener) {
+    throw new UnavailabilityError('Contacts', 'addContactsChangeListener');
+  }
+  return expoContactsNext.addListener(ON_CONTACTS_CHANGE_EVENT_NAME, listener);
+}
+
+export function removeAllContactsChangeListeners(): void {
+  expoContactsNext.removeAllListeners?.(ON_CONTACTS_CHANGE_EVENT_NAME);
+}

package/src/core/native-module.ts

@@ -0,0 +1,281 @@
+import { Platform, requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import type {
+  ContactDate,
+  ContactPatch,
+  ContactQueryOptions,
+  ContactsPermissionResponse,
+  CreateContactRecord,
+  CreateFormOptions,
+  ExistingAddress,
+  ExistingDate,
+  ExistingEmail,
+  ExistingExtraName,
+  ExistingImAddress,
+  ExistingPhone,
+  ExistingRelation,
+  ExistingSocialProfile,
+  ExistingUrlAddress,
+  FormOptions,
+  NewAddress,
+  NewDate,
+  NewEmail,
+  NewExtraName,
+  NewImAddress,
+  NewPhone,
+  NewRelation,
+  NewSocialProfile,
+  NewUrlAddress,
+  NonGregorianBirthday,
+  PartialContactDetails,
+} from './types';
+import type { ContactField } from './enums';
+
+const EXPO_CONTACTS_NEXT_MODULE_NAME = 'ExpoContactsNext';
+export const ON_CONTACTS_CHANGE_EVENT_NAME = 'contactsDidChange';
+
+export declare class NativeContact {
+  constructor(id: string);
+  readonly id: string;
+
+  delete(): Promise<void>;
+  patch(contact: ContactPatch): Promise<void>;
+  update(contact: CreateContactRecord): Promise<void>;
+  getDetails<T extends readonly ContactField[]>(
+    fields?: T,
+  ): Promise<PartialContactDetails<T>>;
+
+  addEmail(email: NewEmail): Promise<string>;
+  getEmails(): Promise<ExistingEmail[]>;
+  deleteEmail(email: ExistingEmail): Promise<void>;
+  updateEmail(updatedEmail: ExistingEmail): Promise<void>;
+
+  addPhone(phone: NewPhone): Promise<string>;
+  getPhones(): Promise<ExistingPhone[]>;
+  deletePhone(phone: ExistingPhone): Promise<void>;
+  updatePhone(updatedPhone: ExistingPhone): Promise<void>;
+
+  addDate(date: NewDate): Promise<string>;
+  getDates(): Promise<ExistingDate[]>;
+  deleteDate(date: ExistingDate): Promise<void>;
+  updateDate(updatedDate: ExistingDate): Promise<void>;
+
+  /** @platform android */
+  addExtraName(extraName: NewExtraName): Promise<string>;
+  /** @platform android */
+  getExtraNames(): Promise<ExistingExtraName[]>;
+  /** @platform android */
+  deleteExtraName(extraName: ExistingExtraName | string): Promise<void>;
+  /** @platform android */
+  updateExtraName(updatedExtraName: ExistingExtraName): Promise<void>;
+
+  addAddress(address: NewAddress): Promise<string>;
+  getAddresses(): Promise<ExistingAddress[]>;
+  deleteAddress(address: ExistingAddress): Promise<void>;
+  updateAddress(updatedAddress: ExistingAddress): Promise<void>;
+
+  addRelation(relation: NewRelation): Promise<string>;
+  getRelations(): Promise<ExistingRelation[]>;
+  deleteRelation(relation: ExistingRelation | string): Promise<void>;
+  updateRelation(updatedRelation: ExistingRelation): Promise<void>;
+
+  addUrlAddress(urlAddress: NewUrlAddress): Promise<string>;
+  getUrlAddresses(): Promise<ExistingUrlAddress[]>;
+  deleteUrlAddress(urlAddress: ExistingUrlAddress): Promise<void>;
+  updateUrlAddress(updatedUrlAddress: ExistingUrlAddress): Promise<void>;
+
+  /** @platform ios */
+  addSocialProfile?(socialProfile: NewSocialProfile): Promise<string>;
+  /** @platform ios */
+  getSocialProfiles?(): Promise<ExistingSocialProfile[]>;
+  /** @platform ios */
+  deleteSocialProfile?(socialProfile: ExistingSocialProfile): Promise<void>;
+  /** @platform ios */
+  updateSocialProfile?(
+    updatedSocialProfile: ExistingSocialProfile,
+  ): Promise<void>;
+
+  /** @platform ios */
+  addImAddress?(imAddress: NewImAddress): Promise<string>;
+  /** @platform ios */
+  getImAddresses?(): Promise<ExistingImAddress[]>;
+  /** @platform ios */
+  deleteImAddress?(imAddress: ExistingImAddress): Promise<void>;
+  /** @platform ios */
+  updateImAddress?(updatedImAddress: ExistingImAddress): Promise<void>;
+
+  editWithForm(options?: FormOptions): Promise<boolean>;
+  getFullName(): Promise<string>;
+
+  /** @platform android */
+  getIsFavourite?(): Promise<boolean>;
+  /** @platform android */
+  setIsFavourite?(isFavourite: boolean): Promise<boolean>;
+
+  getGivenName(): Promise<string | null>;
+  setGivenName(givenName: string | null): Promise<boolean>;
+  getFamilyName(): Promise<string | null>;
+  setFamilyName(familyName: string | null): Promise<boolean>;
+  getMiddleName(): Promise<string | null>;
+  setMiddleName(middleName: string | null): Promise<boolean>;
+
+  /** @platform ios */
+  getMaidenName?(): Promise<string | null>;
+  /** @platform ios */
+  setMaidenName?(maidenName: string | null): Promise<boolean>;
+  /** @platform ios */
+  getNickname?(): Promise<string | null>;
+  /** @platform ios */
+  setNickname?(nickname: string | null): Promise<boolean>;
+
+  getPrefix(): Promise<string | null>;
+  setPrefix(prefix: string | null): Promise<boolean>;
+  getSuffix(): Promise<string | null>;
+  setSuffix(suffix: string | null): Promise<boolean>;
+  getPhoneticGivenName(): Promise<string | null>;
+  setPhoneticGivenName(phoneticGivenName: string | null): Promise<boolean>;
+  getPhoneticMiddleName(): Promise<string | null>;
+  setPhoneticMiddleName(phoneticMiddleName: string | null): Promise<boolean>;
+  getPhoneticFamilyName(): Promise<string | null>;
+  setPhoneticFamilyName(phoneticFamilyName: string | null): Promise<boolean>;
+  getCompany(): Promise<string | null>;
+  setCompany(company: string | null): Promise<boolean>;
+  getDepartment(): Promise<string | null>;
+  setDepartment(department: string | null): Promise<boolean>;
+  getJobTitle(): Promise<string | null>;
+  setJobTitle(jobTitle: string | null): Promise<boolean>;
+  getPhoneticCompanyName(): Promise<string | null>;
+  setPhoneticCompanyName(phoneticCompanyName: string | null): Promise<boolean>;
+  getNote(): Promise<string | null>;
+  setNote(note: string | null): Promise<boolean>;
+  getImage(): Promise<string | null>;
+  setImage(imageUri: string | null): Promise<boolean>;
+  getThumbnail(): Promise<string | null>;
+
+  /** @platform ios */
+  getBirthday?(): Promise<ContactDate | null>;
+  /** @platform ios */
+  setBirthday?(birthday: ContactDate | null): Promise<boolean>;
+  /** @platform ios */
+  getNonGregorianBirthday?(): Promise<NonGregorianBirthday | null>;
+  /** @platform ios */
+  setNonGregorianBirthday?(
+    nonGregorianBirthday: NonGregorianBirthday | null,
+  ): Promise<boolean>;
+
+  static getAll(options?: ContactQueryOptions): Promise<NativeContact[]>;
+  static create(contact: CreateContactRecord): Promise<NativeContact>;
+  static presentCreateForm(
+    contact?: CreateContactRecord,
+    options?: CreateFormOptions,
+  ): Promise<boolean>;
+  static getCount(): Promise<number>;
+  static hasAny(): Promise<boolean>;
+  static presentPicker(): Promise<NativeContact | null>;
+  /** @platform ios */
+  static presentAccessPicker?(): Promise<NativeContact[]>;
+  static getAllDetails<T extends readonly ContactField[]>(
+    fields: T,
+    options?: ContactQueryOptions,
+  ): Promise<PartialContactDetails<T>[]>;
+}
+
+/** @platform ios - Android has no Group concept in expo-contacts. */
+export declare class NativeGroup {
+  constructor(id: string);
+  readonly id: string;
+  getName(): Promise<string | null>;
+  setName(name: string): Promise<void>;
+  addContact(contact: NativeContact): Promise<void>;
+  removeContact(contact: NativeContact): Promise<void>;
+  getContacts(options?: ContactQueryOptions): Promise<NativeContact[]>;
+  delete(): Promise<void>;
+  static create(name: string, containerId?: string): Promise<NativeGroup>;
+  static getAll(containerId?: string): Promise<NativeGroup[]>;
+}
+
+/** @platform ios - Android has no Container concept in expo-contacts. */
+export declare class NativeContainer {
+  constructor(id: string);
+  readonly id: string;
+  getName(): Promise<string | null>;
+  getType(): Promise<string | null>;
+  getGroups(): Promise<NativeGroup[]>;
+  getContacts(): Promise<NativeContact[]>;
+  static getAll(): Promise<NativeContainer[]>;
+  static getDefault(): Promise<NativeContainer | null>;
+}
+
+export class FallbackGroup {
+  constructor(public readonly id: string) {}
+  getName(): Promise<string | null> {
+    throw new Error('Not implemented');
+  }
+  setName(_name: string): Promise<void> {
+    throw new Error('Not implemented');
+  }
+  addContact(_contact: NativeContact): Promise<void> {
+    throw new Error('Not implemented');
+  }
+  removeContact(_contact: NativeContact): Promise<void> {
+    throw new Error('Not implemented');
+  }
+  getContacts(): Promise<NativeContact[]> {
+    throw new Error('Not implemented');
+  }
+  delete(): Promise<void> {
+    throw new Error('Not implemented');
+  }
+  static create(_name: string, _containerId?: string): Promise<FallbackGroup> {
+    throw new Error('Not implemented');
+  }
+  static getAll(_containerId?: string): Promise<FallbackGroup[]> {
+    throw new Error('Not implemented');
+  }
+}
+
+export class FallbackContainer {
+  constructor(public readonly id: string) {}
+  getName(): Promise<string | null> {
+    throw new Error('Not implemented');
+  }
+  getType(): Promise<string | null> {
+    throw new Error('Not implemented');
+  }
+  getGroups(): Promise<FallbackGroup[]> {
+    throw new Error('Not implemented');
+  }
+  getContacts(): Promise<NativeContact[]> {
+    throw new Error('Not implemented');
+  }
+  static getAll(): Promise<FallbackContainer[]> {
+    throw new Error('Not implemented');
+  }
+  static getDefault(): Promise<FallbackContainer | null> {
+    throw new Error('Not implemented');
+  }
+}
+
+export type INativeContactsNextModule = {
+  ContactNext?: typeof NativeContact;
+  Contact: typeof NativeContact;
+  Group?: typeof NativeGroup;
+  Container?: typeof NativeContainer;
+  getPermissionsAsync(): Promise<ContactsPermissionResponse>;
+  requestPermissionsAsync(): Promise<ContactsPermissionResponse>;
+  addListener?(
+    eventName: typeof ON_CONTACTS_CHANGE_EVENT_NAME,
+    listener: () => void,
+  ): EventSubscription;
+  removeAllListeners?(eventName: typeof ON_CONTACTS_CHANGE_EVENT_NAME): void;
+};
+
+export const expoContactsNext = requireNativeModule<INativeContactsNextModule>(
+  EXPO_CONTACTS_NEXT_MODULE_NAME,
+);
+
+// iOS registers the class as `ContactNext` (distinct from the deprecated legacy `Contact` JS
+// class); Android registers it directly as `Contact`. Alias so both platforms expose `.Contact`.
+if (Platform.OS === 'ios' && expoContactsNext.ContactNext) {
+  expoContactsNext.Contact = expoContactsNext.ContactNext;
+}

package/src/core/permissions.ts

@@ -0,0 +1,10 @@
+import { expoContactsNext } from './native-module';
+import type { ContactsPermissionResponse } from './types';
+
+export async function getPermissionsAsync(): Promise<ContactsPermissionResponse> {
+  return expoContactsNext.getPermissionsAsync();
+}
+
+export async function requestPermissionsAsync(): Promise<ContactsPermissionResponse> {
+  return expoContactsNext.requestPermissionsAsync();
+}

package/src/core/types.ts

@@ -0,0 +1,220 @@
+import type { PermissionResponse } from 'expo-modules-core';
+import type {
+  ContactField,
+  ContactsSortOrder,
+  NonGregorianCalendar,
+} from './enums';
+
+export type ContactsPermissionResponse = PermissionResponse & {
+  accessPrivileges?: 'all' | 'limited' | 'none';
+};
+
+export type ContactQueryOptions = {
+  limit?: number;
+  offset?: number;
+  sortOrder?: ContactsSortOrder;
+  name?: string;
+  /** @platform ios */
+  rawContacts?: boolean;
+};
+
+export type FormOptions = {
+  displayedPropertyKeys?: ContactField[];
+  message?: string;
+  alternateName?: string;
+  allowsEditing?: boolean;
+  allowsActions?: boolean;
+  shouldShowLinkedContacts?: boolean;
+  isNew?: boolean;
+  cancelButtonTitle?: string;
+  showsCancelButton?: boolean;
+  preventAnimation?: boolean;
+  groupId?: string;
+};
+
+export type CreateFormOptions = {
+  cancelButtonTitle?: string;
+  showsCancelButton?: boolean;
+  preventAnimation?: boolean;
+};
+
+export type NewEmail = { label?: string; address?: string };
+export type ExistingEmail = NewEmail & { id: string };
+export type NewPhone = { label?: string; number?: string };
+export type ExistingPhone = NewPhone & { id: string };
+export type NewDate = { label?: string; date?: ContactDate };
+export type ExistingDate = NewDate & { id: string };
+export type NewExtraName = { label?: string; name?: string };
+export type ExistingExtraName = NewExtraName & { id: string };
+export type NewAddress = {
+  label?: string;
+  street?: string;
+  city?: string;
+  state?: string;
+  postcode?: string;
+  region?: string;
+  country?: string;
+};
+export type ExistingAddress = NewAddress & { id: string };
+export type NewRelation = { label?: string; name?: string };
+export type ExistingRelation = NewRelation & { id: string };
+export type NewUrlAddress = { label?: string; url?: string };
+export type ExistingUrlAddress = NewUrlAddress & { id: string };
+export type NewImAddress = {
+  label?: string;
+  username?: string;
+  service?: string;
+};
+export type ExistingImAddress = NewImAddress & { id: string };
+export type NewSocialProfile = {
+  label?: string;
+  username?: string;
+  service?: string;
+  url?: string;
+  userId?: string;
+};
+export type ExistingSocialProfile = NewSocialProfile & { id: string };
+
+export type ContactDate = { year?: number; month: number; day: number };
+
+/** @platform ios */
+export type NonGregorianBirthday = {
+  year?: number;
+  month: number;
+  day: number;
+  calendar: NonGregorianCalendar;
+};
+
+export type ContactPatch = {
+  isFavourite?: boolean | null;
+  givenName?: string | null;
+  middleName?: string | null;
+  familyName?: string | null;
+  nickname?: string | null;
+  maidenName?: string | null;
+  prefix?: string | null;
+  suffix?: string | null;
+  phoneticGivenName?: string | null;
+  phoneticMiddleName?: string | null;
+  phoneticFamilyName?: string | null;
+  company?: string | null;
+  department?: string | null;
+  jobTitle?: string | null;
+  phoneticCompanyName?: string | null;
+  note?: string | null;
+  image?: string | null;
+  birthday?: ContactDate | null;
+  nonGregorianBirthday?: NonGregorianBirthday | null;
+  emails?: (ExistingEmail | NewEmail)[];
+  phones?: (ExistingPhone | NewPhone)[];
+  dates?: (ExistingDate | NewDate)[];
+  extraNames?: (ExistingExtraName | NewExtraName)[];
+  addresses?: (ExistingAddress | NewAddress)[];
+  relations?: (ExistingRelation | NewRelation)[];
+  urlAddresses?: (ExistingUrlAddress | NewUrlAddress)[];
+  socialProfiles?: (ExistingSocialProfile | NewSocialProfile)[];
+  imAddresses?: (ExistingImAddress | NewImAddress)[];
+};
+
+export type CreateContactRecord = {
+  isFavourite?: boolean;
+  givenName?: string;
+  middleName?: string;
+  familyName?: string;
+  maidenName?: string;
+  nickname?: string;
+  prefix?: string;
+  suffix?: string;
+  phoneticGivenName?: string;
+  phoneticMiddleName?: string;
+  phoneticFamilyName?: string;
+  company?: string;
+  department?: string;
+  jobTitle?: string;
+  phoneticCompanyName?: string;
+  note?: string;
+  image?: string;
+  birthday?: ContactDate;
+  nonGregorianBirthday?: NonGregorianBirthday;
+  emails?: NewEmail[];
+  dates?: NewDate[];
+  phones?: NewPhone[];
+  addresses?: NewAddress[];
+  relations?: NewRelation[];
+  urlAddresses?: NewUrlAddress[];
+  imAddresses?: NewImAddress[];
+  socialProfiles?: NewSocialProfile[];
+  extraNames?: NewExtraName[];
+};
+
+export type ContactDetails = {
+  isFavourite: boolean;
+  fullName: string | null;
+  givenName: string | null;
+  middleName: string | null;
+  familyName: string | null;
+  maidenName?: string | null;
+  nickname?: string | null;
+  prefix: string | null;
+  suffix: string | null;
+  phoneticGivenName: string | null;
+  phoneticMiddleName: string | null;
+  phoneticFamilyName: string | null;
+  company: string | null;
+  department: string | null;
+  jobTitle?: string;
+  phoneticCompanyName?: string;
+  note: string | null;
+  image: string | null;
+  thumbnail: string | null;
+  birthday?: ContactDate | null;
+  nonGregorianBirthday?: NonGregorianBirthday | null;
+  emails: ExistingEmail[];
+  dates: ExistingDate[];
+  phones: ExistingPhone[];
+  extraNames: ExistingExtraName[];
+  addresses: ExistingAddress[];
+  relations: ExistingRelation[];
+  urlAddresses: ExistingUrlAddress[];
+  socialProfiles: ExistingSocialProfile[];
+  imAddresses: ExistingImAddress[];
+};
+
+export type ContactFieldKey = {
+  [ContactField.IS_FAVOURITE]: 'isFavourite';
+  [ContactField.FULL_NAME]: 'fullName';
+  [ContactField.GIVEN_NAME]: 'givenName';
+  [ContactField.MIDDLE_NAME]: 'middleName';
+  [ContactField.FAMILY_NAME]: 'familyName';
+  [ContactField.MAIDEN_NAME]: 'maidenName';
+  [ContactField.NICKNAME]: 'nickname';
+  [ContactField.PREFIX]: 'prefix';
+  [ContactField.SUFFIX]: 'suffix';
+  [ContactField.PHONETIC_GIVEN_NAME]: 'phoneticGivenName';
+  [ContactField.PHONETIC_MIDDLE_NAME]: 'phoneticMiddleName';
+  [ContactField.PHONETIC_FAMILY_NAME]: 'phoneticFamilyName';
+  [ContactField.COMPANY]: 'company';
+  [ContactField.PHONETIC_COMPANY_NAME]: 'phoneticCompanyName';
+  [ContactField.DEPARTMENT]: 'department';
+  [ContactField.JOB_TITLE]: 'jobTitle';
+  [ContactField.NOTE]: 'note';
+  [ContactField.IMAGE]: 'image';
+  [ContactField.THUMBNAIL]: 'thumbnail';
+  [ContactField.BIRTHDAY]: 'birthday';
+  [ContactField.NON_GREGORIAN_BIRTHDAY]: 'nonGregorianBirthday';
+  [ContactField.EMAILS]: 'emails';
+  [ContactField.PHONES]: 'phones';
+  [ContactField.ADDRESSES]: 'addresses';
+  [ContactField.DATES]: 'dates';
+  [ContactField.EXTRA_NAMES]: 'extraNames';
+  [ContactField.RELATIONS]: 'relations';
+  [ContactField.URL_ADDRESSES]: 'urlAddresses';
+  [ContactField.SOCIAL_PROFILES]: 'socialProfiles';
+  [ContactField.IM_ADDRESSES]: 'imAddresses';
+};
+
+export type PartialContactDetails<T extends readonly ContactField[]> = {
+  id: string;
+} & {
+  [K in T[number]]: ContactDetails[K];
+};