@zapier/zapier-sdk 0.1.1 → 0.2.1

package/src/api/client.ts

@@ -14,11 +14,13 @@ import type {
 import { getAuthorizationHeader } from "./auth";
 import { createDebugLogger, createDebugFetch } from "./debug";
 import { pollUntilComplete } from "./polling";
+import { getTokenFromEnv } from "../auth";
 
 export function createZapierApi(options: ApiClientOptions): ApiClient {
   const {
     baseUrl,
     token,
+    getToken,
     debug = false,
     fetch: originalFetch = globalThis.fetch,
   } = options;
@@ -41,14 +43,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 = getTokenFromEnv();
+      }
+
+      if (resolvedToken) {
+        headers.Authorization = getAuthorizationHeader(resolvedToken);
+      }
     }
 
     return headers;
@@ -87,7 +104,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 +147,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 +161,14 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
         resultExtractor: options.resultExtractor,
       });
     },
+
+    requireAuthTo(operation: string): void {
+      // Check if any authentication method is available
+      if (!token && !getToken && !getTokenFromEnv()) {
+        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 {
@@ -65,7 +67,15 @@ export interface Action {
   name: string;
   description: string;
   appKey: string;
-  type: "create" | "update" | "search" | "delete" | "read";
+  type:
+    | "read"
+    | "read_bulk"
+    | "write"
+    | "run"
+    | "search"
+    | "search_or_write"
+    | "search_and_write"
+    | "filter";
   inputFields: Field[];
   outputFields: Field[];
 }

package/src/auth.ts

@@ -0,0 +1,340 @@
+/**
+ * SDK Authentication Utilities
+ *
+ * This module provides SDK-level authentication utilities, including
+ * token acquisition, refresh, and user information extraction.
+ */
+
+// Import type { RequestOptions } from "./api/types"; // Commented out - not used yet
+
+let config: any;
+
+// Import event types from common location
+import type { EventCallback } from "./types/events";
+
+// Re-export for backward compatibility
+export type {
+  SdkEvent,
+  AuthEvent,
+  ApiEvent,
+  LoadingEvent,
+  EventCallback,
+} from "./types/events";
+
+// Options interfaces for auth functions
+export interface AuthOptions {
+  onEvent?: EventCallback;
+  fetch?: typeof globalThis.fetch;
+}
+
+// JWT payload interfaces
+interface JwtPayload {
+  payload: Record<string, any>;
+}
+
+export interface LoginData {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+}
+
+// Constants needed for token refresh
+const ZAPIER_BASE = "https://zapier.com";
+const LOGIN_CLIENT_ID = "K5eEnRE9TTmSFATdkkWhKF8NOKwoiOnYAyIqJjae";
+const AUTH_MODE_HEADER = "X-Auth";
+
+// Utility functions for config management
+function getConfig() {
+  if (!config) {
+    const ConfModule = require("conf");
+    const Conf = ConfModule.default || ConfModule;
+    config = new Conf({ projectName: "zapier-sdk-cli" });
+  }
+  return config;
+}
+
+export function updateLogin(loginData: LoginData): void {
+  const cfg = getConfig();
+  cfg.set("login_jwt", loginData.access_token);
+  cfg.set("login_refresh_token", loginData.refresh_token);
+  cfg.set("login_expires_at", Date.now() + loginData.expires_in * 1000);
+}
+
+function clearLogin(): void {
+  const cfg = getConfig();
+  cfg.delete("login_jwt");
+  cfg.delete("login_refresh_token");
+  cfg.delete("login_expires_at");
+}
+
+// JWT utility functions
+function decodeJwtOrThrow(jwt: unknown): JwtPayload {
+  if (typeof jwt !== "string") {
+    throw new Error("Expected JWT to be a string");
+  }
+
+  let jsonwebtoken: any;
+  try {
+    jsonwebtoken = require("jsonwebtoken");
+  } catch {
+    throw new Error(
+      "jsonwebtoken not available - this function requires CLI dependencies",
+    );
+  }
+
+  const decodedJwt = jsonwebtoken.decode(jwt, { complete: true });
+
+  if (!decodedJwt) {
+    throw new Error("Could not decode JWT");
+  }
+
+  if (typeof decodedJwt.payload === "string") {
+    throw new Error("Did not expect JWT payload to be a string");
+  }
+
+  return decodedJwt;
+}
+
+/**
+ * Refreshes an expired JWT token using the refresh token.
+ * Returns the new access token or throws an error.
+ */
+async function refreshJwt(
+  refreshToken: string,
+  options: AuthOptions = {},
+): Promise<string> {
+  const { onEvent, fetch = globalThis.fetch } = options;
+
+  try {
+    onEvent?.({
+      type: "auth_refreshing",
+      payload: {
+        message: "Refreshing your token...",
+        operation: "token_refresh",
+      },
+      timestamp: Date.now(),
+    });
+
+    const response = await fetch(`${ZAPIER_BASE}/oauth/token/`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        [AUTH_MODE_HEADER]: "no",
+      },
+      body: new URLSearchParams({
+        client_id: LOGIN_CLIENT_ID,
+        refresh_token: refreshToken,
+        grant_type: "refresh_token",
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Token refresh failed: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const data: LoginData = await response.json();
+
+    // Update stored login data
+    updateLogin(data);
+
+    onEvent?.({
+      type: "auth_success",
+      payload: {
+        message: "Token refreshed successfully",
+        operation: "token_refresh",
+      },
+      timestamp: Date.now(),
+    });
+    return data.access_token;
+  } catch (error) {
+    // If refresh fails, clear stored login
+    clearLogin();
+    const errorMessage = `Token refresh failed: ${error instanceof Error ? error.message : "Unknown error"}`;
+    onEvent?.({
+      type: "auth_error",
+      payload: {
+        message: errorMessage,
+        error: errorMessage,
+        operation: "token_refresh",
+      },
+      timestamp: Date.now(),
+    });
+    throw error;
+  }
+}
+
+/**
+ * Attempts to read a valid JWT token from the CLI configuration.
+ * Automatically refreshes expired tokens when possible.
+ * Returns undefined if no valid token is found or refresh fails.
+ */
+export async function getTokenFromConfig(
+  options: AuthOptions = {},
+): Promise<string | undefined> {
+  try {
+    const cfg = getConfig();
+
+    const jwt = cfg.get("login_jwt") as string | undefined;
+    const refreshToken = cfg.get("login_refresh_token") as string | undefined;
+    const expiresAt = cfg.get("login_expires_at") as number | undefined;
+
+    // Check if we have all required fields
+    if (!jwt || !refreshToken || !expiresAt) {
+      return undefined;
+    }
+
+    // Check if token is still valid (with 30 second buffer)
+    if (expiresAt > Date.now() + 30 * 1000) {
+      return jwt;
+    }
+
+    // Token is expired - attempt to refresh
+    try {
+      return await refreshJwt(refreshToken, options);
+    } catch {
+      // If refresh fails, return undefined
+      return undefined;
+    }
+  } catch {
+    // If conf is not available or any other error occurs, return undefined
+    return undefined;
+  }
+}
+
+/**
+ * Gets the ZAPIER_TOKEN from environment variables.
+ * Returns undefined if not set.
+ */
+export function getTokenFromEnv(): string | undefined {
+  return process.env.ZAPIER_TOKEN;
+}
+
+/**
+ * Attempts to get a token with the following precedence:
+ * 1. ZAPIER_TOKEN environment variable
+ * 2. Valid JWT from CLI configuration (with auto-refresh)
+ *
+ * Returns undefined if no valid token is found.
+ */
+export async function getTokenFromEnvOrConfig(
+  options: AuthOptions = {},
+): Promise<string | undefined> {
+  // First priority: environment variable
+  const envToken = getTokenFromEnv();
+  if (envToken) {
+    return envToken;
+  }
+
+  // Second priority: CLI configuration (with auto-refresh)
+  return getTokenFromConfig(options);
+}
+
+/**
+ * Gets the current JWT token, refreshing if necessary.
+ * Returns undefined if no valid token is available.
+ */
+export async function getValidJwt(
+  options: AuthOptions = {},
+): Promise<string | undefined> {
+  try {
+    const cfg = getConfig();
+
+    const jwt = cfg.get("login_jwt") as string | undefined;
+    const refreshToken = cfg.get("login_refresh_token") as string | undefined;
+    const expiresAt = cfg.get("login_expires_at") as number | undefined;
+
+    // Check if we have all required fields
+    if (!jwt || !refreshToken || !expiresAt) {
+      return undefined;
+    }
+
+    // Check if token is still valid (with 30 second buffer)
+    if (expiresAt > Date.now() + 30 * 1000) {
+      return jwt;
+    }
+
+    // Token is expired - attempt to refresh
+    return await refreshJwt(refreshToken, options);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Gets the logged-in user information from JWT token.
+ * Automatically refreshes token if expired.
+ */
+export async function getLoggedInUser(options: AuthOptions = {}): Promise<{
+  accountId: number;
+  customUserId: number;
+  email: string;
+}> {
+  const jwt = await getValidJwt(options);
+
+  if (!jwt) {
+    throw new Error(
+      "No valid authentication token available. Please login first.",
+    );
+  }
+
+  let decodedJwt = decodeJwtOrThrow(jwt);
+
+  if (decodedJwt.payload["sub_type"] == "service") {
+    decodedJwt = decodeJwtOrThrow(decodedJwt.payload["njwt"]);
+  }
+
+  if (typeof decodedJwt.payload["zap:acc"] !== "string") {
+    throw new Error("JWT payload does not contain accountId");
+  }
+
+  const accountId = parseInt(decodedJwt.payload["zap:acc"], 10);
+  if (isNaN(accountId)) {
+    throw new Error("JWT accountId is not a number");
+  }
+
+  if (
+    decodedJwt.payload["sub_type"] !== "customuser" ||
+    typeof decodedJwt.payload["sub"] !== "string"
+  ) {
+    throw new Error("JWT payload does not contain customUserId");
+  }
+
+  const customUserId = parseInt(decodedJwt.payload["sub"], 10);
+  if (isNaN(customUserId)) {
+    throw new Error("JWT customUserId is not a number");
+  }
+
+  const email = decodedJwt.payload["zap:uname"];
+  if (typeof email !== "string") {
+    throw new Error("JWT payload does not contain email");
+  }
+
+  return {
+    accountId,
+    customUserId,
+    email,
+  };
+}
+
+/**
+ * Clears stored login information.
+ */
+export function logout(options: Pick<AuthOptions, "onEvent"> = {}): void {
+  const { onEvent } = options;
+  clearLogin();
+  onEvent?.({
+    type: "auth_logout",
+    payload: { message: "Logged out successfully", operation: "logout" },
+    timestamp: Date.now(),
+  });
+}
+
+/**
+ * Gets the path to the configuration file.
+ */
+export function getConfigPath(): string {
+  const cfg = getConfig();
+  return cfg.path;
+}

package/src/functions/getAuthentication/index.ts

@@ -0,0 +1,51 @@
+import { getOrCreateApiClient } from "../../api";
+import type { Authentication } from "../../types/domain";
+import type { GetAuthenticationOptions } from "./schemas";
+
+/**
+ * Get a specific authentication by ID
+ *
+ * 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 - Authentication ID and API configuration options
+ * @returns Promise<Authentication> - The authentication details
+ * @throws Error if authentication not found or access denied
+ */
+export async function getAuthentication(
+  options: GetAuthenticationOptions,
+): Promise<Authentication> {
+  const { authenticationId } = options;
+  const api = getOrCreateApiClient(options);
+  api.requireAuthTo("get authentication");
+
+  const data: Authentication = await api.get(
+    `/api/v4/authentications/${authenticationId}/`,
+    {
+      customErrorHandler: (response) => {
+        if (response.status === 401) {
+          return new Error(
+            `Authentication failed. Your token may not have permission to access authentications or may be expired. (HTTP ${response.status})`,
+          );
+        }
+        if (response.status === 403) {
+          return new Error(
+            `Access forbidden. Your token may not have the required scopes to get authentication ${authenticationId}. (HTTP ${response.status})`,
+          );
+        }
+        if (response.status === 404) {
+          return new Error(
+            `Authentication ${authenticationId} not found. It may not exist or you may not have access to it. (HTTP ${response.status})`,
+          );
+        }
+        return undefined;
+      },
+    },
+  );
+
+  // Coerce title from label if title is missing (API cleanup)
+  return {
+    ...data,
+    title: data.title || (data as any).label || undefined,
+  };
+}

package/src/functions/getAuthentication/info.ts

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

package/src/functions/getAuthentication/schemas.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { withOutputSchema } from "../../schema-utils";
+import { AuthItemSchema } from "../../schemas/Auth";
+import type { Authentication } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetAuthenticationSchema = withOutputSchema(
+  z
+    .object({
+      authenticationId: z
+        .number()
+        .int()
+        .positive()
+        .describe("Authentication ID to retrieve"),
+    })
+    .describe("Get a specific authentication by ID"),
+  AuthItemSchema,
+);
+
+// Type inferred from schema + function config
+export type GetAuthenticationOptions = z.infer<
+  typeof GetAuthenticationSchema
+> & {
+  /** 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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetAuthenticationSdkFunction {
+  getAuthentication: (
+    options: GetAuthenticationOptions,
+  ) => Promise<Authentication>;
+}

package/src/functions/listAuthentications/index.ts

@@ -18,15 +18,8 @@ import type { ListAuthenticationsOptions } from "./schemas";
 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 listAuthenticationsInternal = async (

package/src/functions/listAuthentications/schemas.ts

@@ -44,6 +44,8 @@ export type ListAuthenticationsOptions = z.infer<
   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 */