search

Typeform / js-api-client

Typeform API js client
MIT License
79 stars 29 forks source link
api hacktoberfest javascript sdk type-library typeform use-nonproduction

readme

Typeform JavaScript SDK

Pull Request

JS Client wrapper for Typeform API

Table of contents

Installation

# install with yarn
yarn add @typeform/api-client

# install with npm
npm install @typeform/api-client --save

Usage

In your project

  1. Import client library
// If using ESM syntax
import { createClient } from '@typeform/api-client'
// If using CJS syntax
const { createClient } = require('@typeform/api-client')
  1. Create an instance with your personal token
const typeformAPI = createClient({ token: '<your token>' })

If your account is configured to store responses in the EU Data Center you can pass the apiBaseUrl as https://api.eu.typeform.com.

const typeformAPI = createClient(
  {
    token: '<your token>',
    apiBaseUrl: 'https://api.eu.typeform.com'
  }
)
  1. Use any of the methods available in the reference
// will retrieve all forms
typeformAPI.forms.list().then((response) => {
  // do what do you want with your typeforms
})

Note: You can also execute the client binary directly via command line in your project:

yarn typeform-api <method> [params]

See next section for more details.

Via command line

  1. Clone this repo on your machine

  2. Install all dependencies:

yarn install
  1. Set your personal token as TF_TOKEN env variable
export TF_TOKEN=tfp_XXXXXXXXXX
  1. Run the client:
yarn typeform-api <method> [params]

See reference for all available method names and their params.

Example usage:

yarn typeform-api forms.list
yarn typeform-api forms.get '{uid:"abcd1234"}'
yarn typeform-api themes.list '{pageSize:3}'

Reference

createClient({token})

const typeformClient = createClient({ token: '<your token>' })

// If what you are trying to access doesn't require a token, you can construct the client without any argument
const typeformAPI = createClient()

If your account is configured to store responses in the EU Data Center you can pass the apiBaseUrl as https://api.eu.typeform.com.

const typeformAPI = createClient(
  {
    token: '<your token>',
    apiBaseUrl: 'https://api.eu.typeform.com'
  }
)

Client returns the following properties:

Each one of them encapsulates the operations related to it (like listing, updating, deleting the resource).

Forms

forms.list({ page: 1, pageSize = 10, search = '', page })

forms.get({ uid })

forms.create({ data = {} })

forms.update({ uid, data = {}, override = false })

forms.delete({ uid })

forms.copy({ uid, workspaceUrl })

forms.messages.get({ uid })

forms.messages.update({ uid })

Images

images.list()

images.get({ id, size, backgroundSize, choiceSize })

images.add({ image, url, fileName })

images.delete({ id })

Themes

themes.list({ page, pageSize })

themes.get({ id })

themes.create({ background, colors, font, hasTransparentButton, name })

themes.update({ id, background, colors, font, hasTransparentButton, name })

themes.delete({ id })

Workspaces

workspaces.add({ name })

workspaces.addMembers({ id, members })

workspaces.delete({ id })

workspaces.get({ id })

workspaces.list({ page, pageSize, search })

workspaces.removeMembers({ id, members })

workspaces.update({ id, data })

Responses

responses.delete({ uid, ids })

responses.list({ uid, pageSize, since, until, after, before, ids, completed, sort, query, fields })

Insights

insights.summary({ uid })

Webhooks

webhooks.create({ uid, tag, url, enabled = false, secret, verifySSL })

webhooks.delete({ uid, tag })

webhooks.get({ uid, tag })

webhooks.list({ uid })

webhooks.update({ uid, tag, url, enabled = false, secret, verifySSL })

webhooks.toggle({ uid, tag, enabled })

Examples

Update specific typeform property, as referenced here

typeformClient.forms
  .update({
    uid: 'asdf',
    data: [
      {
        op: 'replace',
        path: '/title',
        value: 'new title',
      },
    ],
  })
  .then((response) => {
    //...
  })

Update the whole typeform

typeformClient.forms
  .update({
    uid: 'asdf',
    override: true,
    data: {
      title: newTitle,
      theme: {
        href: 'https://api.typeform.com/themes/6lPNE6',
      },
    },
  })
  .then((response) => {
    //...
  })

Note: The theme property applies a theme to the form. If you don't specify a value for the 'theme' property, Typeform applies a new copy of the default theme to the form, even if you already have a copy of the default theme applied to this form.

Uploading an image

typeformClient.images
  .add({
    image: 'bGRqZmxzZGpmbHNoZmtoc2RrZmpoc2tqZA==',
    mediaType: 'image/gif',
    fileName: 'newimage.gif',
  })
  .then((response) => {
    //...
  })

Getting the thumbnail of an image

typeformClient.images
  .get({ id: 'asdf', size: 'thumbnail' })
  .then((response) => {
    //...
  })

Testing

To run unit tests.

yarn install

# Runs unit tests
yarn test:unit

Suggestions or feedback

Feel free to open a Github issue.