API Requests

/**
 * Creates and executes an authenticated API request with retry logic and HTTP/2 support
 * @param parameters - Request parameters including options, params, and context
 * @returns Promise resolving to API response
 */
function createAPIRequest<T>(
  parameters: APIRequestParams<T>
): Promise<GaxiosResponseWithHTTP2<T>>;

/**
 * Creates and executes an authenticated API request with callback
 * @param parameters - Request parameters including options, params, and context
 * @param callback - Callback for handling response
 */
function createAPIRequest<T>(
  parameters: APIRequestParams<T>,
  callback: BodyResponseCallback<T>
): void;

/**
 * Request parameters for API calls
 */
interface APIRequestParams<T = any> {
  /** Request options including URL, method, headers, etc. */
  options: MethodOptions;
  /** Query parameters and request body data */
  params: T;
  /** List of required parameter names that must be present */
  requiredParams: string[];
  /** List of parameters that should be inserted into URL path */
  pathParams: string[];
  /** Request context containing authentication and global options */
  context: APIRequestContext;
  /** Optional media upload URL for file uploads */
  mediaUrl?: string | null;
}

import { 
  createAPIRequest, 
  APIRequestParams,
  APIRequestContext,
  MethodOptions 
} from "googleapis-common";

// Basic API request
const requestParams: APIRequestParams = {
  options: {
    url: 'https://example.googleapis.com/v1/projects/{projectId}/resources',
    method: 'GET'
  } as MethodOptions,
  params: { projectId: 'my-project', filter: 'active=true' },
  requiredParams: ['projectId'],
  pathParams: ['projectId'],
  context: {
    _options: {
      auth: googleAuth,
      rootUrl: 'https://example.googleapis.com/'
    }
  }
};

const response = await createAPIRequest(requestParams);

// With callback
createAPIRequest(requestParams, (err, res) => {
  if (err) {
    console.error('API request failed:', err);
  } else {
    console.log('Response data:', res?.data);
  }
});

// Media upload request
const uploadParams: APIRequestParams = {
  options: {
    url: 'https://example.googleapis.com/upload/v1/files',
    method: 'POST',
    body: fileStream
  } as MethodOptions,
  params: { uploadType: 'media', name: 'myfile.txt' },
  requiredParams: ['name'],
  pathParams: [],
  context: { _options: { auth: googleAuth } },
  mediaUrl: 'https://example.googleapis.com/upload/v1/files'
};

const uploadResponse = await createAPIRequest(uploadParams);

/**
 * Request context providing authentication and configuration
 */
interface APIRequestContext {
  /** Google configuration object (optional) */
  google?: GoogleConfigurable;
  /** Global options including authentication */
  _options: GlobalOptions;
}

/**
 * Google-configurable object interface
 */
interface GoogleConfigurable {
  /** Global options for all API calls */
  _options: GlobalOptions;
}

/**
 * Global options extending method options with authentication
 */
interface GlobalOptions extends MethodOptions {
  /** Authentication client or credentials */
  auth?: GoogleAuth | OAuth2Client | BaseExternalAccountClient | string;
  /** Universe domain for API endpoints (e.g., googleapis.com) */
  universeDomain?: string;
  /** Alternative spelling of universeDomain */
  universe_domain?: string;
}

/**
 * Method-specific options extending Gaxios options
 */
interface MethodOptions extends GaxiosOptions {
  /** API version to use (e.g., 'v1', 'v2') */
  apiVersion?: string;
  /** Root URL for API endpoints */
  rootUrl?: string;
  /** Whether to use HTTP/2 for this request */
  http2?: boolean;
  /** Additional user agent directives */
  userAgentDirectives?: UserAgentDirective[];
}

/**
 * Streaming method options requiring stream response type
 */
interface StreamMethodOptions extends MethodOptions {
  /** Response type must be 'stream' for streaming requests */
  responseType: 'stream';
}

/**
 * Service-level options for API clients
 */
interface ServiceOptions extends GlobalOptions {
  /** Service version (e.g., 'v1', 'beta') */
  version?: string;
}

/**
 * Callback function type for API responses
 */
type BodyResponseCallback<T> = (
  err: Error | null,
  res?: GaxiosResponseWithHTTP2<T> | null
) => void;

/**
 * User agent directive for custom user agent strings
 */
interface UserAgentDirective {
  /** Product name */
  product: string;
  /** Product version */
  version: string;
  /** Optional comment */
  comment?: string;
}

/**
 * API endpoint type (read-only endpoint with additional properties)
 */
type APIEndpoint = Readonly<Endpoint & any>;

/**
 * Creates API endpoint instance from version definitions
 * @param api - API name (e.g., 'drive', 'sheets')
 * @param options - Service options or version string
 * @param versions - Object mapping version strings to constructor functions
 * @param context - Optional Google configuration context
 * @returns Frozen API endpoint instance
 */
function getAPI<T>(
  api: string,
  options: ServiceOptions | string,
  versions: {[index: string]: any},
  context?: GoogleConfigurable
): T;

import { getAPI, ServiceOptions } from "googleapis-common";

// Using version string
const driveV3 = getAPI('drive', 'v3', {
  'v3': DriveV3Constructor,
  'v2': DriveV2Constructor
});

// Using service options
const sheetsV4 = getAPI<SheetsV4>('sheets', {
  version: 'v4',
  auth: googleAuth,
  rootUrl: 'https://sheets.googleapis.com/'
} as ServiceOptions, {
  'v4': SheetsV4Constructor
});

// With context
const calendarV3 = getAPI('calendar', 'v3', {
  'v3': CalendarV3Constructor
}, {
  _options: {
    auth: oauth2Client,
    quotaUser: 'user@example.com'
  }
});