@salesforce/afv-skills 1.12.0 → 1.14.0

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

@@ -0,0 +1,158 @@
+# Location Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages location facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the location API of the mobile device, within the LWC.
+
+## Location 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 LocationService}.
+ * @returns An instance of {@linkcode LocationService}.
+ */
+export function getLocationService(): LocationService;
+
+/**
+ * Access and track location in a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice.html|LocationService API}
+ */
+export interface LocationService extends BaseCapability {
+  /**
+   * Gets the device’s current geolocation.
+   * @param options A {@linkcode LocationServiceOptions} object to configure the location request.
+   * @returns A Promise object that resolves as a {@linkcode LocationResult} object with the device location details.
+   */
+  getCurrentPosition(options?: LocationServiceOptions): Promise<LocationResult>;
+
+  /**
+   * Subscribes to asynchronous location updates for the mobile device.
+   * @param options A {@linkcode LocationServiceOptions} object to configure the location request.
+   * @param callback A function to handle location update responses.
+   * @returns An integer identifier for the location subscription, which you can use to end the subscription when you want to stop receiving location updates.
+   */
+  startWatchingPosition(
+    options: LocationServiceOptions | null,
+    callback: (result?: LocationResult, failure?: LocationServiceFailure) => void,
+  ): number;
+
+  /**
+   * Unsubscribes from location updates for the mobile device.
+   * @param watchId An integer identifier for an active location subscription, returned by a call to startWatchingPosition().
+   */
+  stopWatchingPosition(watchId: number): void;
+}
+
+/**
+ * LocationResult interface.
+ */
+export interface LocationResult {
+  /**
+   * The physical location.
+   */
+  coords: Coordinates;
+
+  /**
+   * The time of the location reading, measured in milliseconds since January 1, 1970.
+   */
+  timestamp: number;
+}
+
+/**
+ * An object representing a specific point located on the planet Earth. Includes velocity details, if available.
+ * Includes accuracy information, to the best of the device’s ability to evaluate. Similar to a GeolocationCoordinates in the Geolocation Web API.
+ */
+export interface Coordinates {
+  /**
+   * The latitude, in degrees. Ranges from -90 to 90.
+   */
+  latitude: number;
+
+  /**
+   * The longitude, in degrees. Ranges from -180 to 180.
+   */
+  longitude: number;
+
+  /**
+   * Optional. Accuracy of the location measurement, in meters, as a radius around the measurement.
+   */
+  accuracy?: number;
+
+  /**
+   * Optional. Meters above sea level.
+   */
+  altitude?: number;
+
+  /**
+   * Optional. Accuracy of the altitude measurement, in meters.
+   */
+  altitudeAccuracy?: number;
+
+  /**
+   * Optional. Velocity of motion, if any, in meters per second.
+   */
+  speed?: number;
+
+  /**
+   * Optional. Accuracy of the speed measurement, in meters.
+   */
+  speedAccuracy?: number;
+
+  /**
+   * Optional. Direction of motion, in degrees from true north. Ranges from 0 to 360.
+   */
+  heading?: number;
+
+  /**
+   * Optional. Accuracy of the heading measurement, in degrees.
+   */
+  headingAccuracy?: number; // accuracy for the heading in degree
+}
+
+/**
+ * An object representing an error that occurred when accessing LocationService features.
+ */
+export interface LocationServiceFailure {
+  /**
+   * A value representing the reason for a location error.
+   */
+  code: LocationServiceFailureCode;
+
+  /**
+   * 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 LocationServiceFailureCode =
+  | 'LOCATION_SERVICE_DISABLED' // Android only - The code when 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
+  | '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 LocationServiceFailure message.
+
+/**
+ * An object representing configuration details for a location service session.
+ */
+export interface LocationServiceOptions {
+  /**
+   * Whether to use high accuracy mode when determining location. Set to true to prioritize location accuracy.
+   * Set to false to prioritize battery life and response time.
+   */
+  enableHighAccuracy: boolean;
+
+  /**
+   * 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 Android's location service.
+   */
+  permissionRationaleText?: string;
+}
+```

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

@@ -0,0 +1,30 @@
+# lightning/mobileCapabilities
+
+Module declaration that re-exports every native capability service. Import the factory functions from `lightning/mobileCapabilities` (or the per-service path) when authoring an LWC.
+
+```typescript
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Mobile capabilities are JavaScript APIs that make mobile hardware and platform (operating system) features available in JavaScript. They require access to device hardware, platform APIs, or both.
+ * Mobile capability APIs are available only when a Lightning web component runs in a supported mobile app on a mobile device.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-mobilecapabilities.html|lightning/mobileCapabilities Module}
+ */
+declare module 'lightning/mobileCapabilities' {
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/AppReviewService/appReviewService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/ARSpaceCapture/arSpaceCapture.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/BarcodeScanner/barcodeScanner.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/BiometricsService/biometricsService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/CalendarService/calendarService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/ContactsService/contactsService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/DocumentScanner/documentScanner.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/GeofencingService/geofencingService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/LocationService/locationService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/NfcService/nfcService.js';
+  export * from '@salesforce/lightning-types/dist/lightning/mobileCapabilities/PaymentsService/paymentsService.js';
+}
+```

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

@@ -0,0 +1,181 @@
+# NFC Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages NFC facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the NFC API of the mobile device, within the LWC.
+
+## NFC 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 NfcService}.
+ * @returns An instance of {@linkcode NfcService}.
+ */
+export function getNfcService(): NfcService;
+
+/**
+ * Interact with NFC tags from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice.html|NFCService API}
+ */
+export interface NfcService extends BaseCapability {
+  /**
+   * Reads an NFC tag and returns the data read from it.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns A Promise object that resolves to an array containing a single {@linkcode NFCMessage} object.
+   */
+  read(options?: NFCServiceOptions): Promise<NFCMessage[]>;
+
+  /**
+   * Erase the contents of an NFC tag.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns If successful, the OS returns a Promise object that resolves to null.
+   */
+  erase(options?: NFCServiceOptions): Promise<null>;
+
+  /**
+   * Write text to an NFC tag.
+   * @param payloads An array of {@linkcode NFCRecord} objects containing the raw bytes to be written.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns If successful, the OS returns a Promise object that resolves to null.
+   */
+  write(payloads: NFCRecord[], options?: NFCServiceOptions): Promise<null>;
+
+  /**
+   * Given a text payload, this function creates a properly formatted {@linkcode NFCRecord} to be written to an NFC tag.
+   * @param payload A {@link TextPayload} object, which contains the text to be converted to an NFC record.
+   * @returns A Promise object that resolves to an {@linkcode NFCRecord} object.
+   */
+  createTextRecord(payload: TextPayload): Promise<NFCRecord>;
+
+  /**
+   * Given a URI string payload, this function creates a properly formatted {@linkcode NFCRecord} to be written to an NFC tag.
+   * @param payload The URI to be converted to an NFC record.
+   * @returns A Promise object that resolves to an {@linkcode NFCRecord} object.
+   */
+  createUriRecord(payload: string): Promise<NFCRecord>;
+}
+
+/**
+ * An object returned by an NFC read() operation.
+ */
+export interface NFCMessage {
+  /**
+   * The size, in number of bytes, of the data received by the read() operation.
+   */
+  totalByteLength: number;
+
+  /**
+   * An array containing a single {@linkcode NFCMessageRecord} object, which in turn contains the payload from the NFC tag.
+   */
+  records: NFCMessageRecord[];
+}
+
+/**
+ * An object within an {@linkcode NFCMessage} object, containing the payload read from an NFC tag.
+ */
+export interface NFCMessageRecord {
+  /**
+   * Contains the parsed values of the raw data read from the NFC tag. The parsing operation
+   * only occurs if the value of the typeNameFormat property on the {@linkcode NFCRecord} object is "WELLKNOWN".
+   * Otherwise, this property’s value is null.
+   */
+  parsed: NFCRecord;
+
+  /**
+   * Contains the raw base64 data string read from the NFC tag.
+   */
+  raw: NFCRecord;
+}
+
+/**
+ * An object containing one record of data from an NFC tag scan.
+ */
+export interface NFCRecord {
+  /**
+   * The Type Name Format field of the payload, as defined by the NDEF specification.
+   */
+  typeNameFormat: TypeNameFormat;
+
+  /**
+   * The type of the payload, as defined by the NDEF specification.
+   */
+  type: string;
+
+  /**
+   * The identifier of the payload, as defined by the NDEF specification, or an empty string if no identifier data was present in the tag.
+   */
+  identifier: string;
+
+  /**
+   * The content of the record, encoded in base64 format.
+   */
+  payload: string;
+}
+
+/**
+ * An object containing raw text input, to be converted into an {@linkcode NFCRecord}.
+ */
+export interface TextPayload {
+  /**
+   * The raw text payload to be converted.
+   */
+  text: string;
+
+  /**
+   * The ISO 639-1 language ID of the text.
+   */
+  langId: string;
+}
+
+/**
+ * The following constants are available as properties on an instance of {@linkcode NfcService}. The constants enumerate the accepted values for the associated properties.
+ */
+export type TypeNameFormat = 'ABSOLUTE_URI' | 'EMPTY' | 'EXTERNAL' | 'MEDIA' | 'WELLKNOWN' | 'UNCHANGED' | 'UNKNOWN';
+
+/**
+ * An object containing configuration details for an NFC interaction.
+ */
+export interface NFCServiceOptions {
+  /**
+   * Optional. Provides instructions to display in the user interface. Defaults to no text.
+   */
+  instructionText?: string;
+
+  /**
+   * Optional. Provides a message to display in the user interface when an NFC operation is successfully completed. Defaults to no text.
+   */
+  successText?: string;
+}
+
+/**
+ * An object representing an error that occurred when accessing {@linkcode NfcService} features.
+ */
+export interface NFCServiceFailure {
+  /**
+   * A value representing the reason for an error. See {@linkcode NFCServiceFailureCode} for the list of possible values.
+   */
+  code: NFCServiceFailureCode;
+
+  /**
+   * 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 NFCServiceFailure} object.
+ */
+export type NFCServiceFailureCode =
+  | 'USER_DISMISSED' // The user dismissed the scanner.
+  | 'NFC_NOT_SUPPORTED' // The device doesn’t support NFC capabilities.
+  | 'NFC_NOT_ENABLED' // The device NFC feature is turned off.
+  | 'TAG_EMPTY' // The NFC tag contains no data to be read.
+  | 'SERVICE_NOT_ENABLED' // NFCService 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 NFCServiceFailure message.
+```

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

@@ -0,0 +1,95 @@
+# Payments Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages payments facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the payments API of the mobile device, within the LWC.
+
+## Payments 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 PaymentsService}.
+ * @returns An instance of {@linkcode PaymentsService}.
+ */
+export function getPaymentsService(): PaymentsService;
+
+/**
+ * PaymentsService is a Nimbus plugin that allows JavaScript code in a Lightning web component to call functions that launches Stripe's Tap to Pay capabilities.
+ */
+export interface PaymentsService extends BaseCapability {
+  /**
+   * Process payment.
+   * @param options The customization options.
+   * @returns A Promise object that resolves to {@linkcode CollectPaymentResult} object.
+   */
+  collectPayment(options: CollectPaymentOptions): Promise<CollectPaymentResult>;
+
+  /**
+   * Get the supported payment methods on this device
+   * @param options The customization options.
+   * @returns  A Promise object that resolves to an array containing {@linkcode PaymentMethod} objects.
+   */
+  getSupportedPaymentMethods(options: GetSupportedPaymentMethodsOptions): Promise<PaymentMethod[]>;
+}
+
+/**
+ * PaymentMethod values.
+ */
+export type PaymentMethod = 'TAP_TO_PAY' | 'CREDIT_CARD_DETAILS' | 'PAY_VIA_LINK';
+
+/**
+ * GetSupportedPaymentMethodsOptions interface.
+ */
+export interface GetSupportedPaymentMethodsOptions {
+  countryIsoCode?: string;
+  merchantAccountId?: string;
+  permissionRationaleText?: string;
+}
+
+/**
+ * CollectPaymentOptions interface.
+ */
+export interface CollectPaymentOptions {
+  amount: number;
+  paymentMethod: PaymentMethod;
+  currencyIsoCode: string;
+  merchantAccountId: string;
+  merchantName: string;
+  payerAccountId?: string;
+  sourceObjectIds?: string[];
+  permissionRationaleText?: string;
+}
+
+/**
+ * CollectPaymentResult interface.
+ */
+export interface CollectPaymentResult {
+  gatewayRefId?: string;
+  guid?: string;
+  paymentGatewayId?: string;
+  status?: string;
+}
+
+/**
+ * PaymentsServiceFailure interface.
+ */
+export interface PaymentsServiceFailure {
+  code: PaymentsServiceFailureCode;
+  message: string;
+}
+
+/**
+ * Possible failure codes.
+ */
+export type PaymentsServiceFailureCode =
+  | 'USER_DISMISSED' // User cancelled the operation.
+  | 'USER_DENIED_PERMISSION' // Permission to access device location is denied.
+  | '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 PaymentsServiceFailure message.
+```