@jsforce/jsforce-node 0.0.1 → 3.0.0-next.2

package/lib/api/soap.d.ts

@@ -0,0 +1,76 @@
+import Connection from '../connection';
+import { Schema, Record, SoapSchemaDef, SoapSchema } from '../types';
+import { LeadConvert, LeadConvertResult, MergeRequest, MergeResult, EmptyRecycleBinResult, DescribeTabSetResult, GetServerTimestampResult, GetUserInfoResult, ResetPasswordResult, SaveResult, UpsertResult, DeleteResult } from './soap/schema';
+/**
+ * API class for Partner SOAP call
+ */
+export declare class SoapApi<S extends Schema> {
+    _conn: Connection<S>;
+    constructor(conn: Connection<S>);
+    /**
+     * Call SOAP Api (Partner) endpoint
+     * @private
+     */
+    _invoke(method: string, message: object, schema: SoapSchema | SoapSchemaDef): Promise<any>;
+    /**
+     * Converts a Lead into an Account, Contact, or (optionally) an Opportunity.
+     */
+    convertLead(leadConverts: Partial<LeadConvert>[]): Promise<LeadConvertResult[]>;
+    convertLead(leadConvert: Partial<LeadConvert>): Promise<LeadConvertResult>;
+    convertLead(leadConvert: Partial<LeadConvert> | Partial<LeadConvert>[]): Promise<LeadConvertResult | LeadConvertResult[]>;
+    /**
+     * Merge up to three records into one
+     */
+    merge(mergeRequests: Partial<MergeRequest>[]): Promise<MergeResult[]>;
+    merge(mergeRequest: Partial<MergeRequest>): Promise<MergeResult>;
+    merge(mergeRequest: Partial<MergeRequest> | Partial<MergeRequest>[]): Promise<MergeResult | MergeResult[]>;
+    /**
+     * Delete records from the recycle bin immediately
+     */
+    emptyRecycleBin(ids: string[]): Promise<EmptyRecycleBinResult>;
+    /**
+     * Returns information about the standard and custom apps available to the logged-in user
+     */
+    describeTabs(): Promise<DescribeTabSetResult[]>;
+    /**
+     * Retrieves the current system timestamp (Coordinated Universal Time (UTC) time zone) from the API
+     */
+    getServerTimestamp(): Promise<GetServerTimestampResult>;
+    /**
+     * Retrieves personal information for the user associated with the current session
+     */
+    getUserInfo(): Promise<GetUserInfoResult>;
+    /**
+     * Sets the specified user’s password to the specified value
+     */
+    setPassword(userId: string, password: string): Promise<string>;
+    /**
+     * Resets the specified user’s password
+     */
+    resetPassword(userId: string): Promise<ResetPasswordResult>;
+    /**
+     * Adds one or more new records to your organization’s data
+     */
+    create(sObject: Record[]): Promise<SaveResult[]>;
+    create(sObject: Record): Promise<SaveResult>;
+    create(sObjects: Record | Record[]): Promise<SaveResult | SaveResult[]>;
+    /**
+     * Updates one or more existing records in your organization’s data.
+     */
+    update(sObject: Record[]): Promise<SaveResult[]>;
+    update(sObject: Record): Promise<SaveResult>;
+    update(sObjects: Record | Record[]): Promise<SaveResult | SaveResult[]>;
+    /**
+     * Creates new records and updates existing records in your organization’s data.
+     */
+    upsert(externalIdFieldName: string, sObjects: Record[]): Promise<UpsertResult[]>;
+    upsert(externalIdFieldName: string, sObject: Record): Promise<UpsertResult>;
+    upsert(externalIdFieldName: string, sObjects: Record | Record[]): Promise<UpsertResult | UpsertResult[]>;
+    /**
+     * Deletes one or more records from your organization’s data
+     */
+    delete(ids: string | string[]): Promise<DeleteResult[]>;
+    delete(id: string): Promise<DeleteResult>;
+    delete(ids: string | string[]): Promise<DeleteResult | DeleteResult[]>;
+}
+export default SoapApi;

package/lib/api/soap.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoapApi = void 0;
+/**
+ * @file Salesforce SOAP API
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+const jsforce_1 = require("../jsforce");
+const soap_1 = __importDefault(require("../soap"));
+const schema_1 = require("./soap/schema");
+/**
+ *
+ */
+function toSoapRecord(records) {
+    return (Array.isArray(records) ? records : [records]).map((record) => {
+        const { type, attributes, ...rec } = record;
+        const t = type || attributes?.type;
+        if (!t) {
+            throw new Error('Given record is not including sObject type information');
+        }
+        const fieldsToNull = Object.keys(rec).filter((field) => record[field] === null);
+        for (const field of fieldsToNull) {
+            delete rec[field];
+        }
+        return fieldsToNull.length > 0
+            ? { type: t, fieldsToNull, ...rec }
+            : { type: t, ...rec };
+    });
+}
+/**
+ * API class for Partner SOAP call
+ */
+class SoapApi {
+    _conn;
+    constructor(conn) {
+        this._conn = conn;
+    }
+    /**
+     * Call SOAP Api (Partner) endpoint
+     * @private
+     */
+    async _invoke(method, message, schema) {
+        const soapEndpoint = new soap_1.default(this._conn, {
+            xmlns: 'urn:partner.soap.sforce.com',
+            endpointUrl: `${this._conn.instanceUrl}/services/Soap/u/${this._conn.version}`,
+        });
+        const res = await soapEndpoint.invoke(method, message, schema ? { result: schema } : undefined, schema_1.ApiSchemas);
+        return res.result;
+    }
+    async convertLead(leadConverts) {
+        const schema = Array.isArray(leadConverts)
+            ? [schema_1.ApiSchemas.LeadConvertResult]
+            : schema_1.ApiSchemas.LeadConvertResult;
+        return this._invoke('convertLead', { leadConverts }, schema);
+    }
+    async merge(mergeRequests) {
+        const schema = Array.isArray(mergeRequests)
+            ? [schema_1.ApiSchemas.MergeResult]
+            : schema_1.ApiSchemas.MergeResult;
+        return this._invoke('merge', { mergeRequests }, schema);
+    }
+    /**
+     * Delete records from the recycle bin immediately
+     */
+    async emptyRecycleBin(ids) {
+        return this._invoke('emptyRecycleBin', { ids }, [
+            schema_1.ApiSchemas.EmptyRecycleBinResult,
+        ]);
+    }
+    /**
+     * Returns information about the standard and custom apps available to the logged-in user
+     */
+    async describeTabs() {
+        return this._invoke('describeTabs', {}, [schema_1.ApiSchemas.DescribeTabSetResult]);
+    }
+    /**
+     * Retrieves the current system timestamp (Coordinated Universal Time (UTC) time zone) from the API
+     */
+    async getServerTimestamp() {
+        return this._invoke('getServerTimestamp', {}, schema_1.ApiSchemas.GetServerTimestampResult);
+    }
+    /**
+     * Retrieves personal information for the user associated with the current session
+     */
+    async getUserInfo() {
+        return this._invoke('getUserInfo', {}, schema_1.ApiSchemas.GetUserInfoResult);
+    }
+    /**
+     * Sets the specified user’s password to the specified value
+     */
+    setPassword(userId, password) {
+        return this._invoke('setPassword', { userId, password }, 'string');
+    }
+    /**
+     * Resets the specified user’s password
+     */
+    resetPassword(userId) {
+        return this._invoke('resetPassword', { userId }, schema_1.ApiSchemas.ResetPasswordResult);
+    }
+    create(sObjects) {
+        const schema = Array.isArray(sObjects)
+            ? [schema_1.ApiSchemas.SaveResult]
+            : schema_1.ApiSchemas.SaveResult;
+        const args = {
+            '@xmlns': 'urn:partner.soap.sforce.com',
+            '@xmlns:ns1': 'sobject.partner.soap.sforce.com',
+            'ns1:sObjects': toSoapRecord(sObjects),
+        };
+        return this._invoke('create', args, schema);
+    }
+    update(sObjects) {
+        const schema = Array.isArray(sObjects)
+            ? [schema_1.ApiSchemas.SaveResult]
+            : schema_1.ApiSchemas.SaveResult;
+        const args = {
+            '@xmlns': 'urn:partner.soap.sforce.com',
+            '@xmlns:ns1': 'sobject.partner.soap.sforce.com',
+            'ns1:sObjects': toSoapRecord(sObjects),
+        };
+        return this._invoke('update', args, schema);
+    }
+    upsert(externalIdFieldName, sObjects) {
+        const schema = Array.isArray(sObjects)
+            ? [schema_1.ApiSchemas.UpsertResult]
+            : schema_1.ApiSchemas.UpsertResult;
+        const args = {
+            '@xmlns': 'urn:partner.soap.sforce.com',
+            '@xmlns:ns1': 'sobject.partner.soap.sforce.com',
+            'ns1:externalIDFieldName': externalIdFieldName,
+            'ns1:sObjects': toSoapRecord(sObjects),
+        };
+        return this._invoke('upsert', args, schema);
+    }
+    delete(ids) {
+        const schema = Array.isArray(ids)
+            ? [schema_1.ApiSchemas.DeleteResult]
+            : schema_1.ApiSchemas.DeleteResult;
+        const args = {
+            '@xmlns': 'urn:partner.soap.sforce.com',
+            '@xmlns:ns1': 'sobject.partner.soap.sforce.com',
+            'ns1:ids': ids,
+        };
+        return this._invoke('delete', args, schema);
+    }
+}
+exports.SoapApi = SoapApi;
+/*--------------------------------------------*/
+/*
+ * Register hook in connection instantiation for dynamically adding this API module features
+ */
+(0, jsforce_1.registerModule)('soap', (conn) => new SoapApi(conn));
+exports.default = SoapApi;

package/lib/api/streaming/extension.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Faye Client extensions: https://faye.jcoglan.com/browser/extensions.html
+ *
+ * For use with Streaming.prototype.createClient()
+ **/
+/**
+ * Constructor for an auth failure detector extension
+ *
+ * Based on new feature released with Salesforce Spring '18:
+ * https://releasenotes.docs.salesforce.com/en-us/spring18/release-notes/rn_messaging_cometd_auth_validation.htm?edition=&impact=
+ *
+ * Example triggering error message:
+ *
+ * ```
+ * {
+ *   "ext":{
+ *     "sfdc":{"failureReason":"401::Authentication invalid"},
+ *     "replay":true},
+ *   "advice":{"reconnect":"none"},
+ *   "channel":"/meta/handshake",
+ *   "error":"403::Handshake denied",
+ *   "successful":false
+ * }
+ * ```
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const jsforce = require('jsforce');
+ * const { StreamingExtension } = require('jsforce/api/streaming');
+ *
+ * const conn = new jsforce.Connection({ … });
+ *
+ * const channel = "/event/My_Event__e";
+ *
+ * // Exit the Node process when auth fails
+ * const exitCallback = () => process.exit(1);
+ * const authFailureExt = new StreamingExtension.AuthFailure(exitCallback);
+ *
+ * const fayeClient = conn.streaming.createClient([ authFailureExt ]);
+ *
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ *
+ * subscription.cancel();
+ * ```
+ *
+ * @param {Function} failureCallback - Invoked when authentication becomes invalid
+ */
+export declare class AuthFailure {
+    _failureCallback: Function;
+    constructor(failureCallback: Function);
+    incoming(message: any, callback: Function): void;
+}
+/**
+ * Constructor for a durable streaming replay extension
+ *
+ * Modified from original Salesforce demo source code:
+ * https://github.com/developerforce/SalesforceDurableStreamingDemo/blob/3d4a56eac956f744ad6c22e6a8141b6feb57abb9/staticresources/cometdReplayExtension.resource
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const jsforce = require('jsforce');
+ * const { StreamingExtension } = require('jsforce/api/streaming');
+ 
+ * const conn = new jsforce.Connection({ … });
+ *
+ * const channel = "/event/My_Event__e";
+ * const replayId = -2; // -2 is all retained events
+ *
+ * const replayExt = new StreamingExtension.Replay(channel, replayId);
+ *
+ * const fayeClient = conn.streaming.createClient([ replayExt ]);
+ *
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ *
+ * subscription.cancel();
+ * ```
+ */
+export declare class Replay {
+    _extensionEnabled: boolean;
+    _replay: number | null | undefined;
+    _channel: string;
+    constructor(channel: string, replayId?: number | null);
+    setExtensionEnabled(extensionEnabled: boolean): void;
+    setReplay(replay: string): void;
+    setChannel(channel: string): void;
+    incoming(message: any, callback: Function): void;
+    outgoing(message: any, callback: Function): void;
+}

package/lib/api/streaming/extension.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Faye Client extensions: https://faye.jcoglan.com/browser/extensions.html
+ *
+ * For use with Streaming.prototype.createClient()
+ **/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Replay = exports.AuthFailure = void 0;
+/*-------------------------------------------*/
+/**
+ * Constructor for an auth failure detector extension
+ *
+ * Based on new feature released with Salesforce Spring '18:
+ * https://releasenotes.docs.salesforce.com/en-us/spring18/release-notes/rn_messaging_cometd_auth_validation.htm?edition=&impact=
+ *
+ * Example triggering error message:
+ *
+ * ```
+ * {
+ *   "ext":{
+ *     "sfdc":{"failureReason":"401::Authentication invalid"},
+ *     "replay":true},
+ *   "advice":{"reconnect":"none"},
+ *   "channel":"/meta/handshake",
+ *   "error":"403::Handshake denied",
+ *   "successful":false
+ * }
+ * ```
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const jsforce = require('jsforce');
+ * const { StreamingExtension } = require('jsforce/api/streaming');
+ *
+ * const conn = new jsforce.Connection({ … });
+ *
+ * const channel = "/event/My_Event__e";
+ *
+ * // Exit the Node process when auth fails
+ * const exitCallback = () => process.exit(1);
+ * const authFailureExt = new StreamingExtension.AuthFailure(exitCallback);
+ *
+ * const fayeClient = conn.streaming.createClient([ authFailureExt ]);
+ *
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ *
+ * subscription.cancel();
+ * ```
+ *
+ * @param {Function} failureCallback - Invoked when authentication becomes invalid
+ */
+class AuthFailure {
+    _failureCallback;
+    constructor(failureCallback) {
+        this._failureCallback = failureCallback;
+    }
+    incoming(message, callback) {
+        if ((message.channel === '/meta/connect' ||
+            message.channel === '/meta/handshake') &&
+            message.advice &&
+            message.advice.reconnect == 'none') {
+            this._failureCallback(message);
+        }
+        else {
+            callback(message);
+        }
+    }
+}
+exports.AuthFailure = AuthFailure;
+/*-------------------------------------------*/
+const REPLAY_FROM_KEY = 'replay';
+/**
+ * Constructor for a durable streaming replay extension
+ *
+ * Modified from original Salesforce demo source code:
+ * https://github.com/developerforce/SalesforceDurableStreamingDemo/blob/3d4a56eac956f744ad6c22e6a8141b6feb57abb9/staticresources/cometdReplayExtension.resource
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const jsforce = require('jsforce');
+ * const { StreamingExtension } = require('jsforce/api/streaming');
+ 
+ * const conn = new jsforce.Connection({ … });
+ *
+ * const channel = "/event/My_Event__e";
+ * const replayId = -2; // -2 is all retained events
+ *
+ * const replayExt = new StreamingExtension.Replay(channel, replayId);
+ *
+ * const fayeClient = conn.streaming.createClient([ replayExt ]);
+ *
+ * const subscription = fayeClient.subscribe(channel, data => {
+ *   console.log('topic received data', data);
+ * });
+ *
+ * subscription.cancel();
+ * ```
+ */
+class Replay {
+    _extensionEnabled;
+    _replay;
+    _channel;
+    constructor(channel, replayId) {
+        this._extensionEnabled = replayId != null;
+        this._channel = channel;
+        this._replay = replayId;
+    }
+    setExtensionEnabled(extensionEnabled) {
+        this._extensionEnabled = extensionEnabled;
+    }
+    setReplay(replay) {
+        this._replay = parseInt(replay, 10);
+    }
+    setChannel(channel) {
+        this._channel = channel;
+    }
+    incoming(message, callback) {
+        if (message.channel === '/meta/handshake') {
+            if (message.ext && message.ext[REPLAY_FROM_KEY] == true) {
+                this._extensionEnabled = true;
+            }
+        }
+        else if (message.channel === this._channel &&
+            message.data &&
+            message.data.event &&
+            message.data.event.replayId) {
+            this._replay = message.data.event.replayId;
+        }
+        callback(message);
+    }
+    outgoing(message, callback) {
+        if (message.channel === '/meta/subscribe') {
+            if (this._extensionEnabled) {
+                if (!message.ext) {
+                    message.ext = {};
+                }
+                const replayFromMap = {
+                    [this._channel]: this._replay,
+                };
+                // add "ext : { "replay" : { CHANNEL : REPLAY_VALUE }}" to subscribe message
+                message.ext[REPLAY_FROM_KEY] = replayFromMap;
+            }
+        }
+        callback(message);
+    }
+}
+exports.Replay = Replay;

package/lib/api/streaming.d.ts

@@ -0,0 +1,160 @@
+/// <reference types="node" />
+/**
+ * @file Manages Streaming APIs
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+import { EventEmitter } from 'events';
+import { Client, Subscription } from 'faye';
+import Connection from '../connection';
+import { Record, Schema } from '../types';
+import * as StreamingExtension from './streaming/extension';
+/**
+ *
+ */
+export type StreamingMessage<R extends Record> = {
+    event: {
+        type: string;
+        createdDate: string;
+        replayId: number;
+    };
+    sobject: R;
+};
+export type GenericStreamingMessage = {
+    event: {
+        createdDate: string;
+        replayId: number;
+    };
+    payload: string;
+};
+export type PushEvent = {
+    payload: string;
+    userIds: string[];
+};
+export type PushEventResult = {
+    fanoutCount: number;
+    userOnlineStatus: {
+        [userId: string]: boolean;
+    };
+};
+export { Client, Subscription };
+/**
+ * Streaming API topic class
+ */
+declare class Topic<S extends Schema, R extends Record> {
+    _streaming: Streaming<S>;
+    name: string;
+    constructor(streaming: Streaming<S>, name: string);
+    /**
+     * Subscribe listener to topic
+     */
+    subscribe(listener: (message: StreamingMessage<R>) => void): Subscription;
+    /**
+     * Unsubscribe listener from topic
+     */
+    unsubscribe(subscr: Subscription): this;
+}
+/**
+ * Streaming API Generic Streaming Channel
+ */
+declare class Channel<S extends Schema> {
+    _streaming: Streaming<S>;
+    _id: Promise<string | undefined> | undefined;
+    name: string;
+    constructor(streaming: Streaming<S>, name: string);
+    /**
+     * Subscribe to channel
+     */
+    subscribe(listener: Function): Subscription;
+    unsubscribe(subscr: Subscription): this;
+    push(events: PushEvent): Promise<PushEventResult>;
+    push(events: PushEvent): Promise<PushEventResult[]>;
+}
+/**
+ * Streaming API class
+ */
+export declare class Streaming<S extends Schema> extends EventEmitter {
+    _conn: Connection<S>;
+    _topics: {
+        [name: string]: Topic<S, Record>;
+    };
+    _fayeClients: {
+        [clientType: string]: Client;
+    };
+    /**
+     *
+     */
+    constructor(conn: Connection<S>);
+    _createClient(forChannelName?: string | null, extensions?: any[]): Client;
+    /** @private **/
+    _getFayeClient(channelName: string): Client;
+    /**
+     * Get named topic
+     */
+    topic<R extends Record = Record>(name: string): Topic<S, R>;
+    /**
+     * Get channel for channel name
+     */
+    channel(name: string): Channel<S>;
+    /**
+     * Subscribe topic/channel
+     */
+    subscribe(name: string, listener: Function): Subscription;
+    /**
+     * Unsubscribe topic
+     */
+    unsubscribe(name: string, subscription: Subscription): this;
+    /**
+     * Create a Streaming client, optionally with extensions
+     *
+     * See Faye docs for implementation details: https://faye.jcoglan.com/browser/extensions.html
+     *
+     * Example usage:
+     *
+     * ```javascript
+     * const jsforce = require('jsforce');
+     *
+     * // Establish a Salesforce connection. (Details elided)
+     * const conn = new jsforce.Connection({ … });
+     *
+     * const fayeClient = conn.streaming.createClient();
+     *
+     * const subscription = fayeClient.subscribe(channel, data => {
+     *   console.log('topic received data', data);
+     * });
+     *
+     * subscription.cancel();
+     * ```
+     *
+     * Example with extensions, using Replay & Auth Failure extensions in a server-side Node.js app:
+     *
+     * ```javascript
+     * const jsforce = require('jsforce');
+     * const { StreamingExtension } = require('jsforce/api/streaming');
+     *
+     * // Establish a Salesforce connection. (Details elided)
+     * const conn = new jsforce.Connection({ … });
+     *
+     * const channel = "/event/My_Event__e";
+     * const replayId = -2; // -2 is all retained events
+     *
+     * const exitCallback = () => process.exit(1);
+     * const authFailureExt = new StreamingExtension.AuthFailure(exitCallback);
+     *
+     * const replayExt = new StreamingExtension.Replay(channel, replayId);
+     *
+     * const fayeClient = conn.streaming.createClient([
+     *   authFailureExt,
+     *   replayExt
+     * ]);
+     *
+     * const subscription = fayeClient.subscribe(channel, data => {
+     *   console.log('topic received data', data);
+     * });
+     *
+     * subscription.cancel();
+     * ```
+     */
+    createClient(extensions: any[]): Client;
+}
+export { StreamingExtension };
+export default Streaming;