docs: add API extractor

.gitignore

@@ -13,3 +13,4 @@ yarn-error.log
 function_output.json
 serverlog_stderr.txt
 serverlog_stdout.txt
+temp

CONTRIBUTING.md

@@ -71,6 +71,16 @@ npm unpublish @google-cloud/[email protected]
 npm dist-tag add @google-cloud/[email protected] latest --registry=https://wombat-dressing-room.appspot.com
 ```
 
+### API Extractor
+
+To generate the API Extractor documentation, run the API extractor with the following command:
+
+```sh
+npm run docs
+```
+
+The docs will be generated in [`docs/generated/`](docs/generated/).
+
 ## Community Guidelines
 
 This project follows [Google's Open Source Community

api-extractor.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "build/src/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {
+    "tsconfigFilePath": "tsconfig.json"
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "docs/generated/",
+    "reportFileName": "api.md"
+  },
+
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "docs/generated/api.json"
+  },
+
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "docs/generated/api.d.ts",
+    "omitTrimmingComments": true
+  },
+
+  "tsdocMetadata": {
+  },
+
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

docs/README.md

@@ -8,6 +8,14 @@ This directory contains advanced docs around the Functions Framework.
 - [Writing a Function in Typescript](typescript.md)
 - [ES Modules](esm/README.md)
 
+## Generated Docs
+
+The `generated/` directory contains generated API references.
+
+- [api.md](generated/api.md)
+- [api.d.ts](generated/api.d.ts)
+- [api.json](generated/api.json)
+
 ## TODO Docs
 
 - Run Multiple Cloud Functions [#23](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/issues/23)

docs/generated/api.d.ts

@@ -0,0 +1,172 @@
+import * as express from 'express';
+
+/**
+ * Register a function that handles CloudEvents.
+ * @param functionName - the name of the function
+ * @param handler - the function to trigger when handling cloudevents
+ * @public
+ */
+export declare const cloudevent: (functionName: string, handler: CloudEventFunction) => void;
+
+/**
+ * A cloudevent function handler.
+ * @public
+ */
+export declare interface CloudEventFunction {
+    (cloudevent: CloudEventsContext): any;
+}
+
+/**
+ * A cloudevent function handler with callback.
+ * @public
+ */
+export declare interface CloudEventFunctionWithCallback {
+    (cloudevent: CloudEventsContext, callback: Function): any;
+}
+
+/**
+ * The CloudEvents v1.0 context object for the event.
+ * {@link https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes}
+ * @public
+ */
+export declare interface CloudEventsContext {
+    /**
+     * Type of occurrence which has happened.
+     */
+    type?: string;
+    /**
+     * The version of the CloudEvents specification which the event uses.
+     */
+    specversion?: string;
+    /**
+     * The event producer.
+     */
+    source?: string;
+    /**
+     * ID of the event.
+     */
+    id?: string;
+    /**
+     * Timestamp of when the event happened.
+     */
+    time?: string;
+    /**
+     * Describes the subject of the event in the context of the event producer.
+     */
+    subject?: string;
+    /**
+     * A link to the schema that the event data adheres to.
+     */
+    dataschema?: string;
+    /**
+     * Content type of the event data.
+     */
+    datacontenttype?: string;
+    /**
+     * The event data.
+     */
+    data?: Record<string, unknown | string | number | boolean> | string | number | boolean | null | unknown;
+    /**
+     * The traceparent string, containing a trace version, trace ID, span ID, and trace options.
+     * @see https://github.com/cloudevents/spec/blob/master/extensions/distributed-tracing.md
+     */
+    traceparent?: string;
+}
+
+/**
+ * The Cloud Functions context object for the event.
+ * {@link https://cloud.google.com/functions/docs/writing/background#function_parameters}
+ * @public
+ */
+export declare interface CloudFunctionsContext {
+    /**
+     * A unique ID for the event. For example: "70172329041928".
+     */
+    eventId?: string;
+    /**
+     * The date/time this event was created. For example: "2018-04-09T07:56:12.975Z"
+     * This will be formatted as ISO 8601.
+     */
+    timestamp?: string;
+    /**
+     * The type of the event. For example: "google.pubsub.topic.publish".
+     */
+    eventType?: string;
+    /**
+     * The resource that emitted the event.
+     */
+    resource?: string | {
+        [key: string]: string;
+    };
+}
+
+/**
+ * The function's context.
+ * @public
+ */
+export declare type Context = CloudFunctionsContext | CloudEventsContext;
+
+/**
+ * A data object used for legacy event functions.
+ * @public
+ */
+export declare interface Data {
+    data: object;
+}
+
+/**
+ * A legacy event function handler.
+ * @public
+ */
+export declare interface EventFunction {
+    (data: {}, context: Context): any;
+}
+
+/**
+ * A legacy event function handler with callback.
+ * @public
+ */
+export declare interface EventFunctionWithCallback {
+    (data: {}, context: Context, callback: Function): any;
+}
+
+/**
+ * A function handler.
+ * @public
+ */
+export declare type HandlerFunction = HttpFunction | EventFunction | EventFunctionWithCallback | CloudEventFunction | CloudEventFunctionWithCallback;
+
+/**
+ * Register a function that responds to HTTP requests.
+ * @param functionName - the name of the function
+ * @param handler - the function to invoke when handling HTTP requests
+ * @public
+ */
+export declare const http: (functionName: string, handler: HttpFunction) => void;
+
+/**
+ * A HTTP function handler.
+ * @public
+ */
+export declare interface HttpFunction {
+    (req: express.Request, res: express.Response): any;
+}
+
+/**
+ * A legacy event function context.
+ * @public
+ */
+export declare type LegacyCloudFunctionsContext = CloudFunctionsContext | Data;
+
+/**
+ * A legacy event.
+ * @public
+ */
+export declare interface LegacyEvent {
+    data: {
+        [key: string]: any;
+    };
+    context: CloudFunctionsContext;
+}
+
+export { }