@symbiote-native/contacts 0.1.0

package/src/legacy/contacts.ts

@@ -0,0 +1,274 @@
+import { UnavailabilityError, uuid } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import { Platform, Share } from 'react-native';
+import type { ShareOptions } from 'react-native';
+import { expoContacts, ON_CONTACTS_CHANGE_EVENT_NAME } from './native-module';
+import type {
+  Contact,
+  ContactQuery,
+  ContactResponse,
+  Container,
+  ContainerQuery,
+  ContactsPermissionResponse,
+  ExistingContact,
+  FieldType,
+  FormOptions,
+  Group,
+  GroupQuery,
+} from './types';
+
+export async function isAvailableAsync(): Promise<boolean> {
+  return !!expoContacts.getContactsAsync;
+}
+
+export async function hasContactsAsync(): Promise<boolean> {
+  if (!expoContacts.hasContactsAsync) {
+    throw new UnavailabilityError('Contacts', 'hasContactsAsync');
+  }
+  return expoContacts.hasContactsAsync();
+}
+
+export async function writeContactToFileAsync(
+  contactQuery: ContactQuery = {},
+): Promise<string | undefined> {
+  if (!expoContacts.writeContactToFileAsync) {
+    throw new UnavailabilityError('Contacts', 'writeContactToFileAsync');
+  }
+  return expoContacts.writeContactToFileAsync(contactQuery);
+}
+
+export async function shareContactAsync(
+  contactId: string,
+  message: string,
+  shareOptions: ShareOptions = {},
+): Promise<unknown> {
+  if (Platform.OS === 'ios') {
+    const url = await writeContactToFileAsync({ id: contactId });
+    return Share.share({ url, message }, shareOptions);
+  }
+  if (!expoContacts.shareContactAsync) {
+    throw new UnavailabilityError('Contacts', 'shareContactAsync');
+  }
+  return expoContacts.shareContactAsync(contactId, message);
+}
+
+export async function getContactsAsync(
+  contactQuery: ContactQuery = {},
+): Promise<ContactResponse> {
+  if (!expoContacts.getContactsAsync) {
+    throw new UnavailabilityError('Contacts', 'getContactsAsync');
+  }
+  return expoContacts.getContactsAsync(contactQuery);
+}
+
+export async function getPagedContactsAsync(
+  contactQuery: ContactQuery = {},
+): Promise<ContactResponse> {
+  const { pageSize, ...rest } = contactQuery;
+  if (pageSize != null && pageSize <= 0) {
+    throw new Error(
+      'Error: Contacts.getPagedContactsAsync: `pageSize` must be greater than 0',
+    );
+  }
+  return getContactsAsync({ ...rest, pageSize });
+}
+
+export async function getContactByIdAsync(
+  id: string,
+  fields?: FieldType[],
+): Promise<ExistingContact | undefined> {
+  if (!expoContacts.getContactsAsync) {
+    throw new UnavailabilityError('Contacts', 'getContactsAsync');
+  }
+  const results = await expoContacts.getContactsAsync({
+    pageSize: 1,
+    pageOffset: 0,
+    fields,
+    id,
+  });
+  return results.data.length > 0 ? results.data[0] : undefined;
+}
+
+export async function addContactAsync(
+  contact: Contact,
+  containerId?: string,
+): Promise<string> {
+  if (!expoContacts.addContactAsync) {
+    throw new UnavailabilityError('Contacts', 'addContactAsync');
+  }
+  return expoContacts.addContactAsync(contact, containerId);
+}
+
+export async function updateContactAsync(
+  contact: { id: string } & Partial<ExistingContact>,
+): Promise<string> {
+  if (!expoContacts.updateContactAsync) {
+    throw new UnavailabilityError('Contacts', 'updateContactAsync');
+  }
+  return expoContacts.updateContactAsync(contact);
+}
+
+export async function removeContactAsync(contactId: string): Promise<unknown> {
+  if (!expoContacts.removeContactAsync) {
+    throw new UnavailabilityError('Contacts', 'removeContactAsync');
+  }
+  return expoContacts.removeContactAsync(contactId);
+}
+
+export async function presentFormAsync(
+  contactId?: string | null,
+  contact?: Contact | null,
+  formOptions: FormOptions = {},
+): Promise<unknown> {
+  if (!expoContacts.presentFormAsync) {
+    throw new UnavailabilityError('Contacts', 'presentFormAsync');
+  }
+  if (Platform.OS !== 'ios') {
+    return expoContacts.presentFormAsync(contactId, contact, formOptions);
+  }
+  let adjustedContact = contact;
+  if (contactId) {
+    if (adjustedContact) {
+      adjustedContact = undefined;
+      console.warn(
+        'Expo.Contacts.presentFormAsync: You should define either a `contact` or a `contactId` but not both.',
+      );
+    }
+    if (formOptions.isNew !== undefined) {
+      console.warn(
+        'Expo.Contacts.presentFormAsync: `formOptions.isNew` is not supported with `contactId`',
+      );
+    }
+  }
+  return expoContacts.presentFormAsync(contactId, adjustedContact, formOptions);
+}
+
+export async function addExistingGroupToContainerAsync(
+  groupId: string,
+  containerId: string,
+): Promise<unknown> {
+  if (!expoContacts.addExistingGroupToContainerAsync) {
+    throw new UnavailabilityError(
+      'Contacts',
+      'addExistingGroupToContainerAsync',
+    );
+  }
+  return expoContacts.addExistingGroupToContainerAsync(groupId, containerId);
+}
+
+export async function getDefaultContainerIdAsync(): Promise<string> {
+  if (!expoContacts.getDefaultContainerIdentifierAsync) {
+    throw new UnavailabilityError(
+      'Contacts',
+      'getDefaultContainerIdentifierAsync',
+    );
+  }
+  return expoContacts.getDefaultContainerIdentifierAsync();
+}
+
+export async function createGroupAsync(
+  name?: string,
+  containerId?: string,
+): Promise<string> {
+  if (!expoContacts.createGroupAsync) {
+    throw new UnavailabilityError('Contacts', 'createGroupAsync');
+  }
+  const groupName = name ?? uuid.v4();
+  const resolvedContainerId =
+    containerId ?? (await getDefaultContainerIdAsync());
+  return expoContacts.createGroupAsync(groupName, resolvedContainerId);
+}
+
+export async function updateGroupNameAsync(
+  groupName: string,
+  groupId: string,
+): Promise<unknown> {
+  if (!expoContacts.updateGroupNameAsync) {
+    throw new UnavailabilityError('Contacts', 'updateGroupNameAsync');
+  }
+  return expoContacts.updateGroupNameAsync(groupName, groupId);
+}
+
+export async function removeGroupAsync(groupId: string): Promise<unknown> {
+  if (!expoContacts.removeGroupAsync) {
+    throw new UnavailabilityError('Contacts', 'removeGroupAsync');
+  }
+  return expoContacts.removeGroupAsync(groupId);
+}
+
+export async function addExistingContactToGroupAsync(
+  contactId: string,
+  groupId: string,
+): Promise<unknown> {
+  if (!expoContacts.addExistingContactToGroupAsync) {
+    throw new UnavailabilityError('Contacts', 'addExistingContactToGroupAsync');
+  }
+  return expoContacts.addExistingContactToGroupAsync(contactId, groupId);
+}
+
+export async function removeContactFromGroupAsync(
+  contactId: string,
+  groupId: string,
+): Promise<unknown> {
+  if (!expoContacts.removeContactFromGroupAsync) {
+    throw new UnavailabilityError('Contacts', 'removeContactFromGroupAsync');
+  }
+  return expoContacts.removeContactFromGroupAsync(contactId, groupId);
+}
+
+export async function getGroupsAsync(groupQuery: GroupQuery): Promise<Group[]> {
+  if (!expoContacts.getGroupsAsync) {
+    throw new UnavailabilityError('Contacts', 'getGroupsAsync');
+  }
+  return expoContacts.getGroupsAsync(groupQuery);
+}
+
+export async function presentContactPickerAsync(): Promise<ExistingContact | null> {
+  if (!expoContacts.presentContactPickerAsync) {
+    throw new UnavailabilityError('Contacts', 'presentContactPickerAsync');
+  }
+  return expoContacts.presentContactPickerAsync();
+}
+
+export async function getContainersAsync(
+  containerQuery: ContainerQuery,
+): Promise<Container[]> {
+  if (!expoContacts.getContainersAsync) {
+    throw new UnavailabilityError('Contacts', 'getContainersAsync');
+  }
+  return expoContacts.getContainersAsync(containerQuery);
+}
+
+export async function presentAccessPickerAsync(): Promise<string[]> {
+  if (!expoContacts.presentAccessPickerAsync) {
+    throw new UnavailabilityError('Contacts', 'presentAccessPickerAsync');
+  }
+  return expoContacts.presentAccessPickerAsync();
+}
+
+export async function getPermissionsAsync(): Promise<ContactsPermissionResponse> {
+  if (!expoContacts.getPermissionsAsync) {
+    throw new UnavailabilityError('Contacts', 'getPermissionsAsync');
+  }
+  return expoContacts.getPermissionsAsync();
+}
+
+export async function requestPermissionsAsync(): Promise<ContactsPermissionResponse> {
+  if (!expoContacts.requestPermissionsAsync) {
+    throw new UnavailabilityError('Contacts', 'requestPermissionsAsync');
+  }
+  return expoContacts.requestPermissionsAsync();
+}
+
+export function addContactsChangeListener(
+  listener: () => void,
+): EventSubscription {
+  if (!expoContacts.addListener) {
+    throw new UnavailabilityError('Contacts', 'addContactsChangeListener');
+  }
+  const subscription = expoContacts.addListener(
+    ON_CONTACTS_CHANGE_EVENT_NAME,
+    listener,
+  );
+  return { remove: () => subscription.remove() };
+}

package/src/legacy/enums.ts

@@ -0,0 +1,72 @@
+export enum Fields {
+  ID = 'id',
+  ContactType = 'contactType',
+  Name = 'name',
+  FirstName = 'firstName',
+  MiddleName = 'middleName',
+  LastName = 'lastName',
+  MaidenName = 'maidenName',
+  NamePrefix = 'namePrefix',
+  NameSuffix = 'nameSuffix',
+  Nickname = 'nickname',
+  PhoneticFirstName = 'phoneticFirstName',
+  PhoneticMiddleName = 'phoneticMiddleName',
+  PhoneticLastName = 'phoneticLastName',
+  Birthday = 'birthday',
+  NonGregorianBirthday = 'nonGregorianBirthday',
+  Emails = 'emails',
+  PhoneNumbers = 'phoneNumbers',
+  Addresses = 'addresses',
+  SocialProfiles = 'socialProfiles',
+  InstantMessageAddresses = 'instantMessageAddresses',
+  UrlAddresses = 'urlAddresses',
+  Company = 'company',
+  JobTitle = 'jobTitle',
+  Department = 'department',
+  ImageAvailable = 'imageAvailable',
+  Image = 'image',
+  RawImage = 'rawImage',
+  ExtraNames = 'extraNames',
+  Note = 'note',
+  Dates = 'dates',
+  Relationships = 'relationships',
+  IsFavorite = 'isFavorite',
+}
+
+export enum CalendarFormats {
+  Gregorian = 'gregorian',
+  Buddhist = 'buddhist',
+  Chinese = 'chinese',
+  Coptic = 'coptic',
+  EthiopicAmeteMihret = 'ethiopicAmeteMihret',
+  EthiopicAmeteAlem = 'ethiopicAmeteAlem',
+  Hebrew = 'hebrew',
+  ISO8601 = 'iso8601',
+  Indian = 'indian',
+  Islamic = 'islamic',
+  IslamicCivil = 'islamicCivil',
+  Japanese = 'japanese',
+  Persian = 'persian',
+  RepublicOfChina = 'republicOfChina',
+  IslamicTabular = 'islamicTabular',
+  IslamicUmmAlQura = 'islamicUmmAlQura',
+}
+
+export enum ContainerTypes {
+  Local = 'local',
+  Exchange = 'exchange',
+  CardDAV = 'cardDAV',
+  Unassigned = 'unassigned',
+}
+
+export enum SortTypes {
+  UserDefault = 'userDefault',
+  FirstName = 'firstName',
+  LastName = 'lastName',
+  None = 'none',
+}
+
+export enum ContactTypes {
+  Person = 'person',
+  Company = 'company',
+}

package/src/legacy/index.ts

@@ -0,0 +1,3 @@
+export * from './enums';
+export * from './types';
+export * from './contacts';

package/src/legacy/native-module.ts

@@ -0,0 +1,66 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import type {
+  Contact,
+  ContactQuery,
+  ContactResponse,
+  Container,
+  ContainerQuery,
+  ContactsPermissionResponse,
+  ExistingContact,
+  FormOptions,
+  Group,
+  GroupQuery,
+} from './types';
+
+const EXPO_CONTACTS_MODULE_NAME = 'ExpoContacts';
+export const ON_CONTACTS_CHANGE_EVENT_NAME = 'onContactsChange';
+
+export type INativeContactsModule = {
+  hasContactsAsync?(): Promise<boolean>;
+  shareContactAsync?(contactId: string, message: string): Promise<unknown>;
+  getContactsAsync?(contactQuery: ContactQuery): Promise<ContactResponse>;
+  addContactAsync?(contact: Contact, containerId?: string): Promise<string>;
+  updateContactAsync?(
+    contact: { id: string } & Partial<ExistingContact>,
+  ): Promise<string>;
+  removeContactAsync?(contactId: string): Promise<unknown>;
+  writeContactToFileAsync?(
+    contactQuery: ContactQuery,
+  ): Promise<string | undefined>;
+  presentFormAsync?(
+    contactId?: string | null,
+    contact?: Contact | null,
+    formOptions?: FormOptions,
+  ): Promise<unknown>;
+  addExistingGroupToContainerAsync?(
+    groupId: string,
+    containerId: string,
+  ): Promise<unknown>;
+  createGroupAsync?(name: string, containerId?: string): Promise<string>;
+  updateGroupNameAsync?(groupName: string, groupId: string): Promise<unknown>;
+  removeGroupAsync?(groupId: string): Promise<unknown>;
+  addExistingContactToGroupAsync?(
+    contactId: string,
+    groupId: string,
+  ): Promise<unknown>;
+  removeContactFromGroupAsync?(
+    contactId: string,
+    groupId: string,
+  ): Promise<unknown>;
+  getGroupsAsync?(groupQuery: GroupQuery): Promise<Group[]>;
+  presentContactPickerAsync?(): Promise<ExistingContact | null>;
+  getDefaultContainerIdentifierAsync?(): Promise<string>;
+  getContainersAsync?(containerQuery: ContainerQuery): Promise<Container[]>;
+  presentAccessPickerAsync?(): Promise<string[]>;
+  getPermissionsAsync?(): Promise<ContactsPermissionResponse>;
+  requestPermissionsAsync?(): Promise<ContactsPermissionResponse>;
+  addListener?(
+    eventName: typeof ON_CONTACTS_CHANGE_EVENT_NAME,
+    listener: () => void,
+  ): EventSubscription;
+};
+
+export const expoContacts = requireNativeModule<INativeContactsModule>(
+  EXPO_CONTACTS_MODULE_NAME,
+);

package/src/legacy/types.ts

@@ -0,0 +1,159 @@
+import type { PermissionResponse } from 'expo-modules-core';
+import type {
+  CalendarFormats,
+  ContactTypes,
+  ContainerTypes,
+  Fields,
+  SortTypes,
+} from './enums';
+
+export type ContactsPermissionResponse = PermissionResponse & {
+  accessPrivileges?: 'all' | 'limited' | 'none';
+};
+
+export type CalendarFormatType = CalendarFormats | `${CalendarFormats}`;
+export type ContainerType = ContainerTypes | `${ContainerTypes}`;
+export type ContactType = ContactTypes | `${ContactTypes}`;
+export type FieldType = Fields | `${Fields}`;
+
+export type Date = {
+  day: number;
+  month: number;
+  year?: number;
+  id?: string;
+  label?: string;
+  format?: CalendarFormatType;
+};
+
+export type Relationship = { label: string; name?: string; id?: string };
+export type Email = {
+  email?: string;
+  isPrimary?: boolean;
+  label: string;
+  id?: string;
+};
+export type PhoneNumber = {
+  number?: string;
+  isPrimary?: boolean;
+  digits?: string;
+  countryCode?: string;
+  label: string;
+  id?: string;
+};
+export type Address = {
+  street?: string;
+  city?: string;
+  country?: string;
+  region?: string;
+  neighborhood?: string;
+  postalCode?: string;
+  poBox?: string;
+  isoCountryCode?: string;
+  label: string;
+  id?: string;
+};
+export type SocialProfile = {
+  service?: string;
+  localizedProfile?: string;
+  url?: string;
+  username?: string;
+  userId?: string;
+  label: string;
+  id?: string;
+};
+export type InstantMessageAddress = {
+  service?: string;
+  username?: string;
+  localizedService?: string;
+  label: string;
+  id?: string;
+};
+export type UrlAddress = { label: string; url?: string; id?: string };
+export type Image = {
+  uri?: string;
+  width?: number;
+  height?: number;
+  base64?: string;
+};
+
+export type Contact = {
+  contactType: ContactType;
+  name: string;
+  firstName?: string;
+  middleName?: string;
+  lastName?: string;
+  maidenName?: string;
+  namePrefix?: string;
+  nameSuffix?: string;
+  nickname?: string;
+  phoneticFirstName?: string;
+  phoneticMiddleName?: string;
+  phoneticLastName?: string;
+  company?: string;
+  jobTitle?: string;
+  department?: string;
+  note?: string;
+  imageAvailable?: boolean;
+  image?: Image;
+  rawImage?: Image;
+  birthday?: Date;
+  dates?: Date[];
+  relationships?: Relationship[];
+  emails?: Email[];
+  phoneNumbers?: PhoneNumber[];
+  addresses?: Address[];
+  instantMessageAddresses?: InstantMessageAddress[];
+  urlAddresses?: UrlAddress[];
+  nonGregorianBirthday?: Date;
+  socialProfiles?: SocialProfile[];
+  isFavorite?: boolean;
+};
+
+export type ExistingContact = Contact & { id: string };
+
+export type ContactResponse = {
+  data: ExistingContact[];
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+};
+
+export type ContactSort = `${SortTypes}`;
+
+export type ContactQuery = {
+  pageSize?: number;
+  pageOffset?: number;
+  fields?: FieldType[];
+  sort?: ContactSort;
+  name?: string;
+  id?: string | string[];
+  groupId?: string;
+  containerId?: string;
+  rawContacts?: boolean;
+};
+
+export type FormOptions = {
+  displayedPropertyKeys?: FieldType[];
+  message?: string;
+  alternateName?: string;
+  allowsEditing?: boolean;
+  allowsActions?: boolean;
+  shouldShowLinkedContacts?: boolean;
+  isNew?: boolean;
+  cancelButtonTitle?: string;
+  preventAnimation?: boolean;
+  groupId?: string;
+};
+
+export type GroupQuery = {
+  groupId?: string;
+  groupName?: string;
+  containerId?: string;
+};
+export type Group = { name?: string; id?: string };
+
+export type ContainerQuery = {
+  contactId?: string;
+  groupId?: string;
+  containerId?: string | string[];
+};
+export type Container = { name: string; id: string; type: ContainerType };

package/src/react/contact-access-button.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from 'react';
+import { descriptorToReact } from '@symbiote-native/react';
+import {
+  isContactAccessButtonAvailable,
+  renderContactAccessButton,
+} from '../core/contact-access-button';
+import type { IContactAccessButtonProps } from '../core/contact-access-button';
+
+function ContactAccessButtonView(
+  props: IContactAccessButtonProps,
+): ReactElement | null {
+  const descriptor = renderContactAccessButton(props);
+  return descriptor ? descriptorToReact(descriptor) : null;
+}
+
+/** React twin of `expo-contacts`' `ContactAccessButton`, iOS 18+ only, nothing elsewhere */
+export const ContactAccessButton = Object.assign(ContactAccessButtonView, {
+  /** True only on iOS 18.0 and newer */
+  isAvailable: isContactAccessButtonAvailable,
+});

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { ContactAccessButton } from './contact-access-button';

package/src/solid/contact-access-button.ts

@@ -0,0 +1,24 @@
+import { descriptorToSolid } from '@symbiote-native/solid';
+import {
+  isContactAccessButtonAvailable,
+  renderContactAccessButton,
+} from '../core/contact-access-button';
+import type { IContactAccessButtonProps } from '../core/contact-access-button';
+
+// The platform decision is made once at mount: the descriptor bridge builds the node once and
+// only diffs prop values afterwards, so the descriptor's shape must not change
+function ContactAccessButtonView(
+  props: IContactAccessButtonProps,
+): ReturnType<typeof descriptorToSolid> | null {
+  const initial = renderContactAccessButton({ ...props });
+  if (!initial) return null;
+  return descriptorToSolid(
+    () => renderContactAccessButton({ ...props }) ?? initial,
+  );
+}
+
+/** Solid twin of `expo-contacts`' `ContactAccessButton`, iOS 18+ only, nothing elsewhere */
+export const ContactAccessButton = Object.assign(ContactAccessButtonView, {
+  /** True only on iOS 18.0 and newer */
+  isAvailable: isContactAccessButtonAvailable,
+});

package/src/solid/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { ContactAccessButton } from './contact-access-button';

package/src/svelte/contact-access-button.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  // The native view name is mixed-case, which a literal tag would parse as a component reference,
+  // so the tag is dynamic. The platform decision is made once at mount, like the other adapters
+  import { hostProps } from '@symbiote-native/svelte/native-view-bridge';
+  import {
+    contactAccessButtonViewName,
+    ensureContactAccessButtonRegistered,
+  } from '../core/contact-access-button';
+  import type { IContactAccessButtonProps } from '../core/contact-access-button';
+
+  const props: IContactAccessButtonProps = $props();
+  const isRegistered = ensureContactAccessButtonRegistered();
+  const viewName = contactAccessButtonViewName();
+</script>
+
+{#if isRegistered}
+  <svelte:element this={viewName} {@attach hostProps({ ...props })} />
+{/if}

package/src/svelte/index.ts

@@ -0,0 +1,10 @@
+import { isContactAccessButtonAvailable } from '../core/contact-access-button';
+import ContactAccessButtonView from './contact-access-button.svelte';
+
+export * from '../core';
+
+/** Svelte twin of `expo-contacts`' `ContactAccessButton`, iOS 18+ only, nothing elsewhere */
+export const ContactAccessButton = Object.assign(ContactAccessButtonView, {
+  /** True only on iOS 18.0 and newer */
+  isAvailable: isContactAccessButtonAvailable,
+});

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls svelte's ambient globals ($state/$effect/...) into this package's tsc program,
+// same fix as `packages/navigation/src/svelte/svelte-ambient.d.ts`
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,7 @@
+// Re-exports the existing harness instead of a third copy (packages/sqlite and
+// packages/navigation already carry one, not part of either package's public exports)
+export {
+  createSvelteHarness,
+  loadComponent,
+  type ISvelteHarness,
+} from '../../../sqlite/src/svelte/svelte-compile.test-helper';