Skip to content

Commit cb6ff31

Browse files
relangorelango
committed
Initial version of open source einstein bot sdk
0 parents  commit cb6ff31

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+4472
-0
lines changed

‎.gitignore

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
*.class
2+
3+
# Mobile Tools for Java (J2ME)
4+
.mtj.tmp/
5+
6+
# Package Files #
7+
*.jar
8+
*.war
9+
*.ear
10+
*.iml
11+
*.ipr
12+
*.iws
13+
*.der
14+
15+
# exclude jar for gradle wrapper
16+
!gradle/wrapper/*.jar
17+
18+
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
19+
hs_err_pid*
20+
21+
# build files
22+
**/target
23+
target
24+
.gradle
25+
.idea
26+
build
27+
certs/
28+

‎CODE_OF_CONDUCT.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Salesforce Open Source Community Code of Conduct
2+
3+
## About the Code of Conduct
4+
5+
Equality is a core value at Salesforce. We believe a diverse and inclusive
6+
community fosters innovation and creativity, and are committed to building a
7+
culture where everyone feels included.
8+
9+
Salesforce open-source projects are committed to providing a friendly, safe, and
10+
welcoming environment for all, regardless of gender identity and expression,
11+
sexual orientation, disability, physical appearance, body size, ethnicity, nationality,
12+
race, age, religion, level of experience, education, socioeconomic status, or
13+
other similar personal characteristics.
14+
15+
The goal of this code of conduct is to specify a baseline standard of behavior so
16+
that people with different social values and communication styles can work
17+
together effectively, productively, and respectfully in our open source community.
18+
It also establishes a mechanism for reporting issues and resolving conflicts.
19+
20+
All questions and reports of abusive, harassing, or otherwise unacceptable behavior
21+
in a Salesforce open-source project may be reported by contacting the Salesforce
22+
Open Source Conduct Committee at [email protected].
23+
24+
## Our Pledge
25+
26+
In the interest of fostering an open and welcoming environment, we as
27+
contributors and maintainers pledge to making participation in our project and
28+
our community a harassment-free experience for everyone, regardless of gender
29+
identity and expression, sexual orientation, disability, physical appearance,
30+
body size, ethnicity, nationality, race, age, religion, level of experience, education,
31+
socioeconomic status, or other similar personal characteristics.
32+
33+
## Our Standards
34+
35+
Examples of behavior that contributes to creating a positive environment
36+
include:
37+
38+
* Using welcoming and inclusive language
39+
* Being respectful of differing viewpoints and experiences
40+
* Gracefully accepting constructive criticism
41+
* Focusing on what is best for the community
42+
* Showing empathy toward other community members
43+
44+
Examples of unacceptable behavior by participants include:
45+
46+
* The use of sexualized language or imagery and unwelcome sexual attention or
47+
advances
48+
* Personal attacks, insulting/derogatory comments, or trolling
49+
* Public or private harassment
50+
* Publishing, or threatening to publish, others' private information—such as
51+
a physical or electronic address—without explicit permission
52+
* Other conduct which could reasonably be considered inappropriate in a
53+
professional setting
54+
* Advocating for or encouraging any of the above behaviors
55+
56+
## Our Responsibilities
57+
58+
Project maintainers are responsible for clarifying the standards of acceptable
59+
behavior and are expected to take appropriate and fair corrective action in
60+
response to any instances of unacceptable behavior.
61+
62+
Project maintainers have the right and responsibility to remove, edit, or
63+
reject comments, commits, code, wiki edits, issues, and other contributions
64+
that are not aligned with this Code of Conduct, or to ban temporarily or
65+
permanently any contributor for other behaviors that they deem inappropriate,
66+
threatening, offensive, or harmful.
67+
68+
## Scope
69+
70+
This Code of Conduct applies both within project spaces and in public spaces
71+
when an individual is representing the project or its community. Examples of
72+
representing a project or community include using an official project email
73+
address, posting via an official social media account, or acting as an appointed
74+
representative at an online or offline event. Representation of a project may be
75+
further defined and clarified by project maintainers.
76+
77+
## Enforcement
78+
79+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
80+
reported by contacting the Salesforce Open Source Conduct Committee
81+
at [email protected]. All complaints will be reviewed and investigated
82+
and will result in a response that is deemed necessary and appropriate to the
83+
circumstances. The committee is obligated to maintain confidentiality with
84+
regard to the reporter of an incident. Further details of specific enforcement
85+
policies may be posted separately.
86+
87+
Project maintainers who do not follow or enforce the Code of Conduct in good
88+
faith may face temporary or permanent repercussions as determined by other
89+
members of the project's leadership and the Salesforce Open Source Conduct
90+
Committee.
91+
92+
## Attribution
93+
94+
This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant-home],
95+
version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html.
96+
It includes adaptions and additions from [Go Community Code of Conduct][golang-coc],
97+
[CNCF Code of Conduct][cncf-coc], and [Microsoft Open Source Code of Conduct][microsoft-coc].
98+
99+
This Code of Conduct is licensed under the [Creative Commons Attribution 3.0 License][cc-by-3-us].
100+
101+
[contributor-covenant-home]: https://www.contributor-covenant.org (https://www.contributor-covenant.org/)
102+
[golang-coc]: https://golang.org/conduct
103+
[cncf-coc]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
104+
[microsoft-coc]: https://opensource.microsoft.com/codeofconduct/
105+
[cc-by-3-us]: https://creativecommons.org/licenses/by/3.0/us/

‎LICENSE.txt

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2022, Salesforce.com, Inc.
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
7+
8+
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
9+
10+
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
11+
12+
3. Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
13+
14+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Einstein Bots Runtime - Java SDK
2+
3+
Java SDK to interact with Einstein Bots Runtime. This SDK is a wrapper around the [Einstein Bots Runtime API](https://git.soma.salesforce.com/chatbots/module-api-sdk-java/blob/master/src/main/resources/api4-0-0.yaml) that provides a few added features out of the box:
4+
5+
* Auth support
6+
* Session management
7+
8+
9+
## Auth Support
10+
11+
Einstein Bots Runtime requires requests to be authenticated using OAuth. This SDK supports the [JWT Bearer OAuth Flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm&type=5).
12+
13+
Additional auth mechanisms can be added by implementing the [AuthMechanism interface](src/main/java/com/salesforce/chatbot/sdk/auth/AuthMechanism.java).
14+
15+
## Session Management
16+
17+
A session ID is generated by Einstein Bots Runtime for every new session. This needs to be included in future requests sent to the service.
18+
19+
This SDK provides session management capabilities, caching Einstein Bots Runtime's session ID based on an external session ID.
20+
21+
An external session ID is the unique ID used to identify a session on the channel that is sending messages to Einstein Bots Runtime. Using Slack as an example,
22+
the external session ID could be a combination of Slack app ID, Slack user ID and Slack channel ID (if present).
23+
24+
`Redis` is supported out of the box. There is an `InMemoryCache` included that is meant for testing purposes only. Additional caching methods can be used by implementing the [Cache interface](src/main/java/com/salesforce/chatbot/sdk/cache/Cache.java).
25+
26+
## Usage
27+
28+
### Add POM dependency
29+
30+
```xml
31+
<dependency>
32+
<groupId>com.salesforce.chatbot</groupId>
33+
<artifactId>module-api-sdk-java</artifactId>
34+
<version>${module-api-sdk-java-version}</version>
35+
</dependency>
36+
```
37+
38+
### 1. Create Redis Cache
39+
```java
40+
41+
Cache redis = new RedisCache(); // uses default values for ttl (259,140 seonds) and redisUrl (redis://127.0.0.1:6379)
42+
43+
// for custom ttl or redis url:
44+
Cache redis = new RedisCache(ttlSeconds, redisUrl);
45+
46+
```
47+
48+
### 2. Setup OAuth
49+
```java
50+
private final String pvtKeyFile = "<your pvt key file>"; //filepath to pvt key file in der format
51+
private final String loginEndpoint = "<your login endpoint>"; //i.e. https://login.salesforce.com/
52+
private final String connectedAppId = "<your connected app id>"; //can be found in App Manager page
53+
private final String secret = "<your connected app secret>"; //can be found in App Manager page
54+
private final String userId = "<userId associated with certificate used for connected app>";
55+
56+
JwtBearerOAuth oAuth = new JwtBearerOAuth(pvtKeyFile,
57+
loginEndpoint, connectedAppId, secret, userId,
58+
cache); // 'cache' created in Step 1
59+
```
60+
61+
You are also able to use a different constructor and pass in a `java.security.PrivateKey` instead of a private key file.
62+
63+
```java
64+
public JwtBearerOAuth(PrivateKey privateKey, String loginEndpoint, String connectedAppId, String connectedAppSecret,
65+
String userId, Cache cache)
66+
```
67+
68+
### 3. Setup Session Managed Chatbot Client
69+
70+
```java
71+
SessionManagedChatbotClient client = SessionManagedChatbotClient.builder()
72+
.basePath(basePath) // Einstein Bots Runtime basepath (i.e. https://runtime-api-na-west.chatbots.sfdc.sh). Can be found in the setup page
73+
.authMechanism(oAuth) // 'oAuth' created in Step 2
74+
.integrationName(integName) // Should match integrationName used when adding API Connection for connected app.
75+
.cache(cache) // 'cache' created in Step 1
76+
.build();
77+
```
78+
79+
### 4. Sending a Message
80+
81+
```Java
82+
private void sendUsingSessionManagedClient() {
83+
84+
RequestEnvelopeMessagesOneOf textMessage = buildTextMessage("Initial message");
85+
RequestEnvelope envelope = buildRequestEnvelop(externalSessionKey, orgId, botId, forceConfigEndPoint, Arrays.asList(textMessage));
86+
87+
ResponseEnvelope resp = client.sendChatbotRequest(envelope); // 'client' created in Step 3.
88+
89+
System.out.println(resp);
90+
}
91+
92+
public static RequestEnvelopeMessagesOneOf buildTextMessage(String msg) {
93+
return new TextMessage()
94+
.text(msg)
95+
.type(TextMessage.TypeEnum.TEXT)
96+
.sequenceId(System.currentTimeMillis());
97+
}
98+
99+
public static RequestEnvelope buildRequestEnvelop(String sessionId,
100+
String orgId, String botId,
101+
String forceConfigEndPoint,
102+
List<RequestEnvelopeMessagesOneOf> messages) {
103+
return new RequestEnvelope()
104+
.externalSessionKey(sessionId)
105+
.orgId(orgId)
106+
.botId(botId)
107+
.forceConfig(new ForceConfig().endpoint(forceConfigEndPoint))
108+
.messages(messages);
109+
}
110+
```
111+
112+
### Full code examples
113+
114+
See [ChatbotClientExamples](src/test/java/com/salesforce/chatbot/sdk/examples/ChatbotClientExamples.java) for full code sample sending messages to Einstein Bots Runtime.
115+
116+
See [OAuthExamples](src/test/java/com/salesforce/chatbot/sdk/examples/OAuthExamples.java) for using OAuth.
117+
118+
## Developer Guide
119+
120+
### Code Style
121+
122+
The project uses the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html).
123+
Format settings definition files for importing into IDEs are available for[Eclipse](https://github.com/google/styleguide/blob/gh-pages/eclipse-java-google-style.xml)
124+
and [IntelliJ IDEA](https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml).

‎SECURITY.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## Security
2+
3+
Please report any security issue to [[email protected]](mailto:[email protected])
4+
as soon as it is discovered. This library limits its runtime dependencies in
5+
order to reduce the total cost of ownership as much as can be, but all consumers
6+
should remain vigilant and have their security stakeholders review all third-party
7+
products (3PP) like this one and their dependencies.

‎TERMS_OF_USE.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Copyright 2022 [salesforce.com](https://app.salesforceiq.com/r?target=5aa041084cedfd007a609a0c&t=AFwhZf0GOvrkITUEGk_9Frn8rtTOQ_JcR3V1bPtHyKCQMx9cWuf92b6O6w9dz1LpYaK8lPgjNZvweaqC9W9fv2K3zv4BJWd_VftkdaL13QYpqzPyITBhy9poAZwbKc3bge5ItzFU2Lwc), inc. All rights reserved.
2+
3+
These Terms of Use are between **You** (being the Customer that purchased the Services) and [salesforce.com](salesforce.com), inc. or its Affiliate (“**SFDC**”) that entered into an agreement with You that governs Your purchase of the Services (the “**Agreement**”). Capitalized terms not defined herein shall have the meaning defined in the Agreement.
4+
5+
These Terms of Use were last updated on February 1, 2020, and constitute a legally binding agreement between You and SFDC effective upon Your first download, installation or use of the Software Development Kit (SDK), whichever is earliest. If You do not have authority to bind the Customer that entered into the Agreement or You do not agree to these Terms of Use, do not install or use the SDK.
6+
7+
SFDC grants You a limited non-exclusive, non­transferable, non-sublicensable, revocable license to use the Services in a manner consistent with the Documentation, and subject to the terms of the Agreement.
8+
9+
Use, modification, reproduction, and distribution of components of the SDK are licensed under an open source software license and are governed by the terms of that open source software license and not the Agreement. Some of the software required by or included in the SDK may be offered under other open source licenses. Open source licenses constitute separate written agreements.
10+
11+
Subject to the limited rights expressly granted hereunder, SFDC reserves all rights, title and interest in and to all intellectual property subsisting in the SDK as provided to You. 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 SDK.
12+
13+
The SDK is not part of the Services. Implementation of the SDK may require development work for which You are responsible. The SDK may contain bugs, errors and incompatibilities with Your configuration of the Services and is made available on an AS IS basis without support, updates, or service level commitments.
14+
15+
SFDC reserves the right at any time to modify, suspend or discontinue, the SDK (or any part thereof) with or without notice. You agree that SFDC shall not be liable to You or to any third party for any modification, suspension or discontinuance.
16+
17+
You agree to defend SFDC against any claim, demand, suit or proceeding made or brought against SFDC by a third party arising out of or accruing from (a) your use of the SDK, (b) any application you develop on the SDK 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, and (c) any non-compliance by you with the Agreement, each to the extent allowable by applicable law (each a “Claim Against SFDC”), and will indemnify SFDC from any damages, attorney fees and costs finally awarded against SFDC as a result of, or for any amounts paid by SFDC under a settlement approved by You in writing of, a Claim Against SFDC, provided SFDC (a) promptly gives You written notice of the Claim Against SFDC, (b) gives You sole control of the defense and settlement of the Claim Against SFDC (except that You may not settle any Claim Against SFDC unless it unconditionally releases SFDC of all liability), and (c) gives You all reasonable assistance, at Your expense.
18+
19+
WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SDK IS NOT SUPPORTED, AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SFDC 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 SDK, 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.
20+
21+
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. Except as expressly stated in these Terms of Use, 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 SFDC makes available on this website, or is in writing and signed by the party against whom the modification, amendment or waiver is to be asserted.
22+
23+
#### Data Privacy:
24+
SFDC may collect, process and store device, system, and other information related to Your use of the SDK. This includes, but is not limited to, IP address, user metrics, and other data (“**Usage Data**”). SFDC may use Usage Data for analytics, product development and marketing purposes. You acknowledge that files generated in conjunction with the SDK may contain sensitive or confidential data, and You are solely responsible for anonymizing and protecting such data.

‎download-api-spec.sh

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#
2+
# Copyright (c) 2022, salesforce.com, inc.
3+
# All rights reserved.
4+
# SPDX-License-Identifier: BSD-3-Clause
5+
# For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
6+
#
7+
8+
mvn download:wget validate

0 commit comments

Comments
 (0)