@salesforce/afv-skills 1.12.0 → 1.14.0

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

@@ -0,0 +1,219 @@
+# Barcode Scanner Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages barcode scanning facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the barcode scanning API of the mobile device, within the LWC.
+
+## Barcode 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 BarcodeScanner}.
+ * @returns An instance of {@linkcode BarcodeScanner}.
+ */
+export function getBarcodeScanner(): BarcodeScanner;
+
+/**
+ * Scan barcodes from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner.html|BarcodeScanner API}
+ */
+export interface BarcodeScanner extends BaseCapability {
+  /**
+   * @deprecated Use this function to start a new scanning session. Consider using scan() instead.
+   * @param options A {@linkcode BarcodeScannerOptions} object to configure the scanning session.
+   * @returns A resolved promise returns {@linkcode Barcode} object.
+   */
+  beginCapture(options?: BarcodeScannerOptions): Promise<Barcode>;
+
+  /**
+   * @deprecated Use this function to continue a scanning session. Consider using scan() instead.
+   * @returns A resolved promise returns {@linkcode Barcode} object.
+   */
+  resumeCapture(): Promise<Barcode>;
+
+  /**
+   * @deprecated Use this function to end a scanning session, close the mobile OS scanning interface, and dispose resources. Consider using dismiss() instead.
+   */
+  endCapture(): void;
+
+  /**
+   * Use this function to start scanning barcodes.
+   * @returns A resolved promise returns an array of {@linkcode Barcode} objects.
+   */
+  scan(options: BarcodeScannerOptions): Promise<Barcode[]>;
+
+  /**
+   * Use this function to end a scanning session, close the mobile OS scanning interface, and dispose of resources.
+   */
+  dismiss(): void;
+
+  /**
+   * Available values of barcode types as defined by {@linkcode BarcodeType}.
+   */
+  barcodeTypes: BarcodeType;
+}
+
+/**
+ * An object representing a scanned barcode.
+ */
+export interface Barcode {
+  /**
+   * The type of barcode that was recognized. Available values are enumerated in BarcodeScanner.barcodeTypes.
+   */
+  type: BarcodeType;
+
+  /**
+   * The decoded value of the barcode.
+   */
+  value: string;
+}
+
+/**
+ * An object enumerating the barcode symbologies supported by {@linkcode BarcodeScanner}.
+ */
+export interface BarcodeType {
+  CODE_128: 'code128';
+  CODE_39: 'code39';
+  CODE_93: 'code93';
+  DATA_MATRIX: 'datamatrix';
+  EAN_13: 'ean13';
+  EAN_8: 'ean8';
+  ITF: 'itf';
+  UPC_A: 'upca';
+  UPC_E: 'upce';
+  PDF_417: 'pdf417';
+  QR: 'qr';
+}
+
+/**
+ * An object representing an error that occurred when attempting to scan a barcode.
+ */
+export interface BarcodeScannerFailure {
+  /**
+   * A value representing the reason for the scanning failure
+   */
+  code: BarcodeScannerFailureCode;
+
+  /**
+   * A string value explaining the reason for the scanning 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 BarcodeScannerFailureCode =
+  | 'USER_DISMISSED' // The user clicked the button to dismiss the scanner
+  | 'USER_DENIED_PERMISSION' // This is only ever returned on android. android: permission was denied by user when prompt, could ask again.
+  | 'USER_DISABLED_PERMISSION' // Both ios and android will use this as it requires the same action of the user going to settings.
+  // 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
+  | 'INVALID_BARCODE_TYPE_REQUESTED' // One or more invalid barcode types were passed to the scanner for scanning
+  | 'SERVICE_NOT_ENABLED' // The service is not enabled and therefore cannot be used.
+  | 'UNKNOWN_REASON'; //  A hardware or unknown failure happened when trying to use the camera or other reason, like FirebaseVision failure. This is not caused by a lack of permission.
+
+/**
+ * ScannerSize values.
+ */
+export type ScannerSize = 'SMALL' | 'MEDIUM' | 'LARGE' | 'XLARGE' | 'FULLSCREEN';
+
+/**
+ * CameraFacing values.
+ */
+export type CameraFacing = 'FRONT' | 'BACK';
+
+/**
+ * An object representing configuration details for a barcode scanning session.
+ */
+export interface BarcodeScannerOptions {
+  /**
+   * Optional. Specifies the types of barcodes to scan for. Available values are enumerated in BarcodeScanner.barcodeTypes. Defaults to all supported barcode types.
+   */
+  barcodeTypes?: string[];
+
+  /**
+   * Optional. Provides instructions to display in the scanning interface. Defaults to no text.
+   */
+  instructionText?: string;
+
+  /**
+   * Optional. Provides a message to display in the scanning interface when a barcode is successfully scanned. Defaults to no text.
+   */
+  successText?: string;
+
+  /**
+   * Optional. Indicates whether or not a check mark is displayed upon a successful scan. Defaults to true.
+   */
+  showSuccessCheckMark?: boolean;
+
+  /**
+   * Optional. Determines whether the device vibrates when a scan is successful. Defaults to true.
+   */
+  vibrateOnSuccess?: boolean;
+
+  /**
+   * Optional. Modifies the size of the scanner camera view. The available options represent a percentage of the user's device screen size.
+   */
+  scannerSize?: ScannerSize;
+
+  /**
+   * Optional. Specifies whether the front- or rear-facing camera is used. Defaults to "BACK". Available options include "FRONT" and "BACK". If the user's device doesn't support the specified camera facing, an error is returned.
+   */
+  cameraFacing?: CameraFacing;
+
+  /**
+   * Optional. Defines a custom user interface for the scanner instead of using the standard UI. Defaults to null. If nothing is passed in for this parameter, the standard UI is used. If a custom UI is used, it completely replaces the standard UI,
+   * including the standard Cancel button used for dismissing the scanner. When defining a custom UI, it's the responsibility of the caller to handle dismissing the scanner.
+   */
+  backgroundViewHTML?: string;
+
+  /**
+   * Optional. Determines whether the scanner animates in and out when presented and dismissed. Defaults to true.
+   */
+  presentWithAnimation?: boolean;
+
+  /**
+   * Optional. Determines whether the user has to manually confirm that a detected barcode should be scanned. Defaults to false.
+   */
+  manualConfirmation?: boolean;
+
+  /**
+   * Optional. Determines whether the scanner displays the barcode data while scanning. Defaults to true. Previewing barcode is only supported when backgroundViewHTML is omitted.
+   */
+  previewBarcodeData?: boolean;
+
+  /**
+   * Optional. Determines whether the scanner collects the results of scanned barcodes before sending them back to the caller. Defaults to false. When set to true, the scanner
+   * collects the results of scanned barcodes and displays them on the screen. When the user taps done, the scanned barcode data is sent back to the caller.
+   */
+  enableBulkScan?: boolean;
+
+  /**
+   * Optional. Determines whether the scanner detects multiple barcodes simultaneously. Defaults to false. Setting this parameter to true will automatically set the enableBulkScan parameter to true as well.
+   */
+  enableMultiScan?: boolean;
+
+  /**
+   * Optional. Enable flashlight. Defaults to false.
+   */
+  enableFlashlight?: boolean;
+
+  /**
+   * Optional. Defaults to 1.0 or 1x magnification. Sets the initial magnification level of the camera when launching the scanner.
+   * A value of 1.0 represents no magnification (1x). Higher values (e.g., 2.0 or 4.0) can be useful for scanning small barcodes
+   * without requiring manual zoom gestures. Users can still adjust the zoom level using pinch-to-zoom gestures.
+   * Note: If the provided zoom factor exceeds the device camera's supported range, the value will be clamped to the nearest
+   * supported min/max zoom factor.
+   */
+  initialZoomFactor?: number;
+}
+```

package/skills/using-mobile-native-capabilities/references/base-capability.md

@@ -0,0 +1,22 @@
+# BaseCapability
+
+Common interface implemented by every mobile native capability. Use `isAvailable()` to gate code paths so the LWC degrades gracefully on unsupported surfaces (desktop, mobile web).
+
+```typescript
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Provide all services with common functionalities.
+ */
+export interface BaseCapability {
+  /**
+   * Use this function to determine whether the respective service functionality is available.
+   * @returns Returns true when used on a supported device and false otherwise.
+   */
+  isAvailable(): boolean;
+}
+```

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

@@ -0,0 +1,90 @@
+# Biometrics Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages biometrics scanning facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the face recognition and the finger printing scanner of the mobile device to authorize the user, within the LWC.
+
+## Biometrics 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 BiometricsService}.
+ * @returns An instance of {@linkcode BiometricsService}.
+ */
+export function getBiometricsService(): BiometricsService;
+
+/**
+ * Access a device’s biometrics capabilities from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-biometricsservice.html|BiometricsService API}
+ */
+export interface BiometricsService extends BaseCapability {
+  /**
+   * Verify if the biometrics hardware or pin code is available to use to verify the user’s device ownership.
+   * @param options A {@linkcode BiometricsServiceOptions} object to configure the {@linkcode BiometricsService} request.
+   * @returns A Promise object that resolves as a Boolean value. True if the biometrics hardware or pin code is available for use and false otherwise.
+   */
+  isBiometricsReady(options?: BiometricsServiceOptions): Promise<boolean>;
+
+  /**
+   * Verify if the user is the device owner using the device’s biometrics hardware or pin code.
+   * @param options A {@linkcode BiometricsServiceOptions} object to configure the {@linkcode BiometricsService} request.
+   * @returns A Promise object that resolves as a Boolean value. True if the user is the registered device owner and false otherwise.
+   */
+  checkUserIsDeviceOwner(options?: BiometricsServiceOptions): Promise<boolean>;
+}
+
+/**
+ * An object for specifying which instances of a recurring event are affected by an update to or deletion of one instance of the event.
+ */
+export interface BiometricsServiceOptions {
+  /**
+   * Reason to use biometrics scanner.
+   */
+  permissionRequestBody?: string;
+
+  /**
+   * Title used in the dialog when the reason text is displayed. Allowed on iOS, but effective only on Android.
+   */
+  permissionRequestTitle?: string;
+
+  /**
+   * Policies specified in the array allows customization of the biometrics scan behavior.
+   */
+  additionalSupportedPolicies?: BiometricsServicePolicy[];
+}
+
+/**
+ * An object representing policy to use pin code as an alternative to biometrics.
+ */
+export type BiometricsServicePolicy = /** User cancelled the operation. */ 'PIN_CODE';
+
+/**
+ * An object representing an error that occurred when accessing {@linkcode BiometricsService} features.
+ */
+interface BiometricsServiceFailure {
+  /**
+   * A value representing the reason for a biometrics service error. See {@linkcode BiometricsServiceFailureCode} for the list of possible values.
+   */
+  code: BiometricsServiceFailureCode;
+
+  /**
+   * 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 BiometricsServiceFailure} object.
+ */
+type BiometricsServiceFailureCode =
+  | 'HARDWARE_NOT_AVAILABLE' // There is no fingerprint scanner or face recognition hardware found.
+  | 'NOT_CONFIGURED' // Biometrics hardware was found but has not been set up yet.
+  | 'SERVICE_NOT_ENABLED' // BiometricsService 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 BiometricsServiceFailure message.
+```

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