@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/using-mobile-native-capabilities/references/calendar.md

@@ -0,0 +1,213 @@
+# Calendar Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages calendar facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the calendar API of the mobile device, within the LWC.
+
+## Calendar Service API
+
+```typescript
+/*
+ * 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 CalendarService}.
+ * @returns An instance of {@linkcode CalendarService}.
+ */
+export function getCalendarService(): CalendarService;
+
+/**
+ * Manage calendar events from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice.html|CalendarService API}
+ */
+export interface CalendarService extends BaseCapability {
+  /**
+   * Returns all available calendars from the device’s native Calendar application.
+   * If needed, a permission pop-up for the user to grant calendar access is presented first.
+   * @param options A {@linkcode CalendarServiceOptions} object to configure the {@linkcode CalendarService} request.
+   * @returns A Promise object that resolves as an array of {@linkcode Calendar} objects.
+   */
+  getCalendars(options?: CalendarServiceOptions): Promise<Calendar[]>;
+
+  /**
+   * Returns all events of all available calendar events in a specified date range from the specified calendars.
+   * @param startDateSecondsUTC The start of the date range.
+   * @param endDateSecondsUTC The end of the date range.
+   * @param calendars The titles of calendars to get events from. If not provided, or null is passed in, events are fetched from all available calendars.
+   * @param options A {@linkcode CalendarServiceOptions} object to configure the {@linkcode CalendarService} request.
+   * @returns A Promise object that resolves as an array of {@linkcode CalendarEvent} objects.
+   */
+  getEvents(
+    startDateSecondsUTC: number,
+    endDateSecondsUTC: number,
+    calendars?: string[],
+    options?: CalendarServiceOptions,
+  ): Promise<CalendarEvent[]>;
+
+  /**
+   * Adds an event to the device’s calendar.
+   * @param event A {@linkcode CalendarEvent} object to be added to the device’s calendar.
+   * @param options A {@linkcode CalendarServiceOptions} object to configure the {@linkcode CalendarService} request.
+   * @returns A Promise object that resolves as a coerced version of the {@linkcode CalendarEvent} parameter.
+   */
+  addEvent(event: CalendarEvent, options?: CalendarServiceOptions): Promise<CalendarEvent>;
+
+  /**
+   * Updates an event in the device’s calendar.
+   * @param updatedEvent A {@linkcode CalendarEvent} object with updated data to replace the existing data in the corresponding event on the device’s calendar.
+   * @param options A {@linkcode CalendarServiceOptions}  object to configure the {@linkcode CalendarService}  request.
+   * @returns A Promise object that resolves as a coerced version of the {@linkcode CalendarEvent} parameter.
+   */
+  updateEvent(updatedEvent: CalendarEvent, options?: CalendarServiceOptions): Promise<CalendarEvent>;
+
+  /**
+   * Removes an event from a device’s calendar.
+   * @param event The {@linkcode CalendarEvent} object to be removed from the device’s calendar.
+   * @param options A {@linkcode CalendarServiceOptions} object to configure the {@linkcode CalendarService} request.
+   * @returns If successful, null is returned.
+   */
+  removeEvent(event: CalendarEvent, options?: CalendarServiceOptions): Promise<null>;
+}
+
+/**
+ * Calendar interface.
+ */
+export interface Calendar {
+  id: string;
+  title: string;
+  allowsContentModifications: boolean; // indicates whether the calendar is read-only
+  hexColor: string; // includes # + hex color value, e.g #c603fc
+  type: string; // a string hinting about calendar type. It is platform specific. on iOS it is set to EKSource.sourceType+EKSource.title and on Android it is set to CalendarContract.Calendars.ACCOUNT_TYPE+CalendarContract.Calendars.ACCOUNT_NAME
+  isPrimary: boolean; // indicates whether it is the primary/default calendar
+}
+
+/**
+ * Event interface.
+ */
+export interface CalendarEvent {
+  id: string;
+  isAllDay: boolean; // defaults to False
+  startDateSecondsUTC: number;
+  endDateSecondsUTC: number;
+  availability: EventAvailability; // defaults to Busy
+  status: EventStatus; // read-only - value set by caller will be ignored and overwritten by the plugin
+  calendarId?: string;
+  title: string;
+  location?: string;
+  notes?: string;
+  alarms?: Alarm[];
+  attendees?: Participant[]; // Note: on iOS this field can only be used for fetching attendee info of an existing event, but you cannot create an event with attendee info (which is an EventKit limitation as mentioned here https://apple.co/3toRnDO)
+  recurrenceRules?: RecurrenceRule[];
+}
+
+/**
+ * EventAvailability values.
+ */
+export type EventAvailability = 'Busy' | 'Free' | 'Tentative';
+
+/**
+ * EventStatus values.
+ */
+export type EventStatus = 'Canceled' | 'Confirmed' | 'Tentative';
+
+/**
+ * Alarm interface.
+ */
+export interface Alarm {
+  relativeOffsetSeconds: number;
+}
+
+/**
+ * Participant interface.
+ */
+export interface Participant {
+  name: string;
+  email: string | null;
+  role: ParticipantRole;
+  status: ParticipantStatus;
+}
+
+/**
+ * ParticipantRole values.
+ */
+export type ParticipantRole = 'Required' | 'Optional' | 'Unknown';
+
+/**
+ * ParticipantStatus values.
+ */
+export type ParticipantStatus = 'Accepted' | 'Declined' | 'Pending' | 'Tentative' | 'Unknown';
+
+/**
+ * The recurrence rule as defined by https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10.
+ */
+export interface RecurrenceRule {
+  frequency: RecurrenceFrequency;
+  interval: number;
+  daysOfTheWeek?: RecurrenceDayOfWeek[];
+  daysOfTheMonth?: number[];
+  monthsOfTheYear?: number[];
+  weeksOfTheYear?: number[];
+  daysOfTheYear?: number[];
+  setPositions?: number[];
+  end?: RecurrenceEnd;
+}
+
+/**
+ * RecurrenceFrequency values.
+ */
+export type RecurrenceFrequency = 'Daily' | 'Weekly' | 'Monthly' | 'Yearly';
+
+/**
+ * RecurrenceDayOfWeek interface.
+ */
+export interface RecurrenceDayOfWeek {
+  dayOfTheWeek: Weekday;
+  weekNumber: number;
+}
+
+/**
+ * Weekday values.
+ */
+export type Weekday = 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday';
+
+/**
+ * RecurrenceEnd interface.
+ */
+export interface RecurrenceEnd {
+  endDateSecondsUTC?: number;
+  occurrenceCount?: number;
+}
+
+/**
+ * CalendarServiceOptions interface.
+ */
+export interface CalendarServiceOptions {
+  permissionRationaleText?: string;
+  span?: Span;
+}
+
+/**
+ * Span values.
+ */
+export type Span = 'ThisEvent' | 'ThisAndFollowingEvents';
+
+/**
+ * CalendarServiceFailure interface.
+ */
+export interface CalendarServiceFailure {
+  code: CalendarServiceFailureCode;
+  message: string;
+}
+
+/**
+ * Possible failure codes.
+ */
+export type CalendarServiceFailureCode =
+  | 'USER_DENIED_PERMISSION' // Permission was denied by user when prompt.
+  | 'NOT_FOUND' // A specified item (calendar or event) was not found.
+  | 'SERVICE_NOT_ENABLED' // The service is not enabled and therefore cannot be used.
+  | 'UNKNOWN_REASON'; // An error happened in the native code that is not permission based. Will give more information in the CalendarServiceFailure message.
+```

package/skills/using-mobile-native-capabilities/references/contacts.md

@@ -0,0 +1,232 @@
+# Contacts Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages contacts facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the contacts API of the mobile device, within the LWC.
+
+## Contacts Service API
+
+```typescript
+/*
+ * 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
+```