@zapier/zapier-sdk 0.4.1 → 0.5.1

package/src/sdk.test.ts

@@ -0,0 +1,212 @@
+// Test the flat plugin system
+import { describe, it, expect } from "vitest";
+import { createZapierSdk, createSdk } from "./sdk";
+import type { Plugin } from "./types/plugin";
+
+describe("Flat Plugin System", () => {
+  it("should create SDK with all expected methods", () => {
+    const sdk = createZapierSdk();
+
+    // Test that all core methods are available
+    expect(sdk.listApps).toBeDefined();
+    expect(sdk.listAuthentications).toBeDefined();
+    expect(sdk.getAuthentication).toBeDefined();
+    expect(sdk.runAction).toBeDefined();
+    expect(sdk.request).toBeDefined();
+
+    // Test that plugin methods are available
+    expect(sdk.fetch).toBeDefined();
+    expect(sdk.apps).toBeDefined();
+    expect(sdk.getProfile).toBeDefined();
+
+    // Test that getContext method is available
+    expect(sdk.getContext).toBeDefined();
+    expect(typeof sdk.getContext).toBe("function");
+  });
+
+  it("should have getContext method that returns context", () => {
+    const sdk = createZapierSdk();
+    const context = sdk.getContext() as any; // Type assertion to work around complex context inference
+
+    // Context should be an object
+    expect(typeof context).toBe("object");
+    expect(context).not.toBeNull();
+
+    // Context should have some properties (specific properties depend on plugin composition)
+    expect(Object.keys(context).length).toBeGreaterThan(0);
+
+    // Should have meta object
+    expect(context.meta).toBeDefined();
+    expect(typeof context.meta).toBe("object");
+
+    // Should have getProfile metadata from the plugin (verify it exists in meta)
+    expect("getProfile" in context.meta).toBe(true);
+    expect(context.meta.getProfile).toBeDefined();
+    expect(context.meta.getProfile.inputSchema).toBeDefined();
+  });
+
+  it("should have plugins return flat structure", () => {
+    const sdk = createZapierSdk();
+
+    // fetch should be directly available (not sdk.plugins.fetch or sdk.fetch.fetch)
+    expect(typeof sdk.fetch).toBe("function");
+
+    // apps should be directly available
+    expect(typeof sdk.apps).toBe("object");
+
+    // getProfile should be directly available
+    expect(typeof sdk.getProfile).toBe("function");
+  });
+
+  it("should support fluent plugin chaining with createSdk", () => {
+    // Test that createSdk().addPlugin().addPlugin() works and returns properly typed SDK
+    const testPlugin: Plugin<
+      {}, // no SDK dependencies
+      {}, // no context requirements
+      { testMethod: () => string }
+    > = () => ({
+      testMethod: () => "test result",
+    });
+
+    const sdk = createSdk().addPlugin(testPlugin);
+
+    // Should have getContext method
+    expect(typeof sdk.getContext).toBe("function");
+
+    // Should have addPlugin method for further chaining
+    expect(typeof sdk.addPlugin).toBe("function");
+
+    // Should have the plugin method
+    expect(typeof sdk.testMethod).toBe("function");
+    expect(sdk.testMethod()).toBe("test result");
+  });
+
+  it("should support fluent plugin chaining without .getSdk()", () => {
+    // This demonstrates the simplified API - no .getSdk() needed!
+    const plugin1: Plugin<
+      {}, // no SDK dependencies
+      {}, // no context requirements
+      { method1: () => string }
+    > = () => ({ method1: () => "method1" });
+
+    const plugin2: Plugin<
+      { method1: () => string }, // depends on method1 in SDK
+      {}, // no context requirements
+      { method2: () => string }
+    > = () => ({ method2: () => "method2" });
+
+    // Fluent chaining - each addPlugin returns a new SDK
+    const sdk = createSdk().addPlugin(plugin1).addPlugin(plugin2);
+
+    expect(sdk.method1()).toBe("method1");
+    expect(sdk.method2()).toBe("method2");
+    expect(typeof sdk.getContext).toBe("function");
+    expect(typeof sdk.addPlugin).toBe("function"); // Can still add more plugins!
+  });
+
+  it("should support plugins with options", () => {
+    // Test that addPlugin(pluginFn, options) works correctly
+    const pluginWithOptions: Plugin<
+      {}, // no SDK dependencies
+      {}, // no context requirements
+      { getMessage: () => string }
+    > = (params) => ({
+      getMessage: () => (params as any).message,
+    });
+
+    const sdk = createSdk().addPlugin(pluginWithOptions, {
+      message: "Hello from options!",
+    });
+
+    expect(typeof sdk.getMessage).toBe("function");
+    expect(sdk.getMessage()).toBe("Hello from options!");
+  });
+
+  it("should merge context.meta from multiple plugins", () => {
+    // Test that multiple plugins can provide meta without overwriting each other
+    const plugin1: Plugin<
+      {}, // no SDK dependencies
+      {}, // no context requirements
+      {
+        method1: () => string;
+        context: { meta: { plugin1: { info: string } } };
+      }
+    > = () => ({
+      method1: () => "method1",
+      context: {
+        meta: {
+          plugin1: { info: "Plugin 1 metadata" },
+        },
+      },
+    });
+
+    const plugin2: Plugin<
+      { method1: () => string }, // depends on method1 in SDK
+      {}, // no context requirements
+      {
+        method2: () => string;
+        context: { meta: { plugin2: { info: string } } };
+      }
+    > = () => ({
+      method2: () => "method2",
+      context: {
+        meta: {
+          plugin2: { info: "Plugin 2 metadata" },
+        },
+      },
+    });
+
+    const sdk = createSdk().addPlugin(plugin1).addPlugin(plugin2);
+    const context = sdk.getContext();
+
+    // Both plugins should have their meta preserved
+    expect(context.meta.plugin1.info).toBe("Plugin 1 metadata");
+    expect(context.meta.plugin2.info).toBe("Plugin 2 metadata");
+
+    // Both methods should work
+    expect(sdk.method1()).toBe("method1");
+    expect(sdk.method2()).toBe("method2");
+  });
+
+  it("should support context requirements for cleaner plugin definitions", () => {
+    // Test context requirements work correctly
+    const pluginWithHelper: Plugin<
+      { existingMethod: () => string }, // requires existingMethod in SDK
+      { customContext: string }, // requires customContext in context
+      { helperMethod: () => string }
+    > = ({ sdk, context }) => ({
+      helperMethod: () =>
+        `Helper: ${sdk.existingMethod()} + ${context.customContext}`,
+    });
+
+    const baseSdk = { existingMethod: () => "base" };
+    const baseContext = { customContext: "custom", meta: {} };
+    const sdk = createSdk(baseSdk, baseContext).addPlugin(pluginWithHelper);
+
+    expect(sdk.helperMethod()).toBe("Helper: base + custom");
+    expect(sdk.existingMethod()).toBe("base"); // Original method still works
+  });
+
+  it("should ensure context.meta is always available", () => {
+    // Test that context.meta is always at least an empty object, even without explicit initialization
+    const plugin: Plugin<
+      {}, // no SDK dependencies
+      {}, // no context requirements (meta is always guaranteed)
+      { testMethod: () => string }
+    > = ({ context }) => ({
+      testMethod: () => `Meta keys: ${Object.keys(context.meta).length}`,
+    });
+
+    // Create SDK without explicitly providing meta
+    const sdk = createSdk({}).addPlugin(plugin);
+
+    // Should work without error - meta should be at least an empty object
+    expect(sdk.testMethod()).toBe("Meta keys: 0");
+
+    // getContext() should also provide meta
+    const context = sdk.getContext();
+    expect(context.meta).toBeDefined();
+    expect(typeof context.meta).toBe("object");
+    expect(context.meta).not.toBeNull();
+  });
+});

package/src/sdk.ts

@@ -1,116 +1,146 @@
-import { createZapierApi } from "./api";
-import { BaseSdkOptions } from "./types/domain";
-// Import function implementations
-import { listApps } from "./functions/listApps";
-import { getApp } from "./functions/getApp";
-import { listActions } from "./functions/listActions";
-import { getAction } from "./functions/getAction";
-import { runAction } from "./functions/runAction";
-import { listAuthentications } from "./functions/listAuthentications";
-import { getAuthentication } from "./functions/getAuthentication";
-import { findFirstAuthentication } from "./functions/findFirstAuthentication";
-import { findUniqueAuthentication } from "./functions/findUniqueAuthentication";
-import { listFields } from "./functions/listFields";
-import { generateTypes } from "./functions/generateTypes";
-import { bundleCode } from "./functions/bundleCode";
-import { request } from "./functions/request";
-
-// Import function registry info objects (only for CLI registry)
-import { listAppsInfo } from "./functions/listApps/info";
-import { getAppInfo } from "./functions/getApp/info";
-import { listActionsInfo } from "./functions/listActions/info";
-import { getActionInfo } from "./functions/getAction/info";
-import { runActionInfo } from "./functions/runAction/info";
-import { listAuthenticationsInfo } from "./functions/listAuthentications/info";
-import { getAuthenticationInfo } from "./functions/getAuthentication/info";
-import { findFirstAuthenticationInfo } from "./functions/findFirstAuthentication/info";
-import { findUniqueAuthenticationInfo } from "./functions/findUniqueAuthentication/info";
-import { listFieldsInfo } from "./functions/listFields/info";
-import { generateTypesInfo } from "./functions/generateTypes/info";
-import { bundleCodeInfo } from "./functions/bundleCode/info";
-import { requestInfo } from "./functions/request/info";
-
-// Function registry as array - uses names from function info objects
-const functionRegistry = [
-  listAppsInfo,
-  getAppInfo,
-  listActionsInfo,
-  getActionInfo,
-  runActionInfo,
-  listAuthenticationsInfo,
-  getAuthenticationInfo,
-  findFirstAuthenticationInfo,
-  findUniqueAuthenticationInfo,
-  listFieldsInfo,
-  generateTypesInfo,
-  bundleCodeInfo,
-  requestInfo,
-];
+import { BaseSdkOptions } from "./types/sdk";
+// All function implementations now provided by plugins
+
+// All CLI registry info now provided by plugins
 
 // Import the properly typed SDK interfaces
-import type { BaseZapierSdk, ZapierSdk } from "./types/sdk";
+import type { ZapierSdk } from "./types/sdk";
+import type {
+  Sdk,
+  Plugin,
+  ExtractContextProperties,
+  PluginProvides,
+} from "./types/plugin";
 
 // Import plugin functions
-import { createAppsPlugin } from "./plugins/apps/index";
-import { createFetchPlugin } from "./plugins/fetch/index";
-
-// TODO: Add plugin registry back when needed for CLI compatibility
+import { appsPlugin } from "./plugins/apps/index";
+import { fetchPlugin } from "./plugins/fetch/index";
+import { registryPlugin } from "./plugins/registry/index";
+import { apiPlugin } from "./plugins/api/index";
+import { getProfilePlugin } from "./plugins/getProfile";
+import { listAppsPlugin } from "./plugins/listApps";
+import { getAppPlugin } from "./plugins/getApp";
+import { listActionsPlugin } from "./plugins/listActions";
+import { getActionPlugin } from "./plugins/getAction";
+import { runActionPlugin } from "./plugins/runAction";
+import { listAuthenticationsPlugin } from "./plugins/listAuthentications";
+import { getAuthenticationPlugin } from "./plugins/getAuthentication";
+import { findFirstAuthenticationPlugin } from "./plugins/findFirstAuthentication";
+import { findUniqueAuthenticationPlugin } from "./plugins/findUniqueAuthentication";
+import { listInputFieldsPlugin } from "./plugins/listInputFields";
+import { requestPlugin } from "./plugins/request";
 
 // Full SDK interface with plugins applied
-export type { ZapierSdk } from "./types/sdk";
+// Note: ZapierSdk is now defined as ReturnType<typeof createZapierSdk> at the bottom of this file
 
 export interface ZapierSdkOptions extends BaseSdkOptions {}
 
-export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
-  const {
-    fetch: customFetch = globalThis.fetch,
-    baseUrl = "https://zapier.com",
-    token,
-    getToken,
-    onEvent,
-    debug = false,
-  } = options;
-
-  // Create the API client - it will handle token resolution internally
-  const api = createZapierApi({
-    baseUrl,
-    token,
-    getToken,
-    debug,
-    fetch: customFetch,
-    onEvent,
-  });
-
-  // Create base SDK with core functions only - TypeScript will enforce completeness
-  const baseSdk: BaseZapierSdk = {
-    // Registry for CLI
-    __registry: functionRegistry,
-
-    // Function implementations with API config injection
-    listApps: (options = {}) => listApps({ ...options, api }),
-    getApp: (options) => getApp({ ...options, api }),
-    listActions: (options = {}) => listActions({ ...options, api }),
-    getAction: (options) => getAction({ ...options, api }),
-    runAction: (options) => runAction({ ...options, api }),
-    listAuthentications: (options = {}) =>
-      listAuthentications({ ...options, api }),
-    getAuthentication: (options) => getAuthentication({ ...options, api }),
-    findFirstAuthentication: (options = {}) =>
-      findFirstAuthentication({ ...options, api }),
-    findUniqueAuthentication: (options = {}) =>
-      findUniqueAuthentication({ ...options, api }),
-    listFields: (options) => listFields({ ...options, api }),
-    generateTypes: (options) => generateTypes({ ...options, api }),
-    bundleCode: (options) => bundleCode(options), // No API config needed
-    request: (options) => request({ ...options, api }),
+// Create SDK that supports flat plugins - returns an SDK, not a builder
+export function createSdk<
+  TCurrentSdk = {},
+  TCurrentContext = { meta: Record<string, any> },
+>(
+  initialSdk: TCurrentSdk = {} as TCurrentSdk,
+  initialContext: TCurrentContext = { meta: {} } as TCurrentContext,
+): Sdk<TCurrentSdk, TCurrentContext> {
+  return {
+    ...initialSdk,
+    getContext: () => initialContext,
+    addPlugin<TRequiresContext, TProvides extends PluginProvides>(
+      plugin: Plugin<
+        TCurrentSdk & { getContext(): TCurrentContext },
+        TRequiresContext,
+        TProvides
+      >,
+      options: any = {},
+    ) {
+      // Create SDK with getContext method for plugins to use
+      const currentSdkWithContext = {
+        ...initialSdk,
+        getContext: () => initialContext,
+      } as TCurrentSdk & { getContext(): TCurrentContext };
+
+      // Apply the plugin with options merged in
+      const pluginResult = plugin({
+        sdk: currentSdkWithContext,
+        context: initialContext,
+        ...options,
+      });
+
+      // Extract context from plugin result if present
+      const { context: pluginContext, ...sdkProperties } = pluginResult;
+
+      // Merge SDK properties directly (flat structure)
+      const newSdk = { ...initialSdk, ...sdkProperties };
+
+      // Merge context additions if plugin returned any
+      // Ensure meta is always present, starting with existing or empty object
+      let newContext = {
+        ...initialContext,
+        meta: (initialContext as any).meta || {},
+      } as TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>;
+
+      if (pluginContext) {
+        // Extract meta from plugin context for special merging
+        const { meta: pluginMeta, ...otherPluginContext } = pluginContext;
+
+        newContext = {
+          ...newContext,
+          ...otherPluginContext,
+        } as TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>;
+
+        // Merge meta separately to avoid overwriting
+        if (pluginMeta) {
+          newContext = {
+            ...newContext,
+            meta: {
+              ...newContext.meta, // Existing meta (now guaranteed to exist)
+              ...pluginMeta, // New meta from plugin
+            },
+          } as TCurrentContext &
+            NonNullable<ExtractContextProperties<TProvides>>;
+        }
+      }
+
+      // Recursively create new SDK with updated properties
+      return createSdk(newSdk, newContext) as any;
+    },
   };
+}
+
+export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
+  return (
+    createSdk()
+      // Provides the API client in context
+      .addPlugin(apiPlugin, options)
+
+      // Apps/actions/fields
+      .addPlugin(listAppsPlugin)
+      .addPlugin(getAppPlugin)
+      .addPlugin(listActionsPlugin)
+      .addPlugin(getActionPlugin)
+      .addPlugin(listInputFieldsPlugin)
+
+      // Run action
+      .addPlugin(runActionPlugin)
+
+      // Authentications
+      .addPlugin(listAuthenticationsPlugin)
+      .addPlugin(getAuthenticationPlugin)
+      .addPlugin(findFirstAuthenticationPlugin)
+      .addPlugin(findUniqueAuthenticationPlugin)
+
+      // Relay fetching
+      .addPlugin(requestPlugin)
+      .addPlugin(fetchPlugin)
 
-  // Mutate baseSdk to add plugins so they can access each other
-  const fullSdk = baseSdk as ZapierSdk;
+      // Magic apps plugin
+      .addPlugin(appsPlugin)
 
-  // Add plugins to the SDK - they now have access to the full SDK including other plugins
-  fullSdk.apps = createAppsPlugin({ sdk: fullSdk });
-  fullSdk.fetch = createFetchPlugin({ sdk: fullSdk });
+      // Profile
+      .addPlugin(getProfilePlugin)
 
-  return fullSdk;
+      // Register plugins for CLI/MCP metadata
+      .addPlugin(registryPlugin)
+  );
 }

package/src/types/domain.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { splitVersionedKey } from "../utils/domain-utils";
+
+describe("splitVersionedKey", () => {
+  it("should split versioned key with version", () => {
+    const [baseKey, version] = splitVersionedKey("SlackCLIAPI@1.21.1");
+    expect(baseKey).toBe("SlackCLIAPI");
+    expect(version).toBe("1.21.1");
+  });
+
+  it("should split versioned key with complex version", () => {
+    const [baseKey, version] = splitVersionedKey(
+      "GoogleSheetsAPI@2.5.0-beta.1",
+    );
+    expect(baseKey).toBe("GoogleSheetsAPI");
+    expect(version).toBe("2.5.0-beta.1");
+  });
+
+  it("should handle versioned key without version", () => {
+    const [baseKey, version] = splitVersionedKey("SomeAPI");
+    expect(baseKey).toBe("SomeAPI");
+    expect(version).toBeUndefined();
+  });
+
+  it("should handle versioned key with multiple @ symbols", () => {
+    const [baseKey, version] = splitVersionedKey("ComplexAPI@1.0.0@beta");
+    expect(baseKey).toBe("ComplexAPI");
+    expect(version).toBe("1.0.0@beta");
+  });
+
+  it("should handle edge case with many @ symbols", () => {
+    const [baseKey, version] = splitVersionedKey(
+      "API@with@multiple@at@symbols@1.2.3",
+    );
+    expect(baseKey).toBe("API");
+    expect(version).toBe("with@multiple@at@symbols@1.2.3");
+  });
+
+  it("should handle empty string", () => {
+    const [baseKey, version] = splitVersionedKey("");
+    expect(baseKey).toBe("");
+    expect(version).toBeUndefined();
+  });
+
+  it("should handle string that starts with @", () => {
+    const [baseKey, version] = splitVersionedKey("@version");
+    expect(baseKey).toBe("");
+    expect(version).toBe("version");
+  });
+});

package/src/types/domain.ts

@@ -1,75 +1,43 @@
-// Re-export API types from the API module
-export type {
-  Integration,
-  Action,
-  Trigger,
-  Field,
-  Choice,
-  ActionExecutionResult,
-  ActionField,
-  ActionFieldChoice,
-  NeedsRequest,
-  NeedsResponse,
-  Authentication,
-  AuthenticationsResponse,
-} from "../api/types";
-
-// Import event types
-import type { EventCallback } from "./events";
-
-// SDK Configuration Types
-export interface ActionExecutionOptions {
-  inputs?: Record<string, any>;
-  authenticationId?: number;
-}
-
-export interface AuthObject {
-  id: number;
-}
-
-export interface BaseSdkOptions {
-  token?: string;
-  getToken?: () => Promise<string | undefined>;
-  onEvent?: EventCallback;
-  fetch?: typeof fetch;
-  baseUrl?: string;
-  debug?: boolean;
-}
-
-// Common options shared across all function types
-export interface FunctionOptions {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Function to dynamically resolve authentication token */
-  getToken?: () => Promise<string | undefined>;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-}
-
-// Error Classes
-export class ZapierSdkError extends Error {
-  constructor(
-    message: string,
-    public code?: string,
-  ) {
-    super(message);
-    this.name = "ZapierSdkError";
-  }
-}
-
-export class AppNotFoundError extends ZapierSdkError {
-  appKey: string;
-
-  constructor(appKey: string) {
-    super(`App "${appKey}" not found`);
-    this.name = "AppNotFoundError";
-    this.code = "APP_NOT_FOUND";
-    this.appKey = appKey;
-  }
-}
+import type { z } from "zod";
+
+/**
+ * Domain model types - representing business entities returned by SDK functions
+ * These types are inferred from Item schemas and represent transformed/formatted data.
+ */
+
+// Import schemas to infer types from
+import type { AppItemSchema } from "../schemas/App";
+import type { AuthenticationItemSchema } from "../schemas/Auth";
+import type { ActionItemSchema } from "../schemas/Action";
+import type { InputFieldItemSchema } from "../schemas/Field";
+import type { UserProfileItemSchema } from "../schemas/UserProfile";
+
+/**
+ * Represents an app item returned by getApp and listApps functions
+ * Inferred from AppItemSchema which extends the base App API schema
+ */
+export type AppItem = z.infer<typeof AppItemSchema>;
+
+/**
+ * Represents an authentication item returned by listAuthentications functions
+ * Inferred from AuthenticationItemSchema which extends the base Authentication API schema
+ */
+export type AuthenticationItem = z.infer<typeof AuthenticationItemSchema>;
+
+/**
+ * Represents an action item returned by listActions functions
+ * Inferred from ActionItemSchema which extends the base Action API schema
+ */
+export type ActionItem = z.infer<typeof ActionItemSchema>;
+
+/**
+ * Represents an input field item returned by listInputFields functions
+ * Inferred from InputFieldItemSchema which extends the base Need API schema
+ */
+export type InputFieldItem = z.infer<typeof InputFieldItemSchema>;
+
+/**
+ * Represents a user profile item returned by getProfile function
+ * Inferred from UserProfileItemSchema which extends the base UserProfile API schema
+ */
+export type UserProfileItem = z.infer<typeof UserProfileItemSchema>;