@zapier/zapier-sdk 0.4.1 → 0.5.0

package/src/api/debug.ts

@@ -31,7 +31,16 @@ export function createDebugFetch(options: {
 
     debugLog(`→ ${method} ${url}`, {
       headers: options?.headers,
-      body: options?.body ? JSON.parse(options.body as string) : undefined,
+      body:
+        options?.body && typeof options.body === "string"
+          ? (() => {
+              try {
+                return JSON.parse(options.body);
+              } catch {
+                return options.body;
+              }
+            })()
+          : options?.body,
     });
 
     try {

package/src/api/index.ts

@@ -15,9 +15,7 @@ export type {
   PollOptions,
   DebugLogger,
   // API Response Model Types
-  Integration,
   Action,
-  Trigger,
   Field,
   Choice,
   ActionExecutionResult,

package/src/api/polling.ts

@@ -5,6 +5,8 @@
  * with configurable retry logic and exponential backoff.
  */
 
+import { ZapierTimeoutError, ZapierApiError } from "../types/errors";
+
 export async function pollUntilComplete(options: {
   fetchPoll: () => Promise<Response>;
   maxAttempts?: number;
@@ -25,28 +27,47 @@ export async function pollUntilComplete(options: {
   } = options;
 
   let delay = initialDelay;
+  let errorCount = 0;
 
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     const response = await fetchPoll();
 
     if (response.status === successStatus) {
-      // Success - extract and return results
+      // Success - reset error count and return results
+      errorCount = 0;
       const result = await response.json();
       return resultExtractor(result);
     } else if (response.status === pendingStatus) {
-      // Still processing - wait and retry
+      // Still processing - reset error count and wait and retry
+      errorCount = 0;
       if (attempt < maxAttempts - 1) {
         await new Promise((resolve) => setTimeout(resolve, delay));
         delay = Math.min(delay * 2, maxDelay); // Exponential backoff
         continue;
       }
     } else {
-      // Error occurred
-      throw new Error(
-        `Poll request failed: ${response.status} ${response.statusText}`,
-      );
+      // Error occurred - increment error count
+      errorCount++;
+
+      if (errorCount >= 3) {
+        // Too many consecutive errors, fail
+        throw new ZapierApiError(
+          `Poll request failed: ${response.status} ${response.statusText}`,
+          { statusCode: response.status },
+        );
+      }
+
+      // Treat as pending for up to 3 errors - wait and retry
+      if (attempt < maxAttempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * 2, maxDelay); // Exponential backoff
+        continue;
+      }
     }
   }
 
-  throw new Error(`Operation timed out after ${maxAttempts} attempts`);
+  throw new ZapierTimeoutError(
+    `Operation timed out after ${maxAttempts} attempts`,
+    { attempts: maxAttempts, maxAttempts: maxAttempts },
+  );
 }

package/src/api/schemas.ts

@@ -0,0 +1,387 @@
+import { z } from "zod";
+
+/**
+ * Base Zod schemas for API response models.
+ * These schemas represent the raw data structures returned by Zapier API endpoints.
+ * All TypeScript types in api/types.ts are inferred from these schemas.
+ */
+
+// ============================================================================
+// Basic Building Block Schemas
+// ============================================================================
+
+export const NeedChoicesSchema = z.object({
+  key: z.string().optional(),
+  label: z.string().optional(),
+  sample: z.string().optional(),
+  value: z.string().optional(),
+});
+
+export const NeedSchema = z.object({
+  key: z.string(),
+  alters_custom_fields: z.boolean().nullable().optional(),
+  capabilities: z.array(z.string()).optional(),
+  choices: z.array(NeedChoicesSchema).optional(),
+  computed: z.boolean().nullable().optional(),
+  custom_field: z.boolean().optional(),
+  default: z.string().optional(),
+  depends_on: z.array(z.string()).optional(),
+  format: z.literal("SELECT").optional(),
+  from_search: z.boolean().optional(),
+  from_write: z.boolean().optional(),
+  help_text: z.string().optional(),
+  help_text_html: z.string().optional(),
+  input_format: z.array(z.string()).optional(),
+  label: z.string().optional(),
+  language: z.string().optional(),
+  parent_key: z.string().optional(),
+  placeholder: z.string().optional(),
+  prefill: z.string().optional(),
+  required: z.boolean().optional(),
+  searchfill: z.string().optional(),
+  send_in_json: z.boolean().optional(),
+  regex: z.string().optional(),
+  type: z
+    .enum([
+      "integer",
+      "string",
+      "text",
+      "datetime",
+      "boolean",
+      "file",
+      "decimal",
+      "copy",
+      "password",
+      "dict",
+      "code",
+      "filter",
+      "json",
+    ])
+    .optional(),
+  list: z.boolean().optional(),
+});
+
+export const ActionLinksSchema = z.object({
+  action_url: z.string().optional(),
+});
+
+export const ActionPermissionsSchema = z.object({
+  can_use: z.boolean().optional(),
+});
+
+export const ActionSchema = z.object({
+  id: z.string().optional(),
+  type: z.enum([
+    "filter",
+    "read",
+    "read_bulk",
+    "run",
+    "search",
+    "search_and_write",
+    "search_or_write",
+    "write",
+  ]),
+  key: z.string(),
+  name: z.string(),
+  noun: z.string().optional(),
+  description: z.string(),
+  description_html: z.string().optional(),
+  is_important: z.boolean().optional(),
+  is_hidden: z.boolean().optional(),
+  needs: z.array(NeedSchema).optional(),
+  meta: z.string().optional(),
+  selected_api: z.string().optional(),
+  links: ActionLinksSchema.optional(),
+  permissions: ActionPermissionsSchema.optional(),
+});
+
+export const ChoiceSchema = z.object({
+  value: z.union([z.string(), z.number()]),
+  label: z.string(),
+});
+
+export const FieldSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  type: z.enum([
+    "string",
+    "number",
+    "boolean",
+    "datetime",
+    "file",
+    "object",
+    "array",
+  ]),
+  required: z.boolean(),
+  description: z.string().optional(),
+  choices: z.array(ChoiceSchema).optional(),
+});
+
+export const ActionExecutionResultSchema = z.object({
+  data: z.array(z.any()),
+});
+
+export const ActionFieldChoiceSchema = z.object({
+  value: z.union([z.string(), z.number()]),
+  label: z.string(),
+});
+
+export const ActionFieldSchema = z.object({
+  key: z.string(),
+  label: z.string().optional(),
+  required: z.boolean(),
+  type: z.string().optional(),
+  helpText: z.string().optional(),
+  helpTextHtml: z.string().optional(),
+  choices: z.array(ActionFieldChoiceSchema).optional(),
+  default: z.string().optional(),
+  placeholder: z.string().optional(),
+  computed: z.boolean().optional(),
+  customField: z.boolean().optional(),
+  dependsOn: z.array(z.string()).optional(),
+  format: z.string().optional(),
+  inputFormat: z.array(z.string()).optional(),
+});
+
+// ============================================================================
+// Main API Entity Schemas
+// ============================================================================
+
+export const AuthenticationSchema = z.object({
+  id: z.number(),
+  date: z.string(),
+  lastchanged: z.string().optional(),
+  account_id: z.number(),
+  customuser_id: z.number().optional(),
+  selected_api: z.string(),
+  destination_selected_api: z.string().nullable().optional(),
+  is_invite_only: z.boolean(),
+  is_private: z.boolean(),
+  shared_with_all: z.boolean(),
+  is_stale: z.string().optional(),
+  is_shared: z.string().optional(),
+  marked_stale_at: z.string().nullable().optional(),
+  label: z.string().nullable().optional(),
+  identifier: z.string().nullable().optional(),
+  title: z.string().nullable().optional(),
+  url: z.string().optional(),
+  groups: z.string().optional(),
+  members: z.string().optional(),
+  permissions: z.record(z.boolean()).optional(),
+});
+
+export const AuthenticationsResponseSchema = z.object({
+  count: z.number(),
+  next: z.string().nullable().optional(),
+  previous: z.string().nullable().optional(),
+  results: z.array(AuthenticationSchema),
+});
+
+export const UserProfileSchema = z.object({
+  id: z.number(),
+  code: z.string(),
+  user_id: z.number(),
+  auto_provisioned: z.boolean(),
+  first_name: z.string(),
+  last_name: z.string(),
+  username: z.string(),
+  personas: z.string(),
+  user_generated_personas: z.string(),
+  last_login: z.string(),
+  email: z.string(),
+  email_hash: z.string(),
+  email_confirmed: z.boolean(),
+  timezone: z.string(),
+  photo_url: z.string(),
+  has_seen_notifications: z.record(z.boolean().nullable()),
+  signup: z.string(),
+  since_signup: z.string(),
+  has_activated: z.boolean(),
+  enable_gz_creator: z.boolean(),
+  should_see_nps_survey: z.boolean(),
+  is_developer: z.boolean(),
+  is_expert: z.boolean(),
+  tos_agreement: z.boolean(),
+  should_renew_tos: z.boolean(),
+  is_gdpr_consented: z.boolean(),
+  disable_ssl_check: z.boolean(),
+  identity: z.number(),
+  summary_schedule: z.string(),
+  alert_triggers: z.string(),
+  alert_actions: z.string(),
+  is_staff: z.boolean(),
+  is_zt_reviewer: z.boolean(),
+  is_high_value: z.boolean(),
+  is_temporary: z.boolean(),
+  banner_message: z.string(),
+  enable_totp_2fa: z.boolean(),
+  viewed_help: z.record(z.boolean()),
+  show_editor_migration_mesaging: z.boolean(),
+  switches: z.record(z.any()),
+  organizations: z.array(z.any().nullable()),
+  primary_organization: z.any().nullable(),
+  has_active_zaps: z.boolean(),
+  has_google_sso: z.boolean(),
+  auth_realm: z.string(),
+  roles: z.array(
+    z.object({
+      account_id: z.number(),
+      role: z.string(),
+    }),
+  ),
+});
+
+export const AppSchema = z.object({
+  age_in_days: z.string().optional(),
+  api_docs_url: z.string().nullable().optional(),
+  app_profile_url: z.string(),
+  banner: z.string().optional(),
+  categories: z.array(z.any()).optional(), // TODO: Define proper service_category type
+  canonical_id: z.string().optional(),
+  current_implementation_id: z.string(),
+  days_since_last_update: z.string().optional(),
+  description: z.string(),
+  external_url: z.string(),
+  hashtag: z.string().optional(),
+  id: z.number().optional(),
+  image: z.string().optional(),
+  images: z.string().optional(),
+  integration_overview_html: z.string().nullable().optional(),
+  internal_id: z.string(),
+  invite_url: z.string().nullable().optional(),
+  is_beta: z.string().optional(),
+  is_built_in: z.string().optional(),
+  is_featured: z.string().optional(),
+  is_premium: z.boolean().optional(),
+  is_public: z.string().optional(),
+  is_upcoming: z.string().optional(),
+  learn_more_url: z.string(),
+  name: z.string(),
+  popularity: z.number(),
+  primary_color: z.string(),
+  request_count: z.string().optional(),
+  slug: z.string(),
+  zap_usage_count: z.number().nullable().optional(),
+});
+
+export const ServiceSchema = z.object({
+  id: z.number().optional(),
+  canonical_id: z.string().optional(),
+  current_implementation_id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  app_url: z.string().optional(),
+  learn_more_url: z.string().optional(),
+  description: z.string(),
+  primary_color: z.string(),
+  popularity: z.number(),
+  image: z.string().optional(),
+  images: z.string().optional(),
+});
+
+export const ServicesResponseSchema = z.object({
+  results: z.array(ServiceSchema),
+  next: z.string().nullable().optional(),
+  previous: z.string().nullable().optional(),
+});
+
+// ============================================================================
+// Request/Response Schemas
+// ============================================================================
+
+export const NeedsRequestSchema = z.object({
+  selected_api: z.string(),
+  action: z.string(),
+  type_of: z.string(),
+  authentication_id: z.number().optional(),
+  params: z.record(z.any()).optional(),
+});
+
+export const NeedsResponseSchema = z.object({
+  success: z.boolean(),
+  needs: z.array(NeedSchema).optional(),
+  errors: z.array(z.string()).optional(),
+  last_fetched_at: z.string().optional(),
+});
+
+// ============================================================================
+// Implementation Schema
+// ============================================================================
+
+export const ImplementationSchema = z.object({
+  selected_api: z.string(),
+  app_id: z.number().optional(),
+  auth_type: z.string().optional(),
+  auth_fields: z.string().optional(),
+  actions: z.array(ActionSchema).optional(),
+  is_deprecated: z.boolean().optional(),
+  is_private_only: z.boolean().optional(),
+  is_invite_only: z.boolean().optional(),
+  is_beta: z.boolean().optional().default(false),
+  is_premium: z.boolean().optional().default(false),
+  is_hidden: z.string().optional(),
+  name: z.string().optional(),
+  slug: z.string().optional(),
+  images: z.record(z.string().nullable()).optional(),
+  primary_color: z.string().optional(),
+  secondary_color: z.string().optional(),
+  current_implementation: z.string().optional(),
+  other_implementations: z.string().optional(),
+});
+
+export const ImplementationsResponseSchema = z.object({
+  count: z.number(),
+  next: z.string().nullable().optional(),
+  previous: z.string().nullable().optional(),
+  results: z.array(ImplementationSchema),
+});
+
+// ============================================================================
+// Lightweight Implementation Meta Schema
+// ============================================================================
+
+export const ImplementationMetaSchema = z.object({
+  id: z.string(), // e.g. "ZapierFormatterCLIAPI@1.0.7"
+  name: z.string(),
+  slug: z.string(),
+  images: z
+    .object({
+      url_16x16: z.string().optional(),
+      url_32x32: z.string().optional(),
+      url_64x64: z.string().optional(),
+      url_128x128: z.string().optional(),
+    })
+    .optional(),
+  // Include other fields for completeness but we'll only use what we need
+  ageInDays: z.union([z.string(), z.number()]).optional(),
+  authType: z.string().nullable().optional(),
+  banner: z.string().optional(),
+  categories: z
+    .array(
+      z.object({
+        id: z.number(),
+        name: z.string(),
+        slug: z.string(),
+      }),
+    )
+    .optional(),
+  isBeta: z.boolean().optional(),
+  isBuiltIn: z.boolean().optional(),
+  isDeprecated: z.boolean().optional(),
+  isFeatured: z.boolean().optional(),
+  isHidden: z.boolean().optional(),
+  isInvite: z.boolean().optional(),
+  isPremium: z.boolean().optional(),
+  isPublic: z.boolean().optional(),
+  isUpcoming: z.boolean().optional(),
+  popularity: z.number().optional(),
+  apiDocsUrl: z.string().optional(),
+  classification: z.string().optional(),
+});
+
+export const ImplementationsMetaResponseSchema = z.object({
+  count: z.number(),
+  next: z.string().nullable().optional(),
+  previous: z.string().nullable().optional(),
+  results: z.array(ImplementationMetaSchema),
+});

package/src/api/types.ts

@@ -4,8 +4,37 @@
  * This module contains all type definitions related to the Zapier API client,
  * including configuration options, client interfaces, request/response types,
  * and API response models.
+ *
+ * API response model types are inferred from Zod schemas defined in api/schemas.ts
+ * to ensure a single source of truth and eliminate duplication.
  */
 
+import { z } from "zod";
+import {
+  NeedChoicesSchema,
+  NeedSchema,
+  ActionLinksSchema,
+  ActionPermissionsSchema,
+  ActionSchema,
+  ChoiceSchema,
+  FieldSchema,
+  ActionExecutionResultSchema,
+  ActionFieldChoiceSchema,
+  ActionFieldSchema,
+  AuthenticationSchema,
+  AuthenticationsResponseSchema,
+  UserProfileSchema,
+  AppSchema,
+  NeedsRequestSchema,
+  NeedsResponseSchema,
+  ImplementationSchema,
+  ImplementationsResponseSchema,
+  ImplementationMetaSchema,
+  ImplementationsMetaResponseSchema,
+  ServiceSchema,
+  ServicesResponseSchema,
+} from "./schemas";
+
 // ============================================================================
 // API Client Infrastructure Types
 // ============================================================================
@@ -38,7 +67,11 @@ export interface RequestOptions {
   headers?: Record<string, string>;
   searchParams?: Record<string, string>;
   authRequired?: boolean;
-  customErrorHandler?: (response: Response) => Error | undefined;
+  customErrorHandler?: (errorInfo: {
+    status: number;
+    statusText: string;
+    data: any;
+  }) => Error | undefined;
 }
 
 export interface PollOptions extends RequestOptions {
@@ -55,140 +88,43 @@ export interface DebugLogger {
 }
 
 // ============================================================================
-// API Response Models
+// API Response Models (inferred from Zod schemas)
 // ============================================================================
 
-export interface Integration {
-  key: string;
-  name: string;
-  description: string;
-  version: string;
-  category?: string;
-  actions: Action[];
-  triggers: Trigger[];
-  current_implementation_id?: string;
-}
-
-export interface Action {
-  key: string;
-  name: string;
-  description: string;
-  appKey: string;
-  type:
-    | "read"
-    | "read_bulk"
-    | "write"
-    | "run"
-    | "search"
-    | "search_or_write"
-    | "search_and_write"
-    | "filter";
-  inputFields: Field[];
-  outputFields: Field[];
-}
-
-export interface Trigger {
-  key: string;
-  name: string;
-  description: string;
-  appKey: string;
-  type: "instant" | "polling" | "webhook";
-  outputFields: Field[];
-}
-
-export interface Field {
-  key: string;
-  label: string;
-  type:
-    | "string"
-    | "number"
-    | "boolean"
-    | "datetime"
-    | "file"
-    | "object"
-    | "array";
-  required: boolean;
-  description?: string;
-  choices?: Choice[];
-}
-
-export interface Choice {
-  value: string | number;
-  label: string;
-}
-
-export interface ActionExecutionResult {
-  success: boolean;
-  data?: any;
-  error?: string;
-  metadata?: {
-    executionTime?: number;
-    requestId?: string;
-  };
-}
-
-export interface ActionField {
-  key: string;
-  label?: string;
-  required: boolean;
-  type?: string;
-  helpText?: string;
-  helpTextHtml?: string;
-  choices?: ActionFieldChoice[];
-  default?: string;
-  placeholder?: string;
-  computed?: boolean;
-  customField?: boolean;
-  dependsOn?: string[];
-  format?: string;
-  inputFormat?: string[];
-}
-
-export interface ActionFieldChoice {
-  value: string | number;
-  label: string;
-}
-
-export interface NeedsRequest {
-  selected_api: string;
-  action: string;
-  type_of: string;
-  authentication_id?: number;
-  params?: Record<string, any>;
-}
-
-export interface NeedsResponse {
-  success: boolean;
-  needs?: ActionField[];
-  errors?: string[];
-}
-
-export interface Authentication {
-  id: number;
-  date: string;
-  lastchanged?: string;
-  account_id: number;
-  customuser_id?: number;
-  selected_api: string;
-  destination_selected_api?: string | null;
-  is_invite_only: boolean;
-  is_private: boolean;
-  shared_with_all: boolean;
-  is_stale?: string;
-  is_shared?: string;
-  marked_stale_at?: string | null;
-  label?: string | null;
-  identifier?: string | null;
-  title?: string | null;
-  url?: string;
-  groups?: string;
-  members?: string;
-  permissions?: Record<string, boolean>;
-}
-
-export interface AuthenticationsResponse {
-  count: number;
-  next?: string | null;
-  previous?: string | null;
-  results: Authentication[];
-}
+// Basic building blocks
+export type NeedChoices = z.infer<typeof NeedChoicesSchema>;
+export type Need = z.infer<typeof NeedSchema>;
+export type ActionLinks = z.infer<typeof ActionLinksSchema>;
+export type ActionPermissions = z.infer<typeof ActionPermissionsSchema>;
+export type Action = z.infer<typeof ActionSchema>;
+export type Choice = z.infer<typeof ChoiceSchema>;
+export type Field = z.infer<typeof FieldSchema>;
+export type ActionExecutionResult = z.infer<typeof ActionExecutionResultSchema>;
+export type ActionFieldChoice = z.infer<typeof ActionFieldChoiceSchema>;
+export type ActionField = z.infer<typeof ActionFieldSchema>;
+
+// Main API entities
+export type Authentication = z.infer<typeof AuthenticationSchema>;
+export type AuthenticationsResponse = z.infer<
+  typeof AuthenticationsResponseSchema
+>;
+export type UserProfile = z.infer<typeof UserProfileSchema>;
+export type App = z.infer<typeof AppSchema>;
+export type Service = z.infer<typeof ServiceSchema>;
+export type ServicesResponse = z.infer<typeof ServicesResponseSchema>;
+
+// Request/Response types
+export type NeedsRequest = z.infer<typeof NeedsRequestSchema>;
+export type NeedsResponse = z.infer<typeof NeedsResponseSchema>;
+
+// Implementation types
+export type Implementation = z.infer<typeof ImplementationSchema>;
+export type ImplementationsResponse = z.infer<
+  typeof ImplementationsResponseSchema
+>;
+
+// Implementation Meta types (lightweight)
+export type ImplementationMeta = z.infer<typeof ImplementationMetaSchema>;
+export type ImplementationsMetaResponse = z.infer<
+  typeof ImplementationsMetaResponseSchema
+>;