@zapier/zapier-sdk 0.0.2 → 0.1.0

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.listAuths({
+      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,119 @@
+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;
+}

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>;

package/src/schemas/Auth.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { withFormatter } from "../schema-utils";
+
+// ============================================================================
+// Auth Schemas
+// ============================================================================
+
+export const AuthItemSchema = withFormatter(
+  z.object({
+    id: z.number(),
+    title: z.string().optional(),
+    label: z.string().optional(),
+    identifier: z.string().optional(),
+    account_id: z.string().optional(),
+    is_private: z.boolean().optional(),
+    shared_with_all: z.boolean().optional(),
+    marked_stale_at: z.string().optional(),
+  }),
+  {
+    format: (item) => {
+      const details = [];
+
+      if (item.identifier) {
+        details.push({
+          text: `Identifier: ${item.identifier}`,
+          style: "accent" as const,
+        });
+      }
+
+      if (item.label && item.title && item.label !== item.title) {
+        details.push({
+          text: `Label: ${item.label}`,
+          style: "normal" as const,
+        });
+      }
+
+      details.push({
+        text: `Account: ${item.account_id || "unknown"} | Private: ${item.is_private || false} | Shared: ${item.shared_with_all || false}`,
+        style: "dim" as const,
+      });
+
+      if (item.marked_stale_at) {
+        details.push({
+          text: `⚠️  Marked stale: ${new Date(item.marked_stale_at).toLocaleDateString()}`,
+          style: "warning" as const,
+        });
+      }
+
+      return {
+        title: item.title || item.label || `Authentication ${item.id}`,
+        subtitle: `(ID: ${item.id})`,
+        details,
+      };
+    },
+  },
+);
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type AuthItem = z.infer<typeof AuthItemSchema>;

package/src/schemas/Field.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { withFormatter } from "../schema-utils";
+
+// ============================================================================
+// Field Schemas
+// ============================================================================
+
+export const FieldItemSchema = withFormatter(
+  z.object({
+    key: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+  }),
+  {
+    format: (item) => {
+      const details = [];
+      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 FieldItem = z.infer<typeof FieldItemSchema>;