@automate.ax/integration-contracts 0.93.1 → 0.95.0

package/src/close/schemas.ts

@@ -241,7 +241,7 @@ const CLOSE_TASK_FIELDS = {
   dueDate: NULLABLE_DATE_SCHEMA.optional(),
   id: z.string(),
   isComplete: z.boolean(),
-  isDateless: z.boolean().optional(),
+  isDateless: z.boolean().nullable().optional(),
   leadId: z.string().nullable(),
   leadName: z.string().nullable().optional(),
   objectId: z.string().nullable().optional(),

package/src/jobnimbus/api.ts

@@ -44,6 +44,7 @@ interface JobNimbusRequestOptions<TSchema extends z.ZodType> {
 /** Error returned by a rejected JobNimbus API request. */
 export class JobNimbusApiError extends Error {
   readonly details: Encodable
+  readonly retryAfter?: string
   readonly status: number
 
   /**
@@ -51,11 +52,13 @@ export class JobNimbusApiError extends Error {
    *
    * @param status - HTTP response status.
    * @param details - Codec-safe response details.
+   * @param retryAfter - Raw provider retry timing, when present.
    */
-  constructor(status: number, details: Encodable) {
+  constructor(status: number, details: Encodable, retryAfter?: string) {
     super(`JobNimbus API request failed (${status}).`)
     this.name = "JobNimbusApiError"
     this.details = details
+    this.retryAfter = retryAfter
     this.status = status
   }
 }
@@ -139,6 +142,7 @@ export function getJobNimbusApi(secret: unknown, api: JobNimbusApi) {
         throw new JobNimbusApiError(
           response.status,
           parsed.success ? parsed.data : { response: text },
+          response.headers.get("Retry-After") ?? undefined,
         )
       }
       return options.responseSchema.parse(parsed.data)
@@ -162,9 +166,11 @@ export async function downloadJobNimbusFile(secret: unknown, fileId: string) {
     { headers: { Authorization: `Bearer ${apiKey}` } },
   )
   if (!response.ok) {
-    throw new JobNimbusApiError(response.status, {
-      response: await response.text(),
-    })
+    throw new JobNimbusApiError(
+      response.status,
+      { response: await response.text() },
+      response.headers.get("Retry-After") ?? undefined,
+    )
   }
   return response.blob()
 }

package/src/trello/api.ts

@@ -7,6 +7,7 @@ const TRELLO_SECRET_SCHEMA = z.object({
   token: z.string().min(1),
 })
 const TRELLO_ERROR_SCHEMA = z.looseObject({
+  error: z.string().optional(),
   message: z.string().optional(),
 })
 
@@ -15,7 +16,7 @@ type TrelloQueryValue = boolean | number | string | undefined
 
 /** Options for one authenticated Trello REST request. */
 export interface TrelloRequestOptions<TSchema extends z.ZodType> {
-  /** JSON request body for endpoints that accept one. */
+  /** JSON or multipart request body for endpoints that accept one. */
   body?: unknown
 
   /** HTTP verb. Defaults to `GET`. */
@@ -44,9 +45,15 @@ export interface TrelloApi {
 
 /** Structured Trello REST request error. */
 export class TrelloApiError extends Error {
+  /** Provider error code, or an HTTP fallback code. */
+  readonly code: string
+
   /** Provider error body, when Trello returned text. */
   readonly providerMessage?: string
 
+  /** Rate-limit budget returned with the failed request. */
+  readonly rateLimit?: TrelloRateLimitMetadata
+
   /** Retry delay from Trello's `Retry-After` header, in seconds. */
   readonly retryAfter?: number
 
@@ -57,12 +64,16 @@ export class TrelloApiError extends Error {
    * Creates a structured Trello API error.
    *
    * @param options - Provider and transport error details.
+   * @param options.code - Provider error code or HTTP fallback.
    * @param options.providerMessage - Provider error body.
+   * @param options.rateLimit - Provider rate-limit budget.
    * @param options.retryAfter - Retry delay in seconds.
    * @param options.status - HTTP response status.
    */
   constructor(options: {
+    code: string
     providerMessage?: string
+    rateLimit?: TrelloRateLimitMetadata
     retryAfter?: number
     status: number
   }) {
@@ -72,12 +83,35 @@ export class TrelloApiError extends Error {
         : `Trello API request failed with status ${options.status}.`,
     )
     this.name = "TrelloApiError"
+    this.code = options.code
     this.providerMessage = options.providerMessage
+    this.rateLimit = options.rateLimit
     this.retryAfter = options.retryAfter
     this.status = options.status
   }
 }
 
+/** One Trello key or token request budget. */
+export interface TrelloRateLimitBudget {
+  /** Length of the provider budget window in milliseconds. */
+  intervalMs: number
+
+  /** Maximum requests in the provider budget window. */
+  max: number
+
+  /** Requests remaining in the current provider budget window. */
+  remaining: number
+}
+
+/** Rate-limit budgets returned by Trello response headers. */
+export interface TrelloRateLimitMetadata {
+  /** Shared API-key request budget. */
+  apiKey?: TrelloRateLimitBudget
+
+  /** Connected user-token request budget. */
+  apiToken?: TrelloRateLimitBudget
+}
+
 /**
  * Creates a raw authenticated Trello REST helper.
  *
@@ -102,12 +136,17 @@ export function getTrelloApi(secret: Record<string, unknown>): TrelloApi {
       url.searchParams.set("key", apiKey)
       url.searchParams.set("token", token)
 
+      const isMultipart = options.body instanceof FormData
       const headers = new Headers({ Accept: "application/json" })
-      if (options.body !== undefined)
+      if (options.body !== undefined && !isMultipart)
         headers.set("Content-Type", "application/json")
       const response = await fetch(url, {
         body:
-          options.body === undefined ? undefined : JSON.stringify(options.body),
+          options.body === undefined
+            ? undefined
+            : options.body instanceof FormData
+              ? options.body
+              : JSON.stringify(options.body),
         headers,
         method: options.method ?? "GET",
       })
@@ -115,10 +154,15 @@ export function getTrelloApi(secret: Record<string, unknown>): TrelloApi {
         const responseText = await response.text()
         const error = TRELLO_ERROR_SCHEMA.safeParse(parseJson(responseText))
         throw new TrelloApiError({
+          code:
+            error.success && error.data.error
+              ? error.data.error
+              : `http_${response.status}`,
           providerMessage:
             error.success && error.data.message
               ? error.data.message
               : responseText || undefined,
+          rateLimit: parseRateLimitMetadata(response.headers),
           retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
           status: response.status,
         })
@@ -128,6 +172,40 @@ export function getTrelloApi(secret: Record<string, unknown>): TrelloApi {
   }
 }
 
+/**
+ * Parses Trello's key and token request budgets from response headers.
+ *
+ * @param headers - Provider response headers.
+ */
+function parseRateLimitMetadata(headers: Headers) {
+  const apiKey = parseRateLimitBudget(headers, "api-key")
+  const apiToken = parseRateLimitBudget(headers, "api-token")
+  if (!apiKey && !apiToken) return undefined
+  return { apiKey, apiToken } satisfies TrelloRateLimitMetadata
+}
+
+/**
+ * Parses one complete Trello request budget.
+ *
+ * @param headers - Provider response headers.
+ * @param budget - Provider budget header prefix.
+ */
+function parseRateLimitBudget(
+  headers: Headers,
+  budget: "api-key" | "api-token",
+) {
+  const intervalMs = parseFiniteNumber(
+    headers.get(`x-rate-limit-${budget}-interval-ms`),
+  )
+  const max = parseFiniteNumber(headers.get(`x-rate-limit-${budget}-max`))
+  const remaining = parseFiniteNumber(
+    headers.get(`x-rate-limit-${budget}-remaining`),
+  )
+  if (intervalMs === undefined || max === undefined || remaining === undefined)
+    return undefined
+  return { intervalMs, max, remaining } satisfies TrelloRateLimitBudget
+}
+
 /**
  * Accepts a raw card ID, short link, or standard Trello card URL.
  *
@@ -184,7 +262,16 @@ function parseJson(value: string): unknown {
  * @param value - Raw `Retry-After` header.
  */
 function parseRetryAfter(value: string | null) {
+  return parseFiniteNumber(value)
+}
+
+/**
+ * Parses one finite numeric response header.
+ *
+ * @param value - Raw response header value.
+ */
+function parseFiniteNumber(value: string | null) {
   if (value === null) return undefined
-  const seconds = Number(value)
-  return Number.isFinite(seconds) ? seconds : undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
 }