From 2ef95d3a97d3444c3e4eedbe531278cd8544d7b8 Mon Sep 17 00:00:00 2001 From: Thisaru Guruge Date: Thu, 17 Apr 2025 17:38:39 +0530 Subject: [PATCH 1/2] Downgrade The Ballerina Gradle Plugin Version --- gradle.properties | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gradle.properties b/gradle.properties index 5b88d03..6fa8439 100644 --- a/gradle.properties +++ b/gradle.properties @@ -3,5 +3,5 @@ group=io.ballerina.lib version=2.0.0-SNAPSHOT releasePluginVersion=2.8.0 -ballerinaGradlePluginVersion=3.0.0 +ballerinaGradlePluginVersion=2.3.0 ballerinaLangVersion=2201.12.2 From 7918c02f4e825587c60a9905b60e2dfe8352c659 Mon Sep 17 00:00:00 2001 From: Thisaru Guruge Date: Thu, 17 Apr 2025 18:27:05 +0530 Subject: [PATCH 2/2] Rename Package.md to README.md --- ballerina/Package.md | 189 ----------------------------- ballerina/{Module.md => README.md} | 0 2 files changed, 189 deletions(-) delete mode 100644 ballerina/Package.md rename ballerina/{Module.md => README.md} (100%) diff --git a/ballerina/Package.md b/ballerina/Package.md deleted file mode 100644 index 8eb03ed..0000000 --- a/ballerina/Package.md +++ /dev/null @@ -1,189 +0,0 @@ -## Overview - -[HubSpot](https://www.hubspot.com) is an AI-powered customer relationship management (CRM) platform. - -The `ballerinax/hubspot.marketing.subscriptions` offers APIs to connect and interact with the [HubSpot API for Marketing Subscriptions](https://developers.hubspot.com/docs/reference/api/marketing/subscriptions) endpoints, specifically based on the [HubSpot Marketing Events REST API](https://developers.hubspot.com/docs/reference/api). - -Use the subscriptions API to programmatically subscribe or unsubscribe contacts from your email subscription types, or unsubscribe a contact from all email communication. These APIs also provide support for business units. - -## Setup guide - -To use the HubSpot Marketing Subscriptions Connector, you must have access to the HubSpot API via a HubSpot Developer Account and a HubSpot App associated with it. If you don't already have one, you need to register for a developer account at HubSpot. - -### Step 1: Create/Login to a HubSpot Developer Account - -If you already have an account, go to the [HubSpot developer portal](https://app.hubspot.com/). - -If you don't have a HubSpot Developer Account, you can sign up to a free account [here](https://developers.hubspot.com/get-started). - -### Step 2 (Optional): Create a Developer Test Account under your account - -Within app developer accounts, you can create a [Developer Test Account](https://developers.hubspot.com/beta-docs/getting-started/account-types#developer-test-accounts) to test apps and integrations without affecting any real HubSpot data. - ->**Note:** These accounts are intended solely for development and testing purposes and should not be used in production environments. - -1. Navigate to "Test Account" section from the left sidebar. - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test1.png) - -2. Click "Create developer test account". - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test2.png) - -3. In the dialog box, provide a name to your test account and click "Create". - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test3.png) - -### Step 3: Create a HubSpot App under your account. - -1. In your developer account, navigate to the "Apps" section. Click "Create App". - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test4.png) - -2. Provide the necessary details, including the app name and description. - -### Step 4: Configure the Authentication Flow. - -1. Move to the "Auth" Tab. - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test5.png) - -2. In the Scopes section, add the following scopes for your app by using the "Add new scope" button. - - * `communication_preferences.read_write` - * `communication_preferences.statuses.batch.read` - * `communication_preferences.statuses.batch.write` - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test6.png) - -4. Add your Redirect URI in the appropriate section. You can also use _localhost_ addresses for local development purposes. Click "Create App". - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test7.png) - -### Step 5: Get your Client ID and Client Secret - -- Navigate to the "Auth" section of your app. Make sure to save the provided Client ID and Client Secret. - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test8.png) - -### Step 6: Setup Authentication Flow - -Before proceeding with the Quickstart, make sure you have obtained the Access Token using the following steps: - -1. Create an authorization URL using the following format: - - ``` - https://app.hubspot.com/oauth/authorize?client_id=&scope=&redirect_uri= - ``` - - Replace the ``, `` and `` with your specific value. - - >**Note:** If you are using a localhost redirect url, make sure to have a listener running at the relevant port before executing the next step. - -2. Paste it in the browser and select your developer test account to authorize the app when prompted. - - ![Hubspot developer portal](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/main/docs/setup/resources/Test9.png) - -3. An authorization code appears in the browser. Copy the code. - -4. Run the following curl command. Replace the ``, `` and `` with your specific value. Use the code you received in the step 3 above as the ``. - - - Linux/macOS - - ```bash - curl --request POST \ - --url https://api.hubapi.com/oauth/v1/token \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=authorization_code&code=&redirect_uri=&client_id=&client_secret=' - ``` - - - Windows - - ```bash - curl --request POST ^ - --url https://api.hubapi.com/oauth/v1/token ^ - --header 'content-type: application/x-www-form-urlencoded' ^ - --data 'grant_type=authorization_code&code=&redirect_uri=&client_id=&client_secret=' - ``` - - This command returns a JSON response containing access_token and refresh_token. - - ```json - { - "token_type": "bearer", - "refresh_token": "", - "access_token": "", - "expires_in": 1800 - } - ``` - -5. Store the access token securely for use in your application. - -## Quickstart - -To use the `HubSpot Marketing Subscriptions` connector in your Ballerina application, update the `.bal` file as shown below: - -### Step 1: Import the module - -Import the `hubspot.marketing.subscriptions` module and `oauth2` module. - -```ballerina -import ballerina/oauth2; -import ballerinax/hubspot.marketing.subscriptions as hsmsubscriptions; -``` - -### Step 2: Instantiate a new connector - -1. Create a `Config.toml` file and, configure the obtained credentials in the above steps as follows: - - ```toml - clientId = - clientSecret = - refreshToken = - ``` - -2. Instantiate a `hsmsubscriptions:ConnectionConfig` with the obtained credentials and initialize the connector with it. - - ```ballerina - configurable string clientId = ?; - configurable string clientSecret = ?; - configurable string refreshToken = ?; - - final hsmsubscriptions:ConnectionConfig hsmSubscriptionsConfig = { - auth : { - clientId, - clientSecret, - refreshToken, - credentialBearer: oauth2:POST_BODY_BEARER - } - }; - - final hsmsubscriptions:Client hsmSubscriptions = check new (hsmSubscriptionsConfig); - ``` - -### Step 3: Invoke the connector operation - -Now, utilize the available connector operations. A sample use case is shown below. - -#### Get subscription preferences for a specific contact - -```ballerina -public function main() returns error? { - hsmsubscriptions: ActionResponseWithResultsPublicWideStatus response = check hsmSubscriptions->getCommunicationPreferencesV4StatusesSubscriberIdString - (subscriberUserId,channel = "EMAIL"); -} -``` - -### Step 4: Run the Ballerina application - -```shell -bal run -``` - -## Examples - -The `HubSpot Marketing Subscriptions` connector provides practical examples that illustrate its usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/tree/main/examples/), which cover the following use cases: - -1. [Event-Based Email Preference Update](https://github.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/tree/main/examples/event-based-email-preference-update) - Check and update email preferences for event attendees, ensuring that those who unsubscribed post-event are bulk resubscribed for future engagement. - -2. [Bulk Opt-Out of All Email Communication](https://github.com/ballerina-platform/module-ballerinax-hubspot.marketing.subscriptions/tree/main/examples/bulk-opt-out-of-email-communication) - Process a batch of opt-out requests to efficiently unsubscribe multiple customers from all email communications in bulk. diff --git a/ballerina/Module.md b/ballerina/README.md similarity index 100% rename from ballerina/Module.md rename to ballerina/README.md