@zapier/zapier-sdk 0.42.1 → 0.43.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ConnectionSchema, ConnectionsResponseSchema, ConnectionItem as ConnectionItem$2, GetConnectionResponse } from '@zapier/zapier-sdk-core/v0/schemas/connections';
+import { RequestContext } from '@zapier/policy-context';
 import { AppItem as AppItem$1 } from '@zapier/zapier-sdk-core/v0/schemas/apps';
 import { ClientCredentialsItem as ClientCredentialsItem$1, ClientCredentialsCreatedItem } from '@zapier/zapier-sdk-core/v0/schemas/client-credentials';
 import * as _zapier_zapier_sdk_cli_login from '@zapier/zapier-sdk-cli-login';
@@ -841,6 +842,7 @@ interface ApiClient {
     fetch: (path: string, init?: RequestInit & {
         searchParams?: Record<string, string>;
         authRequired?: boolean;
+        approvalContext?: () => RequestContext;
     }) => Promise<Response>;
 }
 interface RequestOptions {
@@ -858,6 +860,12 @@ interface RequestOptions {
         statusText: string;
         data: unknown;
     }) => Error | undefined;
+    /**
+     * Builds the policy context for this request if it triggers the approval
+     * flow. Callers that may receive a 403 `approval_required` response MUST
+     * provide this so the SDK can create an approval with the correct context.
+     */
+    approvalContext?: () => RequestContext;
 }
 interface PollOptions extends RequestOptions {
     initialDelay?: number;
@@ -1260,6 +1268,43 @@ declare class ZapierRateLimitError extends ZapierError {
         retries?: number;
     });
 }
+/**
+ * Terminal status of an approval attempt, exposed on `ZapierApprovalError.approvalStatus`.
+ *
+ * - `pending`: The approval was created but not yet resolved. Only thrown in
+ *   `approvalMode: "fail"` — the caller is expected to surface the approval URL
+ *   to an end user (e.g. an LLM instructing its user to click the link).
+ * - `denied`: A human explicitly rejected the approval in the UI.
+ * - `policy_denied`: A policy rule blocked the request before (or instead of)
+ *   creating an approval. Cannot be approved by a human.
+ * - `approval_required`: The backend requested approval, but the current
+ *   session is non-interactive so the SDK cannot open the approval URL. Retry
+ *   in an interactive session, or use `approvalMode: "fail"` to surface the
+ *   approval URL to the caller.
+ * - `timeout`: Poll mode exceeded `approvalTimeoutMs` without the approval
+ *   being resolved.
+ * - `max_retries_exceeded`: A single request triggered more sequential approval
+ *   rounds than `maxApprovalRetries` allows (runaway-loop safeguard).
+ */
+type ApprovalStatus = "denied" | "timeout" | "pending" | "policy_denied" | "approval_required" | "max_retries_exceeded";
+/**
+ * Error thrown when a request requires approval and the approval is denied, times out,
+ * or the auth type doesn't support the approval flow.
+ */
+declare class ZapierApprovalError extends ZapierError {
+    readonly name = "ZapierApprovalError";
+    readonly code: "ZAPIER_APPROVAL_ERROR";
+    approvalId?: string;
+    approvalStatus?: ApprovalStatus;
+    approvalUrl?: string;
+    pollUrl?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        approvalId?: string;
+        status?: ApprovalStatus;
+        approvalUrl?: string;
+        pollUrl?: string;
+    });
+}
 /**
  * Error thrown when Relay itself encounters an error (as opposed to the upstream partner API returning an error).
  * Indicated by the presence of the X-Relay-Error response header.
@@ -2120,6 +2165,7 @@ declare const CreateClientCredentialsSchema: z.ZodObject<{
         external: "external";
         credentials: "credentials";
     }>>>;
+    policy: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 type CreateClientCredentialsOptions = z.infer<typeof CreateClientCredentialsSchema> & FunctionOptions;
 interface CreateClientCredentialsResult {
@@ -3028,6 +3074,13 @@ declare const BaseSdkOptionsSchema: z.ZodObject<{
     trackingBaseUrl: z.ZodOptional<z.ZodString>;
     maxNetworkRetries: z.ZodOptional<z.ZodNumber>;
     maxNetworkRetryDelayMs: z.ZodOptional<z.ZodNumber>;
+    isInteractive: z.ZodOptional<z.ZodBoolean>;
+    approvalTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxApprovalRetries: z.ZodOptional<z.ZodNumber>;
+    approvalMode: z.ZodOptional<z.ZodEnum<{
+        poll: "poll";
+        fail: "fail";
+    }>>;
     manifestPath: z.ZodOptional<z.ZodString>;
     manifest: z.ZodOptional<z.ZodCustom<Manifest, Manifest>>;
     onEvent: z.ZodOptional<z.ZodCustom<EventCallback, EventCallback>>;
@@ -3783,6 +3836,31 @@ declare const DEFAULT_ACTION_TIMEOUT_MS = 180000;
  */
 declare const ZAPIER_MAX_NETWORK_RETRIES: number;
 declare const ZAPIER_MAX_NETWORK_RETRY_DELAY_MS: number;
+/**
+ * Whether this session is interactive (user can visit approval URLs).
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+declare function getZapierIsInteractive(): boolean;
+/**
+ * Approval flow behavior from environment variable.
+ * - "poll": (default) Opens the approval URL in a browser and polls until resolved.
+ * - "fail": Creates the approval and throws immediately with the approval URL.
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+declare function getZapierApprovalMode(): "poll" | "fail" | undefined;
+/**
+ * Default timeout for approval polling (10 minutes)
+ */
+declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/**
+ * Default cap on chained approval retries for a single request. Multiple
+ * sequential approvals can occur when more than one policy gates the same
+ * action; this cap prevents a runaway loop if the server keeps returning
+ * approval_required after a successful approval.
+ */
+declare const DEFAULT_MAX_APPROVAL_RETRIES = 2;
 
 interface ZapierSdkOptions extends BaseSdkOptions {
 }
@@ -3819,4 +3897,4 @@ declare function createZapierSdkWithoutRegistry(options?: ZapierSdkOptions): Wit
 } & EventEmissionProvides & ApiPluginProvides & ManifestPluginProvides & CapabilitiesPluginProvides & ConnectionsPluginProvides & ListAppsPluginProvides & GetAppPluginProvides & ListActionsPluginProvides & GetActionPluginProvides & ListInputFieldsPluginProvides & GetInputFieldsSchemaPluginProvides & ListInputFieldChoicesPluginProvides & RunActionPluginProvides & ListConnectionsPluginProvides & GetConnectionPluginProvides & FindFirstConnectionPluginProvides & FindUniqueConnectionPluginProvides & ListAuthenticationsPluginProvides & GetAuthenticationPluginProvides & FindFirstAuthenticationPluginProvides & FindUniqueAuthenticationPluginProvides & ListClientCredentialsPluginProvides & CreateClientCredentialsPluginProvides & DeleteClientCredentialsPluginProvides & FetchPluginProvides & RequestPluginProvides & ListTablesPluginProvides & GetTablePluginProvides & DeleteTablePluginProvides & CreateTablePluginProvides & ListTableFieldsPluginProvides & CreateTableFieldsPluginProvides & DeleteTableFieldsPluginProvides & GetTableRecordPluginProvides & ListTableRecordsPluginProvides & CreateTableRecordsPluginProvides & DeleteTableRecordsPluginProvides & UpdateTableRecordsPluginProvides & AppsPluginProvides & GetProfilePluginProvides>;
 declare function createZapierSdk(options?: ZapierSdkOptions): ZapierSdk;
 
-export { type Action, type ActionEntry, type ActionExecutionOptions, type ActionExecutionResult, type ActionField, type ActionFieldChoice, type ActionItem$1 as ActionItem, type ActionKeyProperty, ActionKeyPropertySchema, type ActionProperty, ActionPropertySchema, type ActionTimeoutMsProperty, ActionTimeoutMsPropertySchema, type ActionTypeProperty, ActionTypePropertySchema, type AddActionEntryOptions, type AddActionEntryResult, type ApiError, type ApiEvent, type ApiPluginOptions, type ApiPluginProvides, type App, type AppFactoryInput, type AppItem, type AppKeyProperty, AppKeyPropertySchema, type AppProperty, AppPropertySchema, type ApplicationLifecycleEventData, type AppsPluginProvides, type AppsProperty, AppsPropertySchema, type ArrayResolver, type AuthEvent, type AuthenticationIdProperty, AuthenticationIdPropertySchema, type BaseEvent, BaseSdkOptionsSchema, type BatchOptions, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, type Choice, type ClientCredentialsObject, ClientCredentialsObjectSchema, type Connection, type ConnectionEntry, ConnectionEntrySchema, type ConnectionIdProperty, ConnectionIdPropertySchema, type ConnectionItem, type ConnectionProperty, ConnectionPropertySchema, type ConnectionsMap, ConnectionsMapSchema, type ConnectionsPluginProvides, type ConnectionsProperty, ConnectionsPropertySchema, type ConnectionsResponse, type CreateClientCredentialsPluginProvides, type CreateTableFieldsPluginProvides, type CreateTablePluginProvides, type CreateTableRecordsPluginProvides, type Credentials, type CredentialsFunction, CredentialsFunctionSchema, type CredentialsObject, CredentialsObjectSchema, CredentialsSchema, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_CONFIG_PATH, DEFAULT_PAGE_SIZE, type DebugProperty, DebugPropertySchema, type DeleteClientCredentialsPluginProvides, type DeleteTableFieldsPluginProvides, type DeleteTablePluginProvides, type DeleteTableRecordsPluginProvides, type DynamicResolver, type EnhancedErrorEventData, type ErrorOptions, type EventCallback, type EventContext, type EventEmissionContext, type EventEmissionProvides, type FetchPluginProvides, type Field, type FieldsProperty, FieldsPropertySchema, type FieldsResolver, type FieldsetItem, type FindFirstAuthenticationPluginProvides, type FindFirstConnectionPluginProvides, type FindUniqueAuthenticationPluginProvides, type FindUniqueConnectionPluginProvides, type FormatMetadata, type FormattedItem, type FunctionDeprecation, type FunctionOptions, type FunctionRegistryEntry, type GetActionPluginProvides, type GetAppPluginProvides, type GetAuthenticationPluginProvides, type GetConnectionPluginProvides, type GetProfilePluginProvides, type GetTablePluginProvides, type GetTableRecordPluginProvides, type InfoFieldItem, type InputFieldItem, type InputFieldProperty, InputFieldPropertySchema, type InputsProperty, InputsPropertySchema, type LimitProperty, LimitPropertySchema, type ListActionsPluginProvides, type ListAppsPluginProvides, type ListAuthenticationsPluginProvides, type ListClientCredentialsPluginProvides, type ListConnectionsPluginProvides, type ListInputFieldsPluginProvides, type ListTableFieldsPluginProvides, type ListTableRecordsPluginProvides, type ListTablesPluginProvides, type LoadingEvent, MAX_PAGE_LIMIT, type Manifest, type ManifestEntry, type ManifestPluginOptions, type ManifestPluginProvides, type MethodCalledEvent, type MethodCalledEventData, type Need, type NeedsRequest, type NeedsResponse, type OffsetProperty, OffsetPropertySchema, type OutputFormatter, type OutputProperty, OutputPropertySchema, type PaginatedSdkFunction, type ParamsProperty, ParamsPropertySchema, type PkceCredentialsObject, PkceCredentialsObjectSchema, type Plugin, type PluginProvides, type PositionalMetadata, type RateLimitInfo, type RecordProperty, RecordPropertySchema, type RecordsProperty, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, type RequestPluginProvides, type ResolveAuthTokenOptions, type ResolveCredentialsOptions, type ResolvedCredentials, ResolvedCredentialsSchema, type Resolver, type ResolverMetadata, type RootFieldItem, type RunActionPluginProvides, type SdkEvent, type SdkPage, type StaticResolver, type TableProperty, TablePropertySchema, type TablesProperty, TablesPropertySchema, type UpdateManifestEntryOptions, type UpdateManifestEntryResult, type UpdateTableRecordsPluginProvides, type UserProfile, type UserProfileItem, type WithAddPlugin, ZAPIER_BASE_URL, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, type ZapierFetchInitOptions, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierResourceNotFoundError, type ZapierSdk, type ZapierSdkApps, type ZapierSdkOptions, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createFunction, createOptionsPlugin, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierSdk, createZapierSdkWithoutRegistry, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCredentialsFunction, isCredentialsObject, isPkceCredentials, isPositional, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listInputFieldsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, updateTableRecordsPlugin };
+export { type Action, type ActionEntry, type ActionExecutionOptions, type ActionExecutionResult, type ActionField, type ActionFieldChoice, type ActionItem$1 as ActionItem, type ActionKeyProperty, ActionKeyPropertySchema, type ActionProperty, ActionPropertySchema, type ActionTimeoutMsProperty, ActionTimeoutMsPropertySchema, type ActionTypeProperty, ActionTypePropertySchema, type AddActionEntryOptions, type AddActionEntryResult, type ApiError, type ApiEvent, type ApiPluginOptions, type ApiPluginProvides, type App, type AppFactoryInput, type AppItem, type AppKeyProperty, AppKeyPropertySchema, type AppProperty, AppPropertySchema, type ApplicationLifecycleEventData, type ApprovalStatus, type AppsPluginProvides, type AppsProperty, AppsPropertySchema, type ArrayResolver, type AuthEvent, type AuthenticationIdProperty, AuthenticationIdPropertySchema, type BaseEvent, BaseSdkOptionsSchema, type BatchOptions, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, type Choice, type ClientCredentialsObject, ClientCredentialsObjectSchema, type Connection, type ConnectionEntry, ConnectionEntrySchema, type ConnectionIdProperty, ConnectionIdPropertySchema, type ConnectionItem, type ConnectionProperty, ConnectionPropertySchema, type ConnectionsMap, ConnectionsMapSchema, type ConnectionsPluginProvides, type ConnectionsProperty, ConnectionsPropertySchema, type ConnectionsResponse, type CreateClientCredentialsPluginProvides, type CreateTableFieldsPluginProvides, type CreateTablePluginProvides, type CreateTableRecordsPluginProvides, type Credentials, type CredentialsFunction, CredentialsFunctionSchema, type CredentialsObject, CredentialsObjectSchema, CredentialsSchema, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_APPROVAL_TIMEOUT_MS, DEFAULT_CONFIG_PATH, DEFAULT_MAX_APPROVAL_RETRIES, DEFAULT_PAGE_SIZE, type DebugProperty, DebugPropertySchema, type DeleteClientCredentialsPluginProvides, type DeleteTableFieldsPluginProvides, type DeleteTablePluginProvides, type DeleteTableRecordsPluginProvides, type DynamicResolver, type EnhancedErrorEventData, type ErrorOptions, type EventCallback, type EventContext, type EventEmissionContext, type EventEmissionProvides, type FetchPluginProvides, type Field, type FieldsProperty, FieldsPropertySchema, type FieldsResolver, type FieldsetItem, type FindFirstAuthenticationPluginProvides, type FindFirstConnectionPluginProvides, type FindUniqueAuthenticationPluginProvides, type FindUniqueConnectionPluginProvides, type FormatMetadata, type FormattedItem, type FunctionDeprecation, type FunctionOptions, type FunctionRegistryEntry, type GetActionPluginProvides, type GetAppPluginProvides, type GetAuthenticationPluginProvides, type GetConnectionPluginProvides, type GetProfilePluginProvides, type GetTablePluginProvides, type GetTableRecordPluginProvides, type InfoFieldItem, type InputFieldItem, type InputFieldProperty, InputFieldPropertySchema, type InputsProperty, InputsPropertySchema, type LimitProperty, LimitPropertySchema, type ListActionsPluginProvides, type ListAppsPluginProvides, type ListAuthenticationsPluginProvides, type ListClientCredentialsPluginProvides, type ListConnectionsPluginProvides, type ListInputFieldsPluginProvides, type ListTableFieldsPluginProvides, type ListTableRecordsPluginProvides, type ListTablesPluginProvides, type LoadingEvent, MAX_PAGE_LIMIT, type Manifest, type ManifestEntry, type ManifestPluginOptions, type ManifestPluginProvides, type MethodCalledEvent, type MethodCalledEventData, type Need, type NeedsRequest, type NeedsResponse, type OffsetProperty, OffsetPropertySchema, type OutputFormatter, type OutputProperty, OutputPropertySchema, type PaginatedSdkFunction, type ParamsProperty, ParamsPropertySchema, type PkceCredentialsObject, PkceCredentialsObjectSchema, type Plugin, type PluginProvides, type PositionalMetadata, type RateLimitInfo, type RecordProperty, RecordPropertySchema, type RecordsProperty, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, type RequestPluginProvides, type ResolveAuthTokenOptions, type ResolveCredentialsOptions, type ResolvedCredentials, ResolvedCredentialsSchema, type Resolver, type ResolverMetadata, type RootFieldItem, type RunActionPluginProvides, type SdkEvent, type SdkPage, type StaticResolver, type TableProperty, TablePropertySchema, type TablesProperty, TablesPropertySchema, type UpdateManifestEntryOptions, type UpdateManifestEntryResult, type UpdateTableRecordsPluginProvides, type UserProfile, type UserProfileItem, type WithAddPlugin, ZAPIER_BASE_URL, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierApprovalError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, type ZapierFetchInitOptions, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierResourceNotFoundError, type ZapierSdk, type ZapierSdkApps, type ZapierSdkOptions, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createFunction, createOptionsPlugin, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierSdk, createZapierSdkWithoutRegistry, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, getZapierApprovalMode, getZapierIsInteractive, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCredentialsFunction, isCredentialsObject, isPkceCredentials, isPositional, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listInputFieldsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, updateTableRecordsPlugin };