@zapier/zapier-sdk 0.0.3 → 0.1.1

package/src/plugins/apps/index.ts

@@ -0,0 +1,144 @@
+import {
+  ActionExecutionOptions,
+  ActionExecutionResult,
+} from "../../types/domain";
+import { type ApiClient } from "../../api";
+import { runAction } from "../../functions/runAction";
+import type { ActionProxy } from "./types";
+
+export interface AppsPluginOptions {
+  api: ApiClient;
+  token?: string;
+}
+
+interface AppFactoryOptions {
+  authenticationId: number;
+}
+
+function createActionFunction(
+  appKey: string,
+  actionType: string,
+  actionKey: string,
+  options: AppsPluginOptions,
+  pinnedAuthId?: number,
+) {
+  return async (
+    actionOptions: ActionExecutionOptions = {},
+  ): Promise<ActionExecutionResult> => {
+    const { api, token } = options;
+    const { inputs, authenticationId: providedAuthenticationId } =
+      actionOptions;
+
+    // Use pinned auth ID first, then provided auth ID
+    const authenticationId = pinnedAuthId || providedAuthenticationId;
+
+    if (!authenticationId) {
+      throw new Error(
+        `Authentication ID is required. Either use the factory pattern: sdk.apps.${appKey}({ authenticationId }) or provide authenticationId in the action call.`,
+      );
+    }
+
+    // Call runAction with the resolved parameters
+    return runAction({
+      appKey,
+      actionType: actionType as any,
+      actionKey,
+      inputs,
+      authenticationId,
+      api: api,
+      token,
+    });
+  };
+}
+
+function createActionTypeProxy(
+  appKey: string,
+  actionType: string,
+  options: AppsPluginOptions,
+  pinnedAuthId?: number,
+) {
+  return new Proxy(
+    {},
+    {
+      get(_, actionKey) {
+        if (typeof actionKey === "string") {
+          return createActionFunction(
+            appKey,
+            actionType,
+            actionKey,
+            options,
+            pinnedAuthId,
+          );
+        }
+        return undefined;
+      },
+    },
+  );
+}
+
+function createPinnedAppProxy(
+  appKey: string,
+  options: AppsPluginOptions,
+  pinnedAuthId: number,
+) {
+  return new Proxy(
+    {},
+    {
+      get(_, actionType) {
+        if (typeof actionType === "string") {
+          return createActionTypeProxy(
+            appKey,
+            actionType,
+            options,
+            pinnedAuthId,
+          );
+        }
+        return undefined;
+      },
+    },
+  );
+}
+
+function createAppProxy(appKey: string, options: AppsPluginOptions) {
+  // Create the factory function that returns a pinned version
+  const appFactory = (factoryOptions: AppFactoryOptions) => {
+    return createPinnedAppProxy(
+      appKey,
+      options,
+      factoryOptions.authenticationId,
+    );
+  };
+
+  // Add properties for direct usage (backward compatibility)
+  return new Proxy(appFactory, {
+    get(_, actionType) {
+      if (typeof actionType === "string") {
+        return createActionTypeProxy(appKey, actionType, options);
+      }
+      return undefined;
+    },
+  });
+}
+
+function createAppsProxy(options: AppsPluginOptions): ActionProxy {
+  // Create a proxy object that intercepts property access
+  const appsProxy = new Proxy({} as ActionProxy, {
+    get(_, prop) {
+      if (typeof prop === "string") {
+        // First level: App names (e.g., 'slack')
+        return createAppProxy(prop, options);
+      }
+      return undefined;
+    },
+  });
+
+  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";

package/src/plugins/apps/info.ts

@@ -0,0 +1,12 @@
+import { createAppsPlugin } from "./index";
+import type { AppsPluginOptions } from "./index";
+
+// Plugin info object for registry (keeping for compatibility)
+export const appsPluginInfo = {
+  plugin: (_sdk: any, options: AppsPluginOptions) => {
+    const appsProxy = createAppsPlugin(options);
+    return {
+      apps: appsProxy,
+    };
+  },
+};

package/src/plugins/apps/types.ts

@@ -0,0 +1,34 @@
+import type {
+  ActionExecutionOptions,
+  ActionExecutionResult,
+} from "../../types/domain";
+
+interface AppFactoryOptions {
+  authenticationId: number;
+}
+
+interface ActionTypeProxy {
+  [action: string]: (
+    options?: ActionExecutionOptions,
+  ) => Promise<ActionExecutionResult>;
+}
+
+interface AppProxy {
+  [type: string]: ActionTypeProxy;
+}
+
+interface AppFactory {
+  (options: AppFactoryOptions): AppProxy;
+}
+
+// An app can be both a factory function and have properties for direct access
+type AppProxyWithFactory = AppFactory & AppProxy;
+
+export interface ActionProxy {
+  [app: string]: AppProxyWithFactory;
+}
+
+// Plugin interface - ready to be mixed into main SDK interface
+export interface AppsPluginSdkExtension {
+  apps: ActionProxy;
+}

package/src/resolvers/actionKey.ts

@@ -0,0 +1,33 @@
+import type { ZapierSdk } from "../types/sdk";
+
+export interface ActionKeyResolver {
+  type: "dynamic";
+  depends: readonly string[];
+  fetch: (
+    sdk: ZapierSdk,
+    resolvedParams: Record<string, any>,
+  ) => Promise<any[]>;
+  prompt: (items: any[], params: Record<string, any>) => any;
+}
+
+export const actionKeyResolver: ActionKeyResolver = {
+  type: "dynamic",
+  depends: ["appKey", "actionType"] as const,
+  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+    const actions = await sdk.listActions({ appKey: resolvedParams.appKey });
+    return actions.filter(
+      (action: any) => action.type === resolvedParams.actionType,
+    );
+  },
+  prompt: (actions: any[]) => ({
+    type: "list",
+    name: "actionKey",
+    message: "Select action:",
+    choices: actions.map((action) => ({
+      name: `${action.name || action.key} - ${
+        action.description || "No description"
+      }`,
+      value: action.key,
+    })),
+  }),
+};

package/src/resolvers/actionType.ts

@@ -0,0 +1,30 @@
+import type { ZapierSdk } from "../types/sdk";
+
+export interface ActionTypeResolver {
+  type: "dynamic";
+  depends: readonly string[];
+  fetch: (
+    sdk: ZapierSdk,
+    resolvedParams: Record<string, any>,
+  ) => Promise<any[]>;
+  prompt: (items: any[], params: Record<string, any>) => any;
+}
+
+export const actionTypeResolver: ActionTypeResolver = {
+  type: "dynamic",
+  depends: ["appKey"] as const,
+  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+    const actions = await sdk.listActions({ appKey: resolvedParams.appKey });
+    const types = [...new Set(actions.map((action: any) => action.type))];
+    return types.map((type) => ({ key: type, name: type }));
+  },
+  prompt: (types: any[]) => ({
+    type: "list",
+    name: "actionType",
+    message: "Select action type:",
+    choices: types.map((type) => ({
+      name: type.name,
+      value: type.key,
+    })),
+  }),
+};

package/src/resolvers/appKey.ts

@@ -0,0 +1,11 @@
+export interface AppKeyResolver {
+  type: "static";
+  inputType?: "text" | "password" | "email";
+  placeholder?: string;
+}
+
+export const appKeyResolver: AppKeyResolver = {
+  type: "static",
+  inputType: "text",
+  placeholder: "Enter app slug (e.g., 'slack', 'github')",
+};

package/src/resolvers/authenticationId.ts

@@ -0,0 +1,38 @@
+import type { ZapierSdk } from "../types/sdk";
+
+export interface AuthenticationIdResolver {
+  type: "dynamic";
+  depends: readonly string[];
+  fetch: (
+    sdk: ZapierSdk,
+    resolvedParams: Record<string, any>,
+  ) => Promise<any[]>;
+  prompt: (items: any[], params: Record<string, any>) => any;
+}
+
+export const authenticationIdResolver: AuthenticationIdResolver = {
+  type: "dynamic",
+  depends: ["appKey"] as const,
+  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+    // Get auths for the specific app (owned auths will be prioritized automatically)
+    return await sdk.listAuthentications({
+      appKey: resolvedParams.appKey,
+      limit: 1000,
+    });
+  },
+  prompt: (auths: any[], params: Record<string, any>) => ({
+    type: "list",
+    name: "authenticationId",
+    message: `Select authentication for ${params.appKey}:`,
+    choices: [
+      ...auths.map((auth) => ({
+        name: `${auth.title || auth.label || "Authentication"} (ID: ${auth.id})`,
+        value: auth.id,
+      })),
+      {
+        name: "↗ Skip authentication (may fail)",
+        value: null,
+      },
+    ],
+  }),
+};

package/src/resolvers/index.ts

@@ -0,0 +1,117 @@
+import { appKeyResolver } from "./appKey";
+import { actionTypeResolver } from "./actionType";
+import { actionKeyResolver } from "./actionKey";
+import { authenticationIdResolver } from "./authenticationId";
+import { inputsResolver } from "./inputs";
+
+// Centralized resolver registry
+export const resolverRegistry = {
+  appKey: appKeyResolver,
+  actionType: actionTypeResolver,
+  actionKey: actionKeyResolver,
+  authenticationId: authenticationIdResolver,
+  inputs: inputsResolver,
+} as const;
+
+// Type definitions
+export type ResolverName = keyof typeof resolverRegistry;
+export type ResolverType = (typeof resolverRegistry)[ResolverName];
+
+// Utility functions for working with resolvers
+
+/**
+ * Get a resolver by name
+ */
+export function getResolver(name: string): ResolverType | undefined {
+  return resolverRegistry[name as ResolverName];
+}
+
+/**
+ * Get all resolvers for a list of missing parameters
+ */
+export function getResolversForMissingParams(
+  missingParams: string[],
+): Record<string, ResolverType> {
+  const resolvers: Record<string, ResolverType> = {};
+
+  for (const param of missingParams) {
+    const resolver = resolverRegistry[param as ResolverName];
+    if (resolver) {
+      resolvers[param] = resolver;
+    }
+  }
+
+  return resolvers;
+}
+
+/**
+ * Check if a parameter has a resolver
+ */
+export function hasResolver(paramName: string): boolean {
+  return paramName in resolverRegistry;
+}
+
+/**
+ * Get all parameter names that have resolvers
+ */
+export function getResolvableParams(): string[] {
+  return Object.keys(resolverRegistry);
+}
+
+/**
+ * Resolve dependency chain for a parameter
+ * Returns parameters in the order they need to be resolved
+ */
+export function getResolutionOrder(
+  paramName: string,
+  resolved: Set<string> = new Set(),
+): string[] {
+  const resolver = getResolver(paramName);
+  if (!resolver || resolver.type === "static") {
+    return [paramName];
+  }
+
+  const order: string[] = [];
+
+  if ("depends" in resolver && resolver.depends) {
+    for (const dependency of resolver.depends) {
+      if (!resolved.has(dependency)) {
+        order.push(...getResolutionOrder(dependency, resolved));
+        resolved.add(dependency);
+      }
+    }
+  }
+
+  if (!resolved.has(paramName)) {
+    order.push(paramName);
+    resolved.add(paramName);
+  }
+
+  return order;
+}
+
+/**
+ * Get resolution order for multiple parameters
+ */
+export function getResolutionOrderForParams(paramNames: string[]): string[] {
+  const resolved = new Set<string>();
+  const order: string[] = [];
+
+  for (const paramName of paramNames) {
+    const paramOrder = getResolutionOrder(paramName, resolved);
+    for (const param of paramOrder) {
+      if (!order.includes(param)) {
+        order.push(param);
+      }
+    }
+  }
+
+  return order;
+}
+
+// Re-export individual resolvers for direct access if needed
+export { appKeyResolver } from "./appKey";
+export { actionTypeResolver } from "./actionType";
+export { actionKeyResolver } from "./actionKey";
+export { authenticationIdResolver } from "./authenticationId";
+export { inputsResolver } from "./inputs";

package/src/resolvers/inputs.ts

@@ -0,0 +1,23 @@
+import type { ZapierSdk } from "../types/sdk";
+
+export interface InputsResolver {
+  type: "fields";
+  depends: readonly string[];
+  fetch: (
+    sdk: ZapierSdk,
+    resolvedParams: Record<string, any>,
+  ) => Promise<any[]>;
+}
+
+export const inputsResolver: InputsResolver = {
+  type: "fields",
+  depends: ["appKey", "actionKey", "actionType", "authenticationId"] as const,
+  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+    return await sdk.listFields({
+      appKey: resolvedParams.appKey,
+      actionKey: resolvedParams.actionKey,
+      actionType: resolvedParams.actionType,
+      authenticationId: resolvedParams.authenticationId,
+    });
+  },
+};

package/src/schema-utils.ts

@@ -0,0 +1,154 @@
+import { z } from "zod";
+
+// ============================================================================
+// Format Metadata Types
+// ============================================================================
+
+export interface FormattedItem {
+  title: string;
+  subtitle?: string;
+  details: Array<{
+    text: string;
+    style: "normal" | "dim" | "accent" | "warning" | "success";
+  }>;
+}
+
+export interface FormatMetadata {
+  format: (item: any) => FormattedItem;
+}
+
+// Helper function to add format metadata to schemas
+export function withFormatter<T extends z.ZodType>(
+  schema: T,
+  formatMeta: FormatMetadata,
+): T {
+  // Store format metadata on the schema definition
+  (schema._def as any).formatMeta = formatMeta;
+  return schema;
+}
+
+// Helper function to get format metadata from a schema
+export function getFormatMetadata(
+  schema: z.ZodType,
+): FormatMetadata | undefined {
+  return (schema._def as any).formatMeta;
+}
+
+// Helper function to link input schemas to output schemas
+export function withOutputSchema<T extends z.ZodType>(
+  inputSchema: T,
+  outputSchema: z.ZodType,
+): T {
+  // Store output schema reference on the input schema
+  (inputSchema._def as any).outputSchema = outputSchema;
+  return inputSchema;
+}
+
+// Helper function to get output schema from an input schema
+export function getOutputSchema(inputSchema: z.ZodType): z.ZodType | undefined {
+  return (inputSchema._def as any).outputSchema;
+}
+
+// ============================================================================
+// Resolution Metadata Types
+// ============================================================================
+
+export interface StaticResolver {
+  type: "static";
+  inputType?: "text" | "password" | "email";
+  placeholder?: string;
+}
+
+export interface DynamicResolver {
+  type: "dynamic";
+  fetch: (sdk: any, resolvedParams: any) => Promise<any[]>; // Function to fetch data using SDK
+  prompt: (items: any[], params: any) => any;
+  depends?: string[]; // Parameters this resolver depends on
+}
+
+export interface FieldsResolver {
+  type: "fields";
+  fetch: (sdk: any, resolvedParams: any) => Promise<any[]>; // Function to fetch fields using SDK
+  depends?: string[]; // Parameters this resolver depends on
+}
+
+export type ResolverMetadata =
+  | StaticResolver
+  | DynamicResolver
+  | FieldsResolver;
+
+// Wrapper interface for resolver metadata to allow future extensibility
+export interface ResolverConfig {
+  resolver: ResolverMetadata;
+  // Future metadata types can be added here:
+  // validation?: ValidationMetadata;
+  // display?: DisplayMetadata;
+}
+
+// Helper function to add resolver metadata to schemas
+export function withResolver<T extends z.ZodType>(
+  schema: T,
+  config: ResolverConfig,
+): T {
+  // Store resolver metadata on the schema definition
+  (schema._def as any).resolverMeta = config;
+  return schema;
+}
+
+// ============================================================================
+// Schema Description Utilities
+// ============================================================================
+
+export function getSchemaDescription(schema: z.ZodSchema): string | undefined {
+  return schema.description;
+}
+
+export function getFieldDescriptions(
+  schema: z.ZodObject<any>,
+): Record<string, string> {
+  const descriptions: Record<string, string> = {};
+  const shape = schema.shape;
+
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    if (fieldSchema instanceof z.ZodType && fieldSchema.description) {
+      descriptions[key] = fieldSchema.description;
+    }
+  }
+
+  return descriptions;
+}
+
+// ============================================================================
+// Positional Parameter Metadata
+// ============================================================================
+
+export interface PositionalMetadata {
+  positional: true;
+}
+
+// Helper function to mark a parameter as positional for CLI
+export function withPositional<T extends z.ZodType>(schema: T): T {
+  // Store positional metadata on the schema definition
+  (schema._def as any).positionalMeta = { positional: true };
+  return schema;
+}
+
+// Helper function to check if a parameter should be positional
+export function isPositional(schema: z.ZodType): boolean {
+  // Check the current schema first
+  if ((schema._def as any).positionalMeta?.positional) {
+    return true;
+  }
+
+  // If this is a ZodOptional, check the inner type
+  if (schema instanceof z.ZodOptional) {
+    return isPositional(schema._def.innerType);
+  }
+
+  // If this is a ZodDefault, check the inner type
+  if (schema instanceof z.ZodDefault) {
+    return isPositional(schema._def.innerType);
+  }
+
+  return false;
+}

package/src/schemas/Action.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { withFormatter } from "../schema-utils";
+
+// ============================================================================
+// Action Schemas
+// ============================================================================
+
+export const ActionItemSchema = withFormatter(
+  z.object({
+    key: z.string(),
+    name: z.string().optional(),
+    type: z.string(),
+    appKey: z.string().optional(),
+    description: z.string().optional(),
+  }),
+  {
+    format: (item) => {
+      const details = [];
+      details.push({ text: `Type: ${item.type}`, style: "accent" as const });
+      if (item.appKey) {
+        details.push({ text: `App: ${item.appKey}`, style: "normal" as const });
+      }
+      if (item.description) {
+        details.push({ text: item.description, style: "dim" as const });
+      }
+
+      return {
+        title: item.name || item.key,
+        subtitle: `(${item.key})`,
+        details,
+      };
+    },
+  },
+);
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type ActionItem = z.infer<typeof ActionItemSchema>;

package/src/schemas/App.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { withFormatter } from "../schema-utils";
+
+export { FormattedItem, FormatMetadata } from "../schema-utils";
+
+// ============================================================================
+// App Schemas
+// ============================================================================
+
+export const AppItemSchema = withFormatter(
+  z.object({
+    key: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    category: z.string().optional(),
+  }),
+  {
+    format: (item) => {
+      const details = [];
+      if (item.description) {
+        details.push({ text: item.description, style: "dim" as const });
+      }
+      if (item.category) {
+        details.push({
+          text: `Category: ${item.category}`,
+          style: "accent" as const,
+        });
+      }
+
+      return {
+        title: item.name || item.key,
+        subtitle: `(${item.key})`,
+        details,
+      };
+    },
+  },
+);
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type AppItem = z.infer<typeof AppItemSchema>;