@grantjs/schema 1.17.0 → 1.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantjs/schema",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
   "devDependencies": {
     "@graphql-codegen/add": "^7.1.1",
     "@graphql-codegen/cli": "^7.4.6",
-    "@graphql-codegen/typed-document-node": "^7.1.1",
+    "@graphql-codegen/typed-document-node": "^7.2.0",
     "@graphql-codegen/typescript": "^6.1.2",
     "@graphql-codegen/typescript-operations": "^6.1.10",
     "@graphql-codegen/typescript-resolvers": "^6.1.1",
@@ -34,7 +34,7 @@
     "graphql": "^16.14.2",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "scripts": {
     "dev": "graphql-codegen --config codegen.ts generate --watch",

package/src/events/event-catalog.ts

@@ -83,6 +83,17 @@ const INTEGRATIONS_OWNERS: EventCatalogEntry = {
   audienceRule: { primitives: ['owners'], excludeActor: true },
 };
 
+/**
+ * An event that exists for webhook consumers only: delivered transactionally to
+ * subscriptions, never turned into a notification. The empty audience is what
+ * keeps the notification generator from creating rows for it.
+ */
+const webhookOnly = (category: EventCategory): EventCatalogEntry => ({
+  category,
+  deliveryClass: 'transactional',
+  audienceRule: { primitives: [] },
+});
+
 export const EVENT_TYPES = [
   // IAM mutations (Phase 1 slice)
   'role.created',
@@ -135,6 +146,17 @@ export const EVENT_TYPES = [
   // CDM / project sync job summaries (entity events suppressed during import)
   'project_sync.completed',
   'project_sync.failed',
+  // Webhook-only lifecycle events (no notification): users, project users, API keys, tags
+  'user.created',
+  'user.updated',
+  'user.deleted',
+  'project.user_updated',
+  'api_key.deleted',
+  'tag.created',
+  'tag.updated',
+  'tag.deleted',
+  'tag.linked',
+  'tag.unlinked',
 ] as const;
 
 export type EventType = (typeof EVENT_TYPES)[number];
@@ -200,6 +222,16 @@ export const EVENT_CATALOG: Readonly<Record<EventType, EventCatalogEntry>> = {
   'user.password_changed': SECURITY_SUBJECT,
   'project_sync.completed': INTEGRATIONS_OWNERS,
   'project_sync.failed': INTEGRATIONS_OWNERS,
+  'user.created': webhookOnly('membership'),
+  'user.updated': webhookOnly('membership'),
+  'user.deleted': webhookOnly('membership'),
+  'project.user_updated': webhookOnly('membership'),
+  'api_key.deleted': webhookOnly('security'),
+  'tag.created': webhookOnly('iam'),
+  'tag.updated': webhookOnly('iam'),
+  'tag.deleted': webhookOnly('iam'),
+  'tag.linked': webhookOnly('iam'),
+  'tag.unlinked': webhookOnly('iam'),
 };
 
 export function getEventCatalogEntry(type: EventType): EventCatalogEntry {

package/src/events/event-envelope.ts

@@ -3,17 +3,62 @@ import type { EventCategory, EventType } from './event-catalog';
 
 /**
  * Payload carried inside an event. The internal model can be rich; the external
- * webhook envelope projects `data` through a redaction allowlist.
+ * webhook envelope projects `data` (see `ExternalEventData`): `after` and `delta`
+ * are redacted, `before` is reduced to its identity fields.
  */
 export interface EventData {
   /** Snapshot of the entity after the change (redacted on external delivery). */
   after?: Record<string, unknown> | null;
-  /** Snapshot before the change (optional). */
+  /** Snapshot before the change (optional). External delivery keeps only its identity fields. */
   before?: Record<string, unknown> | null;
   /** Changed-fields delta: field -> { from, to }. */
   delta?: Record<string, { from: unknown; to: unknown }> | null;
 }
 
+/**
+ * Keys an external (webhook) `data.before` may carry. The projection copies these,
+ * and only these, from the internal `before` snapshot, and only when the value is a
+ * string, number, boolean or `null`: a subscriber learns which entity or pivot an
+ * event removed, never its profile fields, metadata or secrets.
+ */
+export const EVENT_IDENTITY_KEYS = [
+  'id',
+  'name',
+  'slug',
+  'kind',
+  'type',
+  'userId',
+  'roleId',
+  'groupId',
+  'permissionId',
+  'tagId',
+  'apiKeyId',
+  'resourceId',
+  'targetKind',
+  'targetId',
+  'projectId',
+  'roleName',
+  'groupName',
+  'permissionName',
+  'tagName',
+] as const;
+
+export type EventIdentityKey = (typeof EVENT_IDENTITY_KEYS)[number];
+
+/** Identity-only projection of an internal `before` snapshot (see `EVENT_IDENTITY_KEYS`). */
+export type EventIdentity = Partial<Record<EventIdentityKey, string | number | boolean | null>>;
+
+/**
+ * `data` as delivered to webhook consumers: `after` and `delta` redacted, `before`
+ * reduced to the identity of the entity or pivot the event is about. Absent when
+ * the internal snapshot has no identity field.
+ */
+export interface ExternalEventData {
+  after?: Record<string, unknown> | null;
+  before?: EventIdentity | null;
+  delta?: Record<string, { from: unknown; to: unknown }> | null;
+}
+
 /** Reference to the aggregate (entity) the event is about. */
 export interface EventAggregateRef {
   kind: string;
@@ -33,6 +78,13 @@ export interface DomainEventInput {
   aggregate?: EventAggregateRef;
   data: EventData;
   occurredAt?: Date;
+  /**
+   * Projects this event is relevant to beyond the one named by its scope. The
+   * publisher adds the projects an entity-bound aggregate is linked to; a caller
+   * passes it only to capture the links before a write that destroys them (a
+   * delete). Never part of the external envelope.
+   */
+  projectIds?: string[];
 }
 
 /**
@@ -51,12 +103,17 @@ export interface DomainEvent {
   aggregate?: EventAggregateRef;
   data: EventData;
   occurredAt: Date;
+  /**
+   * Projects the event is relevant to in addition to the project its scope names
+   * (webhook fan-out, ADR 0012). Internal: not carried by the webhook envelope.
+   */
+  projectIds?: string[];
 }
 
 /**
  * External event envelope delivered to webhook consumers. CloudEvents 1.0 core
  * fields plus Grant extension attributes (prefixed `grant`). `data` is the
- * redacted projection of the internal payload.
+ * redacted projection of the internal payload (`ExternalEventData`).
  */
 export interface CloudEventEnvelope {
   specversion: '1.0';
@@ -68,6 +125,13 @@ export interface CloudEventEnvelope {
   grantsequence: string;
   grantscope: { tenant: string; id: string };
   grantactor?: { userId: string } | null;
+  /**
+   * The user the event is about, when it has one (`user.role_revoked`,
+   * `project.user_removed`, `organization.invitation_sent`, ...). `null` when
+   * the event has no subject user. It names the user even when `data.before`
+   * is absent or carries no `userId`.
+   */
+  grantsubjectuser?: { userId: string } | null;
   grantcategory: EventCategory;
-  data: EventData;
+  data: ExternalEventData;
 }