feat: Add Google CloudEvent Types

experimental/generate_cloudevents/src/generate.ts

@@ -111,6 +111,16 @@ const generateInterfaceBody = (properties: {
   );
 };
 
+/**
+ * Generate the AST for the import declaration that pulls in the base CloudEvent interface.
+ */
+const generateCloudEventImport = (): t.Statement => {
+  return t.importDeclaration(
+    [t.importSpecifier(t.identifier('CloudEvent'), t.identifier('CloudEvent'))],
+    t.stringLiteral('./CloudEvent')
+  );
+};
+
 /**
  * Generate all interfaces in a given cloudevent schema
  * @param schema The cloudevent data payload schema
@@ -128,7 +138,7 @@ const generateInterfaces = (schema: TypeSchema): t.Statement[] => {
       generateInterfaceBody(definitions[definition].properties)
     );
     const exportStmt = t.exportNamedDeclaration(interfaceStmt);
-    utils.addComment(exportStmt, definitions[definition].description);
+    utils.addComment(exportStmt, definitions[definition].description, true);
     return exportStmt;
   });
 };
@@ -146,7 +156,7 @@ const generateCloudEventInterface = (schema: TypeSchema): t.Statement => {
     t.tsInterfaceDeclaration(
       t.identifier(schema.name.replace(/Data$/, 'CloudEvent')),
       null,
-      [],
+      [t.tsExpressionWithTypeArguments(t.identifier('CloudEvent'))],
       t.tsInterfaceBody([
         t.tsPropertySignature(
           t.identifier('type'),
@@ -163,7 +173,8 @@ const generateCloudEventInterface = (schema: TypeSchema): t.Statement => {
   );
   utils.addComment(
     exportStmt,
-    `The CloudEvent schema emmitted by ${schema.product}.`
+    `The schema of CloudEvents emmitted by ${schema.product}.`,
+    true
   );
   return exportStmt;
 };
@@ -173,15 +184,20 @@ const generateCloudEventInterface = (schema: TypeSchema): t.Statement => {
  * googleapis/google-cloudevents
  */
 utils.fetch(ROOT_TYPE_CATALOG_URL).then(catalog => {
-  const rootImports: {importPath: string; ceTypeName: string}[] = [];
+  const rootImports: {
+    importPath: string;
+    ceDataTypeName: string;
+    ceInterface: t.Statement;
+  }[] = [];
   const promises = (catalog as EventCatalog).schemas.map(async catSchema => {
     const schema = (await utils.fetch(catSchema.url)) as TypeSchema;
     const interfaces = generateInterfaces(schema);
-    interfaces.push(generateCloudEventInterface(schema));
+
     const ast = t.file(t.program(interfaces));
     rootImports.push({
       importPath: utils.getCloudEventImportPath(catSchema.url),
-      ceTypeName: utils.getCloudEventTypeName(schema.name),
+      ceDataTypeName: schema.name,
+      ceInterface: generateCloudEventInterface(schema),
     });
     utils.addCopyright(ast);
     const {code} = generate(ast);
@@ -193,24 +209,32 @@ utils.fetch(ROOT_TYPE_CATALOG_URL).then(catalog => {
   Promise.all(promises).then(() => {
     const imports: t.Statement[] = rootImports
       .sort((a, b) => (a.importPath > b.importPath ? 1 : -1))
-      .map(({importPath, ceTypeName}) => {
+      .map(({importPath, ceDataTypeName}) => {
         return t.importDeclaration(
           [
             t.importSpecifier(
-              t.identifier(ceTypeName),
-              t.identifier(ceTypeName)
+              t.identifier(ceDataTypeName),
+              t.identifier(ceDataTypeName)
             ),
           ],
           t.stringLiteral(importPath)
         );
       });
 
+    imports.push(generateCloudEventImport());
+
+    imports.push(...rootImports.map(x => x.ceInterface));
+
     const googleCloudEventExport = t.exportNamedDeclaration(
       t.tsTypeAliasDeclaration(
         t.identifier('GoogleCloudEvent'),
         null,
         t.tsUnionType(
-          rootImports.map(x => t.tsTypeReference(t.identifier(x.ceTypeName)))
+          rootImports.map(x =>
+            t.tsTypeReference(
+              t.identifier(utils.getCloudEventTypeName(x.ceDataTypeName))
+            )
+          )
         )
       )
     );

experimental/generate_cloudevents/src/utils.ts

@@ -25,13 +25,23 @@ export const RELATIVE_SRC_DIR = '../../src/cloudevent_types';
  * Add a JSDoc comment to an AST node
  * @param node the AST node to add a comment to
  * @param comment the text content of the comment
+ * @param isPublic whether or not to add an "@public" annotation
  * @returns the AST node with attached comment
  */
-export const addComment = <T extends t.Node>(node: T, comment?: string): T => {
+export const addComment = <T extends t.Node>(
+  node: T,
+  comment?: string,
+  isPublic = false
+): T => {
   if (comment) {
     const lines = comment.split('\n').map(l => ' * ' + l.trim());
     lines.unshift('*');
 
+    if (isPublic) {
+      lines.push(' * ');
+      lines.push(' * @public');
+    }
+
     t.addComment(node, 'leading', lines.join('\n') + '\n ');
   }
   return node;
@@ -91,6 +101,12 @@ export const getCloudEventTypeName = (dataTypeName: string): string => {
  * @returns the updated AST node
  */
 export const addCopyright = (file: t.File): t.File => {
+  t.addComment(
+    file,
+    'leading',
+    ' eslint-disable @typescript-eslint/no-explicit-any',
+    false
+  );
   [
     ' Copyright 2021 Google LLC',
     '',

src/cloudevent_types/CloudEvent.ts

@@ -0,0 +1,54 @@
+/**
+ * The CloudEvents v1.0 context object for the event.
+ * {@link https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes}
+ * @public
+ */
+export interface CloudEvent {
+  /**
+   * 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;
+}

src/cloudevent_types/GoogleCloudEvent.ts

@@ -0,0 +1,167 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/* eslint-disable @typescript-eslint/no-explicit-any*/
+import {LogEntryData} from './cloud/audit/v1/LogEntryData';
+import {BuildEventData} from './cloud/cloudbuild/v1/BuildEventData';
+import {DocumentEventData} from './cloud/firestore/v1/DocumentEventData';
+import {MessagePublishedData} from './cloud/pubsub/v1/MessagePublishedData';
+import {SchedulerJobData} from './cloud/scheduler/v1/SchedulerJobData';
+import {StorageObjectData} from './cloud/storage/v1/StorageObjectData';
+import {AnalyticsLogData} from './firebase/analytics/v1/AnalyticsLogData';
+import {AuthEventData} from './firebase/auth/v1/AuthEventData';
+import {ReferenceEventData} from './firebase/database/v1/ReferenceEventData';
+import {RemoteConfigEventData} from './firebase/remoteconfig/v1/RemoteConfigEventData';
+import {TestMatrixEventData} from './firebase/testlab/v1/TestMatrixEventData';
+import {CloudEvent} from './CloudEvent';
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Audit Logs.
+ *
+ * @public
+ */
+export interface LogEntryCloudEvent extends CloudEvent {
+  type: 'google.cloud.audit.log.v1.written';
+  data: LogEntryData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Build.
+ *
+ * @public
+ */
+export interface BuildEventCloudEvent extends CloudEvent {
+  type: 'google.cloud.cloudbuild.build.v1.statusChanged';
+  data: BuildEventData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Firestore.
+ *
+ * @public
+ */
+export interface DocumentEventCloudEvent extends CloudEvent {
+  type:
+    | 'google.cloud.firestore.document.v1.created'
+    | 'google.cloud.firestore.document.v1.updated'
+    | 'google.cloud.firestore.document.v1.deleted'
+    | 'google.cloud.firestore.document.v1.written';
+  data: DocumentEventData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Pub/Sub.
+ *
+ * @public
+ */
+export interface MessagePublishedCloudEvent extends CloudEvent {
+  type: 'google.cloud.pubsub.topic.v1.messagePublished';
+  data: MessagePublishedData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Scheduler.
+ *
+ * @public
+ */
+export interface SchedulerJobCloudEvent extends CloudEvent {
+  type: 'google.cloud.scheduler.job.v1.executed';
+  data: SchedulerJobData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Cloud Storage.
+ *
+ * @public
+ */
+export interface StorageObjectCloudEvent extends CloudEvent {
+  type:
+    | 'google.cloud.storage.object.v1.finalized'
+    | 'google.cloud.storage.object.v1.archived'
+    | 'google.cloud.storage.object.v1.deleted'
+    | 'google.cloud.storage.object.v1.metadataUpdated';
+  data: StorageObjectData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Google Analytics for Firebase.
+ *
+ * @public
+ */
+export interface AnalyticsLogCloudEvent extends CloudEvent {
+  type: 'google.firebase.analytics.log.v1.written';
+  data: AnalyticsLogData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Firebase Authentication.
+ *
+ * @public
+ */
+export interface AuthEventCloudEvent extends CloudEvent {
+  type:
+    | 'google.firebase.auth.user.v1.created'
+    | 'google.firebase.auth.user.v1.deleted';
+  data: AuthEventData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Firebase Realtime Database.
+ *
+ * @public
+ */
+export interface ReferenceEventCloudEvent extends CloudEvent {
+  type:
+    | 'google.firebase.database.ref.v1.created'
+    | 'google.firebase.database.ref.v1.updated'
+    | 'google.firebase.database.ref.v1.deleted'
+    | 'google.firebase.database.ref.v1.written';
+  data: ReferenceEventData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Firebase Remote Config.
+ *
+ * @public
+ */
+export interface RemoteConfigEventCloudEvent extends CloudEvent {
+  type: 'google.firebase.remoteconfig.remoteConfig.v1.updated';
+  data: RemoteConfigEventData;
+}
+
+/**
+ * The schema of CloudEvents emmitted by Firebase Test Lab.
+ *
+ * @public
+ */
+export interface TestMatrixEventCloudEvent extends CloudEvent {
+  type: 'google.firebase.testlab.testMatrix.v1.completed';
+  data: TestMatrixEventData;
+}
+
+/**
+ * Union of all known CloudEvents emitted by Google Cloud services
+ */
+export type GoogleCloudEvent =
+  | LogEntryCloudEvent
+  | BuildEventCloudEvent
+  | DocumentEventCloudEvent
+  | MessagePublishedCloudEvent
+  | SchedulerJobCloudEvent
+  | StorageObjectCloudEvent
+  | AnalyticsLogCloudEvent
+  | AuthEventCloudEvent
+  | ReferenceEventCloudEvent
+  | RemoteConfigEventCloudEvent
+  | TestMatrixEventCloudEvent;