Discovery and Schemas

/**
 * Discovery class for discovering API endpoints and generating client code
 */
class Discovery {
  /**
   * Creates a new Discovery instance
   * @param options - Discovery configuration options
   */
  constructor(options: DiscoveryOptions);

  /**
   * Discover an API by fetching its discovery document from URL or file
   * @param apiDiscoveryUrl - URL or filename of discovery doc for API
   * @returns Promise resolving to endpoint creator function
   */
  discoverAPI(apiDiscoveryUrl: string | {url?: string}): Promise<EndpointCreator>;

  /**
   * Discover all APIs from the Google APIs discovery service
   * @param discoveryUrl - URL of the discovery service
   * @returns Promise resolving to discovery results object
   */
  discoverAllAPIs(discoveryUrl: string): Promise<{}>;
}

/**
 * Configuration options for Discovery
 */
interface DiscoveryOptions {
  /** Whether to include private/internal APIs in discovery */
  includePrivate?: boolean;
  /** Enable debug logging for discovery operations */
  debug?: boolean;
}

/**
 * Function type for creating endpoint instances
 */
type EndpointCreator = (options: GlobalOptions, google: {}) => Endpoint;

import { Discovery, DiscoveryOptions, EndpointCreator } from "googleapis-common";

// Create discovery instance
const discovery = new Discovery({
  includePrivate: false,
  debug: true
});

// Discover a specific API from URL
const createDriveEndpoint: EndpointCreator = await discovery.discoverAPI(
  'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest'
);

// Create endpoint instance
const driveClient = createDriveEndpoint({
  auth: googleAuth,
  rootUrl: 'https://www.googleapis.com/'
}, {});

// Discover from local file
const createSheetsEndpoint: EndpointCreator = await discovery.discoverAPI('./sheets-v4.json');

// Discover all available APIs
const allAPIs = await discovery.discoverAllAPIs(
  'https://www.googleapis.com/discovery/v1/apis'
);
console.log('Discovered APIs:', allAPIs);

/**
 * Base endpoint class implementing Target and APIRequestContext
 */
class Endpoint implements Target, APIRequestContext {
  /** Global options for the endpoint */
  _options: GlobalOptions;
  /** Google configuration object */
  google: any;
  /** Dynamic properties for API resources and methods */
  [index: string]: {};

  /**
   * Creates a new Endpoint instance
   * @param options - Configuration options for the endpoint
   */
  constructor(options: {});

  /**
   * Apply a schema to a target object, adding methods and resources
   * @param target - The target to which to apply the schema
   * @param rootSchema - The top-level schema for reference
   * @param schema - The current schema from which to extract methods and resources
   * @param context - The context to add to each method
   */
  applySchema(
    target: Target,
    rootSchema: Schema,
    schema: Schema | SchemaResource,
    context: APIRequestContext
  ): void;
}

/**
 * Target interface for objects that can have schema applied
 */
interface Target {
  /** Dynamic properties for API methods and resources */
  [index: string]: {};
}

/**
 * Root schema collection from discovery service
 */
interface Schemas {
  /** Discovery document version */
  discoveryVersion: string;
  /** Document kind identifier */
  kind: string;
  /** Array of individual API schemas */
  items: Schema[];
}

/**
 * Individual API schema definition
 */
interface Schema {
  /** OAuth2 authentication configuration */
  auth: {
    oauth2: {
      scopes: {[index: string]: {description: string}};
    };
  };
  /** Base path for API endpoints */
  basePath: string;
  /** Base URL for API endpoints */
  baseUrl: string;
  /** Batch request path */
  batchPath: string;
  /** API description */
  description: string;
  /** Discovery version used */
  discoveryVersion: string;
  /** Discovery REST URL */
  discoveryRestUrl: string;
  /** Documentation link */
  documentationLink: string;
  /** ETag for caching */
  etag: string;
  /** API icons */
  icons: {x16: string; x32: string};
  /** Unique API identifier */
  id: string;
  /** Document kind */
  kind: string;
  /** Top-level API methods */
  methods: SchemaMethods;
  /** API name */
  name: string;
  /** Owner domain */
  ownerDomain: string;
  /** Owner name */
  ownerName: string;
  /** Global parameters */
  parameters: SchemaParameters;
  /** Protocol (usually 'rest') */
  protocol: string;
  /** API resources */
  resources: SchemaResources;
  /** Schema revision */
  revision: string;
  /** Root URL for all endpoints */
  rootUrl: string;
  /** Schema definitions for request/response types */
  schemas: SchemaItems;
  /** Service path */
  servicePath: string;
  /** API title */
  title: string;
  /** API version */
  version: string;
}

/**
 * Collection of schema resources
 */
interface SchemaResources {
  [index: string]: SchemaResource;
}

/**
 * Individual schema resource definition
 */
interface SchemaResource {
  /** Methods available on this resource */
  methods?: SchemaMethods;
  /** Sub-resources nested under this resource */
  resources?: SchemaResources;
}

/**
 * Collection of schema methods
 */
interface SchemaMethods {
  [index: string]: SchemaMethod;
}

/**
 * Individual schema method definition
 */
interface SchemaMethod {
  /** Method description */
  description: string;
  /** HTTP method (GET, POST, etc.) */
  httpMethod: HttpMethod;
  /** Unique method identifier */
  id: string;
  /** Order of parameters in method signature */
  parameterOrder?: string[];
  /** Method-specific parameters */
  parameters?: {[index: string]: SchemaParameter};
  /** URL path template */
  path: string;
  /** Request body schema reference */
  request: {$ref: string};
  /** Response body schema reference */
  response: {$ref: string};
  /** Sample URL for testing */
  sampleUrl: string;
  /** Required OAuth2 scopes */
  scopes: string[];
  /** Code fragment for samples */
  fragment: string;
  /** Media upload configuration */
  mediaUpload: {
    protocols: {
      simple: {path: string};
    };
  };
  /** Whether method supports media download */
  supportsMediaDownload?: boolean;
  /** API version for this method */
  apiVersion?: string;
}

/**
 * Collection of schema parameters
 */
interface SchemaParameters {
  [index: string]: SchemaParameter;
}

/**
 * Individual parameter definition
 */
interface SchemaParameter {
  /** Default value */
  default: string;
  /** Parameter description */
  description: string;
  /** Parameter location (query, path, header) */
  location: string;
  /** Enumerated values */
  enum: string[];
  /** Descriptions for enum values */
  enumDescription: string[];
  /** Parameter data type */
  type: SchemaType;
  /** Parameter format specification */
  format: ParameterFormat;
  /** Whether parameter is required */
  required: boolean;
}

/**
 * Collection of schema items (type definitions)
 */
interface SchemaItems {
  [index: string]: SchemaItem;
}

/**
 * Individual schema item (type definition)
 */
interface SchemaItem {
  /** Item description */
  description?: string;
  /** Default value */
  default?: string;
  /** Unique identifier */
  id?: string;
  /** Object properties (for object types) */
  properties?: {[index: string]: SchemaItem};
  /** Additional properties configuration */
  additionalProperties?: {[index: string]: SchemaItem};
  /** Array item definitions */
  items?: {[index: string]: SchemaItem};
  /** Data type */
  type?: SchemaType;
  /** Format specification */
  format?: ParameterFormat;
  /** Reference to another schema item */
  $ref?: string;
}

/**
 * Fragment response for code samples
 */
interface FragmentResponse {
  /** Code fragments by language */
  codeFragment: {[index: string]: {fragment: string}};
}

/**
 * Parameter format specifications
 */
type ParameterFormat = 'int32' | 'int64' | 'float' | 'double' | 'byte' | 'binary' | 'date' | 'date-time' | 'password';

/**
 * Supported HTTP methods
 */
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';

/**
 * Schema data types
 */
type SchemaType = 'object' | 'integer' | 'string' | 'array' | 'boolean' | 'number' | 'null';

import { 
  Schema, 
  SchemaMethod, 
  SchemaResource,
  HttpMethod,
  SchemaType 
} from "googleapis-common";

// Process a schema method
function processMethod(method: SchemaMethod) {
  console.log(`Method: ${method.id}`);
  console.log(`HTTP: ${method.httpMethod}`);
  console.log(`Path: ${method.path}`);
  
  if (method.parameters) {
    Object.entries(method.parameters).forEach(([name, param]) => {
      console.log(`  ${name}: ${param.type} (${param.location})`);
    });
  }
}

// Navigate schema resources
function listResources(resources: SchemaResources, prefix = '') {
  Object.entries(resources).forEach(([name, resource]) => {
    console.log(`${prefix}${name}`);
    
    if (resource.methods) {
      Object.keys(resource.methods).forEach(methodName => {
        console.log(`${prefix}  ${methodName}()`);
      });
    }
    
    if (resource.resources) {
      listResources(resource.resources, prefix + '  ');
    }
  });
}