feat(PR-40): add insights summary (#106)

Add support for form insights endpoint
https://www.typeform.com/developers/responses/reference/retrieve-form-insights/

Author: mathio

README.md

@@ -310,6 +310,14 @@ Each one of them encapsulates the operations related to it (like listing, updati
 - `fields`: Limit request to only responses for the specified fields. Accepts either a string or an array of strings.
 - For parameter details check [the documentation](https://developer.typeform.com/responses/reference/retrieve-responses/)
 
+### Insights
+
+#### `insights.summary({ uid })`
+
+- Returns form level and individual question level insights for a given form.
+- `uid`: Unique ID for the form.
+
+
 ### Webhooks
 
 #### `webhooks.create({ uid, tag, url, enabled = false, secret, verifySSL })`

src/index.ts

@@ -6,6 +6,7 @@ import { Workspaces } from './workspaces'
 import { Responses } from './responses'
 import { Webhooks } from './webhooks'
 import { Typeform } from './typeform-types'
+import { Insights } from './insights'
 
 export { Typeform } from './typeform-types'
 
@@ -19,5 +20,6 @@ export const createClient = (args: Typeform.ClientArg = { token: null }) => {
     workspaces: new Workspaces(http),
     responses: new Responses(http),
     webhooks: new Webhooks(http),
+    insights: new Insights(http),
   }
 }

src/insights.ts

@@ -0,0 +1,14 @@
+import { Typeform } from './typeform-types'
+
+export class Insights {
+  constructor(private _http: Typeform.HTTPClient) {}
+
+  public summary(args: { uid: string }): Promise<Typeform.Insights> {
+    const { uid } = args
+
+    return this._http.request({
+      method: 'get',
+      url: `/insights/${uid}/summary`,
+    })
+  }
+}

src/typeform-types.ts

@@ -1408,6 +1408,37 @@ export namespace Typeform {
       role: 'owner' | 'member'
     }[]
   }
+  /**
+   * Field level insights.
+   */
+  export interface FieldInsights {
+    id: string
+    ref: string
+    title: string
+    type: Type
+    dropoffs: number
+    views: number
+  }
+  /**
+   * Counters and calculations for the results of form.
+   */
+  interface FormInsights {
+    average_time: number
+    completion_rate: number
+    responses_count: number
+    total_visits: number
+    unique_visits: number
+  }
+  interface PlatformFormInsights extends FormInsights {
+    platform: 'desktop' | 'other' | 'phone' | 'tablet'
+  }
+  export interface Insights {
+    fields: FieldInsights[]
+    form: {
+      platforms: PlatformFormInsights[]
+      summary: FormInsights
+    }
+  }
   export class ApiError extends Error {
     code: string
     details: Object[]

tests/unit/insights.test.ts

@@ -0,0 +1,23 @@
+import { axios } from '../common'
+import { clientConstructor } from '../../src/create-client'
+import { Insights } from '../../src/insights'
+import { API_BASE_URL } from '../../src/constants'
+
+beforeEach(() => {
+  axios.reset()
+  axios.onAny().replyOnce(200, {})
+})
+
+const http = clientConstructor({
+  token: '123',
+})
+const insightsRequest = new Insights(http)
+
+test('get insights summary has correct method and path', async () => {
+  const uid = 'foobar'
+  await insightsRequest.summary({ uid })
+  expect(axios.history.get[0].url).toBe(
+    `${API_BASE_URL}/insights/${uid}/summary`
+  )
+  expect(axios.history.get[0].method).toBe('get')
+})