feature(integrations): Adding Shopify Integration

integrations/shopify/.gitignore

@@ -0,0 +1 @@
+.botpress

integrations/shopify/.sentryclirc

@@ -0,0 +1,5 @@
+[defaults]
+project=integration-shopify
+
+[auth]
+dsn=https://58077d91efaa7f20094ecb7e872bc23b@o363631.ingest.sentry.io/4505755730968576

integrations/shopify/hub.md

@@ -0,0 +1,45 @@
+This integration enables you to connect your Botpress chatbot with Shopify, a leading e-commerce platform. With this integration, you can facilitate seamless interactions related to store operations directly from your chatbot.
+
+To effectively use the integration, you'll need to provide your Shopify store name (as seen in the browser/URL) and the access token generated after adding our App to your shop.
+
+For comprehensive instructions on setting up and utilizing the Botpress Shopify integration, please consult our main documentation.
+
+## Prerequisites
+
+Before enabling the Botpress Shopify Integration, ensure you have:
+
+1. A Botpress cloud account.
+2. Access to a Shopify store admin panel.
+3. An access token, generated after adding our App to your Shopify store.
+
+## Configuration Setup
+
+To set up the Shopify integration in Botpress, the following configurations are required:
+
+1. **Shop/Store Name**: Extracted from the browser/URL when accessing your Shopify store. For instance, if the URL to your store admin is \`https://admin.shopify.com/store/botpress-test-store\`, then the shop name you'll enter is \`botpress-test-store\`.
+2. **Admin API access token**: This token is essential for allowing Botpress to communicate with your Shopify store. It can be located within the app settings under the 'API credentials' section in your Shopify admin panel.
+
+## Enable Integration
+
+To activate the Shopify integration in Botpress:
+
+1. Access the Botpress admin dashboard.
+2. Go to the "Integrations" tab.
+3. Search for the Shopify integration and select "Enable" or "Configure."
+4. Input the required Shop/Store Name and Admin API access token.
+5. Save your configurations.
+
+## Usage
+
+After enabling the integration, your Botpress chatbot can seamlessly communicate with Shopify, aiding in tasks like product queries, order updates, and more. Specific built-in actions and more detailed usage instructions will be found in our core documentation.
+
+## Limitations
+
+1. Ensure you always have the correct and latest Admin API access token for accurate integration functionality.
+2. There may be rate limits applied by Shopify's API.
+
+## Contributing
+
+Your contributions are valued! Feel free to submit any issues or pull requests.
+
+Relish the smooth e-commerce operations integration between Botpress and Shopify!

integrations/shopify/integration.definition.ts

@@ -0,0 +1,21 @@
+import { IntegrationDefinition } from '@botpress/sdk'
+import { sentry as sentryHelpers } from '@botpress/sdk-addons'
+import { INTEGRATION_NAME } from './src/const'
+import { actions } from './src/definitions/actions'
+import { configuration } from './src/definitions/configuration'
+import { events } from './src/definitions/events'
+import { states } from './src/definitions/states'
+
+export default new IntegrationDefinition({
+  name: INTEGRATION_NAME,
+  title: 'Shopify',
+  description: 'This integration allows your bot to interact with Shopify.',
+  version: '0.2.0',
+  icon: 'icon.svg',
+  readme: 'hub.md',
+  configuration,
+  actions,
+  states,
+  events,
+  secrets: [...sentryHelpers.COMMON_SECRET_NAMES],
+})

integrations/shopify/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@botpresshub/shopify",
+  "scripts": {
+    "start": "bp serve",
+    "build": "bp build",
+    "deploy": "bp deploy",
+    "type:check": "tsc --noEmit",
+    "test": "echo \"Tests not implemented yet.\""
+  },
+  "keywords": [],
+  "private": true,
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@botpress/client": "workspace:*",
+    "@botpress/sdk": "workspace:*",
+    "@botpress/sdk-addons": "workspace:*",
+    "axios": "^1.4.0",
+    "zod": "^3.21.4"
+  },
+  "devDependencies": {
+    "@botpress/cli": "workspace:*",
+    "@sentry/cli": "^2.18.1",
+    "@types/node": "^18.11.17",
+    "esbuild": "^0.15.18",
+    "nodemon": "^2.0.20",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.4"
+  }
+}

integrations/shopify/src/actions/get-customerOrders.ts

@@ -0,0 +1,37 @@
+import { RuntimeError } from '@botpress/client'
+import axios from 'axios'
+import qs from 'querystring'
+import { SHOPIFY_API_VERSION } from '../const'
+import { IntegrationProps } from '.botpress'
+
+type GetCustomerOrders = IntegrationProps['actions']['getCustomerOrders']
+
+export const getCustomerOrders: GetCustomerOrders = async ({ ctx, input, logger }) => {
+  const { customer_id, status } = input
+  const filters = qs.stringify({ customer_id, status })
+
+  const axiosConfig = {
+    baseURL: `https://${ctx.configuration.shopName}.myshopify.com`,
+    headers: {
+      'X-Shopify-Access-Token': ctx.configuration.access_token,
+    },
+  }
+
+  try {
+    const response = await axios.get(`/admin/api/${SHOPIFY_API_VERSION}/orders.json?${filters}`, axiosConfig)
+
+    const customerOrdersList = response.data.orders
+
+    logger
+      .forBot()
+      .info(
+        `Ran 'Get Customer Orders List' and found ${customerOrdersList.length} customer orders matching criteria ${filters}`
+      )
+
+    return { customerOrdersList }
+  } catch (e) {
+    const errorMsg = `'Get Customer Orders List' exception ${JSON.stringify(e)}`
+    logger.forBot().error(errorMsg)
+    throw new RuntimeError(errorMsg)
+  }
+}

integrations/shopify/src/actions/get-customers.ts

@@ -0,0 +1,35 @@
+import { RuntimeError } from '@botpress/client'
+import axios from 'axios'
+import qs from 'querystring'
+import { SHOPIFY_API_VERSION } from '../const'
+import { IntegrationProps } from '.botpress'
+
+type GetCustomers = IntegrationProps['actions']['getCustomers']
+
+export const getCustomers: GetCustomers = async ({ ctx, input, logger }) => {
+  const { ids, limit } = input
+  const filters = qs.stringify({ ids, limit })
+
+  const axiosConfig = {
+    baseURL: `https://${ctx.configuration.shopName}.myshopify.com`,
+    headers: {
+      'X-Shopify-Access-Token': ctx.configuration.access_token,
+    },
+  }
+
+  try {
+    const response = await axios.get(`/admin/api/${SHOPIFY_API_VERSION}/customers.json?${filters}`, axiosConfig)
+
+    const customersList = response.data.customers
+
+    logger
+      .forBot()
+      .info(`Ran 'Get Customers List' and found ${customersList.length} customers matching criteria ${filters}`)
+
+    return { customersList }
+  } catch (e) {
+    const errorMsg = `'Get Customers List' exception ${JSON.stringify(e)}`
+    logger.forBot().error(errorMsg)
+    throw new RuntimeError(errorMsg)
+  }
+}

integrations/shopify/src/actions/get-productVariant.ts

@@ -0,0 +1,37 @@
+import { RuntimeError } from '@botpress/client'
+import axios from 'axios'
+import qs from 'querystring'
+import { SHOPIFY_API_VERSION } from '../const'
+import { IntegrationProps } from '.botpress'
+
+type GetProductVariants = IntegrationProps['actions']['getProductVariants']
+
+export const getProductVariants: GetProductVariants = async ({ ctx, input, logger }) => {
+  const { product_id, limit } = input
+  const filters = qs.stringify({ product_id, limit })
+
+  const axiosConfig = {
+    baseURL: `https://${ctx.configuration.shopName}.myshopify.com`,
+    headers: {
+      'X-Shopify-Access-Token': ctx.configuration.access_token,
+    },
+  }
+
+  try {
+    const response = await axios.get(`/admin/api/${SHOPIFY_API_VERSION}/variants.json?${filters}`, axiosConfig)
+
+    const productVariantsList = response.data.variants
+
+    logger
+      .forBot()
+      .info(
+        `Ran 'Get Product Variants List' and found ${productVariantsList.length} product variants matching criteria ${filters}`
+      )
+
+    return { productVariantsList }
+  } catch (e) {
+    const errorMsg = `'Get Product Variants List' exception ${JSON.stringify(e)}`
+    logger.forBot().error(errorMsg)
+    throw new RuntimeError(errorMsg)
+  }
+}

integrations/shopify/src/actions/get-products.ts

@@ -0,0 +1,35 @@
+import { RuntimeError } from '@botpress/client'
+import axios from 'axios'
+import qs from 'querystring'
+import { SHOPIFY_API_VERSION } from '../const'
+import { IntegrationProps } from '.botpress'
+
+type GetProductVariants = IntegrationProps['actions']['getProducts']
+
+export const getProducts: GetProductVariants = async ({ ctx, input, logger }) => {
+  const { ids, limit, product_type, title } = input
+  const filters = qs.stringify({ ids, limit, product_type, title })
+
+  const axiosConfig = {
+    baseURL: `https://${ctx.configuration.shopName}.myshopify.com`,
+    headers: {
+      'X-Shopify-Access-Token': ctx.configuration.access_token,
+    },
+  }
+
+  try {
+    const response = await axios.get(`/admin/api/${SHOPIFY_API_VERSION}/products.json?${filters}`, axiosConfig)
+
+    const productsList = response.data.products
+
+    logger
+      .forBot()
+      .info(`Ran 'Get Products List' and found ${productsList.length} products matching criteria ${filters}`)
+
+    return { productsList }
+  } catch (e) {
+    const errorMsg = `'Get Products List' exception ${JSON.stringify(e)}`
+    logger.forBot().error(errorMsg)
+    throw new RuntimeError(errorMsg)
+  }
+}

integrations/shopify/src/actions/index.ts

@@ -0,0 +1,7 @@
+import '@botpress/client'
+import { getCustomerOrders } from './get-customerOrders'
+import { getCustomers } from './get-customers'
+import { getProducts } from './get-products'
+import { getProductVariants } from './get-productVariant'
+
+export default { getProducts, getProductVariants, getCustomers, getCustomerOrders }

integrations/shopify/src/const.ts

@@ -0,0 +1,3 @@
+export const INTEGRATION_NAME = 'shopify'
+export const SHOPIFY_API_VERSION = '2023-07'
+export const ARR_OF_EVENTS = ['orders/create', 'orders/cancelled', 'customers/create']