@zapier/zapier-sdk 0.5.1 → 0.6.0

package/src/plugins/registry/index.ts

@@ -3,9 +3,16 @@ import { FunctionRegistryEntry } from "../../types/sdk";
 
 export interface RegisterPluginFunctionOptions {}
 
-// Registry plugin creates and populates __registry for CLI backward compatibility
 export interface RegistryPluginProvides {
-  __registry: FunctionRegistryEntry[];
+  getRegistry: () => {
+    functions: FunctionRegistryEntry[];
+    categories: {
+      key: string;
+      title: string;
+      titlePlural: string;
+      functions: string[];
+    }[];
+  };
 }
 
 // Registry plugin requires no context but collects SDK metadata
@@ -16,15 +23,89 @@ export const registryPlugin: Plugin<
 > = ({ sdk, context }) => {
   const metaKeys = Object.keys(context.meta || {});
 
-  const registryEntries = metaKeys.map((key) => {
+  const categoryDefinitions: Record<
+    string,
+    { title: string; titlePlural?: string }
+  > = {
+    app: {
+      title: "App",
+      titlePlural: "Apps",
+    },
+    authentication: {
+      title: "Authentication",
+    },
+    action: {
+      title: "Action",
+    },
+    http: {
+      title: "HTTP Request",
+    },
+    user: {
+      title: "User",
+    },
+    utility: {
+      title: "Utility",
+      titlePlural: "Utilities",
+    },
+    other: {
+      title: "Other",
+    },
+  };
+
+  const functions = metaKeys
+    .filter((key) => typeof sdk[key as keyof typeof sdk] === "function")
+    .map((key) => {
+      return {
+        ...context.meta[key],
+        categories: context.meta[key].categories || [],
+        name: key,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const knownCategories = Object.keys(categoryDefinitions);
+
+  const categories = knownCategories
+    .sort((a, b) => {
+      // Keep "other" category last
+      if (a === "other") return 1;
+      if (b === "other") return -1;
+      // Alphabetize by title, not key
+      const titleA = categoryDefinitions[a].title;
+      const titleB = categoryDefinitions[b].title;
+      return titleA.localeCompare(titleB);
+    })
+    .map((categoryKey) => {
+      // Find the functions that are in this category
+      const categoryFunctions = functions
+        .filter(
+          (f) =>
+            f.categories.includes(categoryKey) ||
+            // If the category is "other" and the function is not in any other category, include it
+            (categoryKey === "other" &&
+              !f.categories.some((c) => knownCategories.includes(c))),
+        )
+        .map((f) => f.name)
+        .sort(); // Alphabetize functions within each category
+
+      const definition = categoryDefinitions[categoryKey];
+      const title = definition.title;
+      return {
+        key: categoryKey,
+        title,
+        titlePlural: definition.titlePlural ?? `${title}s`,
+        functions: categoryFunctions,
+      };
+    });
+
+  function getRegistry() {
     return {
-      ...context.meta[key],
-      name: key,
-      implementation: sdk[key as keyof typeof sdk],
+      functions,
+      categories,
     };
-  });
+  }
 
   return {
-    __registry: registryEntries,
+    getRegistry,
   };
 };

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

@@ -2,8 +2,8 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { ZapierValidationError } from "../../types/errors";
 import { requestPlugin } from "./index";
 import { createSdk } from "../../sdk";
-import type { ApiClient } from "../../api";
 import type { RelayRequestOptions } from "./schemas";
+import type { ApiClient } from "../../api";
 
 describe("request plugin", () => {
   let mockApiClient: ApiClient;
@@ -23,10 +23,14 @@ describe("request plugin", () => {
     } as Partial<ApiClient> as ApiClient;
   });
 
+  const apiPlugin = () => ({
+    context: {
+      api: mockApiClient,
+    },
+  });
+
   function createTestSdk() {
-    return createSdk({}, { api: mockApiClient, meta: {} }).addPlugin(
-      requestPlugin,
-    );
+    return createSdk().addPlugin(apiPlugin).addPlugin(requestPlugin);
   }
 
   describe("schema validation", () => {

package/src/plugins/request/index.ts

@@ -95,6 +95,7 @@ export const requestPlugin: Plugin<
     context: {
       meta: {
         request: {
+          categories: ["http"],
           inputSchema: RelayRequestSchema,
         },
       },

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

@@ -44,16 +44,17 @@ describe("runAction plugin", () => {
     mockGetAction = vi.fn().mockResolvedValue({
       data: mockAction,
     });
-
-    mockGetApp = vi.fn().mockResolvedValue({
-      data: { current_implementation_id: "SlackCLIAPI" },
-    });
   });
 
   function createTestSdk() {
     return createSdk(
+      {},
       { getAction: mockGetAction, getApp: mockGetApp }, // Provide getAction and getApp in SDK
-      { api: mockApiClient, meta: {} },
+      {
+        api: mockApiClient,
+        meta: {},
+        getVersionedImplementationId: () => "SlackCLIAPI@1.21.1",
+      },
     ).addPlugin(runActionPlugin as any);
   }
 
@@ -151,7 +152,7 @@ describe("runAction plugin", () => {
 
       expect(mockApiClient.post).toHaveBeenCalledWith("/api/actions/v1/runs", {
         data: {
-          selected_api: "SlackCLIAPI",
+          selected_api: "SlackCLIAPI@1.21.1",
           action_key: "send_message",
           action_type: "write",
           inputs: { message: "Hello", channel: "#general" },
@@ -180,7 +181,7 @@ describe("runAction plugin", () => {
 
       expect(mockApiClient.post).toHaveBeenCalledWith("/api/actions/v1/runs", {
         data: {
-          selected_api: "SlackCLIAPI",
+          selected_api: "SlackCLIAPI@1.21.1",
           action_key: "send_message",
           action_type: "write",
           inputs: { message: "Hello" },
@@ -206,7 +207,7 @@ describe("runAction plugin", () => {
         expect.objectContaining({
           data: expect.objectContaining({
             inputs: { message: "Hello" },
-            selected_api: "SlackCLIAPI",
+            selected_api: "SlackCLIAPI@1.21.1",
             action_key: "send_message",
             action_type: "write",
           }),

package/src/plugins/runAction/index.ts

@@ -13,6 +13,7 @@ import {
 import { createPaginatedFunction } from "../../utils/function-utils";
 import type { GetActionPluginProvides } from "../getAction";
 import type { GetAppPluginProvides } from "../getApp";
+import { GetVersionedImplementationId } from "../manifest/schemas";
 
 export interface RunActionPluginProvides {
   runAction: (options?: RunActionOptions) => Promise<{ data: any[] }> &
@@ -30,7 +31,9 @@ export interface RunActionPluginProvides {
 
 interface ExecuteActionOptions {
   api: ApiClient;
-  sdk: GetSdkType<GetActionPluginProvides & GetAppPluginProvides>;
+  context: {
+    getVersionedImplementationId: GetVersionedImplementationId;
+  };
   appKey: string;
   actionKey: string;
   actionType: string;
@@ -45,7 +48,7 @@ async function executeAction(actionOptions: ExecuteActionOptions): Promise<{
 }> {
   const {
     api,
-    sdk,
+    context,
     appKey,
     actionKey,
     actionType,
@@ -53,9 +56,8 @@ async function executeAction(actionOptions: ExecuteActionOptions): Promise<{
     authenticationId,
   } = actionOptions;
 
-  // Use the getApp plugin to get the current implementation ID
-  const appData = await sdk.getApp({ appKey });
-  const selectedApi = appData.data.current_implementation_id;
+  // Use the manifest plugin to get the current implementation ID
+  const selectedApi = await context.getVersionedImplementationId(appKey);
 
   if (!selectedApi) {
     throw new ZapierConfigurationError(
@@ -87,20 +89,26 @@ async function executeAction(actionOptions: ExecuteActionOptions): Promise<{
     data: runRequestData,
   };
 
-  const runData = await api.post("/api/actions/v1/runs", runRequest);
+  const runData = await api.post<{ data: { id: string } }>(
+    "/api/actions/v1/runs",
+    runRequest,
+  );
   const runId = runData.data.id;
 
   // Step 2: Poll GET /actions/v1/runs/{run_id} for results
   return await api.poll(`/api/actions/v1/runs/${runId}`, {
     successStatus: 200,
     pendingStatus: 202,
-    resultExtractor: (result: { data: unknown }) => result.data,
+    resultExtractor: (result: unknown) => (result as { data: unknown }).data,
   });
 }
 
 export const runActionPlugin: Plugin<
   GetSdkType<GetActionPluginProvides & GetAppPluginProvides>, // requires getAction and getApp in SDK
-  { api: ApiClient }, // requires api in context
+  {
+    api: ApiClient;
+    getVersionedImplementationId: GetVersionedImplementationId;
+  }, // requires api in context
   RunActionPluginProvides
 > = ({ sdk, context }) => {
   const runAction = createPaginatedFunction(async function runActionPage(
@@ -132,7 +140,7 @@ export const runActionPlugin: Plugin<
     // Execute the action using the Actions API (supports all action types)
     const result = await executeAction({
       api,
-      sdk,
+      context,
       appKey,
       actionKey,
       actionType,
@@ -168,6 +176,7 @@ export const runActionPlugin: Plugin<
     context: {
       meta: {
         runAction: {
+          categories: ["action"],
           inputSchema: RunActionSchema,
         },
       },

package/src/schemas/Field.ts

@@ -65,10 +65,13 @@ export const InputFieldItemSchema = withFormatter(
       if (item.choices && item.choices.length > 0) {
         const choiceText =
           item.choices.length <= 3
-            ? `Choices: ${item.choices.map((c: any) => c.label || c.value).join(", ")}`
+            ? `Choices: ${item.choices.map((c: { label?: string; value: string | number }) => c.label || c.value).join(", ")}`
             : `Choices: ${item.choices
                 .slice(0, 3)
-                .map((c: any) => c.label || c.value)
+                .map(
+                  (c: { label?: string; value: string | number }) =>
+                    c.label || c.value,
+                )
                 .join(", ")} (+${item.choices.length - 3} more)`;
         details.push({ text: choiceText, style: "accent" as const });
       }

package/src/sdk.test.ts

@@ -181,7 +181,7 @@ describe("Flat Plugin System", () => {
 
     const baseSdk = { existingMethod: () => "base" };
     const baseContext = { customContext: "custom", meta: {} };
-    const sdk = createSdk(baseSdk, baseContext).addPlugin(pluginWithHelper);
+    const sdk = createSdk({}, baseSdk, baseContext).addPlugin(pluginWithHelper);
 
     expect(sdk.helperMethod()).toBe("Helper: base + custom");
     expect(sdk.existingMethod()).toBe("base"); // Original method still works

package/src/sdk.ts

@@ -10,6 +10,7 @@ import type {
   Plugin,
   ExtractContextProperties,
   PluginProvides,
+  PluginMeta,
 } from "./types/plugin";
 
 // Import plugin functions
@@ -29,6 +30,8 @@ import { findFirstAuthenticationPlugin } from "./plugins/findFirstAuthentication
 import { findUniqueAuthenticationPlugin } from "./plugins/findUniqueAuthentication";
 import { listInputFieldsPlugin } from "./plugins/listInputFields";
 import { requestPlugin } from "./plugins/request";
+import { manifestPlugin } from "./plugins/manifest";
+import { lockVersionPlugin } from "./plugins/lockVersion";
 
 // Full SDK interface with plugins applied
 // Note: ZapierSdk is now defined as ReturnType<typeof createZapierSdk> at the bottom of this file
@@ -38,8 +41,9 @@ export interface ZapierSdkOptions extends BaseSdkOptions {}
 // Create SDK that supports flat plugins - returns an SDK, not a builder
 export function createSdk<
   TCurrentSdk = {},
-  TCurrentContext = { meta: Record<string, any> },
+  TCurrentContext = { meta: Record<string, PluginMeta> },
 >(
+  options: ZapierSdkOptions = {},
   initialSdk: TCurrentSdk = {} as TCurrentSdk,
   initialContext: TCurrentContext = { meta: {} } as TCurrentContext,
 ): Sdk<TCurrentSdk, TCurrentContext> {
@@ -52,7 +56,7 @@ export function createSdk<
         TRequiresContext,
         TProvides
       >,
-      options: any = {},
+      addPluginOptions: any = {},
     ) {
       // Create SDK with getContext method for plugins to use
       const currentSdkWithContext = {
@@ -63,8 +67,12 @@ export function createSdk<
       // Apply the plugin with options merged in
       const pluginResult = plugin({
         sdk: currentSdkWithContext,
-        context: initialContext,
-        ...options,
+        context: {
+          ...initialContext,
+          // Add the options that createSdk was called with to context
+          options,
+        },
+        ...addPluginOptions,
       });
 
       // Extract context from plugin result if present
@@ -77,6 +85,7 @@ export function createSdk<
       // Ensure meta is always present, starting with existing or empty object
       let newContext = {
         ...initialContext,
+        ...addPluginOptions,
         meta: (initialContext as any).meta || {},
       } as TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>;
 
@@ -103,19 +112,22 @@ export function createSdk<
       }
 
       // Recursively create new SDK with updated properties
-      return createSdk(newSdk, newContext) as any;
+      return createSdk(options, newSdk, newContext) as any;
     },
   };
 }
 
 export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
   return (
-    createSdk()
+    createSdk(options)
       // Provides the API client in context
-      .addPlugin(apiPlugin, options)
+      .addPlugin(apiPlugin)
+
+      // Manifest plugin (provides version locking context)
 
       // Apps/actions/fields
       .addPlugin(listAppsPlugin)
+      .addPlugin(manifestPlugin)
       .addPlugin(getAppPlugin)
       .addPlugin(listActionsPlugin)
       .addPlugin(getActionPlugin)
@@ -124,6 +136,9 @@ export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
       // Run action
       .addPlugin(runActionPlugin)
 
+      // Version locking
+      .addPlugin(lockVersionPlugin)
+
       // Authentications
       .addPlugin(listAuthenticationsPlugin)
       .addPlugin(getAuthenticationPlugin)

package/src/types/errors.ts

@@ -6,8 +6,8 @@ export interface ApiError {
   code: string;
   title: string;
   detail: string;
-  source?: any;
-  meta?: any;
+  source?: unknown;
+  meta?: unknown;
 }
 
 /**
@@ -17,7 +17,7 @@ export interface ErrorOptions {
   statusCode?: number;
   errors?: ApiError[];
   cause?: unknown;
-  response?: any;
+  response?: unknown;
 }
 
 /**
@@ -29,7 +29,7 @@ export abstract class ZapierError extends Error {
   public statusCode?: number;
   public errors?: ApiError[];
   public cause?: unknown;
-  public response?: any;
+  public response?: unknown;
 
   constructor(message: string, options: ErrorOptions = {}) {
     super(message);
@@ -74,9 +74,12 @@ export class ZapierAppNotFoundError extends ZapierError {
  */
 export class ZapierValidationError extends ZapierError {
   readonly name = "ZapierValidationError";
-  public details?: any;
+  public details?: unknown;
 
-  constructor(message: string, options: ErrorOptions & { details?: any } = {}) {
+  constructor(
+    message: string,
+    options: ErrorOptions & { details?: unknown } = {},
+  ) {
     super(message, options);
     this.details = options.details;
   }

package/src/types/events.ts

@@ -8,7 +8,7 @@
 // Generic event system
 export interface SdkEvent {
   type: string;
-  payload?: Record<string, any>;
+  payload?: Record<string, unknown>;
   timestamp?: number;
 }
 

package/src/types/plugin.ts

@@ -7,6 +7,9 @@
  * ability to catch missing context at compile time.
  */
 
+import type { z } from "zod";
+import { BaseSdkOptions } from "./sdk";
+
 export interface PluginDependencies<TSdk = {}, TContext = {}> {
   sdk: TSdk;
   context: TContext;
@@ -17,6 +20,12 @@ export interface PluginProvides extends Record<string, any> {
   context?: Record<string, any>;
 }
 
+export interface PluginMeta {
+  categories: string[];
+  inputSchema: z.ZodSchema;
+  [key: string]: any;
+}
+
 // Utility type to extract SDK properties (everything except 'context')
 export type ExtractSdkProperties<T extends Record<string, any>> = Omit<
   T,
@@ -52,7 +61,10 @@ export interface Plugin<
 > {
   (params: {
     sdk: TSdk;
-    context: TRequiresContext & { meta: Record<string, any> };
+    context: TRequiresContext & {
+      meta: Record<string, PluginMeta>;
+      options: BaseSdkOptions;
+    };
   }): TProvides;
 }
 
@@ -86,7 +98,7 @@ type ContextError<TRequired, TCurrent> =
  */
 export type Sdk<
   TCurrentSdk = {},
-  TCurrentContext = { meta: Record<string, any> },
+  TCurrentContext = { meta: Record<string, PluginMeta> },
 > = TCurrentSdk & {
   addPlugin<TRequiresContext, TProvides extends PluginProvides>(
     plugin: Plugin<

package/src/types/sdk.ts

@@ -12,6 +12,15 @@ export interface BaseSdkOptions {
   fetch?: typeof fetch;
   baseUrl?: string;
   debug?: boolean;
+  manifestPath?: string;
+  manifest?: {
+    apps: {
+      [appKey: string]: {
+        implementationName: string;
+        version?: string;
+      };
+    };
+  };
 }
 
 // SDK interface composed from individual function interfaces
@@ -20,6 +29,8 @@ import type { GetAuthenticationSdkFunction } from "../plugins/getAuthentication/
 import type { FindFirstAuthenticationSdkFunction } from "../plugins/findFirstAuthentication/schemas";
 import type { FindUniqueAuthenticationSdkFunction } from "../plugins/findUniqueAuthentication/schemas";
 import type { RelayRequestSdkFunction } from "../plugins/request/schemas";
+import type { LockVersionPluginProvides } from "../plugins/lockVersion";
+
 import type { z } from "zod";
 import { RegistryPluginProvides } from "../plugins/registry";
 import { GetProfilePluginProvides } from "../plugins/getProfile";
@@ -37,6 +48,7 @@ import { FindUniqueAuthenticationPluginProvides } from "../plugins/findUniqueAut
 import { ListInputFieldsPluginProvides } from "../plugins/listInputFields";
 import { RequestPluginProvides } from "../plugins/request";
 import { GetSdkType } from "./plugin";
+import { ManifestPluginProvides } from "../plugins/manifest";
 
 // Plugin interfaces
 // Note: Plugin extension types removed - now using new plugin system
@@ -45,7 +57,7 @@ import { GetSdkType } from "./plugin";
 export interface FunctionRegistryEntry {
   name: string;
   inputSchema: z.ZodSchema;
-  implementation: Function;
+  categories: string[];
 }
 
 // Compose SDK functions from individual function interfaces
@@ -71,10 +83,12 @@ export type ZapierSdk = GetSdkType<
     FetchPluginProvides &
     AppsPluginProvides &
     ListAppsPluginProvides &
+    ManifestPluginProvides &
     GetAppPluginProvides &
     ListActionsPluginProvides &
     GetActionPluginProvides &
     RunActionPluginProvides &
+    LockVersionPluginProvides &
     ListAuthenticationsPluginProvides &
     GetAuthenticationPluginProvides &
     FindFirstAuthenticationPluginProvides &

package/src/utils/validation.test.ts

@@ -42,7 +42,8 @@ describe("validation utilities", () => {
         expect((error as ZapierValidationError).message).toContain("name:");
         expect((error as ZapierValidationError).message).toContain("age:");
         expect(
-          (error as ZapierValidationError).details.zodErrors,
+          ((error as ZapierValidationError).details as { zodErrors: unknown })
+            ?.zodErrors,
         ).toBeDefined();
       }
     });