@automate.ax/integration-contracts 0.147.1 → 0.150.0

package/src/kit/api.ts

@@ -0,0 +1,523 @@
+import { encodableSchema, type Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+import type { KitOperationKey } from "./operation-manifest"
+import {
+  KIT_WIRE_DEFINITIONS,
+  kitOperation,
+  kitOperationOutputSchema,
+  type KitRuntimeParameter,
+} from "./schemas"
+import type { KitOperationInput, KitOperationOutput } from "./types"
+
+const KIT_API_BASE_URL = "https://api.kit.com/v4/"
+const KIT_API_ORIGIN = new URL(KIT_API_BASE_URL).origin
+const KIT_API_KEY_SECRET_SCHEMA = z.object({
+  apiKey: z.string().trim().min(1),
+})
+const KIT_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().trim().min(1),
+})
+
+/** Resolved account accepted by the shared Kit API client. */
+export interface KitResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "kit"
+}
+
+/** Options for an internal provider-native Kit request. */
+export interface KitRequestOptions {
+  body?: Encodable
+  method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT"
+  query?: Record<
+    string,
+    boolean | number | string | (boolean | number | string)[] | null | undefined
+  >
+}
+
+/** Structured error returned by a rejected Kit request. */
+export class KitApiError extends Error {
+  readonly body?: Encodable
+  readonly retryAfter?: string
+  readonly status: number
+
+  /**
+   * Creates a structured provider error.
+   *
+   * @param options Error properties.
+   * @param options.body Parsed provider response body.
+   * @param options.retryAfter Provider retry guidance.
+   * @param options.status HTTP status code.
+   */
+  constructor(options: {
+    body?: Encodable
+    retryAfter?: string
+    status: number
+  }) {
+    super(
+      getErrorMessage(options.body) ??
+        `Kit API request failed with status ${options.status}.`,
+    )
+    this.name = "KitApiError"
+    this.body = options.body
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates an authenticated Kit V4 API client.
+ *
+ * @param account Resolved Kit account.
+ */
+export function getKitApi(account: KitResolvedAccount) {
+  const authorization = getAuthorization(account)
+
+  return {
+    /**
+     * Executes and validates one named public Kit operation.
+     *
+     * @param key Public operation name.
+     * @param input Flattened operation input.
+     */
+    async operation<TKey extends KitOperationKey>(
+      key: TKey,
+      input: KitOperationInput<TKey>,
+    ): Promise<KitOperationOutput<TKey>> {
+      const definition = kitOperation(key)
+      const inputRecord = input as Record<string, Encodable | undefined>
+      // Build the path before request assembly so every interpolation is encoded.
+      const path = definition.path
+        .replace(/^\/v4\//, "")
+        .replace(/\{([^}]+)\}/g, (_match, providerName: string) => {
+          const parameter = definition.pathParameters.find(
+            (candidate) => candidate.providerName === providerName,
+          )
+          if (!parameter) {
+            throw new TypeError(`Unknown Kit path parameter: ${providerName}`)
+          }
+          return encodePathSegment(inputRecord[parameter.name], parameter.name)
+        })
+      // Preserve undefined query fields for the shared serializer to omit.
+      const query = Object.fromEntries(
+        definition.queryParameters.map((parameter) => [
+          parameter.providerName,
+          parseQueryValue(inputRecord[parameter.name]),
+        ]),
+      )
+      const body = Object.fromEntries(
+        definition.bodyParameters.flatMap((name) =>
+          inputRecord[name] === undefined ? [] : [[name, inputRecord[name]]],
+        ),
+      )
+      const parsed = await sendKitRequest(authorization, path, {
+        ...(definition.bodyParameters.length > 0 && {
+          body: kitPublicToWire(body, definition.bodyWireSchema ?? {}),
+        }),
+        method: definition.method,
+        query,
+      })
+      // Normalize provider fields before validating the public return type.
+      const output =
+        definition.responseMode === "void"
+          ? {}
+          : kitWireToPublic(parsed, definition.outputWireSchema)
+      return kitOperationOutputSchema(key).parse(output)
+    },
+
+    /**
+     * Sends an internal provider-native request used for managed webhooks.
+     *
+     * This is not exposed as an automation action.
+     *
+     * @param path Provider-relative Kit V4 path.
+     * @param options Request options.
+     */
+    async requestJson(path: string, options: KitRequestOptions = {}) {
+      return await sendKitRequest(authorization, path, options)
+    },
+  }
+}
+
+/**
+ * Encodes every interpolation as one Kit URL path segment.
+ *
+ * @param strings Template string segments.
+ * @param values Interpolated path values.
+ */
+export function kitPath(
+  strings: TemplateStringsArray,
+  ...values: (number | string)[]
+) {
+  return strings.reduce(
+    (path, part, index) =>
+      `${path}${index === 0 ? "" : encodeURIComponent(String(values[index - 1]))}${part}`,
+    "",
+  )
+}
+
+/**
+ * Converts public camelCase fields to documented Kit wire fields.
+ *
+ * @param value Public value.
+ * @param schema Provider wire schema.
+ */
+export function kitPublicToWire(
+  value: unknown,
+  schema: Record<string, unknown>,
+): Encodable {
+  return encodableSchema.parse(transformKitValue(value, schema, "toWire"))
+}
+
+/**
+ * Converts documented Kit wire fields to public camelCase fields.
+ *
+ * @param value Provider value.
+ * @param schema Provider wire schema.
+ */
+export function kitWireToPublic(
+  value: unknown,
+  schema: Record<string, unknown>,
+): Encodable {
+  return encodableSchema.parse(transformKitValue(value, schema, "toPublic"))
+}
+
+/**
+ * Returns the authorization header for a resolved Kit account.
+ *
+ * @param account Resolved Kit account.
+ * @throws When the connection method is unsupported.
+ */
+function getAuthorization(account: KitResolvedAccount): Record<string, string> {
+  if (account.connectionMethodId === "oauth") {
+    return {
+      Authorization: `Bearer ${KIT_OAUTH_SECRET_SCHEMA.parse(account.secret).accessToken}`,
+    } satisfies Record<string, string>
+  }
+  if (account.connectionMethodId === "api-key") {
+    return {
+      "X-Kit-Api-Key": KIT_API_KEY_SECRET_SCHEMA.parse(account.secret).apiKey,
+    } satisfies Record<string, string>
+  }
+  throw new Error(
+    `Unsupported Kit connection method: ${account.connectionMethodId}`,
+  )
+}
+
+/**
+ * Sends one guarded request to the Kit V4 API.
+ *
+ * @param authorization Authentication headers.
+ * @param path Provider-relative API path.
+ * @param options Request options.
+ */
+async function sendKitRequest(
+  authorization: Record<string, string>,
+  path: string,
+  options: KitRequestOptions,
+) {
+  const normalizedPath = path.replace(/^\/+/, "")
+  const url = new URL(normalizedPath, KIT_API_BASE_URL)
+  if (
+    !normalizedPath ||
+    normalizedPath.includes("://") ||
+    normalizedPath.includes("\\") ||
+    normalizedPath.includes("?") ||
+    normalizedPath.includes("#") ||
+    url.origin !== KIT_API_ORIGIN ||
+    !url.pathname.startsWith(new URL(KIT_API_BASE_URL).pathname)
+  ) {
+    throw new TypeError("Kit API paths must remain provider-relative.")
+  }
+
+  for (const [name, value] of Object.entries(options.query ?? {})) {
+    appendQuery(
+      url,
+      { explode: true, name, providerName: name, style: "form" },
+      value,
+    )
+  }
+  const response = await fetch(url, {
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    headers: {
+      Accept: "application/json",
+      ...authorization,
+      ...(options.body === undefined
+        ? {}
+        : { "Content-Type": "application/json" }),
+    },
+    method: options.method ?? "GET",
+    redirect: "error",
+  })
+  const parsed = await parseResponse(response)
+  if (!response.ok) {
+    const body = encodableSchema.safeParse(parsed)
+    throw new KitApiError({
+      ...(body.success && { body: body.data }),
+      retryAfter: response.headers.get("Retry-After") ?? undefined,
+      status: response.status,
+    })
+  }
+  return parsed
+}
+
+/**
+ * Appends one documented query parameter.
+ *
+ * @param url Mutable request URL.
+ * @param parameter Query parameter metadata.
+ * @param value Public parameter value.
+ */
+function appendQuery(url: URL, parameter: KitRuntimeParameter, value: unknown) {
+  if (value == null) return
+  if (Array.isArray(value)) {
+    if (parameter.style === "form" && parameter.explode) {
+      for (const item of value) {
+        url.searchParams.append(
+          parameter.providerName,
+          stringifyQueryValue(item),
+        )
+      }
+    } else {
+      url.searchParams.set(
+        parameter.providerName,
+        value.map(stringifyQueryValue).join(","),
+      )
+    }
+    return
+  }
+  url.searchParams.set(parameter.providerName, stringifyQueryValue(value))
+}
+
+/**
+ * Converts a query value to its wire representation.
+ *
+ * @param value Public query value.
+ * @throws When the value is not scalar.
+ */
+function stringifyQueryValue(value: unknown) {
+  if (
+    typeof value !== "boolean" &&
+    typeof value !== "number" &&
+    typeof value !== "string"
+  ) {
+    throw new TypeError("Kit query parameters must be scalar.")
+  }
+  return String(value)
+}
+
+/**
+ * Validates a flattened action query value.
+ *
+ * @param value Public action field.
+ * @throws When the value is not a scalar or scalar array.
+ */
+function parseQueryValue(
+  value: unknown,
+):
+  | boolean
+  | number
+  | string
+  | (boolean | number | string)[]
+  | null
+  | undefined {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  ) {
+    return value
+  }
+  if (
+    Array.isArray(value) &&
+    value.every(
+      (item) =>
+        typeof item === "boolean" ||
+        typeof item === "number" ||
+        typeof item === "string",
+    )
+  ) {
+    return value
+  }
+  throw new TypeError("Kit query parameters must be scalar or scalar arrays.")
+}
+
+/**
+ * Encodes one required path parameter.
+ *
+ * @param value Public path value.
+ * @param name Public parameter name.
+ * @throws When the path value is missing or invalid.
+ */
+function encodePathSegment(value: unknown, name: string) {
+  if (typeof value !== "number" && typeof value !== "string") {
+    throw new TypeError(`Kit path parameter ${name} is required.`)
+  }
+  return encodeURIComponent(String(value))
+}
+
+/**
+ * Recursively maps Kit fields between public and wire names.
+ *
+ * @param value Value to transform.
+ * @param schema Provider wire schema.
+ * @param direction Mapping direction.
+ */
+function transformKitValue(
+  value: unknown,
+  schema: Record<string, unknown>,
+  direction: "toPublic" | "toWire",
+): unknown {
+  const resolved = resolveWireSchema(schema)
+  if (Array.isArray(value)) {
+    const itemSchema = isRecord(resolved.items) ? resolved.items : {}
+    return value.map((item) => transformKitValue(item, itemSchema, direction))
+  }
+  if (!isRecord(value)) return value
+
+  const properties = collectWireProperties(resolved)
+  return Object.fromEntries(
+    Object.entries(value).map(([name, item]) => {
+      const providerName =
+        direction === "toPublic"
+          ? name
+          : (Object.keys(properties).find(
+              (candidate) => camelCase(candidate) === name,
+            ) ?? name)
+      const publicName =
+        direction === "toPublic" && providerName in properties
+          ? camelCase(providerName)
+          : name
+      const childSchemas = propertySchemas(resolved, providerName)
+      // Combine alternate provider shapes before recursively mapping nested keys.
+      const childSchema =
+        childSchemas.length === 0
+          ? {}
+          : childSchemas.length === 1
+            ? (childSchemas[0] ?? {})
+            : { anyOf: childSchemas }
+      return [
+        direction === "toPublic" ? publicName : providerName,
+        transformKitValue(item, childSchema, direction),
+      ]
+    }),
+  )
+}
+
+/**
+ * Collects schema properties across composition branches.
+ *
+ * @param schema Provider wire schema.
+ */
+function collectWireProperties(
+  schema: Record<string, unknown>,
+): Record<string, unknown> {
+  const resolved = resolveWireSchema(schema)
+  const properties: Record<string, unknown> = {}
+  return Object.assign(
+    properties,
+    isRecord(resolved.properties) ? resolved.properties : {},
+    ...schemaBranches(resolved).map(collectWireProperties),
+  )
+}
+
+/**
+ * Finds every schema declared for one provider field.
+ *
+ * @param schema Provider wire schema.
+ * @param providerName Provider field name.
+ */
+function propertySchemas(
+  schema: Record<string, unknown>,
+  providerName: string,
+): Record<string, unknown>[] {
+  const resolved = resolveWireSchema(schema)
+  // Inspect the direct declaration before recursively visiting composed branches.
+  const direct =
+    isRecord(resolved.properties) && isRecord(resolved.properties[providerName])
+      ? [resolved.properties[providerName]]
+      : []
+  return [
+    ...direct,
+    ...schemaBranches(resolved).flatMap((branch) =>
+      propertySchemas(branch, providerName),
+    ),
+  ]
+}
+
+/**
+ * Returns all composed schema branches.
+ *
+ * @param schema Provider wire schema.
+ */
+function schemaBranches(schema: Record<string, unknown>) {
+  return ["allOf", "anyOf", "oneOf"].flatMap((keyword) =>
+    Array.isArray(schema[keyword]) ? schema[keyword].filter(isRecord) : [],
+  )
+}
+
+/**
+ * Resolves a top-level provider component reference.
+ *
+ * @param schema Provider wire schema.
+ */
+function resolveWireSchema(schema: Record<string, unknown>) {
+  if (typeof schema.$ref !== "string") return schema
+  const name = /^#\/components\/schemas\/(.+)$/.exec(schema.$ref)?.[1]
+  return name ? (KIT_WIRE_DEFINITIONS[name] ?? schema) : schema
+}
+
+/**
+ * Parses a provider response without assuming JSON on errors.
+ *
+ * @param response Provider response.
+ */
+async function parseResponse(response: Response) {
+  const text = await response.text()
+  if (!text) return {}
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return { response: text }
+  }
+}
+
+/**
+ * Extracts Kit's documented error messages.
+ *
+ * @param value Parsed provider response.
+ */
+function getErrorMessage(value: Encodable | undefined) {
+  if (!isRecord(value)) return undefined
+  if (Array.isArray(value.errors)) {
+    const messages = value.errors.filter(
+      (item): item is string => typeof item === "string" && item.length > 0,
+    )
+    if (messages.length > 0) return messages.join("; ")
+  }
+  return typeof value.message === "string" && value.message
+    ? value.message
+    : undefined
+}
+
+/**
+ * Converts one provider snake_case field name to camelCase.
+ *
+ * @param value Provider field name.
+ */
+function camelCase(value: string) {
+  return value.replace(/_([a-z\d])/g, (_match, letter: string) =>
+    letter.toUpperCase(),
+  )
+}
+
+/**
+ * Narrows an unknown value to a record.
+ *
+ * @param value Candidate object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}