@zapier/zapier-sdk 0.4.1 → 0.5.1

package/src/types/errors.ts

@@ -0,0 +1,275 @@
+/**
+ * Standard error format returned by the Zapier API
+ */
+export interface ApiError {
+  status: number;
+  code: string;
+  title: string;
+  detail: string;
+  source?: any;
+  meta?: any;
+}
+
+/**
+ * Base options for all error constructors
+ */
+export interface ErrorOptions {
+  statusCode?: number;
+  errors?: ApiError[];
+  cause?: unknown;
+  response?: any;
+}
+
+/**
+ * Base class for all Zapier SDK errors
+ * Use instanceof ZapierError to check if an error is from the SDK
+ */
+export abstract class ZapierError extends Error {
+  abstract readonly name: string;
+  public statusCode?: number;
+  public errors?: ApiError[];
+  public cause?: unknown;
+  public response?: any;
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message);
+    this.statusCode = options.statusCode;
+    this.errors = options.errors;
+    this.cause = options.cause;
+    this.response = options.response;
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Error thrown when API requests fail
+ */
+export class ZapierApiError extends ZapierError {
+  readonly name = "ZapierApiError";
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+}
+
+/**
+ * Error thrown when an app is not found
+ */
+export class ZapierAppNotFoundError extends ZapierError {
+  readonly name = "ZapierAppNotFoundError";
+  public appKey?: string;
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { appKey?: string } = {},
+  ) {
+    super(message, options);
+    this.appKey = options.appKey;
+  }
+}
+
+/**
+ * Error thrown when validation fails (e.g., invalid parameters)
+ */
+export class ZapierValidationError extends ZapierError {
+  readonly name = "ZapierValidationError";
+  public details?: any;
+
+  constructor(message: string, options: ErrorOptions & { details?: any } = {}) {
+    super(message, options);
+    this.details = options.details;
+  }
+}
+
+/**
+ * Error for unrecognized/unknown errors that get wrapped by safe functions
+ */
+export class ZapierUnknownError extends ZapierError {
+  readonly name = "ZapierUnknownError";
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+}
+
+/**
+ * Error thrown for authentication and authorization failures (401/403)
+ */
+export class ZapierAuthenticationError extends ZapierError {
+  readonly name = "ZapierAuthenticationError";
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+}
+
+/**
+ * Error thrown when a requested resource is not found
+ */
+export class ZapierResourceNotFoundError extends ZapierError {
+  readonly name = "ZapierResourceNotFoundError";
+  public resourceType?: string;
+  public resourceId?: string;
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { resourceType?: string; resourceId?: string } = {},
+  ) {
+    super(message, options);
+    this.resourceType = options.resourceType;
+    this.resourceId = options.resourceId;
+  }
+}
+
+/**
+ * Error thrown when required app or implementation configuration is missing
+ */
+export class ZapierConfigurationError extends ZapierError {
+  readonly name = "ZapierConfigurationError";
+  public configType?: string;
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { configType?: string } = {},
+  ) {
+    super(message, options);
+    this.configType = options.configType;
+  }
+}
+
+/**
+ * Error thrown when code bundling or compilation fails
+ */
+export class ZapierBundleError extends ZapierError {
+  readonly name = "ZapierBundleError";
+  public buildErrors?: string[];
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { buildErrors?: string[] } = {},
+  ) {
+    super(message, options);
+    this.buildErrors = options.buildErrors;
+  }
+}
+
+/**
+ * Error thrown when operations timeout or exceed retry limits
+ */
+export class ZapierTimeoutError extends ZapierError {
+  readonly name = "ZapierTimeoutError";
+  public attempts?: number;
+  public maxAttempts?: number;
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { attempts?: number; maxAttempts?: number } = {},
+  ) {
+    super(message, options);
+    this.attempts = options.attempts;
+    this.maxAttempts = options.maxAttempts;
+  }
+}
+
+/**
+ * Error thrown when action execution fails due to errors returned from the third-party service
+ * This happens when the Actions API returns a 200 status but includes errors in the response
+ */
+export class ZapierActionError extends ZapierError {
+  readonly name = "ZapierActionError";
+  public appKey?: string;
+  public actionKey?: string;
+
+  constructor(
+    message: string,
+    options: ErrorOptions & { appKey?: string; actionKey?: string } = {},
+  ) {
+    super(message, options);
+    this.appKey = options.appKey;
+    this.actionKey = options.actionKey;
+  }
+
+  // Legacy accessor for backward compatibility
+  get actionErrors() {
+    return this.errors;
+  }
+}
+
+/**
+ * Error thrown when a resource is not found (404)
+ */
+export class ZapierNotFoundError extends ZapierError {
+  readonly name = "ZapierNotFoundError";
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+}
+
+/**
+ * Utility function to format error messages for display
+ */
+export function formatErrorMessage(error: ZapierError): string {
+  let message = error.message;
+
+  // Add additional context from errors array if available
+  if (error.errors && error.errors.length > 0) {
+    const additionalErrors = error.errors.slice(1); // Skip first error (already in message)
+    if (additionalErrors.length > 0) {
+      const errorDetails = additionalErrors
+        .map((err) => `  • ${err.detail || err.title || err.code}`)
+        .join("\n");
+      message += "\n\nAdditional errors:\n" + errorDetails;
+    }
+  }
+
+  // Add error-specific context
+  if (error instanceof ZapierAppNotFoundError && error.appKey) {
+    message += `\nApp key: ${error.appKey}`;
+  }
+
+  if (error instanceof ZapierActionError && (error.appKey || error.actionKey)) {
+    const context = [];
+    if (error.appKey) context.push(`App: ${error.appKey}`);
+    if (error.actionKey) context.push(`Action: ${error.actionKey}`);
+    message += `\n${context.join(", ")}`;
+  }
+
+  if (
+    error instanceof ZapierResourceNotFoundError &&
+    (error.resourceType || error.resourceId)
+  ) {
+    const context = [];
+    if (error.resourceType) context.push(`Type: ${error.resourceType}`);
+    if (error.resourceId) context.push(`ID: ${error.resourceId}`);
+    message += `\n${context.join(", ")}`;
+  }
+
+  if (
+    error instanceof ZapierTimeoutError &&
+    (error.attempts || error.maxAttempts)
+  ) {
+    const context = [];
+    if (error.attempts) context.push(`Attempts: ${error.attempts}`);
+    if (error.maxAttempts) context.push(`Max attempts: ${error.maxAttempts}`);
+    message += `\n${context.join(", ")}`;
+  }
+
+  if (
+    error instanceof ZapierBundleError &&
+    error.buildErrors &&
+    error.buildErrors.length > 0
+  ) {
+    message +=
+      "\n\nBuild errors:\n" +
+      error.buildErrors.map((err) => `  • ${err}`).join("\n");
+  }
+
+  // Add status code if available and not already obvious from the message
+  if (error.statusCode && !message.includes(`${error.statusCode}`)) {
+    message += `\nHTTP Status: ${error.statusCode}`;
+  }
+
+  return message;
+}

package/src/types/functions.ts

@@ -0,0 +1,27 @@
+/**
+ * Function-related types and interfaces
+ */
+
+// 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;
+}
+
+// Generic type helper for paginated SDK functions
+export type PaginatedSdkFunction<TOptions, TItem> = (
+  options: TOptions,
+) => Promise<{ data: TItem[] }> &
+  AsyncIterable<{ data: TItem[]; nextCursor?: string }> & {
+    items(): AsyncIterable<TItem>;
+  };

package/src/types/optional-zapier-sdk-cli-login.d.ts

@@ -0,0 +1,37 @@
+// packages/zapier-sdk/types/cli-login-shim.d.ts
+declare module '@zapier/zapier-sdk-cli-login' {
+  export interface AuthOptions {
+    onEvent?: (event: {
+      type: string;
+      payload: Record<string, any>;
+      timestamp: number;
+    }) => void;
+    fetch?: typeof globalThis.fetch;
+  }
+
+  export interface LoginData {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  }
+
+  // Minimal API — include only what your SDK actually uses.
+  // (Keeping a few extra exports here is harmless and future-proofs a bit.)
+  export function getToken(
+    options?: AuthOptions
+  ): Promise<string | undefined>;
+
+  export function getValidJwt(
+    options?: AuthOptions
+  ): Promise<string | undefined>;
+
+  export function getLoggedInUser(
+    options?: AuthOptions
+  ): Promise<{ accountId: number; customUserId: number; email: string }>;
+
+  export function logout(options?: Pick<AuthOptions, 'onEvent'>): void;
+
+  export function updateLogin(loginData: LoginData): void;
+
+  export function getConfigPath(): string;
+}

package/src/types/plugin.ts

@@ -0,0 +1,105 @@
+/**
+ * ------------------------------
+ * Plugin Type System with Explicit Context Dependencies
+ * ------------------------------
+ *
+ * This system makes context dependencies explicit to restore TypeScript's
+ * ability to catch missing context at compile time.
+ */
+
+export interface PluginDependencies<TSdk = {}, TContext = {}> {
+  sdk: TSdk;
+  context: TContext;
+}
+
+// Plugin provides = sdk properties + optional context
+export interface PluginProvides extends Record<string, any> {
+  context?: Record<string, any>;
+}
+
+// Utility type to extract SDK properties (everything except 'context')
+export type ExtractSdkProperties<T extends Record<string, any>> = Omit<
+  T,
+  "context"
+>;
+
+// Utility type to extract context properties from plugin
+export type ExtractContextProperties<T extends PluginProvides> = T["context"];
+
+// Helper type to create SDK type with properly typed getContext method
+export type GetSdkType<TPluginProvides extends PluginProvides> =
+  ExtractSdkProperties<TPluginProvides> & {
+    getContext(): NonNullable<ExtractContextProperties<TPluginProvides>>;
+  };
+
+// Helper type for standard plugin options with SDK dependency and meta context
+export type PluginOptions<TSdk = {}, TContext = {}> = {
+  sdk: TSdk;
+  context: TContext & { meta: Record<string, any> };
+};
+
+/**
+ * Plugin interface — now has 3 type params:
+ *
+ *   TRequiresContext = what this plugin *needs* in context
+ *   TProvides = what this plugin *returns* (sdk + context)
+ *   TSdk = current sdk shape when plugin runs
+ */
+export interface Plugin<
+  TSdk = {},
+  TRequiresContext = {},
+  TProvides extends PluginProvides = PluginProvides,
+> {
+  (params: {
+    sdk: TSdk;
+    context: TRequiresContext & { meta: Record<string, any> };
+  }): TProvides;
+}
+
+// Helper type to get missing keys from required context
+type MissingContextKeys<TRequired, TCurrent> =
+  TRequired extends Record<string, any>
+    ? TCurrent extends Record<string, any>
+      ? {
+          [K in keyof TRequired]: K extends keyof TCurrent ? never : K;
+        }[keyof TRequired]
+      : keyof TRequired
+    : never;
+
+// Helper type to create detailed error message
+type ContextError<TRequired, TCurrent> =
+  MissingContextKeys<TRequired, TCurrent> extends never
+    ? never
+    : MissingContextKeys<TRequired, TCurrent> extends infer Missing
+      ? Missing extends string
+        ? `❌ Missing required context: { ${Missing}: any }`
+        : Missing extends number
+          ? `❌ Missing required context: { ${Missing}: any }`
+          : `❌ Missing required context properties. Required: ${keyof TRequired extends string ? keyof TRequired : "unknown"}, Available: ${keyof TCurrent extends string ? keyof TCurrent : "unknown"}`
+      : "❌ Context requirement not satisfied";
+
+/**
+ * SDK interface — result of createSdk()
+ *
+ * addPlugin now enforces that TRequiresContext is assignable to TCurrentContext.
+ * If not, TypeScript will emit a detailed error showing missing properties.
+ */
+export type Sdk<
+  TCurrentSdk = {},
+  TCurrentContext = { meta: Record<string, any> },
+> = TCurrentSdk & {
+  addPlugin<TRequiresContext, TProvides extends PluginProvides>(
+    plugin: Plugin<
+      TCurrentSdk & { getContext(): TCurrentContext },
+      TRequiresContext,
+      TProvides
+    >,
+    options?: any,
+  ): TCurrentContext extends TRequiresContext
+    ? Sdk<
+        TCurrentSdk & ExtractSdkProperties<TProvides>,
+        TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>
+      >
+    : ContextError<TRequiresContext, TCurrentContext>;
+  getContext(): TCurrentContext;
+};

package/src/types/properties.ts

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { withPositional } from "../schema-utils";
+import { withPositional } from "../utils/schema-utils";
+import { MAX_PAGE_LIMIT } from "../constants";
 
 // Shared property definitions for common parameters across functions
 // These can be reused in function schemas without duplication
 
 export const AppKeyPropertySchema = withPositional(
-  z.string().min(1).describe("App slug (e.g., 'slack', 'github')"),
+  z.string().min(1).describe("App key (e.g., 'SlackCLIAPI')"),
 );
 
 export const ActionTypePropertySchema = z
@@ -39,7 +40,7 @@ export const LimitPropertySchema = z
   .number()
   .int()
   .min(1)
-  .max(1000)
+  .max(MAX_PAGE_LIMIT)
   .default(50)
   .describe("Maximum number of items to return");
 

package/src/types/sdk.ts

@@ -1,63 +1,85 @@
+/**
+ * SDK-related types and interfaces
+ */
+
+import type { EventCallback } from "./events";
+
+// SDK Configuration Types
+export interface BaseSdkOptions {
+  token?: string;
+  getToken?: () => Promise<string | undefined>;
+  onEvent?: EventCallback;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+  debug?: boolean;
+}
+
 // SDK interface composed from individual function interfaces
-import type { ListActionsSdkFunction } from "../functions/listActions/schemas";
-import type { GetActionSdkFunction } from "../functions/getAction/schemas";
-import type { GetAppSdkFunction } from "../functions/getApp/schemas";
-import type { RunActionSdkFunction } from "../functions/runAction/schemas";
-import type { ListFieldsSdkFunction } from "../functions/listFields/schemas";
-import type { ListAuthenticationsSdkFunction } from "../functions/listAuthentications/schemas";
-import type { GetAuthenticationSdkFunction } from "../functions/getAuthentication/schemas";
-import type { FindFirstAuthenticationSdkFunction } from "../functions/findFirstAuthentication/schemas";
-import type { FindUniqueAuthenticationSdkFunction } from "../functions/findUniqueAuthentication/schemas";
-import type { GenerateTypesSdkFunction } from "../functions/generateTypes/schemas";
-import type { ListAppsSdkFunction } from "../functions/listApps/schemas";
-import type { BundleCodeSdkFunction } from "../functions/bundleCode/schemas";
-import type { RelayRequestSdkFunction } from "../functions/request/schemas";
+import type { ListInputFieldsSdkFunction } from "../plugins/listInputFields/schemas";
+import type { GetAuthenticationSdkFunction } from "../plugins/getAuthentication/schemas";
+import type { FindFirstAuthenticationSdkFunction } from "../plugins/findFirstAuthentication/schemas";
+import type { FindUniqueAuthenticationSdkFunction } from "../plugins/findUniqueAuthentication/schemas";
+import type { RelayRequestSdkFunction } from "../plugins/request/schemas";
+import type { z } from "zod";
+import { RegistryPluginProvides } from "../plugins/registry";
+import { GetProfilePluginProvides } from "../plugins/getProfile";
+import { AppsPluginProvides } from "../plugins/apps";
+import { FetchPluginProvides } from "../plugins/fetch";
+import { ListAppsPluginProvides } from "../plugins/listApps";
+import { GetAppPluginProvides } from "../plugins/getApp";
+import { ListActionsPluginProvides } from "../plugins/listActions";
+import { GetActionPluginProvides } from "../plugins/getAction";
+import { RunActionPluginProvides } from "../plugins/runAction";
+import { ListAuthenticationsPluginProvides } from "../plugins/listAuthentications";
+import { GetAuthenticationPluginProvides } from "../plugins/getAuthentication";
+import { FindFirstAuthenticationPluginProvides } from "../plugins/findFirstAuthentication";
+import { FindUniqueAuthenticationPluginProvides } from "../plugins/findUniqueAuthentication";
+import { ListInputFieldsPluginProvides } from "../plugins/listInputFields";
+import { RequestPluginProvides } from "../plugins/request";
+import { GetSdkType } from "./plugin";
 
 // Plugin interfaces
-import type { AppsPluginSdkExtension } from "../plugins/apps/types";
-import type { FetchPluginSdkExtension } from "../plugins/fetch/types";
+// Note: Plugin extension types removed - now using new plugin system
+
+// Registry entry interface with proper types
+export interface FunctionRegistryEntry {
+  name: string;
+  inputSchema: z.ZodSchema;
+  implementation: Function;
+}
 
 // Compose SDK functions from individual function interfaces
 export interface ZapierSdkFunctions
-  extends ListActionsSdkFunction,
-    GetActionSdkFunction,
-    GetAppSdkFunction,
-    RunActionSdkFunction,
-    ListFieldsSdkFunction,
-    ListAuthenticationsSdkFunction,
+  extends ListInputFieldsSdkFunction,
     GetAuthenticationSdkFunction,
     FindFirstAuthenticationSdkFunction,
     FindUniqueAuthenticationSdkFunction,
-    GenerateTypesSdkFunction,
-    ListAppsSdkFunction,
-    BundleCodeSdkFunction,
     RelayRequestSdkFunction {
   // All functions now properly typed!
 }
 
-// Compose SDK plugins from individual plugin interfaces
-export interface ZapierSdkPlugins
-  extends AppsPluginSdkExtension,
-    FetchPluginSdkExtension {
-  // All plugins now properly typed!
-}
+// Note: ZapierSdkPlugins removed - plugins are now handled by the plugin builder system
 
-// Base SDK interface with core functions only (no plugins)
-export interface BaseZapierSdk extends ZapierSdkFunctions {
-  // Special property for CLI to access schemas
-  __registry: Array<{
-    name: string;
-    inputSchema: any;
-    implementation: Function;
-  }>;
-}
+// Note: BaseZapierSdk removed - all functions now provided by individual plugins
+// The registry is provided by RegistryPlugin
 
-// Main SDK interface with functions and plugins
-export interface ZapierSdk extends ZapierSdkFunctions, ZapierSdkPlugins {
-  // Special property for CLI to access schemas
-  __registry: Array<{
-    name: string;
-    inputSchema: any;
-    implementation: Function;
-  }>;
-}
+// Note: ZapierSdk type removed - use ReturnType<typeof createZapierSdk> instead
+// This ensures the type matches exactly what the builder produces
+
+export type ZapierSdk = GetSdkType<
+  RegistryPluginProvides &
+    FetchPluginProvides &
+    AppsPluginProvides &
+    ListAppsPluginProvides &
+    GetAppPluginProvides &
+    ListActionsPluginProvides &
+    GetActionPluginProvides &
+    RunActionPluginProvides &
+    ListAuthenticationsPluginProvides &
+    GetAuthenticationPluginProvides &
+    FindFirstAuthenticationPluginProvides &
+    FindUniqueAuthenticationPluginProvides &
+    ListInputFieldsPluginProvides &
+    RequestPluginProvides &
+    GetProfilePluginProvides
+>;