@zapier/zapier-sdk 0.4.1 → 0.5.0

package/src/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * SDK Constants
+ *
+ * This module contains shared constants used throughout the SDK.
+ */
+
+/**
+ * Maximum number of items that can be requested per page across all paginated functions
+ */
+export const MAX_PAGE_LIMIT = 10000;

package/src/index.ts

@@ -1,11 +1,31 @@
 // Export everything from types and plugins
 export * from "./types/domain";
+export * from "./types/functions";
 export * from "./types/properties";
+export * from "./types/errors";
 export * from "./plugins/apps";
 export * from "./plugins/fetch";
 
+// Export API types directly (no longer re-exported from domain)
+export type {
+  Action,
+  App,
+  Need,
+  Field,
+  Choice,
+  ActionExecutionResult,
+  ActionField,
+  ActionFieldChoice,
+  NeedsRequest,
+  NeedsResponse,
+  Authentication,
+  AuthenticationsResponse,
+  UserProfile,
+} from "./api/types";
+
 // Export schema utilities for CLI
-export { isPositional } from "./schema-utils";
+export { isPositional } from "./utils/schema-utils";
+export { hasResolver } from "./resolvers";
 
 // Export auth utilities for CLI use
 export * from "./auth";
@@ -15,27 +35,28 @@ export * from "./resolvers";
 
 // Note: SdkSchemas is now available via SDK.__registry
 
-// Export individual functions for tree-shaking
-export { listAuthentications } from "./functions/listAuthentications";
-export { getAuthentication } from "./functions/getAuthentication";
-export { findFirstAuthentication } from "./functions/findFirstAuthentication";
-export { findUniqueAuthentication } from "./functions/findUniqueAuthentication";
-export { listApps } from "./functions/listApps";
-export { getApp } from "./functions/getApp";
-export { listActions } from "./functions/listActions";
-export { getAction } from "./functions/getAction";
-export { runAction } from "./functions/runAction";
-export { listFields } from "./functions/listFields";
-export { generateTypes } from "./functions/generateTypes";
-export { bundleCode } from "./functions/bundleCode";
-export { request, relayFetch } from "./functions/request";
+// All functions now available through the plugin system via createZapierSdk()
+// Export plugin schemas for external use
 export {
   RelayRequestSchema,
   RelayFetchSchema,
-} from "./functions/request/schemas";
+} from "./plugins/request/schemas";
 
-// Export the main combined SDK
-export { createZapierSdk, ZapierSdkOptions } from "./sdk";
+// Export the main combined SDK and new flexible SDK creator
+export { createZapierSdk, createSdk, ZapierSdkOptions } from "./sdk";
 
 // Export SDK types from types (not sdk.ts to avoid circular imports)
-export type { BaseZapierSdk, ZapierSdk } from "./types/sdk";
+export type { FunctionRegistryEntry } from "./types/sdk";
+
+// Export plugin utilities and SDK types
+export type {
+  Plugin,
+  PluginProvides,
+  PluginDependencies,
+  PluginOptions,
+  GetSdkType,
+  Sdk,
+} from "./types/plugin";
+
+// Export ZapierSdk from sdk.ts (it's now ReturnType<typeof createZapierSdk>)
+export type { ZapierSdk } from "./types/sdk";

package/src/plugins/api/index.ts

@@ -0,0 +1,47 @@
+import { createZapierApi } from "../../api";
+import type { ApiClient } from "../../api/types";
+import type { BaseSdkOptions } from "../../types/sdk";
+import type { Plugin } from "../../types/plugin";
+
+export interface ApiPluginOptions extends BaseSdkOptions {}
+
+// API plugin only provides context, no SDK methods
+export interface ApiPluginProvides {
+  context: {
+    api: ApiClient;
+  };
+}
+
+// API plugin requires no context and provides api in context
+export const apiPlugin: Plugin<
+  {}, // no SDK dependencies
+  {}, // requires no context
+  ApiPluginProvides
+> = (params) => {
+  // Extract all options - everything passed to the plugin
+  const {
+    fetch: customFetch = globalThis.fetch,
+    baseUrl = "https://zapier.com",
+    token,
+    getToken,
+    onEvent,
+    debug = false,
+  } = params as any;
+
+  // Create the API client - it will handle token resolution internally
+  const api = createZapierApi({
+    baseUrl,
+    token,
+    getToken,
+    debug,
+    fetch: customFetch,
+    onEvent,
+  });
+
+  // Return flat structure with context only
+  return {
+    context: {
+      api, // Provide API client in context for other plugins to use
+    },
+  };
+};

package/src/plugins/apps/index.ts

@@ -1,12 +1,16 @@
-import {
-  ActionExecutionOptions,
-  ActionExecutionResult,
-} from "../../types/domain";
+import { ActionExecutionOptions } from "./types";
 import type { ActionProxy } from "./types";
-import type { ZapierSdk } from "../../types/sdk";
+import { ZapierValidationError } from "../../types/errors";
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { FetchPluginProvides } from "../fetch/index";
+import type { RunActionPluginProvides } from "../runAction/index";
 
-export interface AppsPluginOptions {
-  sdk: ZapierSdk;
+export interface AppsPluginProvides {
+  apps: ActionProxy;
+}
+
+interface AppsPluginOptions {
+  sdk: GetSdkType<FetchPluginProvides & RunActionPluginProvides>;
 }
 
 interface AppFactoryOptions {
@@ -20,9 +24,7 @@ function createActionFunction(
   options: AppsPluginOptions,
   pinnedAuthId?: number,
 ) {
-  return async (
-    actionOptions: ActionExecutionOptions = {},
-  ): Promise<ActionExecutionResult> => {
+  return (actionOptions: ActionExecutionOptions = {}): any => {
     const { sdk } = options;
     const { inputs, authenticationId: providedAuthenticationId } =
       actionOptions;
@@ -31,7 +33,7 @@ function createActionFunction(
     const authenticationId = pinnedAuthId || providedAuthenticationId;
 
     if (!authenticationId) {
-      throw new Error(
+      throw new ZapierValidationError(
         `Authentication ID is required. Either use the factory pattern: sdk.apps.${appKey}({ authenticationId }) or provide authenticationId in the action call.`,
       );
     }
@@ -69,7 +71,7 @@ function createActionTypeProxy(
       const authenticationId = pinnedAuthId || init?.authenticationId;
 
       if (!authenticationId) {
-        throw new Error(
+        throw new ZapierValidationError(
           `Authentication ID is required for fetch. Either use the factory pattern: sdk.apps.${appKey}({ authenticationId }).fetch(...) or provide authenticationId in the fetch call.`,
         );
       }
@@ -160,10 +162,14 @@ function createAppsProxy(options: AppsPluginOptions): ActionProxy {
   return appsProxy;
 }
 
-// Export the plugin creation function
-export function createAppsPlugin(options: AppsPluginOptions): ActionProxy {
-  return createAppsProxy(options);
-}
-
-// Re-export types
-export type { ActionProxy, AppsPluginSdkExtension } from "./types";
+// Direct plugin function - takes options + sdk + context in one object
+export const appsPlugin: Plugin<
+  GetSdkType<FetchPluginProvides & RunActionPluginProvides>, // requires fetch + runAction in SDK
+  {}, // no context requirements
+  AppsPluginProvides
+> = ({ sdk }) => {
+  // Return flat structure - apps goes directly to SDK
+  return {
+    apps: createAppsProxy({ sdk }),
+  };
+};

package/src/plugins/apps/types.ts

@@ -1,7 +1,8 @@
-import type {
-  ActionExecutionOptions,
-  ActionExecutionResult,
-} from "../../types/domain";
+// Apps plugin-specific execution options
+export interface ActionExecutionOptions {
+  inputs?: Record<string, any>;
+  authenticationId?: number;
+}
 
 interface AppFactoryOptions {
   authenticationId: number;
@@ -9,9 +10,7 @@ interface AppFactoryOptions {
 
 // Base action type proxy for regular actions
 interface BaseActionTypeProxy {
-  [action: string]: (
-    options?: ActionExecutionOptions,
-  ) => Promise<ActionExecutionResult>;
+  [action: string]: (options?: ActionExecutionOptions) => any;
 }
 
 // Special fetch function type
@@ -44,7 +43,4 @@ export interface ActionProxy {
   [app: string]: AppProxyWithFactory;
 }
 
-// Plugin interface - ready to be mixed into main SDK interface
-export interface AppsPluginSdkExtension {
-  apps: ActionProxy;
-}
+// Note: AppsPluginSdkExtension removed - now using AppsPluginProvides in index.ts

package/src/plugins/fetch/index.ts

@@ -1,44 +1,8 @@
-import type { ZapierSdk } from "../../types/sdk";
+import { RelayRequestOptions } from "../request/schemas";
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { RequestPluginProvides } from "../request";
 
-export interface FetchPluginOptions {
-  sdk: ZapierSdk;
-}
-
-/**
- * Creates a fetch function with standard fetch signature that delegates to sdk.request
- */
-export function createFetchPlugin(options: FetchPluginOptions) {
-  const { sdk } = options;
-
-  return async function fetch(
-    url: string | URL,
-    init?: RequestInit & {
-      authenticationId?: number;
-      callbackUrl?: string;
-      authenticationTemplate?: string;
-    },
-  ): Promise<Response> {
-    const {
-      authenticationId,
-      callbackUrl,
-      authenticationTemplate,
-      ...fetchInit
-    } = init || {};
-
-    return sdk.request({
-      url: url.toString(),
-      method: fetchInit.method as any,
-      body: fetchInit.body as any,
-      headers: fetchInit.headers as any,
-      authenticationId,
-      callbackUrl,
-      authenticationTemplate,
-    });
-  };
-}
-
-// Export types for TypeScript
-export interface FetchPluginSdkExtension {
+export interface FetchPluginProvides {
   fetch: (
     url: string | URL,
     init?: RequestInit & {
@@ -48,3 +12,47 @@ export interface FetchPluginSdkExtension {
     },
   ) => Promise<Response>;
 }
+
+/**
+ * Direct plugin function - takes options + sdk + context in one object
+ */
+export const fetchPlugin: Plugin<
+  GetSdkType<RequestPluginProvides>, // requires request in SDK
+  {}, // requires no context (uses SDK methods)
+  FetchPluginProvides
+> = ({ sdk }) => {
+  // Return flat structure - fetch goes directly to SDK
+  return {
+    fetch: async function fetch(
+      url: string | URL,
+      init?: RequestInit & {
+        authenticationId?: number;
+        callbackUrl?: string;
+        authenticationTemplate?: string;
+      },
+    ): Promise<Response> {
+      const {
+        authenticationId,
+        callbackUrl,
+        authenticationTemplate,
+        ...fetchInit
+      } = init || {};
+
+      return sdk.request({
+        url: url.toString(),
+        method: fetchInit.method as RelayRequestOptions["method"],
+        body: fetchInit.body,
+        headers: fetchInit.headers,
+        authenticationId,
+        callbackUrl,
+        authenticationTemplate,
+      });
+    },
+  };
+};
+
+export type ZapierFetchInitOptions = RequestInit & {
+  authenticationId?: number;
+  callbackUrl?: string;
+  authenticationTemplate?: string;
+};

package/src/plugins/findFirstAuthentication/index.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ZapierValidationError } from "../../types/errors";
+import { findFirstAuthenticationPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { AuthenticationItem } from "../../types/domain";
+import { ListAuthenticationsSchema } from "../listAuthentications/schemas";
+
+const mockAuthentications: AuthenticationItem[] = [
+  {
+    id: 123,
+    title: "My Slack",
+    date: "2021-01-01",
+    account_id: 123,
+    implementation_id: "api_123",
+    is_expired: "false",
+    expired_at: null,
+    is_invite_only: false,
+    is_private: false,
+    shared_with_all: false,
+  },
+  {
+    id: 456,
+    title: "Slack Workspace 2",
+    is_expired: "false",
+    expired_at: null,
+    date: "2021-01-01",
+    account_id: 123,
+    implementation_id: "api_123",
+    is_invite_only: false,
+    is_private: false,
+    shared_with_all: false,
+  },
+];
+
+describe("findFirstAuthentication plugin", () => {
+  let mockListAuthentications: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListAuthentications = vi.fn().mockResolvedValue({
+      data: mockAuthentications,
+    });
+  });
+
+  function createTestSdk() {
+    // Create a proper plugin chain: first add a mock listAuthentications plugin, then add findFirstAuthentication
+    const mockListAuthenticationsPlugin = () => ({
+      listAuthentications: mockListAuthentications,
+      context: {
+        meta: {
+          listAuthentications: {
+            inputSchema: ListAuthenticationsSchema,
+          },
+        },
+      },
+    });
+
+    // Build SDK with proper plugin composition
+    return createSdk()
+      .addPlugin(mockListAuthenticationsPlugin)
+      .addPlugin(findFirstAuthenticationPlugin);
+  }
+
+  describe("schema validation", () => {
+    it("should pass validation with empty options", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({});
+      expect(result.data).toBeDefined();
+    });
+
+    it("should pass validation with undefined options", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication();
+      expect(result.data).toBeDefined();
+    });
+
+    it("should throw validation error for invalid appKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          appKey: 123 as any, // intentionally wrong type for testing
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid search type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          search: 123 as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid parameter types", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          title: 123 as any,
+          account_id: 456 as any,
+          owner: true as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all valid fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "slack",
+        search: "workspace",
+        title: "My Slack Workspace",
+        account_id: "acc_123",
+        owner: "me",
+      });
+
+      expect(result.data).toBeDefined();
+    });
+  });
+
+  describe("business logic", () => {
+    it("should return first authentication when found", async () => {
+      const mockAuth = mockAuthentications[0];
+      mockListAuthentications.mockResolvedValue({
+        data: [mockAuth],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "slack",
+      });
+
+      expect(result.data).toEqual(mockAuth);
+    });
+
+    it("should return null when no authentications found", async () => {
+      mockListAuthentications.mockResolvedValue({
+        data: [],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "nonexistent",
+      });
+
+      expect(result.data).toBeNull();
+    });
+
+    it("should return first authentication when multiple found", async () => {
+      const mockAuth = mockAuthentications[0];
+      mockListAuthentications.mockResolvedValue({
+        data: [mockAuth, mockAuthentications[1]],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        search: "Slack",
+      });
+
+      expect(result.data).toEqual(mockAuth);
+    });
+  });
+
+  describe("options forwarding", () => {
+    it("should forward all options to listAuthentications", async () => {
+      const sdk = createTestSdk();
+      const options = {
+        appKey: "slack",
+        search: "workspace",
+        title: "My Slack Workspace",
+        account_id: "acc_123",
+        owner: "me",
+      };
+
+      await sdk.findFirstAuthentication(options);
+
+      expect(mockListAuthentications).toHaveBeenCalledWith({
+        ...options,
+        maxItems: 1,
+      });
+    });
+  });
+
+  describe("limit enforcement", () => {
+    it("should automatically set maxItems to 1", async () => {
+      const sdk = createTestSdk();
+      await sdk.findFirstAuthentication({
+        appKey: "slack",
+      });
+
+      expect(mockListAuthentications).toHaveBeenCalledWith({
+        appKey: "slack",
+        maxItems: 1,
+      });
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect(context.meta.findFirstAuthentication).toBeDefined();
+      expect(context.meta.findFirstAuthentication.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/findFirstAuthentication/index.ts

@@ -0,0 +1,55 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { AuthenticationItem } from "../../types/domain";
+import {
+  FindFirstAuthenticationSchema,
+  type FindFirstAuthenticationOptions,
+} from "./schemas";
+import { createFunction } from "../../utils/function-utils";
+import type { ListAuthenticationsPluginProvides } from "../listAuthentications";
+
+export interface FindFirstAuthenticationPluginProvides {
+  findFirstAuthentication: (
+    options?: FindFirstAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem | null }>;
+  context: {
+    meta: {
+      findFirstAuthentication: {
+        inputSchema: typeof FindFirstAuthenticationSchema;
+      };
+    };
+  };
+}
+
+export const findFirstAuthenticationPlugin: Plugin<
+  GetSdkType<ListAuthenticationsPluginProvides>, // requires listAuthentications in SDK
+  {}, // no context requirements
+  FindFirstAuthenticationPluginProvides
+> = ({ sdk }) => {
+  const findFirstAuthentication = createFunction(
+    async function findFirstAuthentication(
+      options: FindFirstAuthenticationOptions = {},
+    ) {
+      // Use listAuthentications with maxItems 1 to get the first result
+      const authsResponse = await sdk.listAuthentications({
+        ...options,
+        maxItems: 1,
+      });
+
+      return {
+        data: authsResponse.data.length > 0 ? authsResponse.data[0] : null,
+      };
+    },
+    FindFirstAuthenticationSchema,
+  );
+
+  return {
+    findFirstAuthentication,
+    context: {
+      meta: {
+        findFirstAuthentication: {
+          inputSchema: FindFirstAuthenticationSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/findFirstAuthentication/schemas.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { AuthenticationItem } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const FindFirstAuthenticationSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.optional().describe(
+      "App key of authentication to find (e.g., 'SlackCLIAPI')",
+    ),
+    search: z
+      .string()
+      .optional()
+      .describe("Search term to filter authentications by title"),
+    title: z
+      .string()
+      .optional()
+      .describe("Filter authentications by exact title match"),
+    account_id: z.string().optional().describe("Filter by account ID"),
+    owner: z.string().optional().describe("Filter by owner"),
+  })
+  .describe("Find the first authentication matching the criteria");
+
+// Type inferred from schema
+export type FindFirstAuthenticationOptions = z.infer<
+  typeof FindFirstAuthenticationSchema
+>;
+
+// Error union for this function (inherits from listAuthenticationsSafe)
+export type FindFirstAuthenticationError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface
+export interface FindFirstAuthenticationSdkFunction {
+  findFirstAuthentication: (
+    options?: FindFirstAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem | null }>;
+}