@zapier/zapier-sdk 0.18.4 → 0.19.0

package/dist/index.d.mts

@@ -381,6 +381,71 @@ interface EventEmissionProvides {
     context: EventEmissionContext;
 }
 
+/**
+ * Credentials type definitions
+ *
+ * The credentials system provides a unified way to authenticate with Zapier APIs.
+ * It supports multiple credential types:
+ * - String: A token (JWT or API key) used directly
+ * - Client credentials: OAuth client ID + secret exchanged for a token
+ * - PKCE: OAuth client ID for interactive login (CLI only)
+ * - Function: Lazy/dynamic credential resolution
+ */
+/**
+ * Client credentials for OAuth client_credentials flow.
+ * The SDK will exchange these for an access token.
+ */
+interface ClientCredentialsObject {
+    type?: "client_credentials";
+    clientId: string;
+    clientSecret: string;
+    baseUrl?: string;
+    scope?: string;
+}
+/**
+ * PKCE credentials for interactive OAuth flow.
+ * Only works when @zapier/zapier-sdk-cli-login is available.
+ */
+interface PkceCredentialsObject {
+    type?: "pkce";
+    clientId: string;
+    baseUrl?: string;
+    scope?: string;
+}
+/**
+ * Union of all credential object types.
+ */
+type CredentialsObject = ClientCredentialsObject | PkceCredentialsObject;
+/**
+ * Resolved credentials - what a credentials function must return.
+ * Either a string (token) or a credentials object.
+ * Functions are not allowed to return other functions.
+ */
+type ResolvedCredentials = string | CredentialsObject;
+/**
+ * Credentials can be:
+ * - A string (token or API key)
+ * - A credentials object (client_credentials or pkce)
+ * - A function that returns credentials (sync or async)
+ */
+type Credentials = ResolvedCredentials | (() => ResolvedCredentials | Promise<ResolvedCredentials>);
+/**
+ * Type guard for client credentials objects.
+ */
+declare function isClientCredentials(credentials: ResolvedCredentials): credentials is ClientCredentialsObject;
+/**
+ * Type guard for PKCE credentials objects.
+ */
+declare function isPkceCredentials(credentials: ResolvedCredentials): credentials is PkceCredentialsObject;
+/**
+ * Type guard for credentials objects (either type).
+ */
+declare function isCredentialsObject(credentials: ResolvedCredentials): credentials is CredentialsObject;
+/**
+ * Type guard for credentials functions.
+ */
+declare function isCredentialsFunction(credentials: Credentials): credentials is () => ResolvedCredentials | Promise<ResolvedCredentials>;
+
 declare const NeedSchema: z.ZodObject<{
     key: z.ZodString;
     alters_custom_fields: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -1013,24 +1078,26 @@ declare const ListInputFieldsSchema: z.ZodObject<{
 type ListInputFieldsOptions = z.infer<typeof ListInputFieldsSchema>;
 
 declare const FindFirstAuthenticationSchema: z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
     appKey: z.ZodOptional<z.ZodString & {
         _def: z.core.$ZodStringDef & PositionalMetadata;
     }>;
-    search: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
     owner: z.ZodOptional<z.ZodString>;
+    isExpired: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type FindFirstAuthenticationOptions = z.infer<typeof FindFirstAuthenticationSchema>;
 
 declare const FindUniqueAuthenticationSchema: z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
     appKey: z.ZodOptional<z.ZodString & {
         _def: z.core.$ZodStringDef & PositionalMetadata;
     }>;
-    search: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
     owner: z.ZodOptional<z.ZodString>;
+    isExpired: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type FindUniqueAuthenticationOptions = z.infer<typeof FindUniqueAuthenticationSchema>;
 
@@ -1122,6 +1189,7 @@ interface ApiPluginOptions extends BaseSdkOptions {
 interface ApiPluginProvides {
     context: {
         api: ApiClient;
+        resolveCredentials: () => Promise<ResolvedCredentials | undefined>;
     };
 }
 declare const apiPlugin: Plugin<{}, {}, ApiPluginProvides>;
@@ -1468,6 +1536,7 @@ declare const ListAuthenticationsQuerySchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
     owner: z.ZodOptional<z.ZodString>;
+    isExpired: z.ZodOptional<z.ZodBoolean>;
     appKey: z.ZodOptional<z.ZodString & {
         _def: z.core.$ZodStringDef & PositionalMetadata;
     }>;
@@ -1666,13 +1735,21 @@ interface ListInputFieldChoicesPluginProvides {
  */
 
 interface BaseSdkOptions {
+    /**
+     * Authentication credentials. Can be:
+     * - A string (token or API key)
+     * - An object with clientId/clientSecret for client_credentials flow
+     * - An object with clientId (no secret) for PKCE flow
+     * - A function returning any of the above
+     */
+    credentials?: Credentials;
+    /**
+     * @deprecated Use `credentials` instead.
+     */
     token?: string;
-    getToken?: () => Promise<string | undefined>;
     onEvent?: EventCallback;
     fetch?: typeof fetch;
     baseUrl?: string;
-    authBaseUrl?: string;
-    authClientId?: string;
     trackingBaseUrl?: string;
     debug?: boolean;
     manifestPath?: string;
@@ -2147,52 +2224,147 @@ declare const inputFieldKeyResolver: DynamicResolver<InputFieldItem$1, {
  * SDK Authentication Utilities
  *
  * This module provides SDK-level authentication utilities focused
- * solely on token acquisition. CLI-specific functionality like login/logout
- * is handled by the @zapier/zapier-sdk-cli-login package.
+ * on token acquisition. It uses the credentials system for resolution
+ * and handles different credential types appropriately.
+ *
+ * CLI-specific functionality like login/logout is handled by the
+ * @zapier/zapier-sdk-cli-login package.
  */
 
-interface AuthOptions {
+/**
+ * Options for resolving auth tokens.
+ */
+interface ResolveAuthTokenOptions {
+    credentials?: Credentials;
+    /** @deprecated Use `credentials` instead */
+    token?: string;
     onEvent?: EventCallback;
     fetch?: typeof globalThis.fetch;
     baseUrl?: string;
-    authBaseUrl?: string;
-    authClientId?: string;
-}
-interface ResolveAuthTokenOptions extends AuthOptions {
-    token?: string;
-    getToken?: () => Promise<string | undefined> | string | undefined;
 }
 /**
- * Gets the ZAPIER_TOKEN from environment variables.
- * Returns undefined if not set.
+ * Clear the token cache. Useful for testing or forcing re-authentication.
+ */
+declare function clearTokenCache(): void;
+/**
+ * Invalidate a cached token. Called when we get a 401 response.
+ */
+declare function invalidateCachedToken(clientId: string): void;
+/**
+ * Options for getTokenFromCliLogin.
  */
-declare function getTokenFromEnv(): string | undefined;
+interface CliLoginOptions {
+    onEvent?: EventCallback;
+    fetch?: typeof globalThis.fetch;
+    credentials?: {
+        type?: "pkce";
+        clientId: string;
+        baseUrl?: string;
+        scope?: string;
+    };
+}
 /**
  * Attempts to get a token by optionally importing from CLI login package.
  * This provides a graceful fallback when the CLI login package is not available.
  *
  * Returns undefined if no valid token is found or CLI package is not available.
  */
-declare function getTokenFromCliLogin(options?: AuthOptions): Promise<string | undefined>;
+declare function getTokenFromCliLogin(options: CliLoginOptions): Promise<string | undefined>;
 /**
- * Attempts to get a token with the following precedence:
- * 1. ZAPIER_TOKEN environment variable
- * 2. CLI login package (if available) with auto-refresh
+ * Resolves an auth token from wherever it can be found.
+ *
+ * Resolution order:
+ * 1. Explicit credentials option (or deprecated token option)
+ * 2. Environment variables
+ * 3. CLI login package (if available)
+ *
+ * For different credential types:
+ * - String: Used directly as the token
+ * - Client credentials: Exchanged for an access token (with caching)
+ * - PKCE: Delegates to CLI login (throws if not available)
  *
  * Returns undefined if no valid token is found.
  */
-declare function getTokenFromEnvOrConfig(options?: AuthOptions): Promise<string | undefined>;
+declare function resolveAuthToken(options?: ResolveAuthTokenOptions): Promise<string | undefined>;
 /**
- * Resolves an auth token from all possible sources with the following precedence:
- * 1. Explicitly provided token in options
- * 2. Token from getToken callback in options
- * 3. ZAPIER_TOKEN environment variable
- * 4. CLI login package (if available)
+ * Invalidate the cached token for the given credentials, if applicable.
+ * This is called when we receive a 401 response, indicating the token
+ * is no longer valid. Only affects client_credentials flow tokens.
+ */
+declare function invalidateCredentialsToken(options: {
+    credentials?: Credentials;
+    token?: string;
+}): Promise<void>;
+
+/**
+ * Credentials Resolution
  *
- * This is the canonical token resolution logic used throughout the SDK.
- * Returns undefined if no valid token is found.
+ * This module provides the core logic for resolving credentials from various sources:
+ * - Explicit credentials option
+ * - Deprecated token option
+ * - Environment variables (new and deprecated)
+ * - CLI login stored tokens
  */
-declare function resolveAuthToken(options?: ResolveAuthTokenOptions): Promise<string | undefined>;
+
+/**
+ * Options for resolving credentials.
+ */
+interface ResolveCredentialsOptions {
+    credentials?: Credentials;
+    /** @deprecated Use `credentials` instead */
+    token?: string;
+    /** SDK base URL - used to derive auth base URL if not specified in credentials */
+    baseUrl?: string;
+}
+/**
+ * Resolve credentials from environment variables.
+ *
+ * Precedence:
+ * 1. ZAPIER_CREDENTIALS (string token)
+ * 2. ZAPIER_CREDENTIALS_CLIENT_ID + ZAPIER_CREDENTIALS_CLIENT_SECRET (client credentials)
+ * 3. ZAPIER_CREDENTIALS_CLIENT_ID alone (PKCE)
+ * 4. Deprecated ZAPIER_TOKEN, ZAPIER_AUTH_* vars (with warnings)
+ *
+ * @param sdkBaseUrl - SDK base URL used to derive auth base URL if not specified
+ */
+declare function resolveCredentialsFromEnv(sdkBaseUrl?: string): ResolvedCredentials | undefined;
+/**
+ * Resolve credentials from all possible sources.
+ *
+ * Precedence:
+ * 1. Explicit credentials option
+ * 2. Deprecated token option (with warning)
+ * 3. Environment variables
+ * 4. CLI login stored token (handled separately in auth.ts)
+ *
+ * If credentials is a function, it is called and must return
+ * a string or credentials object (not another function).
+ *
+ * The baseUrl option is used to derive the auth base URL if not
+ * specified in credentials.
+ */
+declare function resolveCredentials(options?: ResolveCredentialsOptions): Promise<ResolvedCredentials | undefined>;
+/**
+ * Extract the base URL from credentials for use in auth flows.
+ */
+declare function getBaseUrlFromCredentials(credentials: ResolvedCredentials | undefined): string | undefined;
+/**
+ * Extract the client ID from credentials for use in auth flows.
+ */
+declare function getClientIdFromCredentials(credentials: ResolvedCredentials | undefined): string | undefined;
+
+/**
+ * Logging utilities for the SDK
+ */
+/**
+ * Log a deprecation warning. Each unique message is only logged once per process.
+ */
+declare function logDeprecation(message: string): void;
+/**
+ * Reset the set of logged deprecation warnings.
+ * Useful for testing.
+ */
+declare function resetDeprecationWarnings(): void;
 
 /**
  * SDK Constants
@@ -2207,6 +2379,20 @@ declare const ZAPIER_BASE_URL: string;
  * Maximum number of items that can be requested per page across all paginated functions
  */
 declare const MAX_PAGE_LIMIT = 10000;
+/**
+ * Credentials from environment variables
+ */
+declare const ZAPIER_CREDENTIALS: string | undefined;
+declare const ZAPIER_CREDENTIALS_CLIENT_ID: string | undefined;
+declare const ZAPIER_CREDENTIALS_CLIENT_SECRET: string | undefined;
+declare const ZAPIER_CREDENTIALS_BASE_URL: string | undefined;
+declare const ZAPIER_CREDENTIALS_SCOPE: string | undefined;
+/**
+ * Deprecated environment variables (kept for backwards compatibility)
+ */
+declare const ZAPIER_TOKEN: string | undefined;
+declare const ZAPIER_AUTH_BASE_URL: string | undefined;
+declare const ZAPIER_AUTH_CLIENT_ID: string | undefined;
 
 interface ZapierSdkOptions extends BaseSdkOptions {
 }
@@ -2224,6 +2410,7 @@ declare function createZapierSdkWithoutRegistry(options?: ZapierSdkOptions): Sdk
     meta: Record<string, PluginMeta>;
 } & EventEmissionContext & {
     api: ApiClient;
+    resolveCredentials: () => Promise<ResolvedCredentials | undefined>;
 } & {
     getVersionedImplementationId: GetVersionedImplementationId;
     resolveAppKeys: ResolveAppKeys;
@@ -2351,4 +2538,4 @@ declare function createZapierSdkWithoutRegistry(options?: ZapierSdkOptions): Sdk
 }>;
 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 ActionTypeProperty, ActionTypePropertySchema, type AddActionEntryOptions, type AddActionEntryResult, type ApiError, type ApiEvent, type ApiPluginOptions, type ApiPluginProvides, type App, type AppItem, type AppKeyProperty, AppKeyPropertySchema, type ApplicationLifecycleEventData, type AppsPluginProvides, type AuthEvent, type AuthOptions, type Authentication, type AuthenticationIdProperty, AuthenticationIdPropertySchema, type AuthenticationItem, type AuthenticationsResponse, type BaseEvent, type BatchOptions, type Choice, DEFAULT_CONFIG_PATH, type DebugProperty, DebugPropertySchema, type EnhancedErrorEventData, type ErrorOptions, type EventCallback, type EventContext, type EventEmissionContext, type FetchPluginProvides, type Field, type FieldsetItem, type FindFirstAuthenticationPluginProvides, type FindUniqueAuthenticationPluginProvides, type FormatMetadata, type FormattedItem, type FunctionOptions, type FunctionRegistryEntry, type GetActionPluginProvides, type GetAppPluginProvides, type GetAuthenticationPluginProvides, type GetContextType, type GetProfilePluginProvides, type GetSdkType, type InfoFieldItem, type InputFieldItem, type InputsProperty, InputsPropertySchema, type LimitProperty, LimitPropertySchema, type ListActionsPluginProvides, type ListAppsPluginProvides, type ListAuthenticationsPluginProvides, type ListInputFieldsPluginProvides, 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 OutputProperty, OutputPropertySchema, type PaginatedSdkFunction, type ParamsProperty, ParamsPropertySchema, type Plugin, type PluginDependencies, type PluginOptions, type PluginProvides, type PositionalMetadata, RelayFetchSchema, RelayRequestSchema, type RequestPluginProvides, type ResolveAuthTokenOptions, type RootFieldItem, type RunActionPluginProvides, type Sdk, type SdkEvent, type UpdateManifestEntryOptions, type UpdateManifestEntryResult, type UserProfile, type UserProfileItem, ZAPIER_BASE_URL, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, type ZapierFetchInitOptions, ZapierNotFoundError, ZapierResourceNotFoundError, type ZapierSdk, type ZapierSdkApps, type ZapierSdkOptions, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, authenticationIdGenericResolver, authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, createBaseEvent, createFunction, createSdk, createZapierSdk, createZapierSdkWithoutRegistry, fetchPlugin, findFirstAuthenticationPlugin, findManifestEntry, findUniqueAuthenticationPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getAuthenticationPlugin, getCiPlatform, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTokenFromCliLogin, getTokenFromEnv, getTokenFromEnvOrConfig, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, isCi, isPositional, listActionsPlugin, listAppsPlugin, listAuthenticationsPlugin, listInputFieldsPlugin, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resolveAuthToken, runActionPlugin, toSnakeCase, toTitleCase };
+export { type Action, type ActionEntry, type ActionExecutionOptions, type ActionExecutionResult, type ActionField, type ActionFieldChoice, type ActionItem$1 as ActionItem, type ActionKeyProperty, ActionKeyPropertySchema, type ActionTypeProperty, ActionTypePropertySchema, type AddActionEntryOptions, type AddActionEntryResult, type ApiError, type ApiEvent, type ApiPluginOptions, type ApiPluginProvides, type App, type AppItem, type AppKeyProperty, AppKeyPropertySchema, type ApplicationLifecycleEventData, type AppsPluginProvides, type AuthEvent, type Authentication, type AuthenticationIdProperty, AuthenticationIdPropertySchema, type AuthenticationItem, type AuthenticationsResponse, type BaseEvent, type BatchOptions, type Choice, type ClientCredentialsObject, type Credentials, type CredentialsObject, DEFAULT_CONFIG_PATH, type DebugProperty, DebugPropertySchema, type EnhancedErrorEventData, type ErrorOptions, type EventCallback, type EventContext, type EventEmissionContext, type FetchPluginProvides, type Field, type FieldsetItem, type FindFirstAuthenticationPluginProvides, type FindUniqueAuthenticationPluginProvides, type FormatMetadata, type FormattedItem, type FunctionOptions, type FunctionRegistryEntry, type GetActionPluginProvides, type GetAppPluginProvides, type GetAuthenticationPluginProvides, type GetContextType, type GetProfilePluginProvides, type GetSdkType, type InfoFieldItem, type InputFieldItem, type InputsProperty, InputsPropertySchema, type LimitProperty, LimitPropertySchema, type ListActionsPluginProvides, type ListAppsPluginProvides, type ListAuthenticationsPluginProvides, type ListInputFieldsPluginProvides, 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 OutputProperty, OutputPropertySchema, type PaginatedSdkFunction, type ParamsProperty, ParamsPropertySchema, type PkceCredentialsObject, type Plugin, type PluginDependencies, type PluginOptions, type PluginProvides, type PositionalMetadata, RelayFetchSchema, RelayRequestSchema, type RequestPluginProvides, type ResolveAuthTokenOptions, type ResolveCredentialsOptions, type ResolvedCredentials, type RootFieldItem, type RunActionPluginProvides, type Sdk, type SdkEvent, type UpdateManifestEntryOptions, type UpdateManifestEntryResult, type UserProfile, type UserProfileItem, ZAPIER_AUTH_BASE_URL, ZAPIER_AUTH_CLIENT_ID, ZAPIER_BASE_URL, ZAPIER_CREDENTIALS, ZAPIER_CREDENTIALS_BASE_URL, ZAPIER_CREDENTIALS_CLIENT_ID, ZAPIER_CREDENTIALS_CLIENT_SECRET, ZAPIER_CREDENTIALS_SCOPE, ZAPIER_TOKEN, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, type ZapierFetchInitOptions, ZapierNotFoundError, ZapierResourceNotFoundError, type ZapierSdk, type ZapierSdkApps, type ZapierSdkOptions, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, authenticationIdGenericResolver, authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, clearTokenCache, createBaseEvent, createFunction, createSdk, createZapierSdk, createZapierSdkWithoutRegistry, fetchPlugin, findFirstAuthenticationPlugin, findManifestEntry, findUniqueAuthenticationPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getAuthenticationPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTokenFromCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isClientCredentials, isCredentialsFunction, isCredentialsObject, isPkceCredentials, isPositional, listActionsPlugin, listAppsPlugin, listAuthenticationsPlugin, listInputFieldsPlugin, logDeprecation, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, toSnakeCase, toTitleCase };