@zapier/zapier-sdk 0.30.0 → 0.31.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.31.1
+
+### Patch Changes
+
+- b0f273f: Enrich MethodCalledEvent with selected_api, operation_type, operation_key
+
+## 0.31.0
+
+### Minor Changes
+
+- 4a874c6: Add Zod schema for base SDK options, autodoc generation for SDK factory options and CLI base command options
+
 ## 0.30.0
 
 ### Minor Changes

package/README.md

@@ -6,6 +6,7 @@
 - [Documentation](#documentation)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Factory](#factory)
 - [Available Functions](#available-functions)
 - [Accounts](#accounts)
   - [`getProfile`](#getprofile)
@@ -289,6 +290,19 @@ const emojiData = await emojiResponse.json();
 console.log(emojiData.emoji);
 ```
 
+## Factory
+
+The `createZapierSdk(...)` factory function is the main entry point for the SDK. It provides methods for managing connections, listing apps, running actions, and more.
+
+| Name                     | Type                       | Required | Default | Possible Values | Description                                                                                                                                                                                   |
+| ------------------------ | -------------------------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials`            | `string, object, function` | ❌       | —       | —               | Authentication credentials. Can be a string (token or API key), a client credentials object ({ clientId, clientSecret }), a PKCE object ({ clientId }), or a function returning any of those. |
+| `debug`                  | `boolean`                  | ❌       | —       | —               | Enable debug logging.                                                                                                                                                                         |
+| `baseUrl`                | `string`                   | ❌       | —       | —               | Base URL for Zapier API endpoints.                                                                                                                                                            |
+| `trackingBaseUrl`        | `string`                   | ❌       | —       | —               | Base URL for Zapier tracking endpoints.                                                                                                                                                       |
+| `maxNetworkRetries`      | `number`                   | ❌       | —       | —               | Max retries for rate-limited requests (default: 3).                                                                                                                                           |
+| `maxNetworkRetryDelayMs` | `number`                   | ❌       | —       | —               | Max delay in ms to wait for retry (default: 60000).                                                                                                                                           |
+
 ## Available Functions
 
 ### Accounts
@@ -872,15 +886,15 @@ Make authenticated HTTP requests to any API through Zapier. Pass a connectionId
 
 **Parameters:**
 
-| Name             | Type                             | Required | Default | Possible Values                                            | Description                                                                                         |
-| ---------------- | -------------------------------- | -------- | ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `url`            | `string, custom`                 | ✅       | —       | —                                                          | The full URL of the API endpoint to call (proxied through Zapier's Relay service)                   |
-| `init`           | `object`                         | ❌       | —       | —                                                          | Request options including method, headers, body, and authentication                                 |
-| ↳ `method`       | `string`                         | ❌       | —       | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET)                                                       |
-| ↳ `headers`      | `object`                         | ❌       | —       | —                                                          | HTTP headers to include in the request                                                              |
-| ↳ `body`         | `string, custom, custom, record` | ❌       | —       | —                                                          | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly |
-| ↳ `connectionId` | `string, number`                 | ❌       | —       | —                                                          | Connection ID to use for this action                                                                |
-| ↳ `callbackUrl`  | `string`                         | ❌       | —       | —                                                          | URL to send async response to (makes request async)                                                 |
+| Name             | Type                     | Required | Default | Possible Values                                            | Description                                                                                         |
+| ---------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `url`            | `string, custom`         | ✅       | —       | —                                                          | The full URL of the API endpoint to call (proxied through Zapier's Relay service)                   |
+| `init`           | `object`                 | ❌       | —       | —                                                          | Request options including method, headers, body, and authentication                                 |
+| ↳ `method`       | `string`                 | ❌       | —       | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET)                                                       |
+| ↳ `headers`      | `object`                 | ❌       | —       | —                                                          | HTTP headers to include in the request                                                              |
+| ↳ `body`         | `string, custom, record` | ❌       | —       | —                                                          | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly |
+| ↳ `connectionId` | `string, number`         | ❌       | —       | —                                                          | Connection ID to use for this action                                                                |
+| ↳ `callbackUrl`  | `string`                 | ❌       | —       | —                                                          | URL to send async response to (makes request async)                                                 |
 
 **Returns:** `Promise<Response>`
 

package/dist/api/schemas.d.ts

@@ -42,8 +42,8 @@ export declare const NeedSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodEnum<{
         string: "string";
         boolean: "boolean";
-        filter: "filter";
         file: "file";
+        filter: "filter";
         integer: "integer";
         text: "text";
         datetime: "datetime";
@@ -286,8 +286,8 @@ export declare const NeedsResponseSchema: z.ZodObject<{
         type: z.ZodOptional<z.ZodEnum<{
             string: "string";
             boolean: "boolean";
-            filter: "filter";
             file: "file";
+            filter: "filter";
             integer: "integer";
             text: "text";
             datetime: "datetime";

package/dist/index.cjs

@@ -491,6 +491,16 @@ function runWithTelemetryContext(fn) {
   const currentDepth = telemetryStore.getStore()?.depth ?? -1;
   return telemetryStore.run({ depth: currentDepth + 1 }, fn);
 }
+function setMethodMetadata(metadata) {
+  if (!telemetryStore) return;
+  const store = telemetryStore.getStore();
+  if (!store) return;
+  store.methodMetadata = { ...store.methodMetadata, ...metadata };
+}
+function getMethodMetadata() {
+  if (!telemetryStore) return void 0;
+  return telemetryStore.getStore()?.methodMetadata;
+}
 
 // src/plugins/fetch/index.ts
 function transformUrlToRelayPath(url) {
@@ -1043,6 +1053,7 @@ var AppItemSchema = withFormatter(apps.AppItemSchema, {
 function createTelemetryCallback(emitMethodCalled, methodName) {
   return {
     onMethodCalled: (data) => {
+      const metadata = getMethodMetadata();
       emitMethodCalled({
         method_name: methodName,
         execution_duration_ms: data.durationMs,
@@ -1050,7 +1061,10 @@ function createTelemetryCallback(emitMethodCalled, methodName) {
         error_message: data.error?.message ?? null,
         error_type: data.error?.constructor.name ?? null,
         argument_count: data.argumentCount,
-        is_paginated: data.isPaginated
+        is_paginated: data.isPaginated,
+        selected_api: metadata?.selectedApi ?? null,
+        operation_type: metadata?.operationType ?? null,
+        operation_key: metadata?.operationKey ?? null
       });
     }
   };
@@ -1790,6 +1804,10 @@ var listActionsPlugin = ({ context }) => {
         { configType: "current_implementation_id" }
       );
     }
+    setMethodMetadata({
+      selectedApi,
+      operationType: options.actionType ?? null
+    });
     const searchParams = {
       global: "true",
       public_only: "true",
@@ -2168,6 +2186,11 @@ var listInputFieldsPlugin = ({ sdk, context }) => {
         { configType: "current_implementation_id" }
       );
     }
+    setMethodMetadata({
+      selectedApi,
+      operationType: actionType,
+      operationKey: actionKey
+    });
     const { data: action } = await sdk.getAction({
       appKey,
       actionType,
@@ -2287,6 +2310,7 @@ var listConnectionsPlugin = ({ context }) => {
         options.appKey
       );
       if (implementationId) {
+        setMethodMetadata({ selectedApi: implementationId });
         const [versionlessSelectedApi] = splitVersionedKey(implementationId);
         searchParams.app_key = versionlessSelectedApi;
       } else {
@@ -2653,6 +2677,10 @@ var GetActionSchema = zod.z.object({
 var getActionPlugin = ({ sdk, context }) => {
   async function getAction(options) {
     const { actionKey, actionType, appKey } = options;
+    setMethodMetadata({
+      operationType: actionType,
+      operationKey: actionKey
+    });
     for await (const action of sdk.listActions({ appKey }).items()) {
       if ((action.key === actionKey || action.id === actionKey) && action.action_type === actionType) {
         return { data: action };
@@ -2862,8 +2890,7 @@ var RunActionSchema = zod.z.object({
 async function executeAction(actionOptions) {
   const {
     api,
-    context,
-    appKey,
+    selectedApi,
     actionId,
     actionKey,
     actionType,
@@ -2871,13 +2898,6 @@ async function executeAction(actionOptions) {
     connectionId,
     timeoutMs
   } = actionOptions;
-  const selectedApi = await context.getVersionedImplementationId(appKey);
-  if (!selectedApi) {
-    throw new ZapierConfigurationError(
-      "No current_implementation_id found for app",
-      { configType: "current_implementation_id" }
-    );
-  }
   const runRequestData = {
     selected_api: selectedApi,
     action_id: actionId,
@@ -2920,6 +2940,18 @@ var runActionPlugin = ({ sdk, context }) => {
       timeoutMs
     } = options;
     const resolvedConnectionId = connectionId ?? authenticationId;
+    const selectedApi = await context.getVersionedImplementationId(appKey);
+    if (!selectedApi) {
+      throw new ZapierConfigurationError(
+        "No current_implementation_id found for app",
+        { configType: "current_implementation_id" }
+      );
+    }
+    setMethodMetadata({
+      selectedApi,
+      operationType: actionType,
+      operationKey: actionKey
+    });
     const actionData = await sdk.getAction({
       appKey,
       actionKey,
@@ -2933,8 +2965,7 @@ var runActionPlugin = ({ sdk, context }) => {
     const actionId = actionData.data.id;
     const result = await executeAction({
       api,
-      context,
-      appKey,
+      selectedApi,
       // Some actions require the action ID to run them, but technically the ID is not guaranteed to be available when
       // we retrieve actions (probably legacy reasons), so we just pass along all the things!
       actionId,
@@ -3919,8 +3950,34 @@ async function pollUntilComplete(options) {
     }
   }
 }
-
-// src/types/credentials.ts
+var ClientCredentialsObjectSchema = zod.z.object({
+  type: zod.z.enum(["client_credentials"]).optional().meta({ internal: true }),
+  clientId: zod.z.string().describe("OAuth client ID for authentication.").meta({ valueHint: "id" }),
+  clientSecret: zod.z.string().describe("OAuth client secret for authentication.").meta({ valueHint: "secret" }),
+  baseUrl: zod.z.string().optional().describe("Override authentication base URL.").meta({ valueHint: "url" }),
+  scope: zod.z.string().optional().describe("Authentication scope.").meta({ internal: true })
+});
+var PkceCredentialsObjectSchema = zod.z.object({
+  type: zod.z.enum(["pkce"]).optional().meta({ internal: true }),
+  clientId: zod.z.string().describe("OAuth client ID for authentication.").meta({ valueHint: "id" }),
+  baseUrl: zod.z.string().optional().describe("Override authentication base URL.").meta({ valueHint: "url" }),
+  scope: zod.z.string().optional().describe("Authentication scope.").meta({ internal: true })
+});
+var CredentialsObjectSchema = zod.z.union([
+  ClientCredentialsObjectSchema,
+  PkceCredentialsObjectSchema
+]);
+var ResolvedCredentialsSchema = zod.z.union([
+  zod.z.string().describe("Authentication token.").meta({ valueHint: "token" }),
+  CredentialsObjectSchema
+]);
+var CredentialsFunctionSchema = zod.z.function().input([]).output(
+  zod.z.union([ResolvedCredentialsSchema, zod.z.promise(ResolvedCredentialsSchema)])
+);
+var CredentialsSchema = zod.z.union([
+  ResolvedCredentialsSchema,
+  CredentialsFunctionSchema
+]);
 function isClientCredentials(credentials) {
   return typeof credentials === "object" && credentials !== null && "clientId" in credentials && "clientSecret" in credentials;
 }
@@ -5032,6 +5089,11 @@ var getInputFieldsSchemaPlugin = ({ sdk, context }) => {
         { configType: "current_implementation_id" }
       );
     }
+    setMethodMetadata({
+      selectedApi,
+      operationType: actionType,
+      operationKey: actionKey
+    });
     const { data: action } = await sdk.getAction({
       appKey,
       actionType,
@@ -5151,6 +5213,11 @@ var listInputFieldChoicesPlugin = ({ context, sdk }) => {
         { configType: "current_implementation_id" }
       );
     }
+    setMethodMetadata({
+      selectedApi,
+      operationType: actionType,
+      operationKey: actionKey
+    });
     const { data: action } = await sdk.getAction({
       appKey,
       actionType,
@@ -5402,7 +5469,7 @@ function getCpuTime() {
 
 // package.json
 var package_default = {
-  version: "0.30.0"};
+  version: "0.31.1"};
 
 // src/plugins/eventEmission/builders.ts
 function createBaseEvent(context = {}) {
@@ -5483,13 +5550,13 @@ function buildMethodCalledEvent(data, context = {}) {
     is_paginated: data.is_paginated ?? false,
     sdk_version: package_default.version,
     environment: context.environment ?? (process?.env?.NODE_ENV || null),
-    selected_api: context.selected_api ?? null,
+    selected_api: data.selected_api ?? context.selected_api ?? null,
     app_id: context.app_id ?? null,
     app_version_id: context.app_version_id ?? null,
     zap_id: context.zap_id ?? null,
     node_id: context.node_id ?? null,
-    operation_type: null,
-    operation_key: null,
+    operation_type: data.operation_type ?? null,
+    operation_key: data.operation_key ?? null,
     call_context: null,
     is_retry: false,
     retry_attempt: null,
@@ -5861,13 +5928,46 @@ function createZapierSdkWithoutRegistry(options = {}) {
 function createZapierSdk(options = {}) {
   return createZapierSdkWithoutRegistry(options).addPlugin(registryPlugin);
 }
+var BaseSdkOptionsSchema = zod.z.object({
+  credentials: CredentialsSchema.optional().describe(
+    "Authentication credentials. Can be a string (token or API key), a client credentials object ({ clientId, clientSecret }), a PKCE object ({ clientId }), or a function returning any of those."
+  ),
+  debug: zod.z.boolean().optional().describe("Enable debug logging."),
+  baseUrl: zod.z.string().optional().describe("Base URL for Zapier API endpoints.").meta({ valueHint: "url" }),
+  trackingBaseUrl: zod.z.string().optional().describe("Base URL for Zapier tracking endpoints.").meta({ valueHint: "url" }),
+  /**
+   * Maximum number of retries for rate-limited requests (429 responses).
+   * Set to 0 to disable retries. Default is 3.
+   */
+  maxNetworkRetries: zod.z.number().optional().describe("Max retries for rate-limited requests (default: 3).").meta({ valueHint: "count" }),
+  /**
+   * Maximum delay in milliseconds to wait for a rate limit retry.
+   * If the server requests a longer delay, the request fails immediately.
+   * Default is 60000 (60 seconds).
+   */
+  maxNetworkRetryDelayMs: zod.z.number().optional().describe("Max delay in ms to wait for retry (default: 60000).").meta({ valueHint: "ms" }),
+  // Internal
+  manifestPath: zod.z.string().optional().describe("Path to a .zapierrc manifest file for app version locking.").meta({ internal: true }),
+  manifest: zod.z.custom().optional().describe("Manifest for app version locking.").meta({ internal: true }),
+  onEvent: zod.z.custom().optional().meta({ internal: true }),
+  fetch: zod.z.custom().optional().meta({ internal: true }),
+  eventEmission: zod.z.custom().optional().meta({ internal: true }),
+  // Deprecated
+  token: zod.z.string().optional().meta({ deprecated: true })
+  // Use credentials instead
+});
 
 exports.ActionKeyPropertySchema = ActionKeyPropertySchema;
 exports.ActionTimeoutMsPropertySchema = ActionTimeoutMsPropertySchema;
 exports.ActionTypePropertySchema = ActionTypePropertySchema;
 exports.AppKeyPropertySchema = AppKeyPropertySchema;
 exports.AuthenticationIdPropertySchema = AuthenticationIdPropertySchema;
+exports.BaseSdkOptionsSchema = BaseSdkOptionsSchema;
+exports.ClientCredentialsObjectSchema = ClientCredentialsObjectSchema;
 exports.ConnectionIdPropertySchema = ConnectionIdPropertySchema;
+exports.CredentialsFunctionSchema = CredentialsFunctionSchema;
+exports.CredentialsObjectSchema = CredentialsObjectSchema;
+exports.CredentialsSchema = CredentialsSchema;
 exports.DEFAULT_ACTION_TIMEOUT_MS = DEFAULT_ACTION_TIMEOUT_MS;
 exports.DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_PATH;
 exports.DebugPropertySchema = DebugPropertySchema;
@@ -5877,8 +5977,10 @@ exports.MAX_PAGE_LIMIT = MAX_PAGE_LIMIT;
 exports.OffsetPropertySchema = OffsetPropertySchema;
 exports.OutputPropertySchema = OutputPropertySchema;
 exports.ParamsPropertySchema = ParamsPropertySchema;
+exports.PkceCredentialsObjectSchema = PkceCredentialsObjectSchema;
 exports.RelayFetchSchema = RelayFetchSchema;
 exports.RelayRequestSchema = RelayRequestSchema;
+exports.ResolvedCredentialsSchema = ResolvedCredentialsSchema;
 exports.ZAPIER_AUTH_BASE_URL = ZAPIER_AUTH_BASE_URL;
 exports.ZAPIER_AUTH_CLIENT_ID = ZAPIER_AUTH_CLIENT_ID;
 exports.ZAPIER_BASE_URL = ZAPIER_BASE_URL;