@automate.ax/integration-contracts 0.146.0 → 0.147.0

package/dist/tally/api.d.ts

@@ -0,0 +1,63 @@
+import type { Encodable } from "@automate.ax/codec";
+import { type TallySchemaName, type TallySchemaValue } from "./schemas.js";
+/** 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 declare 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;
+    });
+}
+/**
+ * Creates an authenticated Tally API client.
+ *
+ * @param account Resolved Tally API-key account.
+ * @throws When the account method or API key is invalid.
+ */
+export declare function getTallyApi(account: TallyResolvedAccount): {
+    /**
+     * Sends a request and validates its JSON response.
+     *
+     * @param path Relative Tally API path.
+     * @param options Request and response-schema options.
+     */
+    request<TName extends TallySchemaName>(path: string, options: TallyJsonRequestOptions<TName>): Promise<TallySchemaValue<TName>>;
+    /**
+     * Sends a request whose successful response has no body.
+     *
+     * @param path Relative Tally API path.
+     * @param options Request options.
+     */
+    requestVoid(path: string, options: TallyRequestOptions): Promise<void>;
+};

package/dist/tally/api.js

@@ -0,0 +1,181 @@
+import { encodableSchema } from "@automate.ax/codec";
+import * as z from "zod";
+import { tallySchema, } from "./schemas.js";
+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),
+});
+/** Structured error returned by a rejected Tally request. */
+export class TallyApiError extends Error {
+    body;
+    retryAfter;
+    status;
+    /**
+     * 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) {
+        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) {
+    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(path, options) {
+            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, options) {
+            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, path, options) {
+    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) {
+    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) {
+    try {
+        return JSON.parse(text);
+    }
+    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) {
+    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) {
+    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/dist/tally/events.d.ts

@@ -0,0 +1,202 @@
+import * as z from "zod";
+export declare const TALLY_FORM_RESPONSE_EVENT_TYPE: "FORM_RESPONSE";
+/** Signed form-response webhook payload delivered by Tally. */
+export declare const TALLY_FORM_RESPONSE_EVENT_SCHEMA: z.ZodObject<{
+    createdAt: z.ZodISODateTime;
+    data: z.ZodObject<{
+        createdAt: z.ZodISODateTime;
+        fields: z.ZodArray<z.ZodObject<{
+            columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strip>>>;
+            key: z.ZodString;
+            label: z.ZodString;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strip>>>;
+            rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                text: z.ZodString;
+            }, z.core.$strip>>>;
+            type: z.ZodEnum<{
+                MATRIX: "MATRIX";
+                INPUT_TEXT: "INPUT_TEXT";
+                INPUT_NUMBER: "INPUT_NUMBER";
+                INPUT_EMAIL: "INPUT_EMAIL";
+                INPUT_LINK: "INPUT_LINK";
+                INPUT_PHONE_NUMBER: "INPUT_PHONE_NUMBER";
+                INPUT_DATE: "INPUT_DATE";
+                INPUT_TIME: "INPUT_TIME";
+                TEXTAREA: "TEXTAREA";
+                FILE_UPLOAD: "FILE_UPLOAD";
+                LINEAR_SCALE: "LINEAR_SCALE";
+                RATING: "RATING";
+                HIDDEN_FIELDS: "HIDDEN_FIELDS";
+                PAYMENT: "PAYMENT";
+                SIGNATURE: "SIGNATURE";
+                CALCULATED_FIELDS: "CALCULATED_FIELDS";
+                MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+                CHECKBOXES: "CHECKBOXES";
+                DROPDOWN: "DROPDOWN";
+                RANKING: "RANKING";
+                MULTI_SELECT: "MULTI_SELECT";
+            }>;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                mimeType: z.ZodString;
+                name: z.ZodString;
+                size: z.ZodNumber;
+                url: z.ZodURL;
+            }, z.core.$strip>>, z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>, z.ZodNull]>;
+        }, z.core.$strip>>;
+        formId: z.ZodString;
+        formName: z.ZodString;
+        respondentId: z.ZodString;
+        responseId: z.ZodString;
+        submissionId: z.ZodString;
+        submissionPdfUrl: z.ZodOptional<z.ZodURL>;
+        submissionPreviewUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>;
+    eventId: z.ZodString;
+    eventType: z.ZodLiteral<"FORM_RESPONSE">;
+}, z.core.$strip>;
+export type TallyFormResponseEvent = z.output<typeof TALLY_FORM_RESPONSE_EVENT_SCHEMA>;
+export declare const TALLY_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{
+    formId: z.ZodString;
+}, z.core.$strip>;
+export declare const tallyTriggerContracts: {
+    readonly "tally.form.event": {
+        readonly configSchema: z.ZodObject<{
+            formId: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            createdAt: z.ZodISODateTime;
+            data: z.ZodObject<{
+                createdAt: z.ZodISODateTime;
+                fields: z.ZodArray<z.ZodObject<{
+                    columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    key: z.ZodString;
+                    label: z.ZodString;
+                    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    type: z.ZodEnum<{
+                        MATRIX: "MATRIX";
+                        INPUT_TEXT: "INPUT_TEXT";
+                        INPUT_NUMBER: "INPUT_NUMBER";
+                        INPUT_EMAIL: "INPUT_EMAIL";
+                        INPUT_LINK: "INPUT_LINK";
+                        INPUT_PHONE_NUMBER: "INPUT_PHONE_NUMBER";
+                        INPUT_DATE: "INPUT_DATE";
+                        INPUT_TIME: "INPUT_TIME";
+                        TEXTAREA: "TEXTAREA";
+                        FILE_UPLOAD: "FILE_UPLOAD";
+                        LINEAR_SCALE: "LINEAR_SCALE";
+                        RATING: "RATING";
+                        HIDDEN_FIELDS: "HIDDEN_FIELDS";
+                        PAYMENT: "PAYMENT";
+                        SIGNATURE: "SIGNATURE";
+                        CALCULATED_FIELDS: "CALCULATED_FIELDS";
+                        MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+                        CHECKBOXES: "CHECKBOXES";
+                        DROPDOWN: "DROPDOWN";
+                        RANKING: "RANKING";
+                        MULTI_SELECT: "MULTI_SELECT";
+                    }>;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        mimeType: z.ZodString;
+                        name: z.ZodString;
+                        size: z.ZodNumber;
+                        url: z.ZodURL;
+                    }, z.core.$strip>>, z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>, z.ZodNull]>;
+                }, z.core.$strip>>;
+                formId: z.ZodString;
+                formName: z.ZodString;
+                respondentId: z.ZodString;
+                responseId: z.ZodString;
+                submissionId: z.ZodString;
+                submissionPdfUrl: z.ZodOptional<z.ZodURL>;
+                submissionPreviewUrl: z.ZodOptional<z.ZodURL>;
+            }, z.core.$strip>;
+            eventId: z.ZodString;
+            eventType: z.ZodLiteral<"FORM_RESPONSE">;
+        }, z.core.$strip>;
+    };
+    readonly "tally.form.response": {
+        readonly configSchema: z.ZodObject<{
+            formId: z.ZodString;
+        }, z.core.$strip>;
+        readonly eventSchema: z.ZodObject<{
+            createdAt: z.ZodISODateTime;
+            data: z.ZodObject<{
+                createdAt: z.ZodISODateTime;
+                fields: z.ZodArray<z.ZodObject<{
+                    columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    key: z.ZodString;
+                    label: z.ZodString;
+                    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    rows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        text: z.ZodString;
+                    }, z.core.$strip>>>;
+                    type: z.ZodEnum<{
+                        MATRIX: "MATRIX";
+                        INPUT_TEXT: "INPUT_TEXT";
+                        INPUT_NUMBER: "INPUT_NUMBER";
+                        INPUT_EMAIL: "INPUT_EMAIL";
+                        INPUT_LINK: "INPUT_LINK";
+                        INPUT_PHONE_NUMBER: "INPUT_PHONE_NUMBER";
+                        INPUT_DATE: "INPUT_DATE";
+                        INPUT_TIME: "INPUT_TIME";
+                        TEXTAREA: "TEXTAREA";
+                        FILE_UPLOAD: "FILE_UPLOAD";
+                        LINEAR_SCALE: "LINEAR_SCALE";
+                        RATING: "RATING";
+                        HIDDEN_FIELDS: "HIDDEN_FIELDS";
+                        PAYMENT: "PAYMENT";
+                        SIGNATURE: "SIGNATURE";
+                        CALCULATED_FIELDS: "CALCULATED_FIELDS";
+                        MULTIPLE_CHOICE: "MULTIPLE_CHOICE";
+                        CHECKBOXES: "CHECKBOXES";
+                        DROPDOWN: "DROPDOWN";
+                        RANKING: "RANKING";
+                        MULTI_SELECT: "MULTI_SELECT";
+                    }>;
+                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        mimeType: z.ZodString;
+                        name: z.ZodString;
+                        size: z.ZodNumber;
+                        url: z.ZodURL;
+                    }, z.core.$strip>>, z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>, z.ZodNull]>;
+                }, z.core.$strip>>;
+                formId: z.ZodString;
+                formName: z.ZodString;
+                respondentId: z.ZodString;
+                responseId: z.ZodString;
+                submissionId: z.ZodString;
+                submissionPdfUrl: z.ZodOptional<z.ZodURL>;
+                submissionPreviewUrl: z.ZodOptional<z.ZodURL>;
+            }, z.core.$strip>;
+            eventId: z.ZodString;
+            eventType: z.ZodLiteral<"FORM_RESPONSE">;
+        }, z.core.$strip>;
+    };
+};

package/dist/tally/events.js

@@ -0,0 +1,79 @@
+import * as z from "zod";
+export const TALLY_FORM_RESPONSE_EVENT_TYPE = "FORM_RESPONSE";
+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 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,
+    },
+};

package/dist/tally/index.d.ts

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

package/dist/tally/index.js

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