@zapier/zapier-sdk 0.13.6 → 0.13.8

package/src/api/polling.ts

@@ -1,253 +0,0 @@
-/**
- * Polling Utilities
- *
- * This module provides utilities for polling HTTP endpoints until completion,
- * with configurable retry logic and exponential backoff.
- */
-
-import {
-  ZapierTimeoutError,
-  ZapierApiError,
-  ZapierValidationError,
-} from "../types/errors";
-import { setTimeout } from "timers/promises";
-
-// Constants
-const DEFAULT_TIMEOUT_MS = 180_000;
-const DEFAULT_SUCCESS_STATUS = 200;
-const DEFAULT_PENDING_STATUS = 202;
-const DEFAULT_INITIAL_DELAY_MS = 50;
-const DEFAULT_MAX_POLLING_INTERVAL_MS = 10_000;
-const MAX_CONSECUTIVE_ERRORS = 3;
-const MAX_TIMEOUT_BUFFER_MS = 10_000;
-const BASE_ERROR_BACKOFF_MS = 1_000;
-const JITTER_FACTOR = 0.5;
-
-// Polling stages: [threshold_ms, interval_ms]
-// Note: These are default stages, actual hard timeout is enforced separately below
-const DEFAULT_POLLING_STAGES = [
-  [125, 125], // Up to 125ms: poll every 125ms
-  [375, 250], // Up to 375ms: poll every 250ms
-  [875, 500], // Up to 875ms: poll every 500ms
-  [10_000, 1_000], // Up to 10s: poll every 1s
-  [30_000, 2_500], // Up to 30s: poll every 2.5s
-  [60_000, 5_000], // Up to 60s: poll every 5s
-] as const satisfies Array<[number, number]>;
-
-/**
- * Options for the polling function
- */
-export interface PollOptions<TResult = unknown> {
-  /** Function that performs the HTTP request */
-  fetchPoll: () => Promise<Response>;
-  /** Maximum time to wait for completion (in milliseconds) */
-  timeoutMs?: number;
-  /** HTTP status code indicating successful completion */
-  successStatus?: number;
-  /** HTTP status code indicating the operation is still pending */
-  pendingStatus?: number;
-  /** Function to extract the result from the response */
-  resultExtractor?: (response: unknown) => TResult;
-  /** Initial delay before the first poll attempt (in milliseconds) */
-  initialDelay?: number;
-}
-
-const enum PollStatus {
-  Success = "success",
-  Continue = "continue",
-}
-
-/**
- * Result of a poll operation
- */
-export type PollResult<TResult = unknown> = {
-  result?: TResult;
-  status: PollStatus;
-  errorCount: number;
-};
-
-// Helper to calculate wait time with jitter and error backoff
-const calculateWaitTime = (
-  baseInterval: number,
-  errorCount: number,
-): number => {
-  // Jitter to avoid thundering herd
-  const jitter = Math.random() * JITTER_FACTOR * baseInterval;
-  // More backoff added if errors are seen
-  const errorBackoff = Math.min(
-    BASE_ERROR_BACKOFF_MS * (errorCount / 2),
-    baseInterval * 2, // Cap error backoff at 2x the base interval
-  );
-  return Math.floor(baseInterval + jitter + errorBackoff);
-};
-
-const processResponse = async <TResult = unknown>(
-  response: Response,
-  successStatus: number,
-  pendingStatus: number,
-  resultExtractor: (response: unknown) => TResult,
-  errorCount: number,
-): Promise<PollResult<TResult>> => {
-  // Handle other error responses
-  if (!response.ok) {
-    return {
-      status: PollStatus.Continue,
-      // If for some reason the status is pending, we don't want to increment the error count
-      errorCount:
-        response.status === pendingStatus ? errorCount : errorCount + 1,
-    };
-  }
-
-  // Check for successful completion
-  if (response.status === successStatus) {
-    try {
-      const resultJson = await response.json();
-      return {
-        result: resultExtractor(resultJson),
-        status: PollStatus.Success,
-        errorCount: 0,
-      };
-    } catch (error) {
-      throw new ZapierApiError(
-        "Result extractor failed to parse successful response as JSON",
-        {
-          statusCode: response.status,
-          cause: error,
-        },
-      );
-    }
-  }
-
-  // If it's not pending, it's unexpected
-  if (response.status !== pendingStatus) {
-    throw new ZapierApiError(
-      `Unexpected response status during polling: ${response.status}`,
-      {
-        statusCode: response.status,
-      },
-    );
-  }
-
-  // It's still pending, so we continue polling
-  return {
-    status: PollStatus.Continue,
-    errorCount: 0,
-  };
-};
-
-/**
- * Polls an endpoint until completion, timeout, or error
- * @param options Configuration options for polling
- * @returns The extracted result from the successful response
- * @throws {ZapierValidationError} When the input parameters are invalid
- * @throws {ZapierTimeoutError} When the operation times out
- * @throws {ZapierApiError} When the API returns consecutive errors
- */
-export async function pollUntilComplete<TResult = unknown>(
-  options: PollOptions<TResult>,
-): Promise<TResult> {
-  const {
-    fetchPoll,
-    timeoutMs = DEFAULT_TIMEOUT_MS,
-    initialDelay = DEFAULT_INITIAL_DELAY_MS,
-    successStatus = DEFAULT_SUCCESS_STATUS,
-    pendingStatus = DEFAULT_PENDING_STATUS,
-    resultExtractor = (response) => response as TResult,
-  } = options;
-
-  // Validate input parameters
-  if (timeoutMs <= 0) {
-    throw new ZapierValidationError("Timeout must be greater than 0", {
-      details: { timeoutMs },
-    });
-  }
-
-  if (initialDelay < 0) {
-    throw new ZapierValidationError("Initial delay must be non-negative", {
-      details: { initialDelay },
-    });
-  }
-
-  const startTime = Date.now();
-  let attempts = 0;
-  let errorCount = 0;
-
-  // Build polling stages with the actual timeout appended
-  const pollingStages = [
-    ...DEFAULT_POLLING_STAGES,
-    [timeoutMs + MAX_TIMEOUT_BUFFER_MS, DEFAULT_MAX_POLLING_INTERVAL_MS], // Up to timeout + 10s: poll every 10s
-  ] as const satisfies Array<[number, number]>;
-
-  // Apply initial delay if specified
-  if (initialDelay > 0) {
-    await setTimeout(initialDelay);
-  }
-
-  while (true) {
-    attempts++;
-    const elapsedTime = Date.now() - startTime;
-
-    // Find the current polling stage
-    const pollingInterval = pollingStages.find(
-      ([maxTimeForStage, _interval]) => {
-        return elapsedTime < maxTimeForStage;
-      },
-    );
-
-    // If there isn't a current stage, throw timeout error
-    if (!pollingInterval) {
-      throw new ZapierTimeoutError(
-        `Operation timed out after ${Math.floor(elapsedTime / 1000)}s (${attempts} attempts)`,
-        {
-          attempts,
-        },
-      );
-    }
-
-    // Wait before polling (except on first attempt)
-    if (attempts > 1) {
-      const waitTime = calculateWaitTime(pollingInterval[1], errorCount);
-      await setTimeout(waitTime);
-    }
-
-    // Perform the poll request
-    try {
-      const response = await fetchPoll();
-      const {
-        result,
-        errorCount: newErrorCount,
-        status,
-      } = await processResponse<TResult>(
-        response,
-        successStatus,
-        pendingStatus,
-        resultExtractor,
-        errorCount,
-      );
-      errorCount = newErrorCount;
-
-      if (status === PollStatus.Success) {
-        return result as TResult;
-      }
-
-      if (errorCount >= MAX_CONSECUTIVE_ERRORS) {
-        // Too many consecutive errors, fail
-        throw new ZapierApiError(
-          `Poll request failed: ${response.status} ${response.statusText}`,
-          { statusCode: response.status },
-        );
-      }
-    } catch (error) {
-      errorCount++;
-      if (errorCount >= MAX_CONSECUTIVE_ERRORS) {
-        throw new ZapierApiError(
-          `Failed to poll after ${errorCount} consecutive errors: ${error instanceof Error ? error.message : String(error)}`,
-          {
-            cause: error,
-          },
-        );
-      }
-    }
-    // Continue polling if status is pending
-  }
-}

package/src/api/schemas.ts

@@ -1,465 +0,0 @@
-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(),
-  description: z.string(),
-  is_important: z.boolean().optional(),
-  is_hidden: z.boolean().optional(),
-  selected_api: z.string().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.unknown()),
-});
-
-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.unknown()),
-  organizations: z.array(z.record(z.unknown()).nullable()),
-  primary_organization: z.record(z.unknown()).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.string()).optional(), // Service category names
-  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.unknown()).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. "100HiresCLIAPI@1.2.1"
-  name: z.string(),
-  slug: z.string(),
-  age_in_days: z.number().optional(),
-  auth_type: z.string().optional(),
-  banner: z.string().optional(),
-  categories: z
-    .array(
-      z.object({
-        id: z.number(),
-        name: z.string(),
-        slug: z.string(),
-      }),
-    )
-    .optional(),
-  images: z
-    .object({
-      url_16x16: z.string().optional(),
-      url_32x32: z.string().optional(),
-      url_64x64: z.string().optional(),
-      url_128x128: z.string().optional(),
-    })
-    .optional(),
-  popularity: z.number().optional(),
-  has_filters: z.boolean().optional(),
-  has_reads: z.boolean().optional(),
-  has_searches: z.boolean().optional(),
-  has_searches_or_writes: z.boolean().optional(),
-  has_upfront_fields: z.boolean().optional(),
-  has_writes: z.boolean().optional(),
-  is_beta: z.boolean().optional(),
-  is_built_in: z.boolean().optional(),
-  is_deprecated: z.boolean().optional(),
-  is_featured: z.boolean().optional(),
-  is_hidden: z.boolean().optional(),
-  is_invite: z.boolean().optional(),
-  is_premium: z.boolean().optional(),
-  is_public: z.boolean().optional(),
-  is_upcoming: z.boolean().optional(),
-  version: z.string().optional(),
-  visibility: z.string().optional(),
-  actions: z
-    .object({
-      read: z.number().optional(),
-      read_bulk: z.number().optional(),
-      write: z.number().optional(),
-      search: z.number().optional(),
-      search_or_write: z.number().optional(),
-      search_and_write: z.number().optional(),
-      filter: z.number().optional(),
-    })
-    .optional(),
-  description: z.string().optional(),
-  primary_color: z.string().optional(),
-  secondary_color: z.string().optional(),
-  classification: z.string().optional(),
-  api_docs_url: z.string().optional(),
-  image: 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),
-});
-
-// ============================================================================
-// Need Choices Schemas (for listInputFieldChoices functionality)
-// ============================================================================
-
-export const NeedChoicesResponseMetaSchema = z.object({
-  page: z.string().nullable().optional(),
-});
-
-export const NeedChoicesResponseLinksSchema = z.object({
-  next: z.string().nullable().optional(),
-  prev: z.string().nullable().optional(),
-});
-
-export const NeedChoicesRequestSchema = z.object({
-  selected_api: z
-    .string()
-    .optional()
-    .describe(
-      "Something like `SlackAPI` (for Python apps) or `SplitwiseCLIAPI@1.0.0` (for CLI apps). Non-public apps are fine as long as the authed user can access them.",
-    ),
-  authentication_id: z
-    .number()
-    .optional()
-    .describe(
-      "If the app needs auth, provide an `authentication_id` that has the `selected_api` of the app you want to run. Can be any auth visible to the user (including shared).",
-    ),
-  params: z
-    .record(z.unknown())
-    .optional()
-    .describe(
-      "Object that matches the input the node would normally get. Has all the same keys/types as the `needs` of the action.",
-    ),
-  page: z.number().optional().default(0),
-  prefill: z
-    .string()
-    .optional()
-    .describe(
-      "The prefill string to indicate what we're fetching choices for. Likely something like `spreadsheet.id.title`. Must be provided alongside `selected_api` if both `action_id` and `input_field_id` are not.",
-    ),
-  action_id: z
-    .string()
-    .optional()
-    .describe(
-      "The id that will be used to lookup the Action for prefill lookup. If provided, `input_field_id` is required, else `prefill` must be provided.",
-    ),
-  input_field_id: z
-    .string()
-    .optional()
-    .describe(
-      "The id (key) of the input field (Need) that dynamic choices are being retrieved for. If provided, `action_id` is required, else `prefill` must be provided.",
-    ),
-});
-
-export const NeedChoicesResponseSchema = z.object({
-  success: z.boolean(),
-  choices: z.array(NeedChoicesSchema).optional(),
-  next_page: z.number().optional(),
-  errors: z.array(z.string()).optional(),
-  meta: NeedChoicesResponseMetaSchema.optional(),
-  links: NeedChoicesResponseLinksSchema.optional(),
-});