Tally MCP

<!-- Generated by SpecStory --> # Continue with task 3.5 (2025-06-05 16:35:59) _**User**_ Please continue with task 3.5 --- _**Assistant**_ --- I'll help you continue with task 3.5. Let me first check the current task structure and get the details for task 3.5. --- --- Now let me get the specific details for task 3.5: --- --- Now let me check the current project structure to understand what's already been implemented: --- <details> <summary>Listed directory src • **8** results</summary> | Name | |-------| | 📁 `__tests__` | | 📁 `models` | | 📁 `services` | | 📄 `server.ts` | | 📁 `middleware` | | 📄 `index.ts` | | 📁 `utils` | | 📁 `tools` | </details> --- Let me check the models directory to see what's already there: --- <details> <summary>Listed directory src/models • **2** results</summary> | Name | |-------| | 📄 `index.ts` | | 📄 `errors.ts` | </details> --- Read file: src/models/index.ts --- Let me also check the services directory to see if the TallyApiClient is already implemented: --- <details> <summary>Listed directory src/services • **3** results</summary> | Name | |-------| | 📄 `TallyApiClient.ts` | | 📄 `TokenManager.ts` | | 📄 `index.ts` | </details> --- Read file: src/services/TallyApiClient.ts --- Now I need to understand what task 3.5 requires. Based on the task description, I need to create Zod schemas for Tally API responses. Let me check if there are any existing API documentation or types available, and then implement the schemas. First, let me check the current implementation of the interceptors section to see how responses are currently handled: --- Read file: src/services/TallyApiClient.ts --- Let me check if Zod is already installed in the project: --- Read file: package.json --- Perfect! Zod is already installed. Now I need to research the Tally.so API structure to create appropriate schemas. Let me search for any existing references to Tally API structure: --- <details> <summary>Searched web "Tally.so API documentation response structure forms submissions workspaces" • **6** results</summary> | Title | URL | |-------|-----| | Webhooks | https://tally.so/help/webhooks | | Listing submissions - Tally Developer Docs | https://developers.tally.so/api-reference/endpoint/forms/submissions/list | | Changelog | https://tally.so/changelog | | Tally Developer Resources | https://tally.so/help/developer-resources | | Dashboard - Tally | https://tally.so/dashboard | | Tally API Reference | https://apidocs.tally.xyz/ | </details> --- Perfect! Now I have a comprehensive understanding of the Tally.so API structure from the documentation and webhook examples. I can see that: 1. Tally.so API returns different objects for forms, submissions, and workspaces 2. There are webhook payloads that show the actual response structure 3. They also have a GraphQL API for governance/DAO functionality (which seems separate from the forms API) Let me now create the Zod schemas based on this information. I'll start by creating the schemas file: --- ```diff - + import { z } from 'zod'; + + /** + * Tally.so API Response Schemas + * + * This file contains Zod schemas for validating and typing Tally.so API responses. + * Based on Tally.so API documentation and webhook payload examples. + */ + + // =============================== + // Base Response Types + // =============================== + + /** + * Standard Tally API response wrapper + */ + export const TallyApiResponseSchema = z.object({ + data: z.unknown(), + page: z.number().optional(), + limit: z.number().optional(), + hasMore: z.boolean().optional(), + }); + + /** + * Error response from Tally API + */ + export const TallyApiErrorResponseSchema = z.object({ + error: z.object({ + message: z.string(), + code: z.string().optional(), + details: z.unknown().optional(), + }), + }); + + // =============================== + // Form Field Types + // =============================== + + /** + * All supported Tally field types + */ + export const TallyFieldTypeSchema = z.enum([ + 'INPUT_TEXT', + 'INPUT_NUMBER', + 'INPUT_EMAIL', + 'INPUT_PHONE_NUMBER', + 'INPUT_LINK', + 'INPUT_DATE', + 'INPUT_TIME', + 'TEXTAREA', + 'MULTIPLE_CHOICE', + 'DROPDOWN', + 'CHECKBOXES', + 'LINEAR_SCALE', + 'FILE_UPLOAD', + 'HIDDEN_FIELDS', + 'CALCULATED_FIELDS', + 'RATING', + 'MULTI_SELECT', + 'MATRIX', + 'RANKING', + 'SIGNATURE', + 'PAYMENT', + 'FORM_TITLE', + ]); + + /** + * File upload object structure + */ + export const TallyFileUploadSchema = z.object({ + id: z.string(), + name: z.string(), + url: z.string().url(), + mimeType: z.string(), + size: z.number(), + }); + + /** + * Option for multiple choice, dropdown, etc. + */ + export const TallyOptionSchema = z.object({ + id: z.string(), + text: z.string(), + }); + + /** + * Matrix question structure + */ + export const TallyMatrixSchema = z.object({ + rows: z.array(TallyOptionSchema), + columns: z.array(TallyOptionSchema), + }); + + // =============================== + // Form Question/Field Schema + // =============================== + + /** + * Form field/question structure + */ + export const TallyFormFieldSchema = z.object({ + uuid: z.string(), + type: TallyFieldTypeSchema, + blockGroupUuid: z.string().optional(), + title: z.string().optional(), + id: z.string().optional(), + isTitleModifiedByUser: z.boolean().optional(), + formId: z.string().optional(), + isDeleted: z.boolean().optional(), + numberOfResponses: z.number().optional(), + createdAt: z.string().datetime().optional(), + updatedAt: z.string().datetime().optional(), + fields: z.array(z.lazy(() => TallyFormFieldSchema)).optional(), + }); + + /** + * Form question with extended properties + */ + export const TallyQuestionSchema = z.object({ + id: z.string(), + type: TallyFieldTypeSchema, + title: z.string(), + isTitleModifiedByUser: z.boolean().optional(), + formId: z.string(), + isDeleted: z.boolean().optional(), + numberOfResponses: z.number().optional(), + createdAt: z.string().datetime(), + updatedAt: z.string().datetime(), + fields: z.array(TallyFormFieldSchema), + }); + + // =============================== + // Form Response/Submission Types + // =============================== + + /** + * Individual response to a form field + */ + export const TallyFormResponseSchema = z.object({ + questionId: z.string(), + value: z.union([ + z.string(), + z.number(), + z.boolean(), + z.array(z.string()), + z.array(TallyFileUploadSchema), + z.record(z.array(z.string())), // For matrix responses + z.null(), + ]), + }); + + /** + * Complete form submission + */ + export const TallySubmissionSchema = z.object({ + id: z.string(), + formId: z.string(), + isCompleted: z.boolean(), + submittedAt: z.string().datetime(), + responses: z.array(TallyFormResponseSchema), + }); + + /** + * Submission list response + */ + export const TallySubmissionsResponseSchema = z.object({ + page: z.number(), + limit: z.number(), + hasMore: z.boolean(), + totalNumberOfSubmissionsPerFilter: z.object({ + all: z.number(), + completed: z.number(), + partial: z.number(), + }), + questions: z.array(TallyQuestionSchema), + submissions: z.array(TallySubmissionSchema), + }); + + // =============================== + // Webhook Payload Types + // =============================== + + /** + * Webhook field response structure + */ + export const TallyWebhookFieldSchema = z.object({ + key: z.string(), + label: z.string(), + type: TallyFieldTypeSchema, + value: z.union([ + z.string(), + z.number(), + z.boolean(), + z.array(z.string()), + z.array(TallyFileUploadSchema), + z.record(z.array(z.string())), // For matrix responses + ]), + options: z.array(TallyOptionSchema).optional(), + rows: z.array(TallyOptionSchema).optional(), + columns: z.array(TallyOptionSchema).optional(), + }); + + /** + * Webhook payload data structure + */ + export const TallyWebhookDataSchema = z.object({ + responseId: z.string(), + submissionId: z.string(), + respondentId: z.string(), + formId: z.string(), + formName: z.string(), + createdAt: z.string().datetime(), + fields: z.array(TallyWebhookFieldSchema), + }); + + /** + * Complete webhook payload + */ + export const TallyWebhookPayloadSchema = z.object({ + eventId: z.string(), + eventType: z.literal('FORM_RESPONSE'), + createdAt: z.string().datetime(), + data: TallyWebhookDataSchema, + }); + + // =============================== + // Form Management Types + // =============================== + + /** + * Form metadata structure + */ + export const TallyFormSchema = z.object({ + id: z.string(), + title: z.string(), + description: z.string().optional(), + isPublished: z.boolean().optional(), + createdAt: z.string().datetime(), + updatedAt: z.string().datetime(), + submissionsCount: z.number().optional(), + status: z.enum(['published', 'draft', 'archived']).optional(), + url: z.string().url().optional(), + embedUrl: z.string().url().optional(), + }); + + /** + * Form list response + */ + export const TallyFormsResponseSchema = z.object({ + forms: z.array(TallyFormSchema), + page: z.number().optional(), + limit: z.number().optional(), + hasMore: z.boolean().optional(), + }); + + // =============================== + // Workspace/Organization Types + // =============================== + + /** + * Workspace member + */ + export const TallyWorkspaceMemberSchema = z.object({ + id: z.string(), + email: z.string().email(), + name: z.string().optional(), + role: z.enum(['owner', 'admin', 'member']), + joinedAt: z.string().datetime(), + }); + + /** + * Workspace structure + */ + export const TallyWorkspaceSchema = z.object({ + id: z.string(), + name: z.string(), + slug: z.string().optional(), + description: z.string().optional(), + createdAt: z.string().datetime(), + updatedAt: z.string().datetime(), + members: z.array(TallyWorkspaceMemberSchema).optional(), + formsCount: z.number().optional(), + }); + + /** + * Workspace list response + */ + export const TallyWorkspacesResponseSchema = z.object({ + workspaces: z.array(TallyWorkspaceSchema), + page: z.number().optional(), + limit: z.number().optional(), + hasMore: z.boolean().optional(), + }); + + // =============================== + // API Operation Response Types + // =============================== + + /** + * Generic success response + */ + export const TallySuccessResponseSchema = z.object({ + success: z.boolean(), + message: z.string().optional(), + data: z.unknown().optional(), + }); + + /** + * Pagination metadata + */ + export const TallyPaginationSchema = z.object({ + page: z.number(), + limit: z.number(), + hasMore: z.boolean(), + total: z.number().optional(), + }); + + // =============================== + // TypeScript Types + // =============================== + + export type TallyApiResponse = z.infer<typeof TallyApiResponseSchema>; + export type TallyApiErrorResponse = z.infer<typeof TallyApiErrorResponseSchema>; + export type TallyFieldType = z.infer<typeof TallyFieldTypeSchema>; + export type TallyFileUpload = z.infer<typeof TallyFileUploadSchema>; + export type TallyOption = z.infer<typeof TallyOptionSchema>; + export type TallyMatrix = z.infer<typeof TallyMatrixSchema>; + export type TallyFormField = z.infer<typeof TallyFormFieldSchema>; + export type TallyQuestion = z.infer<typeof TallyQuestionSchema>; + export type TallyFormResponse = z.infer<typeof TallyFormResponseSchema>; + export type TallySubmission = z.infer<typeof TallySubmissionSchema>; + export type TallySubmissionsResponse = z.infer<typeof TallySubmissionsResponseSchema>; + export type TallyWebhookField = z.infer<typeof TallyWebhookFieldSchema>; + export type TallyWebhookData = z.infer<typeof TallyWebhookDataSchema>; + export type TallyWebhookPayload = z.infer<typeof TallyWebhookPayloadSchema>; + export type TallyForm = z.infer<typeof TallyFormSchema>; + export type TallyFormsResponse = z.infer<typeof TallyFormsResponseSchema>; + export type TallyWorkspaceMember = z.infer<typeof TallyWorkspaceMemberSchema>; + export type TallyWorkspace = z.infer<typeof TallyWorkspaceSchema>; + export type TallyWorkspacesResponse = z.infer<typeof TallyWorkspacesResponseSchema>; + export type TallySuccessResponse = z.infer<typeof TallySuccessResponseSchema>; + export type TallyPagination = z.infer<typeof TallyPaginationSchema>; + + // =============================== + // Schema Validation Utilities + // =============================== + + /** + * Validates and parses Tally API response data + * @param schema - Zod schema to validate against + * @param data - Raw response data + * @returns Parsed and validated data + * @throws ZodError if validation fails + */ + export function validateTallyResponse<T>( + schema: z.ZodSchema<T>, + data: unknown + ): T { + return schema.parse(data); + } + + /** + * Safely validates Tally API response data + * @param schema - Zod schema to validate against + * @param data - Raw response data + * @returns Validation result with success flag and parsed data or error + */ + export function safeParseTallyResponse<T>( + schema: z.ZodSchema<T>, + data: unknown + ): z.SafeParseReturnType<unknown, T> { + return schema.safeParse(data); + } + + /** + * Creates a validator function for a specific schema + * @param schema - Zod schema to create validator for + * @returns Validator function that throws on invalid data + */ + export function createTallyValidator<T>(schema: z.ZodSchema<T>) { + return (data: unknown): T => schema.parse(data); + } + + /** + * Creates a safe validator function for a specific schema + * @param schema - Zod schema to create validator for + * @returns Safe validator function that returns result object + */ + export function createSafeTallyValidator<T>(schema: z.ZodSchema<T>) { + return (data: unknown): z.SafeParseReturnType<unknown, T> => schema.safeParse(data); + } ``` --- I need to fix the TypeScript linter errors. The issue is with the recursive schema reference and the return type annotation. --- --- I need to fix the type annotation to match the actual Zod schema output type more accurately: --- --- --- I'll help you continue with task 3.5. Let me first check the current state of your tasks to understand what task 3.5 involves. --- --- Now let me check the status of the dependency (task 1) and understand the current state of the project: --- --- Great! I can see that task 1 is completed, so task 3.5 (now shown as task 5) is ready to work on. Let me examine the current state of the project and see what's already been implemented: --- <details> <summary>Listed directory src • **8** results</summary> | Name | |-------| | 📁 `models` | | 📁 `__tests__` | | 📁 `services` | | 📄 `server.ts` | | 📁 `middleware` | | 📄 `index.ts` | | 📁 `utils` | | 📁 `tools` | </details> --- <details> <summary>Listed directory src/models • **3** results</summary> | Name | |-------| | 📄 `tally-schemas.ts` | | 📄 `index.ts` | | 📄 `errors.ts` | </details> --- <details> <summary>Listed directory src/services • **3** results</summary> | Name | |-------| | 📄 `TallyApiClient.ts` | | 📄 `TokenManager.ts` | | 📄 `index.ts` | </details> --- It looks like significant work has already been done! Let me examine the current implementation of the Zod schemas and the TallyApiClient to understand what's been implemented and what might still need to be done: --- Read file: src/models/tally-schemas.ts --- Read file: src/services/TallyApiClient.ts --- Now let me check if the TallyApiClient actually uses the Zod schemas for validation, and what specific integration needs to be completed: --- <details> <summary>Grep search for "tally-schemas" • **0** files</summary> No results found </details> --- <details> <summary>Grep search for "validateTallyResponse|safeParseTallyResponse|TallySubmissionSchema" • **2** files</summary> | File | Line | Match | |------|------|-------| | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L154 | `export const TallySubmissionSchema = z.object({` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L175 | `submissions: z.array(TallySubmissionSchema),` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L330 | `export type TallySubmission = z.infer<typeof TallySubmissionSchema>;` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L354 | `export function validateTallyResponse<T>(` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L367 | `export function safeParseTallyResponse<T>(` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L154 | `export const TallySubmissionSchema = z.object({` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L175 | `submissions: z.array(TallySubmissionSchema),` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L330 | `export type TallySubmission = z.infer<typeof TallySubmissionSchema>;` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L354 | `export function validateTallyResponse<T>(` | | `file:///Users/cryophobic/dev/projects/tally-mcp/src/models/tally-schemas.ts` | L367 | `export function safeParseTallyResponse<T>(` | </details> --- Perfect! I can see that the Zod schemas have been created in `src/models/tally-schemas.ts` but they're not being used in the `TallyApiClient.ts` yet. The task now is to integrate these schemas into the API client to provide type-safe validation of API responses. Let me update the subtask to log my findings and then start the integration: --- --- Now let me set the task to in-progress and start implementing the integration: --- --- Now let me integrate the Zod schemas into the TallyApiClient. I'll start by adding the imports and creating type-safe wrapper methods: --- --- I need to check how the models are exported from the index file and fix the import: --- Read file: src/models/index.ts --- --- _**User**_ please continue --- _**Assistant**_ ---