@automate.ax/integration-contracts 0.116.0 → 0.118.0

package/dist/tidycal/schemas.d.ts

@@ -0,0 +1,121 @@
+import * as z from "zod";
+export declare const TIDYCAL_ACCOUNT_SCHEMA: z.ZodObject<{
+    currencySymbol: z.ZodString;
+    email: z.ZodEmail;
+    language: z.ZodString;
+    lifetimeProAt: z.ZodNullable<z.ZodISODateTime>;
+    name: z.ZodString;
+    profilePictureUrl: z.ZodNullable<z.ZodURL>;
+    vanityPath: z.ZodString;
+}, z.core.$strip>;
+export declare const TIDYCAL_CONTACT_SCHEMA: z.ZodObject<{
+    createdAt: z.ZodISODateTime;
+    email: z.ZodEmail;
+    id: z.ZodNumber;
+    ipAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+    phoneNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_PAYMENT_SCHEMA: z.ZodObject<{
+    amount: z.ZodNumber;
+    bookingId: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    currency: z.ZodString;
+    id: z.ZodNumber;
+    paymentId: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_QUESTION_SCHEMA: z.ZodObject<{
+    answer: z.ZodString;
+    bookingId: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    id: z.ZodNumber;
+    question: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_BOOKING_SCHEMA: z.ZodObject<{
+    bookingTypeId: z.ZodNumber;
+    cancelledAt: z.ZodNullable<z.ZodISODateTime>;
+    contact: z.ZodObject<{
+        createdAt: z.ZodISODateTime;
+        email: z.ZodEmail;
+        id: z.ZodNumber;
+        ipAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodString;
+        phoneNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    contactId: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    endsAt: z.ZodISODateTime;
+    id: z.ZodNumber;
+    meetingId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    meetingUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+    payment: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        amount: z.ZodNumber;
+        bookingId: z.ZodNumber;
+        createdAt: z.ZodISODateTime;
+        currency: z.ZodString;
+        id: z.ZodNumber;
+        paymentId: z.ZodString;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>>>;
+    questions: z.ZodArray<z.ZodObject<{
+        answer: z.ZodString;
+        bookingId: z.ZodNumber;
+        createdAt: z.ZodISODateTime;
+        id: z.ZodNumber;
+        question: z.ZodString;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    startsAt: z.ZodISODateTime;
+    timezone: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_BOOKING_TYPE_SCHEMA: z.ZodObject<{
+    bookingThresholdMinutes: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    currencyCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodString;
+    disabledAt: z.ZodNullable<z.ZodISODateTime>;
+    durationMinutes: z.ZodNumber;
+    id: z.ZodNumber;
+    latestAvailabilityDays: z.ZodNumber;
+    maxBookings: z.ZodNumber;
+    paddingMinutes: z.ZodNumber;
+    paymentPlatform: z.ZodNullable<z.ZodEnum<{
+        tidycal: "tidycal";
+        paypal: "paypal";
+        stripe: "stripe";
+    }>>;
+    paymentPlatformId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    price: z.ZodNumber;
+    private: z.ZodBoolean;
+    redirectUrl: z.ZodNullable<z.ZodURL>;
+    title: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    urlSlug: z.ZodString;
+    userId: z.ZodNumber;
+}, z.core.$strip>;
+export declare const TIDYCAL_TIMESLOT_SCHEMA: z.ZodObject<{
+    availableBookings: z.ZodNumber;
+    endsAt: z.ZodISODateTime;
+    startsAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_TEAM_SCHEMA: z.ZodObject<{
+    createdAt: z.ZodISODateTime;
+    id: z.ZodNumber;
+    name: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const TIDYCAL_TEAM_USER_SCHEMA: z.ZodObject<{
+    createdAt: z.ZodISODateTime;
+    email: z.ZodEmail;
+    id: z.ZodNumber;
+    name: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;

package/dist/tidycal/schemas.js

@@ -0,0 +1,95 @@
+import * as z from "zod";
+const DATE_TIME_SCHEMA = z.iso.datetime({ offset: true });
+const ID_SCHEMA = z.number().int().positive();
+export const TIDYCAL_ACCOUNT_SCHEMA = z.object({
+    currencySymbol: z.string(),
+    email: z.email(),
+    language: z.string(),
+    lifetimeProAt: DATE_TIME_SCHEMA.nullable(),
+    name: z.string(),
+    profilePictureUrl: z.url().nullable(),
+    vanityPath: z.string(),
+});
+export const TIDYCAL_CONTACT_SCHEMA = z.object({
+    createdAt: DATE_TIME_SCHEMA,
+    email: z.email(),
+    id: ID_SCHEMA,
+    ipAddress: z.string().nullable().optional(),
+    name: z.string(),
+    phoneNumber: z.string().nullable().optional(),
+    timezone: z.string().nullable().optional(),
+    updatedAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_PAYMENT_SCHEMA = z.object({
+    amount: z.number().nonnegative(),
+    bookingId: ID_SCHEMA,
+    createdAt: DATE_TIME_SCHEMA,
+    currency: z.string(),
+    id: ID_SCHEMA,
+    paymentId: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_QUESTION_SCHEMA = z.object({
+    answer: z.string(),
+    bookingId: ID_SCHEMA,
+    createdAt: DATE_TIME_SCHEMA,
+    id: ID_SCHEMA,
+    question: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_BOOKING_SCHEMA = z.object({
+    bookingTypeId: ID_SCHEMA,
+    cancelledAt: DATE_TIME_SCHEMA.nullable(),
+    contact: TIDYCAL_CONTACT_SCHEMA,
+    contactId: ID_SCHEMA,
+    createdAt: DATE_TIME_SCHEMA,
+    endsAt: DATE_TIME_SCHEMA,
+    id: ID_SCHEMA,
+    meetingId: z.string().nullable().optional(),
+    meetingUrl: z.url().nullable().optional(),
+    payment: TIDYCAL_PAYMENT_SCHEMA.nullable().optional(),
+    questions: TIDYCAL_QUESTION_SCHEMA.array(),
+    startsAt: DATE_TIME_SCHEMA,
+    timezone: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_BOOKING_TYPE_SCHEMA = z.object({
+    bookingThresholdMinutes: z.number().int().min(0),
+    createdAt: DATE_TIME_SCHEMA,
+    currencyCode: z.string().nullable().optional(),
+    description: z.string(),
+    disabledAt: DATE_TIME_SCHEMA.nullable(),
+    durationMinutes: z.number().int().positive(),
+    id: ID_SCHEMA,
+    latestAvailabilityDays: z.number().int().min(0),
+    maxBookings: z.number().int().positive(),
+    paddingMinutes: z.number().int().min(0),
+    paymentPlatform: z.enum(["paypal", "stripe", "tidycal"]).nullable(),
+    paymentPlatformId: z.string().nullable().optional(),
+    price: z.number().nonnegative(),
+    private: z.boolean(),
+    redirectUrl: z.url().nullable(),
+    title: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+    url: z.url(),
+    urlSlug: z.string(),
+    userId: ID_SCHEMA,
+});
+export const TIDYCAL_TIMESLOT_SCHEMA = z.object({
+    availableBookings: z.number().int().nonnegative(),
+    endsAt: DATE_TIME_SCHEMA,
+    startsAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_TEAM_SCHEMA = z.object({
+    createdAt: DATE_TIME_SCHEMA,
+    id: ID_SCHEMA,
+    name: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+});
+export const TIDYCAL_TEAM_USER_SCHEMA = z.object({
+    createdAt: DATE_TIME_SCHEMA,
+    email: z.email(),
+    id: ID_SCHEMA,
+    name: z.string(),
+    updatedAt: DATE_TIME_SCHEMA,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
       "./slack": "./src/slack/index.ts",
       "./stripe": "./src/stripe/index.ts",
       "./teams": "./src/teams/index.ts",
+      "./tidycal": "./src/tidycal/index.ts",
       "./trello": "./src/trello/index.ts",
       "./triggers": "./src/triggers.ts",
       "./vercel": "./src/vercel/index.ts",
@@ -52,7 +53,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.116.0",
+    "@automate.ax/codec": "0.118.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -213,6 +214,11 @@
       "types": "./dist/teams/index.d.ts",
       "default": "./dist/teams/index.js"
     },
+    "./tidycal": {
+      "bun": "./src/tidycal/index.ts",
+      "types": "./dist/tidycal/index.d.ts",
+      "default": "./dist/tidycal/index.js"
+    },
     "./trello": {
       "bun": "./src/trello/index.ts",
       "types": "./dist/trello/index.d.ts",

package/src/gmail/index.ts

@@ -1,5 +1,10 @@
 import * as z from "zod"
-import { LABEL_CHANGE_SCHEMA, MESSAGE_SCHEMA } from "./schemas"
+import {
+  LABEL_CHANGE_SCHEMA,
+  MAILBOX_CHANGE_SCHEMA,
+  MESSAGE_DELETED_SCHEMA,
+  MESSAGE_SCHEMA,
+} from "./schemas"
 
 export * from "./gmail"
 export * from "./schemas"
@@ -15,6 +20,18 @@ export const gmailTriggerContracts = {
     configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
     eventSchema: LABEL_CHANGE_SCHEMA,
   },
+  "gmail.mailbox.changed": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: MAILBOX_CHANGE_SCHEMA,
+  },
+  "gmail.message.added": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: MESSAGE_SCHEMA,
+  },
+  "gmail.message.deleted": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: MESSAGE_DELETED_SCHEMA,
+  },
   "gmail.message.received": {
     configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
     eventSchema: MESSAGE_SCHEMA,

package/src/gmail/schemas.ts

@@ -363,6 +363,32 @@ export const LABEL_CHANGE_SCHEMA = z.object({
   message: MESSAGE_SCHEMA,
 })
 
+/** Stable identity retained after Gmail permanently deletes a message. */
+export const MESSAGE_DELETED_SCHEMA = MESSAGE_IDENTIFIER_SCHEMA.extend({
+  /** Mailbox history record that reported the deletion. */
+  historyId: z.string(),
+})
+
+/** Broad normalized Gmail mailbox-history change. */
+export const MAILBOX_CHANGE_SCHEMA = z.discriminatedUnion("changeType", [
+  z.object({
+    changeType: z.literal("messageAdded"),
+    historyId: z.string(),
+    message: MESSAGE_SCHEMA,
+  }),
+  MESSAGE_DELETED_SCHEMA.extend({
+    changeType: z.literal("messageDeleted"),
+  }),
+  LABEL_CHANGE_SCHEMA.extend({
+    changeType: z.literal("labelAdded"),
+    historyId: z.string(),
+  }),
+  LABEL_CHANGE_SCHEMA.extend({
+    changeType: z.literal("labelRemoved"),
+    historyId: z.string(),
+  }),
+])
+
 export const THREAD_IDENTIFIER_SCHEMA = z.object({
   /** Immutable Gmail thread ID. */
   threadId: z.string(),

package/src/google-calendar/event-schemas.ts

@@ -14,3 +14,21 @@ export const GOOGLE_CALENDAR_EVENT_DELETED_SCHEMA = z.object({
   /** Immutable provider event ID. */
   eventId: z.string(),
 })
+
+/** Broad normalized Google Calendar event lifecycle change. */
+export const GOOGLE_CALENDAR_EVENT_CHANGED_SCHEMA = z.discriminatedUnion(
+  "changeType",
+  [
+    z.object({
+      changeType: z.literal("created"),
+      event: CALENDAR_EVENT_SCHEMA,
+    }),
+    z.object({
+      changeType: z.literal("updated"),
+      event: CALENDAR_EVENT_SCHEMA,
+    }),
+    GOOGLE_CALENDAR_EVENT_DELETED_SCHEMA.extend({
+      changeType: z.literal("deleted"),
+    }),
+  ],
+)

package/src/google-calendar/index.ts

@@ -1,5 +1,8 @@
 import * as z from "zod"
-import { GOOGLE_CALENDAR_EVENT_DELETED_SCHEMA } from "./event-schemas"
+import {
+  GOOGLE_CALENDAR_EVENT_CHANGED_SCHEMA,
+  GOOGLE_CALENDAR_EVENT_DELETED_SCHEMA,
+} from "./event-schemas"
 import { CALENDAR_EVENT_SCHEMA } from "./schemas"
 
 export * from "./event-schemas"
@@ -12,6 +15,10 @@ export const GOOGLE_CALENDAR_TRIGGER_CONFIG_SCHEMA = z.object({
 })
 
 export const googleCalendarTriggerContracts = {
+  "googleCalendar.event.changed": {
+    configSchema: GOOGLE_CALENDAR_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: GOOGLE_CALENDAR_EVENT_CHANGED_SCHEMA,
+  },
   "googleCalendar.event.created": {
     configSchema: GOOGLE_CALENDAR_TRIGGER_CONFIG_SCHEMA,
     eventSchema: CALENDAR_EVENT_SCHEMA,

package/src/tidycal/api.ts

@@ -0,0 +1,239 @@
+import type { Encodable } from "@automate.ax/codec"
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+
+const TIDYCAL_API_BASE_URL = "https://tidycal.com/api/"
+const TIDYCAL_API_ORIGIN = new URL(TIDYCAL_API_BASE_URL).origin
+const TIDYCAL_PERSONAL_ACCESS_TOKEN_SECRET_SCHEMA = z.object({
+  apiKey: z.string().min(1),
+})
+const TIDYCAL_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+
+/** Resolved TidyCal account accepted by the shared API client. */
+export interface TidyCalResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "tidycal"
+}
+
+/** Options for one authenticated TidyCal REST request. */
+export interface TidyCalRequestOptions<TSchema extends z.ZodType> {
+  /** Public camelCase JSON body. */
+  body?: Encodable
+
+  /** HTTP verb. Defaults to `GET`. */
+  method?: "DELETE" | "GET" | "PATCH" | "POST"
+
+  /** Public camelCase query parameters. */
+  query?: Record<string, boolean | number | string | undefined>
+
+  /** Schema for the normalized provider response. */
+  responseSchema: TSchema
+}
+
+/** Structured TidyCal REST error. */
+export class TidyCalApiError extends Error {
+  /** Normalized provider error payload, when it was valid JSON. */
+  readonly body?: Encodable
+
+  /** Retry delay in seconds, when TidyCal returned one. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by TidyCal. */
+  readonly status: number
+
+  /**
+   * Creates a structured error from one TidyCal response.
+   *
+   * @param options - Response status, provider body, and retry metadata.
+   * @param options.body - Normalized provider error payload.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: number
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `TidyCal API request failed with status ${options.status}.`,
+    )
+    this.name = "TidyCalApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated TidyCal REST client.
+ *
+ * @param account - Resolved OAuth or personal-access-token account.
+ * @throws When the connection method or secret shape is unsupported.
+ */
+export function getTidyCalApi(account: TidyCalResolvedAccount) {
+  const accessToken =
+    account.connectionMethodId === "oauth"
+      ? TIDYCAL_OAUTH_SECRET_SCHEMA.parse(account.secret).accessToken
+      : account.connectionMethodId === "personal-access-token"
+        ? TIDYCAL_PERSONAL_ACCESS_TOKEN_SECRET_SCHEMA.parse(account.secret)
+            .apiKey
+        : undefined
+  if (!accessToken) {
+    throw new Error(
+      `Unsupported TidyCal connection method: ${account.connectionMethodId}`,
+    )
+  }
+
+  /**
+   * Runs one request and returns its normalized response.
+   *
+   * @param path - TidyCal API path relative to the API root.
+   * @param options - Method, parameters, and response schema.
+   */
+  async function request<TSchema extends z.ZodType>(
+    path: string,
+    options: TidyCalRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>> {
+    const url = new URL(path.replace(/^\//, ""), TIDYCAL_API_BASE_URL)
+    if (url.origin !== TIDYCAL_API_ORIGIN) {
+      throw new Error("TidyCal API paths must use the TidyCal API origin.")
+    }
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined)
+        url.searchParams.set(toSnakeCase(name), String(value))
+    }
+    const response = await fetch(url, {
+      body:
+        options.body === undefined
+          ? undefined
+          : JSON.stringify(toTidyCal(options.body)),
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${accessToken}`,
+        ...(options.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+      },
+      method: options.method ?? "GET",
+    })
+    const normalized = fromTidyCal(parseJson(await response.text()))
+    if (!response.ok) {
+      const body = encodableSchema.safeParse(normalized)
+      throw new TidyCalApiError({
+        ...(body.success && { body: body.data }),
+        retryAfter: parseFiniteNumber(response.headers.get("Retry-After")),
+        status: response.status,
+      })
+    }
+    return options.responseSchema.parse(normalized)
+  }
+
+  return { request }
+}
+
+/**
+ * Converts public camelCase JSON to TidyCal wire keys.
+ *
+ * @param value - Codec-safe public value.
+ */
+export function toTidyCal(value: Encodable): Encodable {
+  if (value instanceof Date) return value.toISOString()
+  if (Array.isArray(value)) return value.map(toTidyCal)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toSnakeCase(key),
+      toTidyCal(item),
+    ]),
+  )
+}
+
+/**
+ * Converts TidyCal wire JSON to public camelCase keys.
+ *
+ * @param value - Untrusted provider JSON value.
+ */
+export function fromTidyCal(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(fromTidyCal)
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toCamelCase(key),
+      fromTidyCal(item),
+    ]),
+  )
+}
+
+/**
+ * Returns whether a value is a plain JSON object.
+ *
+ * @param value - Value to inspect.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parses JSON without obscuring the eventual structured API error.
+ *
+ * @param value - Response text to parse.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses a finite numeric response header.
+ *
+ * @param value - Header value.
+ */
+function parseFiniteNumber(value: string | null) {
+  if (value === null) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/**
+ * Extracts the provider's primary error text without weakening its payload.
+ *
+ * @param body - Normalized provider error body.
+ */
+function getErrorMessage(body: Encodable | undefined) {
+  if (!isPlainObject(body)) return undefined
+  if (typeof body.message === "string") return body.message
+  const errors = body.errors
+  if (!isPlainObject(errors)) return undefined
+  const first = Object.values(errors)[0]
+  if (typeof first === "string") return first
+  return Array.isArray(first) && typeof first[0] === "string"
+    ? first[0]
+    : undefined
+}
+
+/**
+ * Converts one camelCase public key to snake_case.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value: string) {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+/**
+ * Converts one snake_case provider key to camelCase.
+ *
+ * @param value - Provider key.
+ */
+function toCamelCase(value: string) {
+  return value.replace(/_([a-z0-9])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  )
+}

package/src/tidycal/index.ts

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