@zapier/zapier-sdk 0.0.3 → 0.1.1

package/src/functions/bundleCode/schemas.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { OutputPropertySchema } from "../../types/properties";
+
+// Pure Zod schema - no resolver metadata!
+export const BundleCodeSchema = z
+  .object({
+    input: z.string().min(1).describe("Input TypeScript file path to bundle"),
+    output: OutputPropertySchema.optional().describe(
+      "Output file path (defaults to input with .js extension)",
+    ),
+    string: z
+      .boolean()
+      .default(false)
+      .describe("Return bundled code as string instead of writing to file"),
+    minify: z.boolean().default(false).describe("Minify the bundled output"),
+    target: z.string().default("es2017").describe("ECMAScript target version"),
+    cjs: z
+      .boolean()
+      .default(false)
+      .describe("Output CommonJS format instead of ESM"),
+  })
+  .describe("Bundle TypeScript code into executable JavaScript");
+
+// Type inferred from schema (no additional function config needed for bundleCode)
+export type BundleCodeOptions = z.infer<typeof BundleCodeSchema>;
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface BundleCodeSdkFunction {
+  bundleCode: (options: BundleCodeOptions) => Promise<string>;
+}

package/src/functions/findFirstAuthentication/index.ts

@@ -0,0 +1,24 @@
+import type { Authentication } from "../../types/domain";
+import { listAuthentications } from "../listAuthentications";
+import type { FindFirstAuthenticationOptions } from "./schemas";
+
+/**
+ * Find the first authentication matching the given criteria
+ *
+ * This function can be used standalone without instantiating a full SDK,
+ * which enables better tree-shaking in applications that only need this functionality.
+ *
+ * @param options - Filtering and API configuration options
+ * @returns Promise<Authentication | null> - First matching authentication or null if not found
+ */
+export async function findFirstAuthentication(
+  options: Partial<FindFirstAuthenticationOptions> = {},
+): Promise<Authentication | null> {
+  // Use listAuthentications with limit 1 to get the first result
+  const auths = await listAuthentications({
+    ...options,
+    limit: 1,
+  });
+
+  return auths.length > 0 ? auths[0] : null;
+}

package/src/functions/findFirstAuthentication/info.ts

@@ -0,0 +1,9 @@
+import { findFirstAuthentication } from "./index";
+import { FindFirstAuthenticationSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const findFirstAuthenticationInfo = {
+  name: findFirstAuthentication.name,
+  inputSchema: FindFirstAuthenticationSchema,
+  implementation: findFirstAuthentication,
+};

package/src/functions/findFirstAuthentication/schemas.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  LimitPropertySchema,
+  OffsetPropertySchema,
+} from "../../types/properties";
+import { withOutputSchema } from "../../schema-utils";
+import { AuthItemSchema } from "../../schemas/Auth";
+import type { Authentication } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const FindFirstAuthenticationSchema = withOutputSchema(
+  z
+    .object({
+      appKey: AppKeyPropertySchema.optional().describe(
+        "App slug to get authentications for (e.g., 'slack', 'github')",
+      ),
+      search: z
+        .string()
+        .optional()
+        .describe("Search term to filter authentications by title"),
+      title: z
+        .string()
+        .optional()
+        .describe("Filter authentications by exact title match"),
+      account_id: z.string().optional().describe("Filter by account ID"),
+      owner: z.string().optional().describe("Filter by owner"),
+      limit: LimitPropertySchema.optional().describe(
+        "Maximum number of items to return (1-200)",
+      ),
+      offset: OffsetPropertySchema.optional().describe(
+        "Number of items to skip for pagination",
+      ),
+    })
+    .describe("Find the first authentication matching the criteria"),
+  AuthItemSchema,
+);
+
+// Type inferred from schema + function config
+export type FindFirstAuthenticationOptions = z.infer<
+  typeof FindFirstAuthenticationSchema
+> & {
+  /** Base URL for Zapier API */
+  baseUrl?: string;
+  /** Authentication token */
+  token?: string;
+  /** Optional pre-instantiated API client */
+  api?: any;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface FindFirstAuthenticationSdkFunction {
+  findFirstAuthentication: (
+    options?: Partial<FindFirstAuthenticationOptions>,
+  ) => Promise<Authentication | null>;
+}

package/src/functions/findUniqueAuthentication/index.ts

@@ -0,0 +1,35 @@
+import type { Authentication } from "../../types/domain";
+import { listAuthentications } from "../listAuthentications";
+import type { FindUniqueAuthenticationOptions } from "./schemas";
+
+/**
+ * Find a unique authentication matching the given criteria
+ *
+ * This function can be used standalone without instantiating a full SDK,
+ * which enables better tree-shaking in applications that only need this functionality.
+ *
+ * @param options - Filtering and API configuration options
+ * @returns Promise<Authentication> - The unique matching authentication
+ * @throws Error if no authentication found or multiple authentications found
+ */
+export async function findUniqueAuthentication(
+  options: Partial<FindUniqueAuthenticationOptions> = {},
+): Promise<Authentication> {
+  // Use listAuthentications with a reasonable limit to check for uniqueness
+  const auths = await listAuthentications({
+    ...options,
+    limit: 2, // Get up to 2 to check for uniqueness
+  });
+
+  if (auths.length === 0) {
+    throw new Error("No authentication found matching the specified criteria");
+  }
+
+  if (auths.length > 1) {
+    throw new Error(
+      "Multiple authentications found matching the specified criteria. Expected exactly one.",
+    );
+  }
+
+  return auths[0];
+}

package/src/functions/findUniqueAuthentication/info.ts

@@ -0,0 +1,9 @@
+import { findUniqueAuthentication } from "./index";
+import { FindUniqueAuthenticationSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const findUniqueAuthenticationInfo = {
+  name: findUniqueAuthentication.name,
+  inputSchema: FindUniqueAuthenticationSchema,
+  implementation: findUniqueAuthentication,
+};

package/src/functions/findUniqueAuthentication/schemas.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  LimitPropertySchema,
+  OffsetPropertySchema,
+} from "../../types/properties";
+import { withOutputSchema } from "../../schema-utils";
+import { AuthItemSchema } from "../../schemas/Auth";
+import type { Authentication } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const FindUniqueAuthenticationSchema = withOutputSchema(
+  z
+    .object({
+      appKey: AppKeyPropertySchema.optional().describe(
+        "App slug to get authentications for (e.g., 'slack', 'github')",
+      ),
+      search: z
+        .string()
+        .optional()
+        .describe("Search term to filter authentications by title"),
+      title: z
+        .string()
+        .optional()
+        .describe("Filter authentications by exact title match"),
+      account_id: z.string().optional().describe("Filter by account ID"),
+      owner: z.string().optional().describe("Filter by owner"),
+      limit: LimitPropertySchema.optional().describe(
+        "Maximum number of items to return (1-200)",
+      ),
+      offset: OffsetPropertySchema.optional().describe(
+        "Number of items to skip for pagination",
+      ),
+    })
+    .describe("Find a unique authentication matching the criteria"),
+  AuthItemSchema,
+);
+
+// Type inferred from schema + function config
+export type FindUniqueAuthenticationOptions = z.infer<
+  typeof FindUniqueAuthenticationSchema
+> & {
+  /** Base URL for Zapier API */
+  baseUrl?: string;
+  /** Authentication token */
+  token?: string;
+  /** Optional pre-instantiated API client */
+  api?: any;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface FindUniqueAuthenticationSdkFunction {
+  findUniqueAuthentication: (
+    options?: Partial<FindUniqueAuthenticationOptions>,
+  ) => Promise<Authentication>;
+}

package/src/functions/{generateTypes.ts → generateTypes/index.ts}

@@ -1,12 +1,7 @@
-import type { Action, ActionField, FunctionConfig } from "../types";
-import { listActions } from "./listActions";
-import { listFields } from "./listFields";
-
-export interface GenerateTypesOptions extends FunctionConfig {
-  appKey: string;
-  authId?: number;
-  output?: string;
-}
+import type { Action, ActionField } from "../../types/domain";
+import { listActions } from "../listActions";
+import { listFields } from "../listFields";
+import type { GenerateTypesOptions } from "./schemas";
 
 interface ActionWithActionFields extends Omit<Action, "inputFields"> {
   inputFields: ActionField[];
@@ -18,13 +13,17 @@ interface ActionWithActionFields extends Omit<Action, "inputFields"> {
  * This function can be used standalone without instantiating a full SDK,
  * which enables better tree-shaking in applications that only need this functionality.
  *
- * @param options - App key, auth ID, output path, and API configuration options
+ * @param options - App key, authentication ID, output path, and API configuration options
  * @returns Promise<string> - Generated TypeScript code
  */
 export async function generateTypes(
   options: GenerateTypesOptions,
 ): Promise<string> {
-  const { appKey, authId, output = `./types/${appKey}.d.ts` } = options;
+  const {
+    appKey,
+    authenticationId,
+    output = `./types/${appKey}.d.ts`,
+  } = options;
 
   // Parse app identifier (support app@version format)
   const { app, version } = parseAppIdentifier(appKey);
@@ -51,15 +50,15 @@ export async function generateTypes(
   // Fetch input fields for each action
   const actionsWithFields: ActionWithActionFields[] = [];
 
-  if (authId) {
+  if (authenticationId) {
     for (const action of actions) {
       try {
         const fields = await listFields({
           ...options,
-          app: action.appKey,
-          action: action.key,
-          type: action.type,
-          authId: authId,
+          appKey: action.appKey,
+          actionKey: action.key,
+          actionType: action.type,
+          authenticationId: authenticationId,
         });
         actionsWithFields.push({ ...action, inputFields: fields });
       } catch {
@@ -137,8 +136,15 @@ ${versionComment}
  * Generated on: ${new Date().toISOString()}
  * 
  * Usage:
- *   import type { ${appName}Actions } from './path/to/this/file'
- *   const sdk: ActionsSdk & { actions: ${appName}Actions } = createActionsSdk(...)
+ *   import type { ${appName}Sdk } from './path/to/this/file'
+ *   const sdk = createZapierSdk() as unknown as ${appName}Sdk
+ *   
+ *   // Direct usage (per-call auth):
+ *   await sdk.apps.${appKey}.search.user_by_email({ authenticationId: 123, inputs: { email } })
+ *   
+ *   // Factory usage (pinned auth):
+ *   const my${appName} = sdk.apps.${appKey}({ authenticationId: 123 })
+ *   await my${appName}.search.user_by_email({ inputs: { email } })
  */
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
@@ -197,17 +203,28 @@ import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapi
     output += `}\n\n`;
   });
 
-  // Generate the main app actions interface
-  output += `export interface ${appName}Actions {\n`;
-  output += `  run: {\n`;
-  output += `    ${appKey}: {\n`;
+  // Generate the main app SDK interface with factory pattern support
 
+  // Generate the app proxy interface (actions grouped by type)
+  output += `interface ${appName}AppProxy {\n`;
   Object.keys(actionsByType).forEach((actionType) => {
     const typeName = `${appName}${capitalize(actionType)}Actions`;
-    output += `      ${actionType}: ${typeName}\n`;
+    output += `  ${actionType}: ${typeName}\n`;
   });
+  output += `}\n\n`;
+
+  // Generate the factory function interface
+  output += `interface ${appName}AppFactory {\n`;
+  output += `  (options: { authenticationId: number }): ${appName}AppProxy\n`;
+  output += `}\n\n`;
 
-  output += `    }\n`;
+  // Combine factory and direct access
+  output += `type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy\n\n`;
+
+  // Generate the main SDK interface
+  output += `export interface ${appName}Sdk {\n`;
+  output += `  apps: {\n`;
+  output += `    ${appKey}: ${appName}AppWithFactory\n`;
   output += `  }\n`;
   output += `}\n`;
 
@@ -231,11 +248,19 @@ ${versionComment}
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
 
-export interface ${appName}Actions {
-  run: {
-    ${appKey}: {
-      // No actions available
-    }
+interface ${appName}AppProxy {
+  // No actions available
+}
+
+interface ${appName}AppFactory {
+  (options: { authenticationId: number }): ${appName}AppProxy
+}
+
+type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy
+
+export interface ${appName}Sdk {
+  apps: {
+    ${appKey}: ${appName}AppWithFactory
   }
 }
 `;
@@ -247,12 +272,26 @@ function capitalize(str: string): string {
 
 function sanitizeActionName(actionKey: string): string {
   // Ensure the action name is a valid TypeScript identifier
-  return actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+  let sanitized = actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
 }
 
 function sanitizeFieldName(fieldKey: string): string {
   // Ensure the field name is a valid TypeScript identifier
-  return fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+  let sanitized = fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
 }
 
 function escapeComment(comment: string): string {

package/src/functions/generateTypes/info.ts

@@ -0,0 +1,9 @@
+import { generateTypes } from "./index";
+import { GenerateTypesSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const generateTypesInfo = {
+  name: generateTypes.name,
+  inputSchema: GenerateTypesSchema,
+  implementation: generateTypes,
+};

package/src/functions/generateTypes/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  AuthenticationIdPropertySchema,
+  OutputPropertySchema,
+  DebugPropertySchema,
+} from "../../types/properties";
+
+// Pure Zod schema - no resolver metadata!
+export const GenerateTypesSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.describe("App key to generate SDK code for"),
+    authenticationId: AuthenticationIdPropertySchema.optional(),
+    output: OutputPropertySchema.optional().describe(
+      "Output file path (defaults to generated/<appKey>.ts)",
+    ),
+    debug: DebugPropertySchema.describe(
+      "Enable debug logging during generation",
+    ),
+  })
+  .describe("Generate TypeScript SDK code for a specific app");
+
+// Type inferred from schema + function config
+export type GenerateTypesOptions = z.infer<typeof GenerateTypesSchema> & {
+  /** Base URL for Zapier API */
+  baseUrl?: string;
+  /** Authentication token */
+  token?: string;
+  /** Optional pre-instantiated API client */
+  api?: any;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GenerateTypesSdkFunction {
+  generateTypes: (options: GenerateTypesOptions) => Promise<string>;
+}

package/src/functions/{getAction.ts → getAction/index.ts}

@@ -1,11 +1,6 @@
-import type { Action, FunctionConfig } from "../types";
-import { listActions } from "./listActions";
-
-export interface GetActionOptions extends FunctionConfig {
-  app: string;
-  action: string;
-  type: string;
-}
+import type { Action } from "../../types/domain";
+import { listActions } from "../listActions";
+import type { GetActionOptions } from "./schemas";
 
 /**
  * Get a specific action by app, action key, and type
@@ -17,18 +12,22 @@ export interface GetActionOptions extends FunctionConfig {
  * @returns Promise<Action>
  */
 export async function getAction(options: GetActionOptions): Promise<Action> {
-  const { app, action: actionKey, type } = options;
+  const { appKey, actionKey, actionType } = options;
 
   const actions = await listActions({
     ...options,
-    appKey: app,
+    appKey: appKey,
   });
 
-  const action = actions.find((a) => a.key === actionKey && a.type === type);
+  const action = actions.find(
+    (a) => a.key === actionKey && a.type === actionType,
+  );
 
   if (!action) {
-    throw new Error(`Action not found: ${actionKey} with type ${type}`);
+    throw new Error(`Action not found: ${actionKey} with type ${actionType}`);
   }
 
   return action;
 }
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/getAction/info.ts

@@ -0,0 +1,9 @@
+import { getAction } from "./index";
+import { GetActionSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const getActionInfo = {
+  name: getAction.name,
+  inputSchema: GetActionSchema,
+  implementation: getAction,
+};

package/src/functions/getAction/schemas.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  ActionTypePropertySchema,
+  ActionKeyPropertySchema,
+} from "../../types/properties";
+import type { Action } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetActionSchema = z
+  .object({
+    appKey: AppKeyPropertySchema,
+    actionType: ActionTypePropertySchema,
+    actionKey: ActionKeyPropertySchema,
+  })
+  .describe("Get detailed information about a specific action");
+
+// Type inferred from schema + function config
+export type GetActionOptions = z.infer<typeof GetActionSchema> & {
+  /** Base URL for Zapier API */
+  baseUrl?: string;
+  /** Authentication token */
+  token?: string;
+  /** Optional pre-instantiated API client */
+  api?: any;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetActionSdkFunction {
+  getAction: (options: GetActionOptions) => Promise<Action>;
+}

package/src/functions/{getApp.ts → getApp/index.ts}

@@ -1,9 +1,7 @@
-import { getOrCreateApiClient } from "../api";
-import type { Integration, FunctionConfig } from "../types";
-
-export interface GetAppOptions extends FunctionConfig {
-  key: string;
-}
+import { getOrCreateApiClient } from "../../api";
+import type { Integration } from "../../types/domain";
+import { AppNotFoundError } from "../../types/domain";
+import type { GetAppOptions } from "./schemas";
 
 /**
  * Get a specific app by key
@@ -17,18 +15,12 @@ export interface GetAppOptions extends FunctionConfig {
 export async function getApp(options: GetAppOptions): Promise<Integration> {
   const api = getOrCreateApiClient(options);
 
-  const { key } = options;
+  const { appKey } = options;
 
-  const app = await api.get(`/api/v4/apps/${key}/`, {
+  const app = await api.get(`/api/v4/apps/${appKey}/`, {
     customErrorHandler: (response) => {
       if (response.status === 404) {
-        const AppNotFoundError = class extends Error {
-          constructor(appKey: string) {
-            super(`App not found: ${appKey}`);
-            this.name = "AppNotFoundError";
-          }
-        };
-        return new AppNotFoundError(key);
+        return new AppNotFoundError(appKey);
       }
       return undefined;
     },
@@ -45,3 +37,5 @@ export async function getApp(options: GetAppOptions): Promise<Integration> {
     current_implementation_id: app.current_implementation_id,
   };
 }
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/getApp/info.ts

@@ -0,0 +1,9 @@
+import { getApp } from "./index";
+import { GetAppSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const getAppInfo = {
+  name: getApp.name,
+  inputSchema: GetAppSchema,
+  implementation: getApp,
+};

package/src/functions/getApp/schemas.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { Integration } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetAppSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.describe(
+      "App key or slug to fetch (e.g., google-sheets, slack, github)",
+    ),
+  })
+  .describe("Get detailed information about a specific app");
+
+// Type inferred from schema + function config
+export type GetAppOptions = z.infer<typeof GetAppSchema> & {
+  /** Base URL for Zapier API */
+  baseUrl?: string;
+  /** Authentication token */
+  token?: string;
+  /** Optional pre-instantiated API client */
+  api?: any;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom fetch implementation */
+  fetch?: typeof globalThis.fetch;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetAppSdkFunction {
+  getApp: (options: GetAppOptions) => Promise<Integration>;
+}

package/src/functions/{listActions.ts → listActions/index.ts}

@@ -1,11 +1,7 @@
-import { getOrCreateApiClient } from "../api";
-import type { Action, FunctionConfig } from "../types";
-import { getApp } from "./getApp";
-
-export interface ListActionsOptions extends FunctionConfig {
-  appKey?: string;
-  type?: string;
-}
+import { getOrCreateApiClient } from "../../api";
+import type { Action } from "../../types/domain";
+import { getApp } from "../getApp";
+import type { ListActionsOptions } from "./schemas";
 
 /**
  * List available actions with optional filtering
@@ -17,7 +13,7 @@ export interface ListActionsOptions extends FunctionConfig {
  * @returns Promise<Action[]> with pagination metadata
  */
 export async function listActions(
-  options: ListActionsOptions = {},
+  options: Partial<ListActionsOptions> = {},
 ): Promise<Action[]> {
   const api = getOrCreateApiClient(options);
 
@@ -26,7 +22,7 @@ export async function listActions(
     try {
       // Use the standalone getApp function
       const appData = await getApp({
-        key: options.appKey,
+        appKey: options.appKey,
         api,
         token: options.token,
         baseUrl: options.baseUrl,
@@ -149,3 +145,5 @@ export async function listActions(
 
   return actions;
 }
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/listActions/info.ts

@@ -0,0 +1,9 @@
+import { listActions } from "./index";
+import { ListActionsSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const listActionsInfo = {
+  name: listActions.name,
+  inputSchema: ListActionsSchema,
+  implementation: listActions,
+};