@salesforce/afv-skills 1.12.0 → 1.14.0

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
+```

package/skills/using-mobile-native-capabilities/references/document-scanner.md

@@ -0,0 +1,342 @@
+# Document Scanner Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages document scanning facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the document scanner API of the mobile device, within the LWC.
+
+## Document Scanner 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 DocumentScanner}.
+ * @returns An instance of {@linkcode DocumentScanner}.
+ */
+export function getDocumentScanner(): DocumentScanner;
+
+/**
+ * Scan documents from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner.html|DocumentScanner API}
+ */
+export interface DocumentScanner extends BaseCapability {
+  /**
+   * Use this function to start scanning a document.
+   * @param options A {@linkcode DocumentScannerOptions} object to configure the scanning session.
+   * @returns A Promise object that resolves to an array containing one or more {@linkcode Document} objects.
+   */
+  scan(options?: DocumentScannerOptions): Promise<Document[]>;
+}
+
+/**
+ * An object representing a scanned document. Returned as the result of a successful scan operation.
+ */
+export interface Document {
+  /**
+   * A string containing the base64 image data of the scanned document. Only provided when returnImageBytes is set to true in your {@linkcode DocumentScannerOptions} configuration object.
+   */
+  imageBytes?: string;
+
+  /**
+   * A string value providing the recognized text from the scanned document.
+   */
+  text: string;
+
+  /**
+   * An array of {@linkcode TextBlock} objects that represent a structured text result that is visually aligned with the corresponding image. See {@linkcode TextBlock} for details of this structured text data.
+   */
+  blocks: TextBlock[];
+
+  /**
+   * An array of {@linkcode Entity} objects.
+   */
+  entities: Entity[];
+}
+
+/**
+ * An object representing a contiguous section of the scanned text. Text that is visually close together is grouped into a block of text.
+ * A document is made up of one to many blocks, and each block can be further broken down into smaller text elements: {@linkcode TextLine} (a single line of text in
+ * a visually aligned run of text) and {@linkcode TextElement} (an individual word or glyph).
+ */
+export interface TextBlock {
+  /**
+   * A string containing the text content of the block.
+   */
+  text: string;
+
+  /**
+   * An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the {@linkcode TextBlock}.
+   */
+  frame: Frame;
+
+  /**
+   * An array of Point objects that define a closed shape within the scanned image that contains the {@linkcode TextBlock}.
+   */
+  cornerPoints: Point[];
+
+  /**
+   * The BCP-47 language code values for the languages detected in the recognized text.
+   */
+  recognizedLangCodes: string[];
+
+  /**
+   * An array of {@linkcode TextLine} objects, each of which represents a visually aligned line of text within the {@linkcode TextBlock}.
+   */
+  lines: TextLine[];
+}
+
+/**
+ * An object representing a single line of scanned text.
+ */
+export interface TextLine {
+  /**
+   * A string containing the text content of the line.
+   */
+  text: string;
+
+  /**
+   * An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the {@linkcode TextLine}.
+   */
+  frame: Frame;
+
+  /**
+   * An array of {@linkcode Point} objects that define a closed shape within the scanned image that contains the {@linkcode TextLine}.
+   */
+  cornerPoints: Point[];
+
+  /**
+   * The BCP-47 language code values for the languages detected in the recognized text.
+   */
+  recognizedLangCodes: string[];
+
+  /**
+   * An array of {@linkcode TextElement} objects, each of which represents a word or glyph within the {@linkcode TextLine}.
+   */
+  elements: TextElement[];
+}
+
+/**
+ * An object representing a single word, individual character, or glyph.
+ */
+export interface TextElement {
+  /**
+   * A string containing the text content of the word or character.
+   */
+  text: string;
+
+  /**
+   * An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the {@linkcode TextElement}.
+   */
+  frame: Frame;
+
+  /**
+   * An array of {@linkcode Point} objects that define a closed shape within the scanned image that contains the {@linkcode TextElement}.
+   */
+  cornerPoints: Point[];
+
+  /**
+   * The BCP-47 language code values for the languages detected in the recognized text.
+   */
+  recognizedLangCodes: string[];
+}
+
+/**
+ * An object representing a bounding rectangle. When used in {@linkcode DocumentScanner}, the Frame is the smallest that fully encloses a region of scanned text for a {@linkcode TextBlock}, {@linkcode TextLine}, or {@linkcode TextElement}.
+ */
+export interface Frame {
+  /**
+   * The X coordinate of the top-left of the rectangle, in pixels, within the coordinate system of the scanned image.
+   */
+  x: number;
+
+  /**
+   * The Y coordinate of the top-left of the rectangle, in pixels, within the coordinate system of the scanned image.
+   */
+  y: number;
+
+  /**
+   * The width of the rectangle, in pixels.
+   */
+  width: number;
+
+  /**
+   * The height of the rectangle, in pixels.
+   */
+  height: number;
+}
+
+/**
+ * An object representing a point in a coordinate system.
+ */
+export interface Point {
+  /**
+   * The X coordinate of the point.
+   */
+  x: number;
+
+  /**
+   * The Y coordinate of the point.
+   */
+  y: number;
+}
+
+/**
+ * Entity interface.
+ */
+export interface Entity {
+  type: EntityType;
+  value: string;
+  dateTimeEntity?: DateTimeEntity;
+  flightNumberEntity?: FlightNumberEntity;
+  ibanEntity?: IBANEntity;
+  moneyEntity?: MoneyEntity;
+  paymentCardEntity?: PaymentCardEntity;
+  trackingNumberEntity?: TrackingNumberEntity;
+}
+
+/**
+ * EntityType values.
+ */
+export type EntityType =
+  | 'ADDRESS'
+  | 'DATETIME'
+  | 'EMAIL'
+  | 'FLIGHTNUMBER'
+  | 'IBAN'
+  | 'ISBN'
+  | 'MONEY'
+  | 'PAYMENTCARD'
+  | 'PHONE'
+  | 'TRACKINGNUMBER'
+  | 'URL';
+
+/**
+ * DateTimeEntity interface.
+ */
+export interface DateTimeEntity {
+  secondsUTC: number;
+  granularity: string;
+}
+
+/**
+ * FlightNumberEntity interface.
+ */
+export interface FlightNumberEntity {
+  airlineCode: string;
+  flightNumber: string;
+}
+
+/**
+ * IBANEntity interface.
+ */
+export interface IBANEntity {
+  countryCode: string;
+  iban: string;
+}
+
+/**
+ * MoneyEntity interface.
+ */
+export interface MoneyEntity {
+  unnormalizedCurrency: string;
+  integerPart: number;
+  fractionalPart: number;
+}
+
+/**
+ * PaymentCardEntity interface.
+ */
+export interface PaymentCardEntity {
+  network: string;
+  cardNumber: string;
+}
+
+/**
+ * TrackingNumberEntity interface.
+ */
+export interface TrackingNumberEntity {
+  carrier: string;
+  trackingNumber: string;
+}
+
+/**
+ * DocumentScannerSource values.
+ */
+export type DocumentScannerSource = 'INPUT_IMAGE' | 'PHOTO_LIBRARY' | 'DEVICE_CAMERA';
+
+/**
+ * Script values.
+ */
+export type Script = 'CHINESE' | 'DEVANAGARI' | 'JAPANESE' | 'KOREAN' | 'LATIN';
+
+/**
+ * An object containing configuration details for a document scanning session.
+ */
+export interface DocumentScannerOptions {
+  /**
+   * Optional, and only for Android implementations. The text shown in the UI when the device prompts the user to grant permission for your app to use the camera.
+   */
+  permissionRationaleText?: string;
+
+  /**
+   * Optional. Specifies the source of the document to be scanned. Defaults to "DEVICE_CAMERA".
+   */
+  imageSource?: DocumentScannerSource;
+
+  /**
+   * Optional. Specifies the language writing system of the text to be scanned. Defaults to "LATIN".
+   */
+  scriptHint?: Script;
+
+  /**
+   * Defaults to FALSE when omitted.
+   */
+  extractEntities?: boolean;
+
+  /**
+   * Defaults to EN when omitted.
+   */
+  entityExtractionLanguageCode?: string;
+
+  /**
+   * Optional. Specifies whether the image data should (true) or should not (false) be returned by the plugin. Defaults to false. This setting is overridden and set to false when imageSource is set to “INPUT_IMAGE”.
+   */
+  returnImageBytes?: boolean;
+
+  /**
+   * Optional. A stringified array of base64 image data to be scanned. Used when imageSource is set to "INPUT_IMAGE".
+   */
+  inputImageBytes?: string[];
+}
+
+/**
+ * An object representing an error that occurred when accessing {@linkcode DocumentScanner} features.
+ */
+export interface DocumentScannerFailure {
+  /**
+   * A value representing the reason for a document scanner error. See {@linkcode DocumentScannerFailureCode} for the list of possible values.
+   */
+  code: DocumentScannerFailureCode;
+
+  /**
+   * 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;
+}
+
+/**
+ * Correlates with the code property on the {@linkcode DocumentScannerFailure} object.
+ */
+export type DocumentScannerFailureCode =
+  | 'USER_DISMISSED' // User dismissed the scanner.
+  | 'USER_DENIED_CAMERA_PERMISSION' // A user denied permission to access the device camera when prompted.
+  | 'USER_DENIED_PHOTO_LIBRARY_PERMISSION' // A user denied permission to access the device photo library when prompted.
+  | 'NO_SUPPORTED_CAMERA' // The device doesn’t have a supported camera.
+  | 'INVALID_INPUT_IMAGE' // The input image data can’t be read as an image.
+  | 'SERVICE_NOT_ENABLED' // DocumentScanner is not enabled and cannot be used.
+  | 'UNKNOWN_REASON'; // An error occurred in the native code that isn’t related to permissions or hardware issues. More information is provided in the DocumentScannerFailure message.
+```

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

@@ -0,0 +1,123 @@
+# Geofencing Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages geofencing facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the geofencing API of the mobile device, within the LWC.
+
+## Geofencing 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 GeofencingService}.
+ * @returns An instance of {@linkcode GeofencingService}.
+ */
+export function getGeofencingService(): GeofencingService;
+
+/**
+ * Create and monitor geofences in a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-geofencingservice.html|GeofencingService API}
+ */
+export interface GeofencingService extends BaseCapability {
+  /**
+   * Starts geofence monitoring.
+   * @param geofence A {@linkcode Geofencing} object to monitor.
+   * @returns A Promise object that resolves as a string value. The value is a unique ID that’s assigned to the monitored geofence.
+   */
+  startMonitoringGeofence(geofence: Geofence): Promise<string>;
+
+  /**
+   * Stop monitoring a specific geofence.
+   * @param id  Unique ID assigned to a specific geofence.
+   * @returns A Promise object that resolves as null.
+   */
+  stopMonitoringGeofence(id: string): Promise<null>;
+
+  /**
+   * Stop monitoring all geofences.
+   * @returns A Promise object that resolves as null.
+   */
+  stopMonitoringAllGeofences(): Promise<null>;
+
+  /**
+   * Get all IDs of monitored geofences.
+   * @returns A Promise object that resolves as an array of string values. The values are unique IDs assigned to monitored geofences.
+   */
+  getMonitoredGeofences(): Promise<string[]>;
+}
+
+/**
+ * An object representing an error that occurred when accessing {@linkcode GeofencingService} features.
+ */
+export interface GeofencingServiceFailure {
+  /**
+   * A value representing the reason for a location error.
+   */
+  code: GeofencingServiceFailureCode;
+
+  /**
+   * A string value explaining 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;
+}
+
+/**
+ * Possible failure codes.
+ */
+export type GeofencingServiceFailureCode =
+  | 'LOCATION_SERVICE_DISABLED' // Android Only: The location service is disabled on the device, not just for this app.
+  | 'USER_DENIED_PERMISSION' // Permission was denied by user when prompt, could ask again
+  | 'USER_DISABLED_PERMISSION' // Android: permission was denied along "don't ask again" when prompt, will need to go app setting to turn on. iOS: permission was disabled by the user and will need to be turned on in settings
+  | 'UNAVAILABLE_ON_HARDWARE' // Geofence monitoring not available on the hardware.
+  | 'MAX_GEOFENCE_MONITORED_REACHED' // The maximum number of geofences that can be monitored by the OS has been reached.
+  | 'INVALID_LATITUDE' // The range of latitude for a geofence is -90...90
+  | 'INVALID_LONGITUDE' // The range of longitude for a geofence is -180...180
+  | '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 GeofencingServiceFailure message.
+
+/**
+ * An object representing the coordinates and radius of the geofence region.
+ */
+export interface Geofence {
+  /**
+   * The latitude, in degrees. Ranges from -90 to 90.
+   */
+  latitude: number;
+
+  /**
+   * The longitude, in degrees. Ranges from -180 to 180.
+   */
+  longitude: number;
+
+  /**
+   * The radius of the geofence in meters.
+   */
+  radius: number;
+
+  /**
+   * Monitors the entry into the geofence radius. Defaults to true.
+   */
+  notifyOnEntry: boolean;
+
+  /**
+   * Monitors the exit out of the geofence radius. Defaults to true.
+   */
+  notifyOnExit: boolean;
+
+  /**
+   * Notification triggered by a geofence event.
+   */
+  message: string;
+
+  /**
+   * Removes geofence after it’s triggered. Defaults to true.
+   */
+  triggerOnce: boolean;
+}
+```