Releases: intercom/intercom-node
v6.0.0
v6.0.0
The Intercom team is excited to announce a new and improved TypeScript SDK. Check out the API reference here.
Installation
Install the latest version by running the following command:
npm
npm install intercom-clientpnpm
pnpm install intercom-clientyarn
yarn add intercom-clientbun
bun install intercom-clientNew Features
1. Strongly typed
All types and endpoints are strongly typed and up to date with Intercom’s latest API.
In version 5.0.0, some of the SDK types included any and unknown properties, which put more onus on the caller to determine what type was expected.
But with the new SDK, you’ll always know exactly what type you’re working with. For example, consider the RequestOptions type:
Before
interface RequestOptions {
url: string;
data?: any;
params?: any;
}After
interface RequestOptions {
/** The maximum time to wait for a response in seconds. */
timeoutInSeconds?: number;
/** The number of times to retry the request. Defaults to 2. */
maxRetries?: number;
/** A hook to abort the request. */
abortSignal?: AbortSignal;
/** Override the Intercom-Version header */
version?:
| "1.0"
| "1.1"
| "1.2"
| "1.3"
| "1.4"
| "2.0"
| "2.1"
| "2.2"
| "2.3"
| "2.4"
| "2.5"
| "2.6"
| "2.7"
| "2.8"
| "2.9"
| "2.10"
| "2.11"
| "Unstable";
}2. Rich documentation
The new SDK includes in-lined documentation on both endpoints and object properties. This helps the user recognize exactly what parameters need to be specified and allows them to iterate even faster.
For example, consider the following endpoint documentation:
/**
* You can update the details of a single article by making a PUT request to `https://api.intercom.io/articles/<id>`.
*
* @param {Intercom.UpdateArticleRequest} request
* @param {Articles.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link Intercom.UnauthorizedError}
* @throws {@link Intercom.NotFoundError}
*
* @example
* await client.articles.update({
* article_id: "123",
* title: "Christmas is here!",
* body: "<p>New gifts in store for the jolly season</p>"
* })
*/
public async update(
request: Intercom.UpdateArticleRequest,
requestOptions?: Articles.RequestOptions
): Promise<Intercom.Article> {
...
}3. Improved exception handling
The SDK now defines structured errors that users can use to influence their program’s control flow. For example, consider the following:
import { Intercom } from "intercom-client";
try {
await client.articles.update(...);
} catch (err) {
if (err instanceof Intercom.NotFoundError) {
// Do something with the 404 ...
}
}With this, users can write their programs to take specific actions whenever an endpoint returns any of the well-known Intercom errors (the Intercom.NotFoundError in this case).
4. Auto-pagination
Intercom’s paginated endpoints now support auto-pagination with an async iterator.
Callers don’t need to manually fetch the next page at all - they can simply iterate over the entire list, and the client will automatically fetch the next page behind the scenes.
Before
const response = client.companies.list({});
for (const company of response.data) {
// Do something with the company …
}
if (response.pages.next != null) {
// Fetch the next page, and keep iterating …
}After
const companies = client.companies.list();
for await (const company of companies) {
// Do something with the company …
}5. Version selection
The Intercom client now includes version selection support.
The SDK is configured to use the latest stable version by default (i.e. 2.11), but users can override this value to influence the behavior of the server. Configuring a version is as simple as the following:
const client = new IntercomClient({ token, version: "2.11" });Migration Guide
These improvements include a few breaking changes (primarily related to request parameters), which are categorized by the following:
1. Client constructor
The client constructor is simplified and doesn’t require a nested type to specify the API token.
Before
const client = new Client({
tokenAuth: { token },
});After
const client = new IntercomClient({ token });2. Parameters names
You’ll notice a few parameter names have changed. Primarily, id parameters are often prefixed with their resource type, for example: contact_id.
Before
const response = client.contacts.listAttachedCompanies({
id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
});After
const response = client.contacts.listAttachedCompanies({
contact_id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
});3. Request properties naming convention (camelCase -> snake_case).
Request properties now use the snake_case naming convention, whereas response properties preserve the camelCase naming convention.
Before
const response = client.contacts.listAttachedCompanies({
id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b"
perPage: 1,
})After
const response = client.contacts.listAttachedCompanies({
contact_id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
per_page: 1,
});4. Request parameters with body property
The client.conversations.reply and client.conversations.manage functions now accept a request object where most parameters are in the body property.
const replyResponse = await client.conversations.reply({
conversation_id: conversationId,
body: {
message_type: "comment",
type: "admin",
body: "test",
admin_id: adminId,
}
});const openResponse = await client.conversations.manage({
conversation_id: conversationId,
body: {
message_type: "open",
admin_id: adminId,
}
});5. Assigning a conversation
Previously, you could manually and auto-assign a conversation using a single function client.conversations.assign() by passing different parameters to it.
Before
// manually assign conversation
const manualAssignResponse = await client.conversations.assign({
id,
assigneeId: anotherAdminId,
adminId,
type: AssignToConversationUserType.ADMIN,
});
// run assignment rules
const autoAssignResponse = await client.conversations.assign({
id,
withRunningAssignmentRules: true,
});In the new SDK, you can manually assign and auto-assign using the client.conversations.manage() and client.conversations.runAssignmentRules() function.
After
// manually assign conversation
const response = await client.conversations.manage({
conversation_id,
body: {
message_type: "assignment",
type: "admin",
admin_id: adminId,
assignee_id: secondAdminId,
}
});
// run assignment rules
const response = await client.conversations.runAssignmentRules({
conversation_id,
});v6.0.0-beta.3
v6.0.0-beta.2
v6.0.0-beta.1
v6.0.0-beta.0
v5.0.0
What's Changed
- Update intercom-node to 4.0.0 by @SeanHealy33 in #341
- Documentation Error by @colmdoyle in #348
- Revert "Add FOSSA workflow to enable license scanning" by @dannyfallon in #350
- Fix typo in Recepient and RecepientType by @colmdoyle in #354
- typo in README.md by @Vanley in #357
- remove integration tests approval step by @mmartinic in #343
- Update README file by @mhnpd in #362
- Fix test infra by @colmdoyle in #369
- Bump json5 from 2.2.0 to 2.2.3 by @dependabot in #370
- Bump http-cache-semantics from 4.1.0 to 4.1.1 by @dependabot in #368
- Make the company fields optional by @colmdoyle in #367
- Update create conversations endpoint with 2.6 typing by @colmdoyle in #373
- Bump semver from 6.3.0 to 6.3.1 by @dependabot in #374
- bump versions by @colmdoyle in #371
- run tests in parallel by @colmdoyle in #372
- Bump axios from 0.24.0 to 1.6.0 by @dependabot in #388
- Fix tests on Node SDK by @colmdoyle in #392
- Create REPO_OWNER by @kev-null in #385
- Bump @babel/traverse from 7.22.8 to 7.23.2 by @dependabot in #383
- Fix type in ContactObject: opted_out_subscription_tyes by @johnf in #380
- Update the company.update method by @colmdoyle in #375
- Revert "Update the company.update method" by @colmdoyle in #393
- Update package.json by @colmdoyle in #394
New Contributors
- @dannyfallon made their first contribution in #350
- @Vanley made their first contribution in #357
- @mmartinic made their first contribution in #343
- @mhnpd made their first contribution in #362
- @kev-null made their first contribution in #385
- @johnf made their first contribution in #380
Full Changelog: v4.0.0...v5.0.0
Contributors
Assets 2
Release V4.0.0
What's Changed
- Updated typo for conversation.
- Updated Conversations index to API 2.6 standard.
Full Changelog: v3.2.1...v4.0.0
v3.2.1
What's Changed
Fixes bad release of 3.2.0
V3.2.0
What's Changed
Added API to support phone call redirects @SeanHealy33
Added API to support message data export API.
Added ability to list all subscription types (thank you @lukasbals)
Full Changelog: v3.1.5...v3.2.0
Contributors
Assets 2
v3.1.5
What's Changed
- Document how to configure api.eu.intercom.io by @punkle in #286
- Create conversation without contact reply by @MangeFre in #319
- Permit creating leads with email by @drewwatkins11 in #316
- Add email to contact update by @johnnynader in #323
New Contributors
- @punkle made their first contribution in #286
- @enrico-intercom made their first contribution in #312
- @MangeFre made their first contribution in #319
- @drewwatkins11 made their first contribution in #316
Full Changelog: v3.1.4...v3.1.5
