tally-js

A type-safe and developer-friendly TypeScript wrapper for the tally.so API.

Disclaimer: The Tally.so API is currently in Private Beta and might be subject to change. You need to sign up for the Beta to get access.

Documenation

Full documentation available here

Installation

npm install tally-js

Core Concepts

• This tally client provides access to all endpoints of the Tally.so API by exposing services

• Service endpoints always return a response with

  {
    data: TallyDTO | null,
    error: Error | null
  }

• Wrapper uses a three-layer architecture for maximum type safety and flexibility:

  1. DTOs (Data Transfer Objects)

     • Raw API response types
     • Match the exact structure of the API responses

  2. Domain Interfaces

     • Enhanced types for better developer experience
     • Example: TallyForm interface with addBlock function

  3. Models

     • Concrete implementations of domain interfaces
     • Handle DTO to domain model transformation

Quick Start

import { TallyClient } from 'tally-js'

const tally = new TallyClient({
  apiKey: 'your-api-key','https://api.tally.so'
})

// Access data
const { data: form, error } = await tally.forms.get('form-id')
console.log(form)

Examples

Create new form from scratch

// init client as described above

import {
  TallyFormModel,
  TallyFormStatus,
  TallyBlockTypes,
  initNewTallyBlock,
  TallyPayloadFormTitleDTO,
} from 'tally-js'

const newForm = new TallyFormModel(
  [], // no blocks - starting from scratch
  TallyFormStatus.DRAFT,
  {}, // default settings
  'your-workspace-id',
)

const titleBlock = initNewTallyBlock(TallyBlockTypes.TITLE)
titleBlock.payload = {
  title: 'Official Title',
  html: 'Official Title',
} as TallyPayloadFormTitleDTO
// simple option for auto-completion without class instantiation

newForm.addBlock(titleBlock)

const { data: createdForm, error: createError } = await tally.forms.create(newForm)

console.log(createdForm.id, createError)
// should print the form id of the created form and null

List Forms

let forms = null
let currentPage = 0
do {
  currentPage += 1
  const { data, error } = await tally.forms.list(currentPage)
  if (!error && data) {
    forms = data
    forms.items.forEach((form) => {
      console.log(form.id)
    })
  }
} while (forms?.hasMore)

Creating a webhook

const { data, error } = await tally.webhooks.create({
  formId: 'xZllsk',
  url: 'https://webhook.site/1b1b1b1b',
  eventTypes: [TallyWebhookEventType.FORM_RESPONSE],
})

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

Apache 2.0

Directory Structure

tally-js/
├── src/
│ ├── client.ts
│ ├── lib/
│ ├── models/
│ ├── services/
│ ├── types/
│ ├── util/