feat: Client-published events + realtime presence

- POST /projects/:id/events accepts client-authored events restricted to
  the custom.* namespace — system types can't be spoofed. They flow
  through the same publishEvent fan-out: realtime, webhooks, and
  event_pattern functions all fire.
- Presence: subscribe/unsubscribe bumps a per-project count and
  broadcasts presence.update {online} to the realtime stream only —
  deliberately not through publishEvent so webhooks and "*" functions
  don't fire on connect noise. GET …/realtime/presence reads the count.
- @primora/client gains publish() and presence(); CLI gains events:send.

Verified live: presence 0->1 on subscribe, presence.update frame
delivered, custom event delivered to SSE + fired a custom.* function,
spoofed document.created rejected 400.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

packages/api-client/src/generated/index.ts

@@ -117,6 +117,7 @@ export type { ProjectOverview } from './models/ProjectOverview';
 export type { ProjectSecret } from './models/ProjectSecret';
 export type { ProjectSecretListResponse } from './models/ProjectSecretListResponse';
 export type { ProjectSummary } from './models/ProjectSummary';
+export type { PublishEventRequest } from './models/PublishEventRequest';
 export type { ReadinessStatus } from './models/ReadinessStatus';
 export type { RevealProjectSecretResponse } from './models/RevealProjectSecretResponse';
 export type { RybbitMetricItem } from './models/RybbitMetricItem';
@@ -269,6 +270,7 @@ export { $ProjectOverview } from './schemas/$ProjectOverview';
 export { $ProjectSecret } from './schemas/$ProjectSecret';
 export { $ProjectSecretListResponse } from './schemas/$ProjectSecretListResponse';
 export { $ProjectSummary } from './schemas/$ProjectSummary';
+export { $PublishEventRequest } from './schemas/$PublishEventRequest';
 export { $ReadinessStatus } from './schemas/$ReadinessStatus';
 export { $RevealProjectSecretResponse } from './schemas/$RevealProjectSecretResponse';
 export { $RybbitMetricItem } from './schemas/$RybbitMetricItem';

packages/api-client/src/generated/models/PublishEventRequest.ts

@@ -0,0 +1,15 @@
+/* generated using openapi-typescript-codegen -- do not edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+export type PublishEventRequest = {
+    /**
+     * Event type in the custom.* namespace — realtime subscribers, matching webhooks, and event_pattern functions all fire.
+     */
+    type: string;
+    /**
+     * Arbitrary JSON payload carried to subscribers.
+     */
+    data?: Record<string, any>;
+};
+

packages/api-client/src/generated/schemas/$PublishEventRequest.ts

@@ -0,0 +1,21 @@
+/* generated using openapi-typescript-codegen -- do not edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+export const $PublishEventRequest = {
+    properties: {
+        type: {
+            type: 'string',
+            description: `Event type in the custom.* namespace — realtime subscribers, matching webhooks, and event_pattern functions all fire.`,
+            isRequired: true,
+            pattern: '^custom\\.[a-z0-9][a-z0-9_.-]{0,62}$',
+        },
+        data: {
+            type: 'dictionary',
+            contains: {
+                properties: {
+                },
+            },
+        },
+    },
+} as const;

packages/api-client/src/generated/services/AutomationService.ts

@@ -3,6 +3,7 @@
 /* tslint:disable */
 /* eslint-disable */
 import type { CreateScheduledJobRequest } from '../models/CreateScheduledJobRequest';
+import type { PublishEventRequest } from '../models/PublishEventRequest';
 import type { ScheduledJobCreateResponse } from '../models/ScheduledJobCreateResponse';
 import type { ScheduledJobListResponse } from '../models/ScheduledJobListResponse';
 import type { ScheduledJobRun } from '../models/ScheduledJobRun';
@@ -12,6 +13,35 @@ import type { CancelablePromise } from '../core/CancelablePromise';
 import { OpenAPI } from '../core/OpenAPI';
 import { request as __request } from '../core/request';
 export class AutomationService {
+    /**
+     * Publishes a client-authored domain event. Type must be in the custom.* namespace; the event fans out to realtime subscribers, matching webhooks, and event_pattern functions.
+     * @returns any Event accepted for fan-out
+     * @throws ApiError
+     */
+    public static publishProjectEvent({
+        projectId,
+        requestBody,
+    }: {
+        projectId: string,
+        requestBody: PublishEventRequest,
+    }): CancelablePromise<{
+        published?: string;
+    }> {
+        return __request(OpenAPI, {
+            method: 'POST',
+            url: '/projects/{projectID}/events',
+            path: {
+                'projectID': projectId,
+            },
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Error response`,
+                401: `Error response`,
+                403: `Error response`,
+            },
+        });
+    }
     /**
      * @returns ScheduledJobListResponse Scheduled jobs for the project
      * @throws ApiError
@@ -191,4 +221,27 @@ export class AutomationService {
             },
         });
     }
+    /**
+     * Count of clients currently subscribed to the project's realtime stream. The stream also emits presence.update events on every join/leave.
+     * @returns any Online subscriber count
+     * @throws ApiError
+     */
+    public static getRealtimePresence({
+        projectId,
+    }: {
+        projectId: string,
+    }): CancelablePromise<{
+        online?: number;
+    }> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/projects/{projectID}/realtime/presence',
+            path: {
+                'projectID': projectId,
+            },
+            errors: {
+                401: `Error response`,
+            },
+        });
+    }
 }

packages/client/src/realtime.ts

@@ -2,8 +2,10 @@
 // (GET /api/v1/projects/:id/realtime/stream). EventSource can't send auth
 // headers, so the stream is consumed via fetch + ReadableStream.
 //
-// jarvis: ceiling — subscriptions only. Presence and client-broadcast are a
-// protocol question; add when a concrete consumer needs them.
+// Presence: the server broadcasts `presence.update` {online: n} on every
+// subscriber join/leave — subscribe via channel("presence").on("update").
+// Client-broadcast: publish() emits a custom.* event through the server
+// fan-out (webhooks and event_pattern functions fire too).
 
 export interface RealtimeEvent {
   /** e.g. "document.created", "object.deleted", "issue.created", "deploy.marker" */
@@ -41,6 +43,13 @@ export interface RealtimeClient {
    * `channel("documents")` and `channel("document")` are equivalent.
    */
   channel(name: string): RealtimeChannel;
+  /**
+   * Publishes a `custom.*` event to the project — realtime subscribers,
+   * matching webhooks, and event_pattern functions all receive it.
+   */
+  publish(type: string, data?: Record<string, unknown>): Promise<void>;
+  /** Current count of clients subscribed to the project's realtime stream. */
+  presence(): Promise<number>;
   close(): void;
   readonly state: RealtimeState;
 }
@@ -142,6 +151,27 @@ export function createRealtimeClient(opts: RealtimeClientOptions): RealtimeClien
         },
       };
     },
+    async publish(type, data = {}) {
+      const res = await fetch(
+        opts.endpoint.replace(/\/$/, "") +
+          `/api/v1/projects/${encodeURIComponent(opts.projectId)}/events`,
+        {
+          method: "POST",
+          headers: { "X-API-Key": opts.key, "Content-Type": "application/json" },
+          body: JSON.stringify({ type, data }),
+        },
+      );
+      if (!res.ok) throw new Error(`publish event: HTTP ${res.status}`);
+    },
+    async presence() {
+      const res = await fetch(
+        opts.endpoint.replace(/\/$/, "") +
+          `/api/v1/projects/${encodeURIComponent(opts.projectId)}/realtime/presence`,
+        { headers: { "X-API-Key": opts.key } },
+      );
+      if (!res.ok) throw new Error(`presence: HTTP ${res.status}`);
+      return ((await res.json()) as { online: number }).online;
+    },
     close: () => abort.abort(),
     get state() {
       return state;