fix(kits): restore the extensions' event payload shapes

kits/delete-user-data/README.md

@@ -30,6 +30,7 @@ service account for this codebase — it conflicts with that automatic setup.
 | `roles/pubsub.admin` | publish/subscribe discovery and deletion topics |
 | `roles/eventarc.eventReceiver` | receive Gen2 event triggers |
 | `roles/run.invoker` | allow Eventarc to invoke the Gen2 Cloud Run service |
+| `roles/eventarc.publisher` | publish the kit's custom Eventarc events (the Extensions platform granted this implicitly) |
 
 ## Usage
 

kits/delete-user-data/src/index.ts

@@ -42,6 +42,11 @@ const REQUIRED_ROLES: ReadonlyArray<Role> = [
   // Gen2 event triggers need Eventarc receive and run.invoker on the function SA.
   "roles/eventarc.eventReceiver",
   "roles/run.invoker",
+  // The Extensions platform granted publish rights on the extension's Eventarc
+  // channel implicitly from `events:` in extension.yaml. Kits get no implicit
+  // grant, so without this the `channel.publish()` calls in ./events fail with
+  // PERMISSION_DENIED and no custom event is ever delivered.
+  "roles/eventarc.publisher",
 ];
 
 for (const role of REQUIRED_ROLES) {

kits/firestore-bigquery-export/README.md

@@ -30,6 +30,7 @@ conflicts with that automatic setup.
 | `roles/datastore.user` | write failed-row records back to Firestore (only if you configure a backup collection) |
 | `roles/eventarc.eventReceiver` | receive Gen2 Firestore trigger events |
 | `roles/run.invoker` | allow Eventarc to invoke the Gen2 Cloud Run service |
+| `roles/eventarc.publisher` | publish the kit's custom Eventarc events (the Extensions platform granted this implicitly) |
 | `bigquery.googleapis.com` | mirror Firestore collection changes in BigQuery |
 
 If the dataset lives in a different project (`BIGQUERY_PROJECT_ID`), grant the

kits/firestore-bigquery-export/src/index.ts

@@ -61,6 +61,11 @@ const REQUIRED_ROLES: ReadonlyArray<Role> = [
   // Gen2 Firestore triggers need Eventarc receive and run.invoker on the function SA.
   "roles/eventarc.eventReceiver",
   "roles/run.invoker",
+  // The Extensions platform granted publish rights on the extension's Eventarc
+  // channel implicitly from `events:` in extension.yaml. Kits get no implicit
+  // grant, so without this the `channel.publish()` calls in ./events fail with
+  // PERMISSION_DENIED and no custom event is ever delivered.
+  "roles/eventarc.publisher",
 ];
 const REQUIRED_APIS = [
   {

kits/firestore-counter/README.md

@@ -27,6 +27,7 @@ service account for this codebase — it conflicts with that automatic setup.
 | `roles/cloudscheduler.admin` | schedule the controller that flushes shards |
 | `roles/eventarc.eventReceiver` | receive Gen2 Firestore trigger events |
 | `roles/run.invoker` | allow Eventarc/Scheduler to invoke the Gen2 Cloud Run service |
+| `roles/eventarc.publisher` | publish the kit's custom Eventarc events (the Extensions platform granted this implicitly) |
 
 ## Usage
 
@@ -161,16 +162,6 @@ for them, so no events are published until you create a channel and put both
 values in your `.env`. If you set `EVENTARC_CHANNEL` and leave
 `EXT_SELECTED_EVENTS` unset, every event type is published.
 
-### Event payloads have a different shape
-
-The event types are unchanged, but what they carry is not. `onStart` used to
-carry `{change, context}` and now carries `{data, params}`: the write is under
-`data` instead of `change`, and the 1st gen `context` is gone. `onCompletion`
-used to carry `{context}` and now carries `{params}` only. Anything reading
-`context.eventId`, `context.timestamp`, `context.eventType` or
-`context.resource` from these events needs updating; the trigger wildcards
-(`collection`, `counter`, `shardId`) survive as `params`.
-
 ### Your codebase's global options apply to these functions
 
 The functions are exported from your own functions codebase, so a
@@ -201,8 +192,11 @@ carry on getting them from the extension repo.
 - The aggregation behaviour: inline aggregation up to 200 shards, workers above
   that, 45 second self-scheduling worker runs, partial shard cleanup, and
   deletion of shards once they are summed into the counter field.
-- The three functions and the event types they publish, aside from the worker
-  and payload points above.
+- The three functions, the event types they publish and their payloads:
+  `onStart` still carries `{change, context}` and `onCompletion` still carries
+  `{context}`, with `context.eventId`, `context.timestamp`, `context.eventType`,
+  `context.resource` and the trigger wildcards under `context.params`. Aside
+  from the worker point above.
 
 ## API surface
 

kits/firestore-counter/src/event-context.ts

@@ -0,0 +1,64 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import type { FirestoreEvent } from "firebase-functions/v2/firestore";
+
+/**
+ * The 1st gen `EventContext` shape that the extension published inside its
+ * `onStart` and `onCompletion` payloads.
+ */
+export interface EventContext {
+  eventId: string;
+  timestamp: string;
+  eventType: string;
+  resource: {
+    service: string;
+    name: string;
+  };
+  params: Record<string, string>;
+}
+
+/**
+ * Every 1st gen Firestore `onWrite` trigger reported this event type, so
+ * subscribers matching on `context.eventType` keep matching it.
+ */
+const FIRESTORE_WRITE_EVENT_TYPE = "google.firestore.document.write";
+
+const FIRESTORE_SERVICE = "firestore.googleapis.com";
+
+/**
+ * Rebuilds the 1st gen `EventContext` from a 2nd gen `FirestoreEvent`.
+ *
+ * The extension handed the 1st gen handler's `context` straight to Eventarc, so
+ * subscribers read `eventId`, `timestamp`, `eventType`, `resource` and `params`
+ * off it. `FirestoreEvent` carries the same information under different names,
+ * so the published payload keeps its original shape instead of following the
+ * 2nd gen handler signature.
+ */
+export function toEventContext(
+  event: FirestoreEvent<unknown, Record<string, string>>
+): EventContext {
+  return {
+    eventId: event.id,
+    timestamp: event.time,
+    eventType: FIRESTORE_WRITE_EVENT_TYPE,
+    resource: {
+      service: FIRESTORE_SERVICE,
+      name: `projects/${event.project}/databases/${event.database}/documents/${event.document}`,
+    },
+    params: event.params,
+  };
+}

kits/firestore-counter/src/handlers.ts

@@ -18,6 +18,7 @@ import type { DocumentSnapshot, Firestore } from "firebase-admin/firestore";
 import type { Change, FirestoreEvent } from "firebase-functions/v2/firestore";
 import type { ScheduledEvent } from "firebase-functions/v2/scheduler";
 import { ControllerStatus, ShardedCounterController } from "./controller";
+import { toEventContext } from "./event-context";
 import * as events from "./events";
 import type { ResolvedCounterConfig } from "./export-config";
 import { ShardedCounterWorker } from "./worker";
@@ -62,7 +63,8 @@ export async function handleShardWrite(
   event: CounterWriteEvent,
   ctx: HandlerContext
 ): Promise<void> {
-  await events.recordStartEvent({ data: event.data, params: event.params });
+  const context = toEventContext(event);
+  await events.recordStartEvent({ change: event.data, context });
   const metadocRef = ctx.firestore.doc(ctx.config.internalStatePath);
   const controller = new ShardedCounterController(
     metadocRef,
@@ -73,7 +75,7 @@ export async function handleShardWrite(
     INLINE_AGGREGATION_LIMIT,
     INLINE_AGGREGATION_TIMEOUT_MS
   );
-  await events.recordCompletionEvent({ params: event.params });
+  await events.recordCompletionEvent({ context });
 }
 
 export async function handleWorker(event: CounterWriteEvent): Promise<void> {

kits/firestore-counter/src/index.ts

@@ -39,6 +39,11 @@ const REQUIRED_ROLES: ReadonlyArray<Role> = [
   // Gen2 Firestore triggers need Eventarc receive and run.invoker on the function SA.
   "roles/eventarc.eventReceiver",
   "roles/run.invoker",
+  // The Extensions platform granted publish rights on the extension's Eventarc
+  // channel implicitly from `events:` in extension.yaml. Kits get no implicit
+  // grant, so without this the `channel.publish()` calls in ./events fail with
+  // PERMISSION_DENIED and no custom event is ever delivered.
+  "roles/eventarc.publisher",
 ];
 
 for (const role of REQUIRED_ROLES) {

kits/firestore-counter/tests/event-context.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import { describe, expect, test } from "vitest";
+import { toEventContext } from "../src/event-context";
+
+/**
+ * The extension published its 1st gen handler's `context` verbatim, so these
+ * assertions pin the fields subscribers read off it.
+ */
+describe("toEventContext", () => {
+  const event = {
+    id: "event-1",
+    time: "2026-01-01T00:00:00.000Z",
+    project: "demo-project",
+    database: "(default)",
+    document: "pages/home/_counter_shards_/0000",
+    params: { collection: "pages", counter: "home", shardId: "0000" },
+  } as any;
+
+  test("rebuilds the 1st gen event context from a 2nd gen event", () => {
+    expect(toEventContext(event)).toEqual({
+      eventId: "event-1",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      eventType: "google.firestore.document.write",
+      resource: {
+        service: "firestore.googleapis.com",
+        name: "projects/demo-project/databases/(default)/documents/pages/home/_counter_shards_/0000",
+      },
+      params: { collection: "pages", counter: "home", shardId: "0000" },
+    });
+  });
+
+  test("names the resource under the event's own database", () => {
+    const context = toEventContext({ ...event, database: "counters" });
+
+    expect(context.resource.name).toBe(
+      "projects/demo-project/databases/counters/documents/pages/home/_counter_shards_/0000"
+    );
+  });
+
+  test("passes the trigger wildcards through unchanged", () => {
+    const params = { collection: "docs", counter: "a/b/c", shardId: "0001" };
+
+    expect(toEventContext({ ...event, params }).params).toEqual(params);
+  });
+});

kits/firestore-counter/tests/events.test.ts

@@ -15,6 +15,17 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { toEventContext } from "../src/event-context";
+
+/** A shard write on the `{collection}/{counter=**}/_counter_shards_/{shardId}` trigger. */
+const SHARD_WRITE = {
+  id: "event-1",
+  time: "2026-01-01T00:00:00.000Z",
+  project: "demo-project",
+  database: "(default)",
+  document: "pages/home/_counter_shards_/0000",
+  params: { collection: "pages", counter: "home", shardId: "0000" },
+} as any;
 
 const publish = vi.fn();
 const channel = vi.fn(() => ({ publish }));
@@ -81,11 +92,16 @@ describe("event publishing", () => {
   test("publishes start events", async () => {
     const events = await setupEnabledEvents();
 
-    await events.recordStartEvent({ params: { shardId: "0000" } });
+    const context = toEventContext(SHARD_WRITE);
+
+    await events.recordStartEvent({
+      change: { before: {}, after: {} },
+      context,
+    });
 
     expect(publish).toHaveBeenCalledWith({
       type: "firebase.extensions.firestore-counter.v1.onStart",
-      data: { params: { shardId: "0000" } },
+      data: { change: { before: {}, after: {} }, context },
     });
   });
 
@@ -119,12 +135,41 @@ describe("event publishing", () => {
   test("publishes completion events", async () => {
     const events = await setupEnabledEvents();
 
-    await events.recordCompletionEvent({ params: { shardId: "0000" } });
+    const context = toEventContext(SHARD_WRITE);
+
+    await events.recordCompletionEvent({ context });
 
     expect(publish).toHaveBeenCalledWith({
       type: "firebase.extensions.firestore-counter.v1.onCompletion",
-      data: { params: { shardId: "0000" } },
+      data: { context },
+    });
+  });
+
+  test("puts the whole 1st gen context on the wire", async () => {
+    const events = await setupEnabledEvents();
+    const context = toEventContext(SHARD_WRITE);
+
+    await events.recordStartEvent({
+      change: { before: {}, after: {} },
+      context,
     });
+    await events.recordCompletionEvent({ context });
+
+    // `firebase-admin` sends the payload as `JSON.stringify(data)`, so this is
+    // what a subscriber of the extension's events actually reads.
+    expect(publish.mock.calls.length).toBe(2);
+    for (const [event] of publish.mock.calls) {
+      expect(JSON.parse(JSON.stringify(event.data)).context).toEqual({
+        eventId: "event-1",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        eventType: "google.firestore.document.write",
+        resource: {
+          service: "firestore.googleapis.com",
+          name: "projects/demo-project/databases/(default)/documents/pages/home/_counter_shards_/0000",
+        },
+        params: { collection: "pages", counter: "home", shardId: "0000" },
+      });
+    }
   });
 
   test("does nothing before the channel is set up", async () => {

kits/firestore-counter/tests/handlers.test.ts

@@ -113,24 +113,40 @@ describe("handleSchedule", () => {
 describe("handleShardWrite", () => {
   test("aggregates continuously and records lifecycle events", async () => {
     const event = {
+      id: "event-1",
+      time: "2026-01-01T00:00:00.000Z",
+      project: "demo-project",
+      database: "(default)",
+      document: "pages/home/_counter_shards_/0000",
       data: { after: { exists: true } },
-      params: { shardId: "0000" },
+      params: { collection: "pages", counter: "home", shardId: "0000" },
     } as any;
 
     await handleShardWrite(event, makeCtx());
 
+    // The extension published the 1st gen `{change, context}` payload, so the
+    // kit rebuilds the same shape rather than exposing the 2nd gen event.
+    const context = {
+      eventId: "event-1",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      eventType: "google.firestore.document.write",
+      resource: {
+        service: "firestore.googleapis.com",
+        name: "projects/demo-project/databases/(default)/documents/pages/home/_counter_shards_/0000",
+      },
+      params: { collection: "pages", counter: "home", shardId: "0000" },
+    };
+
     expect(events.recordStartEvent).toHaveBeenCalledWith({
-      data: event.data,
-      params: event.params,
+      change: event.data,
+      context,
     });
     expect(aggregateContinuously).toHaveBeenCalledWith(
       { start: "", end: "" },
       200,
       60000
     );
-    expect(events.recordCompletionEvent).toHaveBeenCalledWith({
-      params: event.params,
-    });
+    expect(events.recordCompletionEvent).toHaveBeenCalledWith({ context });
   });
 });
 

kits/firestore-send-email/README.md

@@ -27,6 +27,7 @@ service account for this codebase — it conflicts with that automatic setup.
 | `roles/datastore.user` | read mail documents and write delivery status |
 | `roles/eventarc.eventReceiver` | receive Gen2 Firestore trigger events |
 | `roles/run.invoker` | allow Eventarc to invoke the Gen2 Cloud Run service |
+| `roles/eventarc.publisher` | publish the kit's custom Eventarc events (the Extensions platform granted this implicitly) |
 
 ## Usage
 

kits/firestore-send-email/src/index.ts

@@ -34,6 +34,11 @@ const REQUIRED_ROLES: ReadonlyArray<Role> = [
   // Gen2 Firestore triggers need Eventarc receive and run.invoker on the function SA.
   "roles/eventarc.eventReceiver",
   "roles/run.invoker",
+  // The Extensions platform granted publish rights on the extension's Eventarc
+  // channel implicitly from `events:` in extension.yaml. Kits get no implicit
+  // grant, so without this the `channel.publish()` calls in ./events fail with
+  // PERMISSION_DENIED and no custom event is ever delivered.
+  "roles/eventarc.publisher",
 ];
 
 for (const role of REQUIRED_ROLES) {