@automate.ax/integration-contracts 0.146.1 → 0.147.0

package/dist/tally/openapi-types.generated.js

@@ -0,0 +1 @@
+export {};

package/dist/tally/schemas.d.ts

@@ -0,0 +1,17 @@
+import type { Encodable } from "@automate.ax/codec";
+import * as z from "zod";
+import type { components } from "./openapi-types.generated";
+type OpenApiSchemas = components["schemas"];
+export type TallySchemaName = keyof OpenApiSchemas;
+type TallyEncodable<TValue> = unknown extends TValue ? Encodable : TValue extends null | undefined | boolean | number | string ? TValue : TValue extends readonly (infer TItem)[] ? TallyEncodable<TItem>[] : TValue extends object ? keyof TValue extends never ? Record<string, Encodable> : {
+    [TKey in keyof TValue]: TallyEncodable<TValue[TKey]>;
+} : never;
+/** Public JSON-safe value for one generated Tally OpenAPI schema. */
+export type TallySchemaValue<TName extends TallySchemaName> = TallyEncodable<OpenApiSchemas[TName]>;
+/**
+ * Validates one value against the frozen Tally OpenAPI schema.
+ *
+ * @param name OpenAPI schema name.
+ */
+export declare function tallySchema<TName extends TallySchemaName>(name: TName): z.ZodType<TallySchemaValue<TName>, TallySchemaValue<TName>>;
+export {};

package/dist/tally/schemas.js

@@ -0,0 +1,23 @@
+import { Validator } from "@cfworker/json-schema";
+import * as z from "zod";
+import schemaData from "./openapi-schemas.generated.json" with { type: "json" };
+const VALIDATOR = new Validator({
+    $defs: schemaData.definitions,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: false,
+    maxProperties: 1,
+    minProperties: 1,
+    properties: Object.fromEntries(Object.keys(schemaData.definitions).map((name) => [
+        name,
+        { $ref: `#/$defs/${name}` },
+    ])),
+    type: "object",
+}, "2020-12");
+/**
+ * Validates one value against the frozen Tally OpenAPI schema.
+ *
+ * @param name OpenAPI schema name.
+ */
+export function tallySchema(name) {
+    return z.custom((value) => VALIDATOR.validate({ [name]: value }).valid);
+}

package/dist/triggers.d.ts

@@ -32,12 +32,13 @@ import type { resendTriggerContracts } from "./resend/index.js";
 import type { slackTriggerContracts } from "./slack/index.js";
 import type { stripeTriggerContracts } from "./stripe/index.js";
 import type { teamsTriggerContracts } from "./teams/index.js";
+import type { tallyTriggerContracts } from "./tally/index.js";
 import type { trelloTriggerContracts } from "./trello/index.js";
 import type { vercelTriggerContracts } from "./vercel/index.js";
 import type { webflowTriggerContracts } from "./webflow/index.js";
 import type { whatsappTriggerContracts } from "./whatsapp/index.js";
 import type { z } from "zod";
-export type TriggerContractMap = typeof airtableTriggerContracts & typeof anthropicTriggerContracts & typeof apifyTriggerContracts & typeof axiomTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof calcomTriggerContracts & typeof convexTriggerContracts & typeof discordTriggerContracts & typeof closeTriggerContracts & typeof clickUpTriggerContracts & typeof calendlyTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleDriveTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleAdsTriggerContracts & typeof googleSheetsTriggerContracts & typeof hubspotTriggerContracts & typeof highLevelTriggerContracts & typeof linearTriggerContracts & typeof millionVerifierTriggerContracts & typeof metaAdsTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof redditTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
+export type TriggerContractMap = typeof airtableTriggerContracts & typeof anthropicTriggerContracts & typeof apifyTriggerContracts & typeof axiomTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof calcomTriggerContracts & typeof convexTriggerContracts & typeof discordTriggerContracts & typeof closeTriggerContracts & typeof clickUpTriggerContracts & typeof calendlyTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleDriveTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleAdsTriggerContracts & typeof googleSheetsTriggerContracts & typeof hubspotTriggerContracts & typeof highLevelTriggerContracts & typeof linearTriggerContracts & typeof millionVerifierTriggerContracts & typeof metaAdsTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof redditTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof tallyTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
 export type IntegrationTriggerType = keyof TriggerContractMap;
 /** Canonical authoring configuration for one integration trigger type. */
 export type TriggerConfig<TType extends IntegrationTriggerType> = z.input<TriggerContractMap[TType]["configSchema"]> extends Record<string, never> ? object : z.input<TriggerContractMap[TType]["configSchema"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.146.1",
+  "version": "0.147.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,7 @@
       "./slack": "./src/slack/index.ts",
       "./stripe": "./src/stripe/index.ts",
       "./teams": "./src/teams/index.ts",
+      "./tally": "./src/tally/index.ts",
       "./tidycal": "./src/tidycal/index.ts",
       "./trello": "./src/trello/index.ts",
       "./triggers": "./src/triggers.ts",
@@ -68,7 +69,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.123.0",
-    "@automate.ax/codec": "0.146.1",
+    "@automate.ax/codec": "0.147.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^16.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -105,6 +106,7 @@
     "generate:github": "bun scripts/generate-github-webhook-schemas.ts",
     "generate:calcom": "bun scripts/generate-calcom-openapi.ts",
     "generate:highlevel": "bun scripts/generate-highlevel-openapi.ts",
+    "generate:tally": "bun scripts/generate-tally-openapi.ts",
     "typecheck": "resource-broker run --pool automate-ax-validation --limit 2 --weight 1 -- tsc --noEmit",
     "lint": "oxlint --type-aware --threads=2 && bun --bun eslint . --cache --cache-strategy content",
     "lint:fix": "oxlint --type-aware --threads=2 --fix --fix-suggestions && bun --bun eslint . --fix --cache --cache-strategy content",
@@ -303,6 +305,11 @@
       "types": "./dist/teams/index.d.ts",
       "default": "./dist/teams/index.js"
     },
+    "./tally": {
+      "bun": "./src/tally/index.ts",
+      "types": "./dist/tally/index.d.ts",
+      "default": "./dist/tally/index.js"
+    },
     "./tidycal": {
       "bun": "./src/tidycal/index.ts",
       "types": "./dist/tidycal/index.d.ts",

package/src/tally/api.ts

@@ -0,0 +1,233 @@
+import type { Encodable } from "@automate.ax/codec"
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+import {
+  tallySchema,
+  type TallySchemaName,
+  type TallySchemaValue,
+} from "./schemas"
+
+const TALLY_API_BASE_URL = "https://api.tally.so/"
+const TALLY_API_ORIGIN = new URL(TALLY_API_BASE_URL).origin
+const TALLY_API_VERSION = "2026-08-04"
+const TALLY_API_KEY_SECRET_SCHEMA = z.object({
+  apiKey: z.string().trim().min(1),
+})
+
+/** Resolved account accepted by the shared Tally API client. */
+export interface TallyResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "tally"
+}
+
+/** Options for one authenticated Tally REST request. */
+export interface TallyRequestOptions {
+  /** Tally request body. */
+  body?: Encodable
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "DELETE" | "GET" | "PATCH" | "POST"
+
+  /** Query parameters accepted by the selected endpoint. */
+  query?: Record<string, number | string | string[] | null | undefined>
+}
+
+/** Options for a Tally request with a JSON response. */
+export interface TallyJsonRequestOptions<TName extends TallySchemaName>
+  extends TallyRequestOptions {
+  /** Frozen OpenAPI response schema name. */
+  responseSchema: TName
+}
+
+/** Structured error returned by a rejected Tally request. */
+export class TallyApiError extends Error {
+  readonly body?: Encodable
+  readonly retryAfter?: number
+  readonly status: number
+
+  /**
+   * Creates an error from one rejected Tally response.
+   *
+   * @param options Rejected response details.
+   * @param options.body Parsed provider response body.
+   * @param options.retryAfter Provider retry delay in seconds.
+   * @param options.status HTTP response status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `Tally API request failed with status ${options.status}.`,
+    )
+    this.name = "TallyApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated Tally API client.
+ *
+ * @param account Resolved Tally API-key account.
+ * @throws When the account method or API key is invalid.
+ */
+export function getTallyApi(account: TallyResolvedAccount) {
+  if (account.connectionMethodId !== "api-key") {
+    throw new Error(
+      `Unsupported Tally connection method: ${account.connectionMethodId}`,
+    )
+  }
+  const { apiKey } = TALLY_API_KEY_SECRET_SCHEMA.parse(account.secret)
+
+  return {
+    /**
+     * Sends a request and validates its JSON response.
+     *
+     * @param path Relative Tally API path.
+     * @param options Request and response-schema options.
+     */
+    async request<TName extends TallySchemaName>(
+      path: string,
+      options: TallyJsonRequestOptions<TName>,
+    ): Promise<TallySchemaValue<TName>> {
+      return tallySchema(options.responseSchema).parse(
+        await sendTallyRequest(apiKey, path, options),
+      )
+    },
+
+    /**
+     * Sends a request whose successful response has no body.
+     *
+     * @param path Relative Tally API path.
+     * @param options Request options.
+     */
+    async requestVoid(path: string, options: TallyRequestOptions) {
+      await sendTallyRequest(apiKey, path, options)
+    },
+  }
+}
+
+/**
+ * Sends one authenticated request while enforcing the Tally API origin.
+ *
+ * @param apiKey Tally API key.
+ * @param path Relative Tally API path.
+ * @param options Request options.
+ */
+async function sendTallyRequest(
+  apiKey: string,
+  path: string,
+  options: TallyRequestOptions,
+) {
+  const normalizedPath = path.replace(/^\/+/, "")
+  if (
+    !normalizedPath ||
+    normalizedPath.includes("://") ||
+    normalizedPath.includes("\\") ||
+    normalizedPath.includes("?") ||
+    normalizedPath.includes("#") ||
+    normalizedPath.split("/").some(isTraversalSegment)
+  ) {
+    throw new TypeError("Tally API paths must be relative.")
+  }
+  const url = new URL(normalizedPath, TALLY_API_BASE_URL)
+  if (url.origin !== TALLY_API_ORIGIN) {
+    throw new TypeError("Tally API paths must remain on api.tally.so.")
+  }
+  for (const [name, value] of Object.entries(options.query ?? {})) {
+    if (value == null) continue
+    if (Array.isArray(value)) {
+      for (const item of value) url.searchParams.append(name, item)
+    } else {
+      url.searchParams.set(name, String(value))
+    }
+  }
+
+  const response = await fetch(url, {
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiKey}`,
+      "tally-version": TALLY_API_VERSION,
+      ...(options.body === undefined
+        ? {}
+        : { "Content-Type": "application/json" }),
+    },
+    method: options.method ?? "GET",
+    redirect: "error",
+  })
+  const text = await response.text()
+  const parsed = text ? parseJson(text) : undefined
+  if (!response.ok) {
+    const body = encodableSchema.safeParse(parsed)
+    throw new TallyApiError({
+      ...(body.success && { body: body.data }),
+      retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+      status: response.status,
+    })
+  }
+  return parsed
+}
+
+/**
+ * Detects direct or encoded path traversal segments.
+ *
+ * @param segment One URL path segment.
+ */
+function isTraversalSegment(segment: string) {
+  try {
+    const decoded = decodeURIComponent(segment)
+    return decoded === "." || decoded === ".." || decoded.includes("/")
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Parses one JSON response or reports a provider contract failure.
+ *
+ * @param text Provider response text.
+ * @throws When the provider response is not valid JSON.
+ */
+function parseJson(text: string) {
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    throw new Error("Tally API returned invalid JSON.")
+  }
+}
+
+/**
+ * Parses Retry-After seconds or an HTTP date into a delay in seconds.
+ *
+ * @param value Retry-After header value.
+ */
+function parseRetryAfter(value: string | null) {
+  if (!value) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds
+  const date = Date.parse(value)
+  return Number.isNaN(date)
+    ? undefined
+    : Math.max(0, (date - Date.now()) / 1_000)
+}
+
+/**
+ * Extracts the provider's human-readable error message.
+ *
+ * @param body Parsed provider error response.
+ */
+function getErrorMessage(body: Encodable | undefined) {
+  if (typeof body === "string") return body
+  if (!body || Array.isArray(body) || typeof body !== "object") return undefined
+  for (const key of ["message", "error"]) {
+    const value = Reflect.get(body, key)
+    if (typeof value === "string" && value) return value
+  }
+  return undefined
+}

package/src/tally/events.ts

@@ -0,0 +1,88 @@
+import * as z from "zod"
+
+export const TALLY_FORM_RESPONSE_EVENT_TYPE = "FORM_RESPONSE" as const
+
+const TALLY_OPTION_SCHEMA = z.object({ id: z.string(), text: z.string() })
+const TALLY_FILE_SCHEMA = z.object({
+  id: z.string(),
+  mimeType: z.string(),
+  name: z.string(),
+  size: z.number().int().nonnegative(),
+  url: z.url(),
+})
+const TALLY_FIELD_SCHEMA = z.object({
+  columns: TALLY_OPTION_SCHEMA.array().optional(),
+  key: z.string(),
+  label: z.string(),
+  options: TALLY_OPTION_SCHEMA.array().optional(),
+  rows: TALLY_OPTION_SCHEMA.array().optional(),
+  type: z.enum([
+    "CALCULATED_FIELDS",
+    "CHECKBOXES",
+    "DROPDOWN",
+    "FILE_UPLOAD",
+    "HIDDEN_FIELDS",
+    "INPUT_DATE",
+    "INPUT_EMAIL",
+    "INPUT_LINK",
+    "INPUT_NUMBER",
+    "INPUT_PHONE_NUMBER",
+    "INPUT_TEXT",
+    "INPUT_TIME",
+    "LINEAR_SCALE",
+    "MATRIX",
+    "MULTIPLE_CHOICE",
+    "MULTI_SELECT",
+    "PAYMENT",
+    "RANKING",
+    "RATING",
+    "SIGNATURE",
+    "TEXTAREA",
+  ]),
+  value: z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.string().array(),
+    TALLY_FILE_SCHEMA.array(),
+    z.record(z.string(), z.string().array()),
+    z.null(),
+  ]),
+})
+
+/** Signed form-response webhook payload delivered by Tally. */
+export const TALLY_FORM_RESPONSE_EVENT_SCHEMA = z.object({
+  createdAt: z.iso.datetime({ offset: true }),
+  data: z.object({
+    createdAt: z.iso.datetime({ offset: true }),
+    fields: TALLY_FIELD_SCHEMA.array(),
+    formId: z.string(),
+    formName: z.string(),
+    respondentId: z.string(),
+    responseId: z.string(),
+    submissionId: z.string(),
+    submissionPdfUrl: z.url().optional(),
+    submissionPreviewUrl: z.url().optional(),
+  }),
+  eventId: z.string(),
+  eventType: z.literal(TALLY_FORM_RESPONSE_EVENT_TYPE),
+})
+
+export type TallyFormResponseEvent = z.output<
+  typeof TALLY_FORM_RESPONSE_EVENT_SCHEMA
+>
+
+export const TALLY_TRIGGER_CONFIG_SCHEMA = z.object({
+  formId: z.string().trim().min(1),
+})
+
+export const tallyTriggerContracts = {
+  "tally.form.event": {
+    configSchema: TALLY_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TALLY_FORM_RESPONSE_EVENT_SCHEMA,
+  },
+  "tally.form.response": {
+    configSchema: TALLY_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: TALLY_FORM_RESPONSE_EVENT_SCHEMA,
+  },
+} as const

package/src/tally/index.ts

@@ -0,0 +1,3 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"