@zapier/zapier-sdk 0.1.0 → 0.2.0

package/dist/functions/runAction/index.js

@@ -15,10 +15,8 @@ const getApp_1 = require("../getApp");
  */
 async function runAction(options) {
     const { appKey, actionType, actionKey, inputs, authenticationId: providedAuthenticationId, token, } = options;
-    if (!token && !process.env.ZAPIER_TOKEN) {
-        throw new Error("Authentication token is required to run actions. Please provide token in options or set ZAPIER_TOKEN environment variable.");
-    }
     const api = (0, api_1.getOrCreateApiClient)(options);
+    api.requireAuthTo("run actions");
     // Validate that the action exists
     const actionData = await (0, getAction_1.getAction)({
         ...options,

package/dist/functions/runAction/schemas.d.ts

@@ -24,6 +24,8 @@ export type RunActionOptions = z.infer<typeof RunActionSchema> & {
     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 */

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export * from "./types/domain";
 export * from "./types/properties";
 export * from "./plugins/apps";
+export { isPositional } from "./schema-utils";
 export * from "./resolvers";
-export { listAuths } from "./functions/listAuths";
+export { listAuthentications } from "./functions/listAuthentications";
+export { findFirstAuthentication } from "./functions/findFirstAuthentication";
+export { findUniqueAuthentication } from "./functions/findUniqueAuthentication";
 export { listApps } from "./functions/listApps";
 export { getApp } from "./functions/getApp";
 export { listActions } from "./functions/listActions";

package/dist/index.js

@@ -14,17 +14,24 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createZapierSdk = exports.bundleCode = exports.generateTypes = exports.listFields = exports.runAction = exports.getAction = exports.listActions = exports.getApp = exports.listApps = exports.listAuths = void 0;
+exports.createZapierSdk = exports.bundleCode = exports.generateTypes = exports.listFields = exports.runAction = exports.getAction = exports.listActions = exports.getApp = exports.listApps = exports.findUniqueAuthentication = exports.findFirstAuthentication = exports.listAuthentications = exports.isPositional = void 0;
 // Export everything from types and plugins
 __exportStar(require("./types/domain"), exports);
 __exportStar(require("./types/properties"), exports);
 __exportStar(require("./plugins/apps"), exports);
+// Export schema utilities for CLI
+var schema_utils_1 = require("./schema-utils");
+Object.defineProperty(exports, "isPositional", { enumerable: true, get: function () { return schema_utils_1.isPositional; } });
 // Export resolvers for CLI use
 __exportStar(require("./resolvers"), exports);
 // Note: SdkSchemas is now available via SDK.__registry
 // Export individual functions for tree-shaking
-var listAuths_1 = require("./functions/listAuths");
-Object.defineProperty(exports, "listAuths", { enumerable: true, get: function () { return listAuths_1.listAuths; } });
+var listAuthentications_1 = require("./functions/listAuthentications");
+Object.defineProperty(exports, "listAuthentications", { enumerable: true, get: function () { return listAuthentications_1.listAuthentications; } });
+var findFirstAuthentication_1 = require("./functions/findFirstAuthentication");
+Object.defineProperty(exports, "findFirstAuthentication", { enumerable: true, get: function () { return findFirstAuthentication_1.findFirstAuthentication; } });
+var findUniqueAuthentication_1 = require("./functions/findUniqueAuthentication");
+Object.defineProperty(exports, "findUniqueAuthentication", { enumerable: true, get: function () { return findUniqueAuthentication_1.findUniqueAuthentication; } });
 var listApps_1 = require("./functions/listApps");
 Object.defineProperty(exports, "listApps", { enumerable: true, get: function () { return listApps_1.listApps; } });
 var getApp_1 = require("./functions/getApp");

package/dist/resolvers/authenticationId.js

@@ -6,7 +6,7 @@ exports.authenticationIdResolver = {
     depends: ["appKey"],
     fetch: async (sdk, resolvedParams) => {
         // Get auths for the specific app (owned auths will be prioritized automatically)
-        return await sdk.listAuths({
+        return await sdk.listAuthentications({
             appKey: resolvedParams.appKey,
             limit: 1000,
         });

package/dist/schema-utils.d.ts

@@ -37,3 +37,8 @@ export interface ResolverConfig {
 export declare function withResolver<T extends z.ZodType>(schema: T, config: ResolverConfig): T;
 export declare function getSchemaDescription(schema: z.ZodSchema): string | undefined;
 export declare function getFieldDescriptions(schema: z.ZodObject<any>): Record<string, string>;
+export interface PositionalMetadata {
+    positional: true;
+}
+export declare function withPositional<T extends z.ZodType>(schema: T): T;
+export declare function isPositional(schema: z.ZodType): boolean;

package/dist/schema-utils.js

@@ -7,6 +7,8 @@ exports.getOutputSchema = getOutputSchema;
 exports.withResolver = withResolver;
 exports.getSchemaDescription = getSchemaDescription;
 exports.getFieldDescriptions = getFieldDescriptions;
+exports.withPositional = withPositional;
+exports.isPositional = isPositional;
 const zod_1 = require("zod");
 // Helper function to add format metadata to schemas
 function withFormatter(schema, formatMeta) {
@@ -50,3 +52,25 @@ function getFieldDescriptions(schema) {
     }
     return descriptions;
 }
+// Helper function to mark a parameter as positional for CLI
+function withPositional(schema) {
+    // Store positional metadata on the schema definition
+    schema._def.positionalMeta = { positional: true };
+    return schema;
+}
+// Helper function to check if a parameter should be positional
+function isPositional(schema) {
+    // Check the current schema first
+    if (schema._def.positionalMeta?.positional) {
+        return true;
+    }
+    // If this is a ZodOptional, check the inner type
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return isPositional(schema._def.innerType);
+    }
+    // If this is a ZodDefault, check the inner type
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return isPositional(schema._def.innerType);
+    }
+    return false;
+}

package/dist/schemas/Auth.d.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 export declare const AuthItemSchema: z.ZodObject<{
     id: z.ZodNumber;
     title: z.ZodOptional<z.ZodString>;
-    label: z.ZodOptional<z.ZodString>;
     identifier: z.ZodOptional<z.ZodString>;
     account_id: z.ZodOptional<z.ZodString>;
     is_private: z.ZodOptional<z.ZodBoolean>;
@@ -11,7 +10,6 @@ export declare const AuthItemSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     id: number;
     title?: string | undefined;
-    label?: string | undefined;
     identifier?: string | undefined;
     account_id?: string | undefined;
     is_private?: boolean | undefined;
@@ -20,7 +18,6 @@ export declare const AuthItemSchema: z.ZodObject<{
 }, {
     id: number;
     title?: string | undefined;
-    label?: string | undefined;
     identifier?: string | undefined;
     account_id?: string | undefined;
     is_private?: boolean | undefined;

package/dist/schemas/Auth.js

@@ -9,7 +9,6 @@ const schema_utils_1 = require("../schema-utils");
 exports.AuthItemSchema = (0, schema_utils_1.withFormatter)(zod_1.z.object({
     id: zod_1.z.number(),
     title: zod_1.z.string().optional(),
-    label: zod_1.z.string().optional(),
     identifier: zod_1.z.string().optional(),
     account_id: zod_1.z.string().optional(),
     is_private: zod_1.z.boolean().optional(),
@@ -24,12 +23,6 @@ exports.AuthItemSchema = (0, schema_utils_1.withFormatter)(zod_1.z.object({
                 style: "accent",
             });
         }
-        if (item.label && item.title && item.label !== item.title) {
-            details.push({
-                text: `Label: ${item.label}`,
-                style: "normal",
-            });
-        }
         details.push({
             text: `Account: ${item.account_id || "unknown"} | Private: ${item.is_private || false} | Shared: ${item.shared_with_all || false}`,
             style: "dim",
@@ -41,7 +34,7 @@ exports.AuthItemSchema = (0, schema_utils_1.withFormatter)(zod_1.z.object({
             });
         }
         return {
-            title: item.title || item.label || `Authentication ${item.id}`,
+            title: item.title || `Authentication ${item.id}`,
             subtitle: `(ID: ${item.id})`,
             details,
         };

package/dist/sdk.js

@@ -8,7 +8,9 @@ const getApp_1 = require("./functions/getApp");
 const listActions_1 = require("./functions/listActions");
 const getAction_1 = require("./functions/getAction");
 const runAction_1 = require("./functions/runAction");
-const listAuths_1 = require("./functions/listAuths");
+const listAuthentications_1 = require("./functions/listAuthentications");
+const findFirstAuthentication_1 = require("./functions/findFirstAuthentication");
+const findUniqueAuthentication_1 = require("./functions/findUniqueAuthentication");
 const listFields_1 = require("./functions/listFields");
 const generateTypes_1 = require("./functions/generateTypes");
 const bundleCode_1 = require("./functions/bundleCode");
@@ -18,10 +20,12 @@ const info_2 = require("./functions/getApp/info");
 const info_3 = require("./functions/listActions/info");
 const info_4 = require("./functions/getAction/info");
 const info_5 = require("./functions/runAction/info");
-const info_6 = require("./functions/listAuths/info");
-const info_7 = require("./functions/listFields/info");
-const info_8 = require("./functions/generateTypes/info");
-const info_9 = require("./functions/bundleCode/info");
+const info_6 = require("./functions/listAuthentications/info");
+const info_7 = require("./functions/findFirstAuthentication/info");
+const info_8 = require("./functions/findUniqueAuthentication/info");
+const info_9 = require("./functions/listFields/info");
+const info_10 = require("./functions/generateTypes/info");
+const info_11 = require("./functions/bundleCode/info");
 // Function registry as array - uses names from function info objects
 const functionRegistry = [
     info_1.listAppsInfo,
@@ -29,32 +33,22 @@ const functionRegistry = [
     info_3.listActionsInfo,
     info_4.getActionInfo,
     info_5.runActionInfo,
-    info_6.listAuthsInfo,
-    info_7.listFieldsInfo,
-    info_8.generateTypesInfo,
-    info_9.bundleCodeInfo,
+    info_6.listAuthenticationsInfo,
+    info_7.findFirstAuthenticationInfo,
+    info_8.findUniqueAuthenticationInfo,
+    info_9.listFieldsInfo,
+    info_10.generateTypesInfo,
+    info_11.bundleCodeInfo,
 ];
 // Import plugin functions
 const index_1 = require("./plugins/apps/index");
 function createBaseZapierSdk(options = {}) {
-    // Auto-load .env files (searches up directory tree)
-    try {
-        const { findUpSync } = require("find-up");
-        const envPath = findUpSync(".env");
-        if (envPath) {
-            require("dotenv").config({ path: envPath, quiet: true });
-        }
-    }
-    catch {
-        // Silently fail if dotenv/find-up not available or .env not found
-    }
-    const { fetch: customFetch = globalThis.fetch, baseUrl = "https://zapier.com", token, debug = false, } = options;
-    // If no token provided, try to get it from environment variable
-    const finalToken = token || process.env.ZAPIER_TOKEN;
+    const { fetch: customFetch = globalThis.fetch, baseUrl = "https://zapier.com", token, getToken, debug = false, } = options;
     // Create the API client
     const api = (0, api_1.createZapierApi)({
         baseUrl,
-        token: finalToken,
+        token,
+        getToken,
         debug,
         fetch: customFetch,
     });
@@ -63,14 +57,16 @@ function createBaseZapierSdk(options = {}) {
         // Registry for CLI
         __registry: functionRegistry,
         // Function implementations with API config injection
-        listApps: (options = {}) => (0, listApps_1.listApps)({ ...options, api, token: finalToken }),
-        getApp: (options) => (0, getApp_1.getApp)({ ...options, api, token: finalToken }),
-        listActions: (options = {}) => (0, listActions_1.listActions)({ ...options, api, token: finalToken }),
-        getAction: (options) => (0, getAction_1.getAction)({ ...options, api, token: finalToken }),
-        runAction: (options) => (0, runAction_1.runAction)({ ...options, api, token: finalToken }),
-        listAuths: (options = {}) => (0, listAuths_1.listAuths)({ ...options, api, token: finalToken }),
-        listFields: (options) => (0, listFields_1.listFields)({ ...options, api, token: finalToken }),
-        generateTypes: (options) => (0, generateTypes_1.generateTypes)({ ...options, api, token: finalToken }),
+        listApps: (options = {}) => (0, listApps_1.listApps)({ ...options, api }),
+        getApp: (options) => (0, getApp_1.getApp)({ ...options, api }),
+        listActions: (options = {}) => (0, listActions_1.listActions)({ ...options, api }),
+        getAction: (options) => (0, getAction_1.getAction)({ ...options, api }),
+        runAction: (options) => (0, runAction_1.runAction)({ ...options, api }),
+        listAuthentications: (options = {}) => (0, listAuthentications_1.listAuthentications)({ ...options, api }),
+        findFirstAuthentication: (options = {}) => (0, findFirstAuthentication_1.findFirstAuthentication)({ ...options, api }),
+        findUniqueAuthentication: (options = {}) => (0, findUniqueAuthentication_1.findUniqueAuthentication)({ ...options, api }),
+        listFields: (options) => (0, listFields_1.listFields)({ ...options, api }),
+        generateTypes: (options) => (0, generateTypes_1.generateTypes)({ ...options, api }),
         bundleCode: (options) => (0, bundleCode_1.bundleCode)(options), // No API config needed
     };
     return sdk;
@@ -79,19 +75,19 @@ function createZapierSdk(options = {}) {
     // Create base SDK
     const baseSdk = createBaseZapierSdk(options);
     // Extract options needed for plugins
-    const { fetch: customFetch = globalThis.fetch, baseUrl = "https://zapier.com", token, debug = false, } = options;
-    const finalToken = token || process.env.ZAPIER_TOKEN;
+    const { fetch: customFetch = globalThis.fetch, baseUrl = "https://zapier.com", token, getToken, debug = false, } = options;
     // Create the API client for plugins
     const api = (0, api_1.createZapierApi)({
         baseUrl,
-        token: finalToken,
+        token,
+        getToken,
         debug,
         fetch: customFetch,
     });
     // Create plugins directly - TypeScript will enforce correct implementation
     const appsPlugin = (0, index_1.createAppsPlugin)({
         api,
-        token: finalToken,
+        token,
     });
     // Compose final SDK - TypeScript will enforce we have all required properties
     const fullSdk = {

package/dist/types/domain.d.ts

@@ -8,6 +8,7 @@ export interface AuthObject {
 }
 export interface BaseSdkOptions {
     token?: string;
+    getToken?: () => Promise<string | undefined>;
     fetch?: typeof fetch;
     baseUrl?: string;
     debug?: boolean;

package/dist/types/properties.js

@@ -2,12 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParamsPropertySchema = exports.DebugPropertySchema = exports.OutputPropertySchema = exports.OffsetPropertySchema = exports.LimitPropertySchema = exports.InputsPropertySchema = exports.AuthenticationIdPropertySchema = exports.ActionKeyPropertySchema = exports.ActionTypePropertySchema = exports.AppKeyPropertySchema = void 0;
 const zod_1 = require("zod");
+const schema_utils_1 = require("../schema-utils");
 // Shared property definitions for common parameters across functions
 // These can be reused in function schemas without duplication
-exports.AppKeyPropertySchema = zod_1.z
-    .string()
-    .min(1)
-    .describe("App slug (e.g., 'slack', 'github')");
+exports.AppKeyPropertySchema = (0, schema_utils_1.withPositional)(zod_1.z.string().min(1).describe("App slug (e.g., 'slack', 'github')"));
 exports.ActionTypePropertySchema = zod_1.z
     .enum(["read", "write", "search", "create", "update", "delete"])
     .describe("Action type that matches the action's defined type");

package/dist/types/sdk.d.ts

@@ -3,12 +3,14 @@ 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 { ListAuthsSdkFunction } from "../functions/listAuths/schemas";
+import type { ListAuthenticationsSdkFunction } from "../functions/listAuthentications/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 { AppsPluginSdkExtension } from "../plugins/apps/types";
-export interface ZapierSdkFunctions extends ListActionsSdkFunction, GetActionSdkFunction, GetAppSdkFunction, RunActionSdkFunction, ListFieldsSdkFunction, ListAuthsSdkFunction, GenerateTypesSdkFunction, ListAppsSdkFunction, BundleCodeSdkFunction {
+export interface ZapierSdkFunctions extends ListActionsSdkFunction, GetActionSdkFunction, GetAppSdkFunction, RunActionSdkFunction, ListFieldsSdkFunction, ListAuthenticationsSdkFunction, FindFirstAuthenticationSdkFunction, FindUniqueAuthenticationSdkFunction, GenerateTypesSdkFunction, ListAppsSdkFunction, BundleCodeSdkFunction {
 }
 export interface ZapierSdkPlugins extends AppsPluginSdkExtension {
 }

package/dist/utils/getTokenFromConfig.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Attempts to read the JWT token from the CLI config file.
+ * This is a synchronous function that only returns valid, non-expired tokens.
+ * For token refresh logic, the CLI should handle that separately.
+ * Returns undefined if config file doesn't exist, token is not available, or token is expired.
+ */
+export declare function getTokenFromConfig(): string | undefined;

package/dist/utils/getTokenFromConfig.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenFromConfig = getTokenFromConfig;
+/**
+ * Attempts to read the JWT token from the CLI config file.
+ * This is a synchronous function that only returns valid, non-expired tokens.
+ * For token refresh logic, the CLI should handle that separately.
+ * Returns undefined if config file doesn't exist, token is not available, or token is expired.
+ */
+function getTokenFromConfig() {
+    try {
+        // Dynamically import conf to avoid dependency issues if not installed
+        const Conf = require("conf");
+        const config = new Conf({ projectName: "zapier-sdk-cli" });
+        // Get the stored JWT token
+        const jwt = config.get("login_jwt");
+        const expiresAt = config.get("login_expires_at");
+        // Check if token exists and is not expired (with 30s buffer)
+        if (jwt && expiresAt && expiresAt > Date.now() + 30 * 1000) {
+            return jwt;
+        }
+        // Token is missing or expired - return undefined so SDK will require explicit auth
+        return undefined;
+    }
+    catch {
+        // Config package not available or other error - silently fail
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,9 +18,7 @@
     "access": "restricted"
   },
   "dependencies": {
-    "dotenv": "^17.0.0",
     "esbuild": "^0.25.5",
-    "find-up": "^7.0.0",
     "zod": "^3.25.67"
   },
   "devDependencies": {

package/src/api/client.ts

@@ -19,6 +19,7 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
   const {
     baseUrl,
     token,
+    getToken,
     debug = false,
     fetch: originalFetch = globalThis.fetch,
   } = options;
@@ -41,14 +42,29 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
   }
 
   // Helper to build headers
-  function buildHeaders(options: RequestOptions = {}): Record<string, string> {
+  async function buildHeaders(
+    options: RequestOptions = {},
+  ): Promise<Record<string, string>> {
     const headers: Record<string, string> = {
       ...options.headers,
     };
 
     // Add auth header if token provided and not explicitly disabled
-    if (token && options.authRequired !== false) {
-      headers.Authorization = getAuthorizationHeader(token);
+    if (options.authRequired !== false) {
+      let resolvedToken = token;
+
+      // Token resolution precedence: explicit token > getToken() > env var
+      if (!resolvedToken && getToken) {
+        resolvedToken = await getToken();
+      }
+
+      if (!resolvedToken) {
+        resolvedToken = process.env.ZAPIER_TOKEN;
+      }
+
+      if (resolvedToken) {
+        headers.Authorization = getAuthorizationHeader(resolvedToken);
+      }
     }
 
     return headers;
@@ -87,7 +103,7 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
     options: RequestOptions = {},
   ): Promise<any> {
     const url = buildUrl(path, options.searchParams);
-    const headers = buildHeaders(options);
+    const headers = await buildHeaders(options);
 
     // Add Content-Type for JSON requests with body data
     if (data && typeof data === "object") {
@@ -130,7 +146,7 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
 
     async poll(path: string, options: PollOptions = {}): Promise<any> {
       const url = buildUrl(path, options.searchParams);
-      const headers = buildHeaders(options);
+      const headers = await buildHeaders(options);
 
       return pollUntilComplete({
         fetch,
@@ -144,5 +160,14 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
         resultExtractor: options.resultExtractor,
       });
     },
+
+    requireAuthTo(operation: string): void {
+      // Check if any authentication method is available
+      if (!token && !getToken && !process.env.ZAPIER_TOKEN) {
+        throw new Error(
+          `Authentication token is required to ${operation}. Please provide token in options or set ZAPIER_TOKEN environment variable.`,
+        );
+      }
+    },
   };
 }

package/src/api/index.ts

@@ -29,6 +29,9 @@ export type {
   AuthenticationsResponse,
 } from "./types";
 
+// Import for local use
+import type { ApiClient } from "./types";
+
 // Re-export authentication utilities
 export { isJwt, getAuthorizationHeader } from "./auth";
 
@@ -41,6 +44,9 @@ export { pollUntilComplete } from "./polling";
 // Re-export the main client factory
 export { createZapierApi } from "./client";
 
+// Import for local use
+import { createZapierApi } from "./client";
+
 // Utility Functions
 export function generateRequestId(): string {
   return Math.random().toString(36).substring(2) + Date.now().toString(36);
@@ -55,13 +61,15 @@ export function generateRequestId(): string {
 export function getOrCreateApiClient(config: {
   baseUrl?: string;
   token?: string;
-  api?: import("./types").ApiClient;
+  getToken?: () => Promise<string | undefined>;
+  api?: ApiClient;
   debug?: boolean;
   fetch?: typeof globalThis.fetch;
-}): import("./types").ApiClient {
+}): ApiClient {
   const {
     baseUrl = "https://zapier.com",
-    token = process.env.ZAPIER_TOKEN,
+    token,
+    getToken,
     api: providedApi,
     debug = false,
     fetch: customFetch,
@@ -72,11 +80,10 @@ export function getOrCreateApiClient(config: {
     return providedApi;
   }
 
-  // Import createZapierApi locally to avoid circular imports
-  const { createZapierApi } = require("./client");
   return createZapierApi({
     baseUrl,
     token,
+    getToken,
     debug,
     fetch: customFetch,
   });

package/src/api/types.ts

@@ -13,6 +13,7 @@
 export interface ApiClientOptions {
   baseUrl: string;
   token?: string;
+  getToken?: () => Promise<string | undefined>;
   debug?: boolean;
   fetch?: typeof globalThis.fetch;
 }
@@ -23,6 +24,7 @@ export interface ApiClient {
   put: (path: string, data?: any, options?: RequestOptions) => Promise<any>;
   delete: (path: string, options?: RequestOptions) => Promise<any>;
   poll: (path: string, options?: PollOptions) => Promise<any>;
+  requireAuthTo: (operation: string) => void;
 }
 
 export interface RequestOptions {

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