Skip to main content
Version: Latest

Getting started with Alphasense Javascript SDK

This SDK provides standardized access to the AlphaSense's API capabilities, sparing developers from the complexities of direct API calls and eliminating the need for deep GraphQL knowledge. The SDK is designed to be used in a Node.js environment and is compatible with TypeScript.

Quick Start & Starting From Scratch​

You can create a new project with the help of the project template. To create a new project, run the following command:

npx @alphasense/sdk-create-app my-app

This command will create a new project with the following structure:

my-app
├── node_modules
├── alphasense.config.ts
├── index.ts
├── package.json
└── tsconfig.json

See the Configuration section for all the configuration options.

After updating the configuration, you can install the dependencies by running the following command:

npm install

After installing the dependencies, you can start using the SDK in your project! Update the index.ts file however you want, and you can run the code with the following command:

npm run dev

You can see the example result in the console if you have a valid configuration. Feel free to modify index.ts to make different queries.

Using SDK in your existing project​

Add necessary packages to your project​

Add the @alphasense/sdk-cli package to your project as a development dependency with the following command:

npm i --save-dev @alphasense/sdk-cli

Add the @alphasense/sdk-client package to your project with the following command:

npm i @alphasense/sdk-client

Configuring the SDK​

Create an AlphaSense config file alphasense.config.json in the root folder of your project. See the Configuration section for all the configuration options.

Generating typings​

@alphasense/sdk-cli package provides asgql command that translates JavaScript code into GraphQL queries, enabling you to get auto-completion in your IDE and validation for your GraphQL queries. Please add this command as a script in your package.json file:

package.json
{
  "scripts": {
    "generate": "asgql"
  }
}

After you have configured the SDK and added the script in your package.json file, you can generate the typings for the queries by running the following command:

npm run generate

Using the SDK in your project​

Check the following example to see how you can use the SDK in your project:

alphasense.api.ts
import { createClient } from "@alphasense/sdk-client";

const client = await createClient();

const getWatchlists = async () => {
  return client.query({
    user: {
      watchlists: {
        name: true,
        companies: {
          name: true,
        },
      },
    },
  });
};

const showResult = async (res: any) => console.log(JSON.stringify(res, null, 2));

getWatchlists().then(showResult).catch(console.error);

Advanced Usage​

You can also choose to use the raw GraphQL query instead of the generated typings. Here is an example:

import {createClient} from '@alphasense/sdk-client'

const searchDocuments = async (query: string) => {
  const client = await createClient()
  const rawResp = await client.raw(
    `
    query searchDocuments($query: String!) {
      search(
          limit: 20
          filter: {
              keyword: {
                  query: $query
              }
              date: {
                  preset: LAST_30_DAYS
              }
          }
          sorting: {
              field: DATE
              direction: DESC
          }
      ){
        documents {
            id
            title
            releasedAt
            type {
              ids
            }
        }
        cursor
      }
    }
  `,
    {query},
  )

  return rawResp.search.documents
}

searchDocuments('incentive structure').then(console.log).catch(console.error)

Configuration​

The SDK checks for the configuration in the following order:

  'package.json',
  'alphasense.config.json'
  'alphasense.config.ts'
  'alphasense.config.js'
  'alphasense.config.cjs'
  'alphasense.config.mjs'

Please check the following examples to see how you can configure the SDK:

alphasense.config.ts
import {AlphaSenseConfig} from '@alphasense/sdk-client';

const config: AlphaSenseConfig = {
  username: '',
  password: '',
  apiKey: '',
  clientId: '',
  clientSecret: '',

};

export default config;

Configuration Options​

These options allow you to customize the behavior of the SDK to fit your project's needs.

OptionRequiredDefault ValueDescription
usernamerequiredThe username for authentication.
passwordrequiredThe password for authentication.
apiKeyrequiredThe API key for authentication.
clientIdrequiredThe client ID for authentication, provided by AlphaSense.
clientSecretrequiredThe client secret for authentication, provided by AlphaSense.
urlOptional'https://api.alpha-sense.com'The base URL for the API. The default value is recommended for most cases.
authEndpointOptional'/auth'The endpoint for authentication. The default value is recommended for most cases.
apiEndpointOptional'/gql'The endpoint for the API. The default value is recommended for most cases.
schemaEndpointConditional'/gql/client-sdk/schema'The endpoint for the GraphQL schema. This or schemaPath is a required field.
schemaPathConditional''The path to the GraphQL schema definition file. This or schemaEndpoint is a required field.
outputDirNameOptional'generated'The output directory for the generated files. The default value is recommended for most cases.
cliDirNameOptional'sdk-cli'The directory name for the SDK Command Line Interface. The default value is recommended.
clientDirNameOptional'sdk-client'The directory name for the generated SDK Client. The default value is recommended.

Configuration Options via Environment Variables​

You can use environment variables to set or override the configuration options:

Configuration OptionEnvironment Variable
usernameALPHASENSE_USERNAME
passwordALPHASENSE_PASSWORD
apiKeyALPHASENSE_API_KEY
clientIdALPHASENSE_CLIENT_ID
clientSecretALPHASENSE_CLIENT_SECRET
urlALPHASENSE_API_URL
authEndpointALPHASENSE_AUTH_ENDPOINT
apiEndpointALPHASENSE_API_ENDPOINT
schemaEndpointALPHASENSE_GRAPHQL_SCHEMA_ENDPOINT
schemaPathALPHASENSE_GRAPHQL_SCHEMA_PATH
outputDirNameALPHASENSE_OUTPUT_DIR_NAME
cliDirNameALPHASENSE_SDK_CLI_DIR_NAME
clientDirNameALPHASENSE_SDK_CLIENT_DIR_NAME

The SDK will honor the environment variables if they are set which will override the configuration in the config file. You can use .env file to set the environment variables. The SDK will automatically load the .env file if it is present in the root folder of your project.