/*
* Copyright (c) 2024, Salesforce, Inc.
* All rights reserved.
* For full license text, see the LICENSE.txt file
*/
import { BaseCapability } from "../BaseCapability.js";
/**
* Use this factory function to get an instance of {@linkcode ContactsService}.
* @returns An instance of {@linkcode ContactsService}.
*/
export function getContactsService(): ContactsService;
/**
* Access contacts from a Lightning web component.
* @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice.html|ContactsService API}
*/
export interface ContactsService extends BaseCapability {
/**
* Allows the user to pick one or more contacts from the device’s Contacts app. If needed, presents a
* permissions pop-up to the user to request access to contacts first, and then presents the user with the contacts selector.
* @param options A {@linkcode ContactsServiceOptions} object to configure the {@linkcode ContactsService} request.
* @returns A Promise object that resolves as an array of {@linkcode Contacts} objects. If an error is encountered, the array is empty.
*/
getContacts(options?: ContactsServiceOptions): Promise<Contact[]>;
/**
* Save a contact record into the mobile device address book.
* @param contact A {@linkcode Contacts} object.
* @param options A {@linkcode ContactsServiceOptions} object to configure the {@linkcode ContactsService} request. Currently
* used to override the device's permission UX sequence text.
* @returns A resolved promise returns a {@linkcode Contacts} object.
*/
putContact(
contact: Contact,
options?: ContactsServiceOptions,
): Promise<Contact>;
}
/**
* An object representing a contact.
*/
export interface Contact {
/**
* A stringified number unique to each contact. Generated by the native device at the time of contact creation.
*/
id: string;
/**
* An object representing a contact's name.
*/
name: ContactName;
/**
* An array of objects containing phone numbers for the contact.
*/
phoneNumbers: ContactLabeledValue[];
/**
* An array of objects containing email addresses for the contact.
*/
emails: ContactLabeledValue[];
/**
* An array of objects representing contact's addresses.
*/
addresses: ContactAddress[];
/**
* An array of objects containing instant messaging (IM) usernames for the contact.
*/
ims: ContactLabeledValue[];
/**
* An object representing a contact's organization.
*/
organizations: ContactOrganization[];
/**
* A text field for any extra information about the contact.
*/
note: string;
/**
* An array of objects containing URLs for the contact.
*/
urls: ContactLabeledValue[];
}
/**
* An object representing a contact’s address.
*/
export interface ContactAddress {
/**
* A string representing the type of address for a contact’s address.
*/
type: string;
/**
* A string representing the street address for a contact’s address.
*/
streetAddress: string;
/**
* A string representing the locality (also known as the “city”) for a contact’s address.
*/
locality: string;
/**
* A string representing the region (also known as the “state” or “province”) for a contact’s address.
*/
region: string;
/**
* A string representing the postal code for a contact’s address.
*/
postalCode: string;
/**
* A string representing the country for a contact’s address.
*/
country: string;
}
/**
* An object representing a contact’s organization.
*/
export interface ContactOrganization {
/**
* A string representing the name of a contact’s organization.
*/
name: string;
/**
* A string representing the department of a contact’s organization.
*/
department: string;
/**
* A string representing the title the contact holds in the organization.
*/
title: string;
}
/**
* An object representing a contact’s name.
*/
export interface ContactName {
/**
* A string representing the contact’s family name (also known as “surname” or “last name”).
*/
familyName: string;
/**
* A string representing the contact’s given name (also known as “first name”).
*/
givenName: string;
/**
* A string representing the contact’s middle name.
*/
middleName: string;
/**
* A string representing the contact’s name prefix.
*/
namePrefix: string;
/**
* A string representing the contact’s name suffix.
*/
nameSuffix: string;
}
/**
* An object containing a label and a value for a miscellaneous piece of contact information.
*/
export interface ContactLabeledValue {
/**
* The display name that categorizes the data in value. In the following examples, home, homepage, and work are label properties.
*/
label: string;
/**
* The value of the data specified in label.
*/
value: string;
}
/**
* An object representing an error that occurred when accessing {@linkcode ContactsService} features.
*/
export interface ContactsServiceFailure {
/**
* A value representing the reason for a contacts error.
*/
code: ContactsServiceFailureCode;
/**
* A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.
*/
message: string;
}
/**
* An object representing configuration details for a {@linkcode ContactsService} session.
*/
export interface ContactsServiceOptions {
/**
* Optional parameter, used by Android only. This only appears after an initial denial by the user. To use the default permission message, pass in an empty object.
* The default permission message is “To import Contacts, permission is needed to access Contacts. Tap Allow in the following permissions dialog.”
*/
permissionRationaleText?: string;
}
/**
* Possible failure codes.
*/
export type ContactsServiceFailureCode =
| "USER_DISMISSED" // The user clicked the cancel button.
| "USER_DENIED_PERMISSION" // Permission was denied to access contacts (older versions of Android only).
| "USER_DISABLED_PERMISSION" // Android Only - Permission was denied. User will need to go to app setting to turn on.
| "USER_RESTRICTED_PERMISSION" // The application is restricted (perhaps by parental controls) from accessing Contacts (iOS only).
| "SERVICE_NOT_ENABLED" // The service is not enabled and therefore cannot be used.
| "SAVE_OPERATION_FAILED" // The service couldn't save the contact record into the address book.
| "UNKNOWN_REASON"; // Generic error that is not captured by any of the above categories
