@salesforce/nimbus-plugin-lds 1.100.2

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2022 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2022, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/Readme.md

@@ -0,0 +1,11 @@
+# nimbus-plugin-lds
+
+Nimbus plugins for LDS on Mobile native integrations: durable store, networking, and draft queue.
+
+## Install
+
+Install as a dev dependency using:
+
+```sh
+npm install -D @salesforce/nimbus-plugin-lds
+```

package/dist/BinaryStorePlugin.d.ts

@@ -0,0 +1,82 @@
+declare module 'nimbus-types' {
+    interface NimbusPlugins {
+        LdsBinaryStorePlugin: BinaryStorePlugin;
+    }
+}
+/**
+ * A nimbus plugin for interacting with a binary file store.
+ *
+ * The implementation can be used as a "store" where the file in the store is the only
+ * copy and there is essentially no expiration (the file is never stale). Or it can be
+ * used as a "cache" where the canonical copy of the file exists somewhere else (like
+ * on a remote server).
+ *
+ * The caching behavior should follow the "stale-while-revalidate" pattern, where
+ * a cached file (which has a non-null expiration and a canonical URI) should always
+ * return the cached version, and if the file is past expiration (ie: "stale") then
+ * the implementation should attempt to re-downloaded the file from the canonical
+ * URI in the background.
+ *
+ */
+export interface BinaryStorePlugin {
+    /**
+     * Stores a binary file in the store.  The file will not have a TTL. This is
+     * meant to store local-only files.
+     *
+     * @param data The data of the binary file to put into the store.
+     * @param type The MIME type of the binary file. Ex: "image/png".
+     * @param size The number of bytes of data contained within the file.
+     * @param onSuccess Callback to call with the string representing the URI of
+     *        the binary file.
+     * @param onError Callback to call if there was an error.
+     */
+    storeBinary(data: Uint8Array, type: string, size: number, onSuccess: (uri: string) => void, onError: (errorMessage: string) => void): void;
+    /**
+     * Caches a binary file in the store.  This is meant to locally cache a file
+     * thats source-of-truth exists at the given URL.
+     *
+     * If the file is unable to be downloaded the onError callback will be called.
+     *
+     * This method should return a URI to the file, which may or may not be the
+     * same as the remote URL. In other words, the URI returned to callers should
+     * be treated as opaque by the callers.
+     *
+     * @param url The URL of the file.
+     * @param ttlSeconds The TTL in seconds for this file.  The file's expiration
+     *        should be calculated by Date.now + ttlSeconds.
+     * @param onSuccess Callback to call with the string representing the URI of
+     *        the binary file.
+     * @param onError Callback to call if there was an error.
+     */
+    cacheBinary(url: string, ttlSeconds: number, onSuccess: (uri: string) => void, onError: (errorMessage: string) => void): void;
+    /**
+     * Removes the binary file given its URI.
+     *
+     * @param uri The URI of the binary file
+     * @param onSuccess Callback to be called once finished.  The wasFound
+     *        parameter will be true if the file existed and has been removed, or
+     *        false if the file does not exist.
+     * @param onError Callback to call if there was an unexpected error.
+     */
+    removeBinary(uri: string, onSuccess: (wasFound: boolean) => void, onError: (errorMessage: string) => void): void;
+    /**
+     * Set the canonical URL for the file at the given uri.  The file will immediately
+     * be marked as stale (since we know the file's source of truth has changed).
+     *
+     * If there is no file at the given URI then this method will immediately cache
+     * the file at the canonicalUrl (essentially the same as calling {@link cacheBinary}).
+     *
+     * This method should return a URI to the file, which may or may not be
+     * different from the original URI, and may or may not be the same as the
+     * canonicalUrl.
+     *
+     * @param uri The URI of the existing, local binary file
+     * @param canonicalUrl The new, canonical URL (a URL is a type of URI) of the file
+     * @param ttlSeconds The TTL in seconds for this file.  The file's expiration
+     *        should be calculated by Date.now + ttlSeconds.
+     * @param onSuccess Callback to call with the string representing the new URI
+     *        to the file, which may or may not be the same as canonicalUrl.
+     * @param onError Callback to call if there was an error.
+     */
+    setCanonicalUrl(uri: string, canonicalUrl: string, ttlSeconds: number, onSuccess: (uri: string) => void, onError: (errorMessage: string) => void): void;
+}

package/dist/DraftQueue.d.ts

@@ -0,0 +1,22 @@
+declare module 'nimbus-types' {
+    interface NimbusPlugins {
+        LdsDraftQueue: DraftQueue;
+    }
+}
+/**
+ * Defines the DraftQueue that allows LDS running in the webview to interact with the
+ * DraftQueue instance running in JSCore. Since the method parameters are opaque
+ * to the native container everything passed into the nimbus plugin is serialized
+ * and the jscore-side of the plugin implementation will perform the
+ * serialization/deserialization of the parameters
+ */
+export interface DraftQueue {
+    /**
+     * A generic proxy method to invoke various methods on the draft queue
+     * @param methodName The name of the proxy method to invoke
+     * @param serializedArgsArray A serialized array of arguments
+     * @param resultCallback Success callback containing serialized result
+     * @param errorCallback Error callback containing serialized error
+     */
+    callProxyMethod(methodName: string, serializedArgsArray: string, resultCallback: (serializedResult: string) => void, errorCallback: (serializedError: string) => void): void;
+}

package/dist/InspectorPlugin.d.ts

@@ -0,0 +1,8 @@
+declare module 'nimbus-types' {
+    interface NimbusPlugins {
+        LdsInspectorPlugin: InspectorPlugin;
+    }
+}
+export interface InspectorPlugin {
+    sendAdapterReport(serializedReport: string): void;
+}

package/dist/JsSqliteStorePlugin/JsSqliteStorePlugin.d.ts

@@ -0,0 +1,23 @@
+import type { SqliteType, SqliteResult } from '@salesforce/lds-store-sql';
+import type { Database } from 'sql.js';
+import type { SqliteOperation, SqliteStorePlugin } from '../SqliteStorePlugin';
+import { JsSqliteStorePluginBase } from './JsSqliteStorePluginBase';
+type DatabaseFactory = () => Promise<Database>;
+/**
+ * A class that implements the {@link SqliteStorePlugin} interface based on
+ * sql.js (https://sql.js.org/)
+ */
+export declare class JsSqliteStorePlugin extends JsSqliteStorePluginBase implements SqliteStorePlugin {
+    private db;
+    private readonly dbFactory;
+    /**
+     * @param factory A factory that returns a Promise to a sql.js Database object
+     */
+    constructor(factory: DatabaseFactory);
+    private factoryPromise;
+    private getDatabase;
+    resetDatabase(): void;
+    query(sql: string, params: SqliteType[], onResult: (result: SqliteResult) => void, onError: (message: string) => void): Promise<void>;
+    batchOperations(operations: SqliteOperation[], onCompletion: (error: string | null) => void): Promise<void>;
+}
+export {};

package/dist/JsSqliteStorePlugin/JsSqliteStorePluginBase.d.ts

@@ -0,0 +1,17 @@
+import type { SqliteType, SqliteResult } from '@salesforce/lds-store-sql';
+import type { SqliteOperation, SqliteStoreChange, SqliteStorePlugin } from '../SqliteStorePlugin';
+type ListenerMap = Map<string, (changes: SqliteStoreChange[]) => void>;
+export declare abstract class JsSqliteStorePluginBase implements SqliteStorePlugin {
+    private listenerCounter;
+    protected listeners: ListenerMap;
+    abstract query(sql: string, params: SqliteType[], onResult: (result: SqliteResult) => void, onError: (message: string) => void): Promise<void>;
+    abstract batchOperations(operations: SqliteOperation[], onCompletion: (error: string | null) => void): Promise<void>;
+    registerOnChangedListener(listener: (changes: SqliteStoreChange[]) => void): Promise<string>;
+    unsubscribeOnChangedListener(id: string): Promise<void>;
+    protected notifyListeners(operations: SqliteOperation[]): void;
+}
+/**
+ * This function takes an unknown error and normalizes it to an Error object
+ */
+export declare function normalizeError(error: unknown): Error;
+export {};

package/dist/JsSqliteStorePlugin/JsWorkerSqliteStorePlugin.d.ts

@@ -0,0 +1,12 @@
+import type { SqliteType, SqliteResult } from '@salesforce/lds-store-sql';
+import { JsSqliteStorePluginBase } from './JsSqliteStorePluginBase';
+import type { SqliteOperation, SqliteStorePlugin } from '../SqliteStorePlugin';
+export declare class JsSqliteStoreWebWorkerPlugin extends JsSqliteStorePluginBase implements SqliteStorePlugin {
+    private callbackId;
+    private readonly queryCallbackMap;
+    private readonly batchCallbackMap;
+    private readonly worker;
+    constructor();
+    query(sql: string, params: SqliteType[], onResult: (result: SqliteResult) => void, onError: (message: string) => void): Promise<void>;
+    batchOperations(operations: SqliteOperation[], onCompletion: (error: string | null) => void): Promise<void>;
+}

package/dist/JsSqliteStorePlugin/JsWorkerSqliteStorePlugin.worker.d.ts

@@ -0,0 +1,24 @@
+import type { SqliteType } from '@salesforce/lds-store-sql';
+import type { SqliteOperation } from '../SqliteStorePlugin';
+export type QueryRequest = {
+    functionName: 'query';
+    sql: string;
+    params: SqliteType[];
+    callbackId: number;
+};
+export type BatchOperationsRequest = {
+    functionName: 'batchOperations';
+    operations: SqliteOperation[];
+    callbackId: number;
+};
+export type Response<T, E = Error> = {
+    callbackId: number;
+    functionName: 'query' | 'batchOperations';
+    result: T;
+    error: undefined;
+} | {
+    callbackId: number;
+    functionName: 'query' | 'batchOperations';
+    result: undefined;
+    error: E;
+};

package/dist/JsSqliteStorePlugin/PluginFunctions.d.ts

@@ -0,0 +1,9 @@
+import type { SqliteType, SqliteResult } from '@salesforce/lds-store-sql';
+import type { Database } from 'sql.js';
+import type { SqliteOperation } from '../SqliteStorePlugin';
+export declare function query(database: Database, sql: string, params: SqliteType[], onResult: (result: SqliteResult) => void, onError: (message: string) => void): void;
+/**
+ * Performs the operations on the DB.  NOTE: this function does not do anything
+ * with notifying change listeners.  Callers need to handle that.
+ */
+export declare function batchOperations(database: Database, operations: SqliteOperation[]): void;

package/dist/NetworkAdapter.d.ts

@@ -0,0 +1,89 @@
+declare module 'nimbus-types' {
+    interface NimbusPlugins {
+        LdsNetworkAdapter: NetworkAdapter;
+    }
+}
+/**
+ *  ObservabilityContext helps us trace the path of a request
+ *  through the Native and JS layers
+ */
+export interface ObservabilityContext {
+    /**
+     * Uniquely identify a root activity like Priming, Navigation etc
+     * Multiple adapter calls can be tied to one root activity
+     *
+     * Optional
+     */
+    rootId?: string;
+    /**
+     * Should we transmit the activity from the client side
+     *
+     * Required if rootId is provided.
+     */
+    isRootActivitySampled?: boolean;
+    /**
+     * Uniquely identifies each adapter call
+     *
+     * Optional
+     */
+    traceId?: string;
+}
+/**
+ * A `NetworkError` represents a type of transient request error and an associated message
+ * if one is available.
+ */
+export interface NetworkError {
+    type: 'timeout' | 'unspecified';
+    message: string | null;
+}
+/**
+ * A `NetworkAdapter` is capable of handling `Request`s and generating `Response`s.
+ */
+export interface NetworkAdapter {
+    /**
+     * Send the request, returning a token that can be used to cancel the request.
+     *
+     * @param request the request to handle
+     * @param onResponse called when a Response is received
+     * @param onError called when there is an error handling the `Request`. The `error`
+     * is a NetworkError describing what caused the error.
+     * @returns {Promise<string>} A promise resolving to a token for this request
+     */
+    sendRequest(request: Request, onResponse: (response: Response) => void, onError: (error: NetworkError) => void): Promise<string>;
+    /**
+     * Attempt to cancel a request associated with the specified token.
+     *
+     * @param token a token returned from `sendRequest`
+     * @returns {void}
+     */
+    cancelRequest(token: string): void;
+}
+/**
+ * An HTTP request
+ */
+export interface Request {
+    method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE';
+    priority: 'background' | 'normal' | 'high';
+    path: string;
+    headers: {
+        [key: string]: string;
+    };
+    queryParams: {
+        [key: string]: string;
+    };
+    body: string | null;
+    observabilityContext: ObservabilityContext | null;
+}
+/**
+ * An HTTP response
+ */
+export interface Response {
+    status: number;
+    headers: {
+        [key: string]: string;
+    };
+    /**
+     * A string-encoded object or null.
+     */
+    body: string | null;
+}

package/dist/SqliteStorePlugin.d.ts

@@ -0,0 +1,152 @@
+declare module 'nimbus-types' {
+    interface NimbusPlugins {
+        LdsSqliteStore: SqliteStorePlugin;
+    }
+}
+import type { SqliteResult, SqliteType } from '@salesforce/lds-store-sql';
+/**
+ * A plugin interface that is backed by a sqlite database and
+ * used by a `SqliteStore`.
+ */
+export interface SqliteStorePlugin {
+    /**
+     * @see SqliteStore.query
+     */
+    query(sql: string, params: SqliteType[], onResult: (result: SqliteResult) => void, onError: (message: string) => void): Promise<void>;
+    /**
+     * Perform a set of operations on the underlying database.
+     */
+    batchOperations(operations: SqliteOperation[], onCompletion: (error: string | null) => void): Promise<void>;
+    /**
+     * Setup a listener to be notified of changes to the Durable Store
+     *
+     * @param listener callback taking an array of store changes
+     * @returns {Promise<string>} a generated id of the listener to unsubscribe with
+     */
+    registerOnChangedListener(listener: (changes: SqliteStoreChange[]) => void): Promise<string>;
+    /**
+     *
+     * @param id the identifier given from registerOnChangedListener
+     */
+    unsubscribeOnChangedListener(id: string): Promise<void>;
+}
+/**
+ * An operation to perform on the database.
+ */
+interface SqliteOperationBase {
+    table: 'lds_data' | 'lds_internal' | 'lds_env_drafts' | 'lds_env_draft_id_map';
+    keyColumn: string;
+    context: SqliteOperationContext;
+}
+/**
+ * An upsert attempts to insert rows into the database. If
+ * there is a primary key or unique constraint violation it
+ * can attempt to update the existing rows.
+ *
+ * ex:
+ * ```javascript
+ * let operation = {
+ *   type: "upsert",
+ *   table: "luvio_internal",
+ *   columns: ["key", "namespace", "data", "metadata"],
+ *   keyColumn: "key",
+ *   conflictColumns: ["key", "namespace"],
+ *   rows: [
+ *     ["001002003004005001", "ADAPTER_CONTEXT",  "{'a': 1, 'b': 2}", "{}"],
+ *     ["001002003004005002", "ADAPTER_CONTEXT", "{'a': 3, 'b': 5}", "{}"]
+ *   ],
+ *   context: {
+ *     segment: "ADAPTER_CONTEXT"
+ *   }
+ * }
+ * ```
+ *
+ * ```sql
+ * insert into luvio_internal (key, namespace, data, metadata)
+ * values (?, ?, ?, ?)
+ * on conflict (key, namespace) do
+ * update set value = excluded.value, metada = excluded.metadata
+ * ```
+ */
+interface SqliteUpsert extends SqliteOperationBase {
+    type: 'upsert';
+    conflictColumns: string[];
+    columns: string[];
+    rows: SqliteType[][];
+}
+/**
+ * Delete rows from the database.
+ *
+ * ex:
+ * ```javascript
+ * let operation = {
+ *   type: "delete",
+ *   table: "luvio_data",
+ *   keyColumn: "key",
+ *   ids: ["001002003004005001", "001002003004005002"],
+ *   context: {
+ *     segment: "DEFAULT"
+ *   }
+ * }
+ * ```
+ *
+ * ```sql
+ * delete from luvio_data where key in ("001002003004005001", "001002003004005002")
+ * ```
+ */
+interface SqliteDelete extends SqliteOperationBase {
+    type: 'delete';
+    ids: string[];
+}
+export type SqliteOperation = SqliteDelete | SqliteUpsert;
+export declare function isUpsertOperation(operation: SqliteOperation): operation is SqliteUpsert;
+/**
+ * Operations can pass any context object along with the operation.
+ * This context is opaque to the plugin and will be included in any
+ * change notifications generated from the operation.
+ */
+export type SqliteOperationContext = {
+    [s: string]: SqliteType;
+};
+/**
+ * A change from the underlying sqlite database triggered by executing a set of operations.
+ *
+ * Example:
+ *
+ * The following operation:
+ *
+ * ```javascript
+ * let operation = {
+ *   type: "delete",
+ *   table: "luvio_data",
+ *   keyColumn: "key",
+ *   ids: ["001", "002"],
+ *   context: {
+ *     segment: "DEFAULT"
+ *   }
+ * }
+ * ```
+ *
+ * should trigger the following change:
+ * ```javascript
+ * {
+ *   type: "delete",
+ *   table: "luvio_data",
+ *   keys: ["001", "002"],
+ *   context: {
+ *     segment: "DEFAULT"
+ *   }
+ * }
+ * ```
+ */
+export interface SqliteStoreChange {
+    type: SqliteOperation['type'];
+    table: string;
+    keys: SqliteType[];
+    context: SqliteOperationContext;
+}
+export declare const sortedSchemaMigrations: Array<{
+    version: number;
+    sql: string;
+}>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type * as NimbusTypes from 'nimbus-types';
+export type { NimbusTypes };
+export type { NetworkAdapter, Request, Response, NetworkError, ObservabilityContext, } from './NetworkAdapter';
+export type { DraftQueue } from './DraftQueue';
+export type { SqliteStorePlugin, SqliteOperation } from './SqliteStorePlugin';
+export type { BinaryStorePlugin } from './BinaryStorePlugin';
+export type { InspectorPlugin } from './InspectorPlugin';
+export { sortedSchemaMigrations, isUpsertOperation } from './SqliteStorePlugin';
+export { JsSqliteStorePlugin } from './JsSqliteStorePlugin/JsSqliteStorePlugin';
+export { JsSqliteStoreWebWorkerPlugin } from './JsSqliteStorePlugin/JsWorkerSqliteStorePlugin';