@zapier/zapier-sdk 0.1.0 → 0.2.0

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/{listAuths → listAuthentications}/index.ts

@@ -4,7 +4,7 @@ import type {
   AuthenticationsResponse,
 } from "../../types/domain";
 import { getApp } from "../getApp";
-import type { ListAuthsOptions } from "./schemas";
+import type { ListAuthenticationsOptions } from "./schemas";
 
 /**
  * List available authentications with optional filtering
@@ -15,22 +15,15 @@ import type { ListAuthsOptions } from "./schemas";
  * @param options - Filtering, pagination, and API configuration options
  * @returns Promise<Authentication[]> with pagination metadata
  */
-export async function listAuths(
-  options: Partial<ListAuthsOptions> = {},
+export async function listAuthentications(
+  options: Partial<ListAuthenticationsOptions> = {},
 ): Promise<Authentication[]> {
-  const { token } = options;
-
-  if (!token && !process.env.ZAPIER_TOKEN) {
-    throw new Error(
-      "Authentication token is required to list authentications. Please provide token in options or set ZAPIER_TOKEN environment variable.",
-    );
-  }
-
   const api = getOrCreateApiClient(options);
+  api.requireAuthTo("list authentications");
 
   // Local function to handle the actual API fetching
-  const listAuthsInternal = async (
-    options: ListAuthsOptions = {},
+  const listAuthenticationsInternal = async (
+    options: ListAuthenticationsOptions = {},
   ): Promise<Authentication[]> => {
     // Build search parameters
     const searchParams: Record<string, string> = {};
@@ -68,6 +61,12 @@ export async function listAuths(
     }
 
     // Add other query parameters if provided
+    // Use title as search if no explicit search provided
+    if (options.search) {
+      searchParams.search = options.search;
+    } else if (options.title) {
+      searchParams.search = options.title;
+    }
     if (options.account_id) {
       searchParams.account_id = options.account_id;
     }
@@ -102,7 +101,18 @@ export async function listAuths(
     );
 
     // Transform API response
-    const auths = data.results || [];
+    let auths = data.results || [];
+
+    // Coerce title from label if title is missing (API cleanup)
+    auths = auths.map((auth) => ({
+      ...auth,
+      title: auth.title || (auth as any).label || undefined,
+    }));
+
+    // Filter by exact title match if specified
+    if (options.title) {
+      auths = auths.filter((auth) => auth.title === options.title);
+    }
 
     // Add pagination metadata to the response
     if (auths.length > 0) {
@@ -121,7 +131,7 @@ export async function listAuths(
   // If a limit is provided and no specific owner filter, prioritize owned auths
   if (options.limit && options.owner === undefined) {
     // First get owned auths
-    const ownedAuths = await listAuthsInternal({
+    const ownedAuths = await listAuthenticationsInternal({
       ...options,
       owner: "me",
     });
@@ -132,7 +142,7 @@ export async function listAuths(
     }
 
     // Get all auths up to the original limit to fill remaining slots
-    const allAuths = await listAuthsInternal({
+    const allAuths = await listAuthenticationsInternal({
       ...options,
       owner: undefined,
     });
@@ -149,5 +159,5 @@ export async function listAuths(
   }
 
   // Standard implementation for non-prioritized requests
-  return listAuthsInternal(options);
+  return listAuthenticationsInternal(options);
 }

package/src/functions/listAuthentications/info.ts

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

package/src/functions/{listAuths → listAuthentications}/schemas.ts

@@ -9,12 +9,20 @@ import { AuthItemSchema } from "../../schemas/Auth";
 import type { Authentication } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
-export const ListAuthsSchema = withOutputSchema(
+export const ListAuthenticationsSchema = 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(
@@ -29,11 +37,15 @@ export const ListAuthsSchema = withOutputSchema(
 );
 
 // Type inferred from schema + function config
-export type ListAuthsOptions = z.infer<typeof ListAuthsSchema> & {
+export type ListAuthenticationsOptions = z.infer<
+  typeof ListAuthenticationsSchema
+> & {
   /** 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 */
@@ -43,6 +55,8 @@ export type ListAuthsOptions = z.infer<typeof ListAuthsSchema> & {
 };
 
 // SDK function interface - ready to be mixed into main SDK interface
-export interface ListAuthsSdkFunction {
-  listAuths: (options?: Partial<ListAuthsOptions>) => Promise<Authentication[]>;
+export interface ListAuthenticationsSdkFunction {
+  listAuthentications: (
+    options?: Partial<ListAuthenticationsOptions>,
+  ) => Promise<Authentication[]>;
 }

package/src/functions/runAction/index.ts

@@ -25,13 +25,8 @@ export async function runAction(
     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 = getOrCreateApiClient(options);
+  api.requireAuthTo("run actions");
 
   // Validate that the action exists
   const actionData = await getAction({

package/src/functions/runAction/schemas.ts

@@ -27,6 +27,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/src/index.ts

@@ -3,13 +3,18 @@ export * from "./types/domain";
 export * from "./types/properties";
 export * from "./plugins/apps";
 
+// Export schema utilities for CLI
+export { isPositional } from "./schema-utils";
+
 // Export resolvers for CLI use
 export * from "./resolvers";
 
 // Note: SdkSchemas is now available via SDK.__registry
 
 // Export individual functions for tree-shaking
-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/src/resolvers/authenticationId.ts

@@ -15,7 +15,7 @@ export const authenticationIdResolver: AuthenticationIdResolver = {
   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({
+    return await sdk.listAuthentications({
       appKey: resolvedParams.appKey,
       limit: 1000,
     });

package/src/schema-utils.ts

@@ -117,3 +117,38 @@ export function getFieldDescriptions(
 
   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/Auth.ts

@@ -9,7 +9,6 @@ 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(),
@@ -27,13 +26,6 @@ export const AuthItemSchema = withFormatter(
         });
       }
 
-      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,
@@ -47,7 +39,7 @@ export const AuthItemSchema = withFormatter(
       }
 
       return {
-        title: item.title || item.label || `Authentication ${item.id}`,
+        title: item.title || `Authentication ${item.id}`,
         subtitle: `(ID: ${item.id})`,
         details,
       };

package/src/sdk.ts

@@ -6,7 +6,9 @@ import { getApp } from "./functions/getApp";
 import { listActions } from "./functions/listActions";
 import { getAction } from "./functions/getAction";
 import { runAction } from "./functions/runAction";
-import { listAuths } from "./functions/listAuths";
+import { listAuthentications } from "./functions/listAuthentications";
+import { findFirstAuthentication } from "./functions/findFirstAuthentication";
+import { findUniqueAuthentication } from "./functions/findUniqueAuthentication";
 import { listFields } from "./functions/listFields";
 import { generateTypes } from "./functions/generateTypes";
 import { bundleCode } from "./functions/bundleCode";
@@ -17,7 +19,9 @@ import { getAppInfo } from "./functions/getApp/info";
 import { listActionsInfo } from "./functions/listActions/info";
 import { getActionInfo } from "./functions/getAction/info";
 import { runActionInfo } from "./functions/runAction/info";
-import { listAuthsInfo } from "./functions/listAuths/info";
+import { listAuthenticationsInfo } from "./functions/listAuthentications/info";
+import { findFirstAuthenticationInfo } from "./functions/findFirstAuthentication/info";
+import { findUniqueAuthenticationInfo } from "./functions/findUniqueAuthentication/info";
 import { listFieldsInfo } from "./functions/listFields/info";
 import { generateTypesInfo } from "./functions/generateTypes/info";
 import { bundleCodeInfo } from "./functions/bundleCode/info";
@@ -29,7 +33,9 @@ const functionRegistry = [
   listActionsInfo,
   getActionInfo,
   runActionInfo,
-  listAuthsInfo,
+  listAuthenticationsInfo,
+  findFirstAuthenticationInfo,
+  findUniqueAuthenticationInfo,
   listFieldsInfo,
   generateTypesInfo,
   bundleCodeInfo,
@@ -55,7 +61,9 @@ interface BaseZapierSdkWithFunctions {
   listActions: ZapierSdk["listActions"];
   getAction: ZapierSdk["getAction"];
   runAction: ZapierSdk["runAction"];
-  listAuths: ZapierSdk["listAuths"];
+  listAuthentications: ZapierSdk["listAuthentications"];
+  findFirstAuthentication: ZapierSdk["findFirstAuthentication"];
+  findUniqueAuthentication: ZapierSdk["findUniqueAuthentication"];
   listFields: ZapierSdk["listFields"];
   generateTypes: ZapierSdk["generateTypes"];
   bundleCode: ZapierSdk["bundleCode"];
@@ -69,31 +77,19 @@ export interface ZapierSdkOptions extends BaseSdkOptions {}
 function createBaseZapierSdk(
   options: ZapierSdkOptions = {},
 ): BaseZapierSdkWithFunctions {
-  // 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,
+    getToken,
     debug = false,
   } = options;
 
-  // If no token provided, try to get it from environment variable
-  const finalToken = token || process.env.ZAPIER_TOKEN;
-
   // Create the API client
   const api = createZapierApi({
     baseUrl,
-    token: finalToken,
+    token,
+    getToken,
     debug,
     fetch: customFetch,
   });
@@ -104,18 +100,19 @@ function createBaseZapierSdk(
     __registry: functionRegistry,
 
     // Function implementations with API config injection
-    listApps: (options = {}) =>
-      listApps({ ...options, api, token: finalToken }),
-    getApp: (options) => getApp({ ...options, api, token: finalToken }),
-    listActions: (options = {}) =>
-      listActions({ ...options, api, token: finalToken }),
-    getAction: (options) => getAction({ ...options, api, token: finalToken }),
-    runAction: (options) => runAction({ ...options, api, token: finalToken }),
-    listAuths: (options = {}) =>
-      listAuths({ ...options, api, token: finalToken }),
-    listFields: (options) => listFields({ ...options, api, token: finalToken }),
-    generateTypes: (options) =>
-      generateTypes({ ...options, api, token: finalToken }),
+    listApps: (options = {}) => listApps({ ...options, api }),
+    getApp: (options) => getApp({ ...options, api }),
+    listActions: (options = {}) => listActions({ ...options, api }),
+    getAction: (options) => getAction({ ...options, api }),
+    runAction: (options) => runAction({ ...options, api }),
+    listAuthentications: (options = {}) =>
+      listAuthentications({ ...options, api }),
+    findFirstAuthentication: (options = {}) =>
+      findFirstAuthentication({ ...options, api }),
+    findUniqueAuthentication: (options = {}) =>
+      findUniqueAuthentication({ ...options, api }),
+    listFields: (options) => listFields({ ...options, api }),
+    generateTypes: (options) => generateTypes({ ...options, api }),
     bundleCode: (options) => bundleCode(options), // No API config needed
   };
 
@@ -131,15 +128,15 @@ export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
     fetch: customFetch = globalThis.fetch,
     baseUrl = "https://zapier.com",
     token,
+    getToken,
     debug = false,
   } = options;
 
-  const finalToken = token || process.env.ZAPIER_TOKEN;
-
   // Create the API client for plugins
   const api = createZapierApi({
     baseUrl,
-    token: finalToken,
+    token,
+    getToken,
     debug,
     fetch: customFetch,
   });
@@ -147,7 +144,7 @@ export function createZapierSdk(options: ZapierSdkOptions = {}): ZapierSdk {
   // Create plugins directly - TypeScript will enforce correct implementation
   const appsPlugin = createAppsPlugin({
     api,
-    token: finalToken,
+    token,
   });
 
   // Compose final SDK - TypeScript will enforce we have all required properties

package/src/types/domain.ts

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

package/src/types/properties.ts

@@ -1,12 +1,12 @@
 import { z } from "zod";
+import { withPositional } from "../schema-utils";
 
 // Shared property definitions for common parameters across functions
 // These can be reused in function schemas without duplication
 
-export const AppKeyPropertySchema = z
-  .string()
-  .min(1)
-  .describe("App slug (e.g., 'slack', 'github')");
+export const AppKeyPropertySchema = withPositional(
+  z.string().min(1).describe("App slug (e.g., 'slack', 'github')"),
+);
 
 export const ActionTypePropertySchema = z
   .enum(["read", "write", "search", "create", "update", "delete"])

package/src/types/sdk.ts

@@ -4,7 +4,9 @@ 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";
@@ -19,7 +21,9 @@ export interface ZapierSdkFunctions
     GetAppSdkFunction,
     RunActionSdkFunction,
     ListFieldsSdkFunction,
-    ListAuthsSdkFunction,
+    ListAuthenticationsSdkFunction,
+    FindFirstAuthenticationSdkFunction,
+    FindUniqueAuthenticationSdkFunction,
     GenerateTypesSdkFunction,
     ListAppsSdkFunction,
     BundleCodeSdkFunction {

package/src/utils/getTokenFromConfig.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 function getTokenFromConfig(): string | undefined {
+  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") as string | undefined;
+    const expiresAt = config.get("login_expires_at") as number | undefined;
+
+    // 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/dist/functions/listAuths/info.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listAuthsInfo = void 0;
-const index_1 = require("./index");
-const schemas_1 = require("./schemas");
-// Function registry info - imports both function and schema
-exports.listAuthsInfo = {
-    name: index_1.listAuths.name,
-    inputSchema: schemas_1.ListAuthsSchema,
-    implementation: index_1.listAuths,
-};

package/src/functions/listAuths/info.ts

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